Audio Source

Detailed Description

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.

Classes

struct  ARAAudioSourceProperties
 Audio source 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 ARAAudioSourceRefMarkupType * ARAAudioSourceRef
 Reference to the plug-in side representation of an audio source (opaque to the host).
 
typedef struct ARAAudioSourceHostRefMarkupType * ARAAudioSourceHostRef
 Reference to the host side representation of an audio source (opaque to the plug-in).
 

Class Documentation

◆ ARAAudioSourceProperties

struct ARAAudioSourceProperties

Audio source 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.
 
ARAUtf8String name
 User-readable name of the audio source 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 source. In that case, the host should not make up some dummy name just to satisfy the API, 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.
 
ARAPersistentID persistentID
 ID used to re-connect model graph when archiving/unarchiving. This ID must be unique for all audio sources within the document. The plug-in must copy the persistentID, the pointer may be only valid for the duration of the call.
 
ARASampleCount sampleCount
 Total number of samples per channel of the contained audio material. May only be changed while access to the audio source is disabled, see ARADocumentControllerInterface::enableAudioSourceSamplesAccess().
 
ARASampleRate sampleRate
 Sample rate of the contained audio material. May only be changed while access to the audio source is disabled, see ARADocumentControllerInterface::enableAudioSourceSamplesAccess(). Note that the sample rate of the audio source may not match the sample rate(s) used in the companion plug-in instances that render playback regions based on this audio source - plug-ins must apply sample rate conversion as needed. However, if the sample rate is changed, plug-ins are not required to translate their model to the new sample rate, and may instead restart with a fresh analysis, causing all user edits applied at the previous sample rate to be lost.
 
ARAChannelCount channelCount
 Count of discrete channels of the contained audio material. May only be changed while access to the audio source is disabled, see ARADocumentControllerInterface::enableAudioSourceSamplesAccess(). As with sample rate changes, plug-ins may discard all edits and start with a fresh analysis if the channel count is changed.
 
ARABool merits64BitSamples
 Flag to indicating that the data is available in a resolution that cannot be represented in 32 bit float samples without losing quality. Depending on its internal algorithms, the plug-in may or may not base its decision to read either 32 or 64 bit samples on this flag, see ARAAudioAccessControllerInterface::createAudioReaderForSource().
 
ARAChannelArrangementDataType channelArrangementDataType
 Type information of the data the opaque channelArrangement actually points to. Host shall use the data type associated with the Companion API that was used to create the respective document controller.
 
const void * channelArrangement
 Spacial arrangement information: defines which channel carries the signal from which direction. The data type that this pointer references is defined by channelArrangementDataType, see ARAChannelArrangementDataType.
If channelCount not larger than 2 (i.e. mono or stereo), this information may omitted by setting channelArrangementDataType to kARAChannelArrangementUndefined and channelArrangement to NULL. The behavior is then the same as in hosts that do not support surround for ARA: for stereo, channel 0 is the left and channel 1 the right speaker.
To determine which channel arrangements are supported by the plug-in, the host will use the Companion API and read the valid render input formats.