Skip to content

Terminology and Schema

Jump to bottom
Anthony edited this page Sep 2, 2016 · 3 revisions

To provided a consistent experience for developers and users alike, a common vocabulary should be used to refer to the various components of Synthea. The application can be mentally divided into two parts: the UI Board and the Sound Board

The UI Board

From the user's perspective, Synthea has the following hierarchy:

- Application
  | - Project
    | - Page
      | - Section
        | - Cue
          | - Sources

The APPLICATION is the top level software, or Synthea itself. It manages everything the user engages with.

A PROJECT is a collection of audio files and a configuration file documenting the layout of those files into a series of Pages, Sections, and Cues. Projects can also contain individual configuration options, like crossfade preferences and default cue types. Each Project has a name that is displayed prominently throughout the Application, and a key that exists behind the scenes and references the /Projects subfolder containing the Project data.

A PAGE is the highest level of Cue organization within a Project, and represents a major psychological or thematic grouping. In the Application, only one Page can be viewed at any given time. Each Page has a unique name and contains an arbitrary number of Sections, which are always unique to that Page.

A SECTION is a lower level of Cue organization within a Page, and represents a minor stylistic, tonal, or thematic grouping. Each Section is tied to a specific Page, and is displayed when that Page is selected in the Application. A Section has a unique name and contains an arbitrary number of Cues, though a given Cue can exist simultaneously in any number of Sections.

A CUE is the building block of Synthea, and represents a media file (or files) that can be queued or played. A Cue has numerous configuration options, including a name, a loop toggle, a list of Sections it appears in, and an array of Sources with one or more media files.

The SOURCES are the names of media files that can be found in the Project's /audio folder. At least one file is required for a Cue to be playable. When a Cue with multiple Sources is played, a non-sequential random selection will designate a different file to play each time.

The Sound Board

From the sound mixing and playback perspective, Synthea has the following hierarchy:

- Mixer
  | - Subgroup
    | - Channel
      | - Player
      | - Media

The MIXER is the master controller for audio playback, and Synthea only has one (though it is re-instantiated for each project load). Global-level actions, like stopping all playback, are handled at the Mixer level, as are user-indifferent actions (like playing a cue).

A SUBGROUP is a collection of channels that correspond to a single "type" of cue, such as music, rain, jungle noises, or background ambience. The Mixer can have as many Subgroups as are required for a given board, though only two are instantiated by default: music and common. Each Subgroup is responsible for creating and managing its own Channels, and works as an intermediary between the "type-indifferent" Mixer and the "type-specific" Channels.

A CHANNEL is a vehicle for the playback of a single Media Cue. While a Channel may only have a single object of Media at any time, Channels are re-used over the course of the application's runtime. When assigned an object of Media, a Channel instantiates and provides a wrapper around a Player object and ties the Player and Media together. The Channel's public methods may be called to interact with the media playback, which protects the rest of the application from changes in the Player object.

A PLAYER is an object directly responsible for feeding audio streams to the system audio processor. In the current version of Synthea (0.1.0), a Player is an instance of a Howl object from the Howler.js library. All interaction with a Player is handled through the Channel, and as such the Player is never exposed directly to the rest of the application.

A MEDIA object is the argument passed to trigger the queuing and/or playback of audio on the board. The only point of convergence between the Sound Board and the UI Board, a Media object is a Cue object. While the names could be used interchangeably, using the word 'Media' helps to identify the Cue's specific use when bound to a Channel and Player (as opposed to any arbitrary Cue in the Project). The word 'Media' also helps to mitigate homonymic confusion when referring to cues queuing or a list of queued cues.

Clone this wiki locally