Subpages | |
| Document | |
| The document is the root object for a model graph and typically represents a piece of music such as a song or an entire performance. It is bound to a document controller in a 1:1 relationship. The document controller is used to manage the entire graph it contains. Because of the 1:1 relationship, the document is never specified when calling into the document controller. Edits of the document and any of the objects it contains are done in cycles started with ARADocumentControllerInterface::beginEditing() and concluded with ARADocumentControllerInterface::endEditing(). This allows plug-ins to deal with any render thread synchronization that may be necessary, as well as postponing any internal updates until the end of the cycle when the ARA graph has its full state available. A document is the root object for persistency and is the owner of any amount of associated audio sources, region sequences and musical contexts. Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::Document class. | |
| Musical Context | |
| A musical context describes both rhythmical concepts of the music such as bars and beats and their distribution over time, as well as harmonic structures and their distribution over time. A musical context is always owned by one document. Musical contexts are not persistent when storing documents, instead the host re-creates them as needed. Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::MusicalContext class. | |
| Region Sequences (Added In ARA 2.0) | |
| Region sequences allow hosts to group playback regions, typically by "tracks" or "lanes" in their arrangement. Each sequence is associated with a musical context, and all regions in a sequence will be adapted to that same context. Further, all regions within a sequence are expected to play back through the same routing (incl. same latency), typically the same "mixer track" or "audio channel". Regions in a sequence can overlap, and such overlapping regions will sound concurrently. A region sequence is always owned by one document, and refers to a musical context. Region sequences are not persistent when storing documents, instead the host re-creates them as needed. Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::RegionSequence class. | |
| Audio Source | |
| An audio source represents a continuous sequence of sampled audio data. Typically a host will create an audio source object for each audio file used with ARA plug-ins. Conceptually, the contents of an audio source are immutable (even though updates are possible, this is an expensive process, and user edits based on the modified content may get lost). An audio source is always owned by one document, and in turn owns any amount of associated audio modifications. Audio sources are persistent when storing documents. Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::AudioSource class. | |
| Audio Modification | |
| An audio modification contains a set of musical edits that the user has made to transform the content of an audio source when rendered by the ARA plug-in. An audio modification is always owned by one audio source, and in turn owns any amount of associated playback regions. Audio modifications are persistent when storing documents. Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::AudioModification class. | |
| Playback Region | |
| A playback region is a reference to an arbitrary time section of an audio modification, mapped to a certain section of playback time. It is linked to a region sequence, which in turn is linked to a musical context. All playback regions that share the same audio modification play back the same musical content, but may adapt that content to the given section of the musical context and to the content of other regions in the same region sequence (see content based fades). Note that if a plug-in offers any user settings to control this adaptation (such as groove settings), then these settings should be part of the audio modification state, not of the individual playback regions. A playback is always owned by one audio modification, and refers to a region sequence. Playback regions are not persistent when storing documents, instead the host re-creates them as needed. Plug-in developers using the C++ ARA Library can use the ARA::PlugIn::PlaybackRegion class. | |