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