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.
Classes | |
| struct | ARAPlaybackRegionProperties |
| Playback region properties. Note that like all properties, a pointer to this struct is only valid for the duration of the call receiving the pointer - the data must be evaluated/copied inside the call, and the pointer must not be stored anywhere. More... | |
Typedefs | |
| typedef struct ARAPlaybackRegionRefMarkupType * | ARAPlaybackRegionRef |
| Reference to the plug-in side representation of a playback region (opaque to the host). | |
| typedef struct ARAPlaybackRegionHostRefMarkupType * | ARAPlaybackRegionHostRef |
| Reference to the host side representation of a playback region (opaque to the plug-in). | |
| struct ARAPlaybackRegionProperties |
Playback region properties. Note that like all properties, a pointer to this struct is only valid for the duration of the call receiving the pointer - the data must be evaluated/copied inside the call, and the pointer must not be stored anywhere.
Public Attributes | |
| ARASize | structSize |
| Size-based struct versioning - see Versioned structs. | |
| ARAPlaybackTransformationFlags | transformationFlags |
| Configuration of possible transformations upon playback, i.e. time-stretching etc. The host may only enable flags that are listed in ARAFactory::supportedPlaybackTransformationFlags. | |
| ARATimePosition | startInModificationTime |
| startInModificationTime and durationInModificationTime define the audible audio modification time range. This section of the modification's audio data will be mapped to the song playback time range defined below as configured by the transformationFlags, including optional time stretching. See Manipulating The Timing for more information. | |
| ARATimeDuration | durationInModificationTime |
| See startInModificationTime. Plug-ins must deal with durationInModificationTime being 0.0. | |
| ARATimePosition | startInPlaybackTime |
| startInPlaybackTime and durationInPlaybackTime define the relationship between the audible modification time range and the song playback time in seconds as communicated via the companion API. Musical context content (such as kARAContentTypeTempoEntries) is also expressed in song playback time. | |
| ARATimeDuration | durationInPlaybackTime |
| See startInPlaybackTime. Plug-ins must deal with durationInPlaybackTime being 0.0. | |
| ARAMusicalContextRef | musicalContextRef |
| Musical context in which the playback region will be edited and rendered. Note that when rendering the playback region via any plug-in instance, the time information provided for this plug-in through the companion API must match this musical context. Deprecated No longer used since adding region sequences in ARA 2.0, which already define the musical context for all their respective regions. If structSize indicates that a sequence is used (i.e. when using ARA 2.0 or higher), this field must be ignored by plug-ins. Hosts are free to additionally set a valid musical context if desired for ARA 1 backwards compatibility, or leave the field uninitialized otherwise. | |
| ARARegionSequenceRef | regionSequenceRef |
| Region sequence with which the playback region is associated in the host. | |
| ARAUtf8String | name |
| User-readable name of the playback region as displayed in the host. The plug-in must copy the name, the pointer may be only valid for the duration of the call. It may be NULL if the host cannot provide a name for the audio modification. In that case, the host should not make up some name (e.g. derived from the audio source), but rather let the plug-in do this if desired - this way it can distinguish between a proper name visible somewhere in the host and a dummy name implicitly derived from other state. | |
| const ARAColor * | color |
| Color associated with the playback region in the host. The plug-in must copy the color, the pointer may be only valid for the duration of the call. It may be NULL if the host cannot provide a color for the playback region. In that case, the host should not make up some color (e.g. derived from the track color), but rather let the plug-in do this if desired - this way it can distinguish between a proper color visible somewhere in the host and a dummy color implicitly derived from other state. | |
Playback region transformations. Plug-ins may or may not support all transformations that can be configured in a playback region. They express these capabilities at factory level, and the host must respect this. Also used in ARAFactory::supportedPlaybackTransformationFlags.
| Enumerator | |
|---|---|
| kARAPlaybackTransformationNoChanges | Named constant if no flags are set. If no flags are set, the modification is played back "as is", without further adoption to the given playback situation. |
| kARAPlaybackTransformationTimestretch | Time-stretching enable flag. If time-stretching is supported by the plug-in, the host can use this flag to enable it. If disabled, the host must always specify the same duration in modification and playback time, and the plug-in should ignore ARAPlaybackRegionProperties::durationInModificationTime. |
| kARAPlaybackTransformationTimestretchReflectingTempo | Time-stretching tempo configuration flag. If kARAPlaybackTransformationTimestretch is set, this flag allows to distinguish whether the stretching shall be done in a strictly linear fashion (flag is off) or whether it shall reflect the tempo relationship between the musical context and the content of the audio modification (flag is on). |
| kARAPlaybackTransformationContentBasedFadeAtTail | |
| kARAPlaybackTransformationContentBasedFadeAtHead | |
| kARAPlaybackTransformationContentBasedFades | Content-based fades enabling flags. These flags are used to enable smart, content-based fades at either end of the playback region. If supported by the plug-in, the host no longer needs to apply its regular overall fades at region borders, but can instead delegate this functionality to the plug-in. Based on the region sequence grouping, the plug-in can determine neighboring regions and utilize head and tail time to calculate a smart, musical transition. Even when no neighboring region is found, it may be appropriate to fade in or out to avoid cutting off signals abruptly. Note that while the transformation of a playback region can be defined separately for each border of the region, it must be enabled for either both or neither border in the ARAFactory::supportedPlaybackTransformationFlags. |