Playback Region

Detailed Description

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).
 

Class Documentation

◆ ARAPlaybackRegionProperties

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.
 

Enumeration Type Documentation

◆ ARAPlaybackTransformationFlags

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 

see kARAPlaybackTransformationContentBasedFades

kARAPlaybackTransformationContentBasedFadeAtHead 

see kARAPlaybackTransformationContentBasedFades

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.