This interface allows plug-ins to read the audio data from the host in a random access order. It is used from multiple threads, both host and plug-in need to carefully observe the threading rules for each function. The basic design idea is that each audio reader is used single-threaded, but multiple audio readers can work concurrently (even on the same audio source). Audio readers can be considered random access iterators, and like most iterators operate on conceptually constant data structures. If the host changes sample rate, channel count or other audio source properties that the reader relies upon, the plug-in must discard any existing audio readers for the source and later re-create them based on the new configuration. The host can temporarily disable access to the audio source in order to control the exact timing of stopping the readers from accessing the source. Whenever an audio reader is destroyed, the plug-in is responsible for thread safety - it may need to block until a concurrent read operation on the I/O thread has finished. Hosts must take care in their audio reader implementation to avoid potential deadlocks in this situation. Note that when rendering, the audio source will often not be read in a consecutive order - depending on the edits the user applied at audio modification level, the access may jump back and forth quite often. The reader implementation should be optimized accordingly.
Host developer using C++ ARA Library can implement the ARA::Host::AudioAccessControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostAudioAccessController.
|
| struct | ARAAudioAccessControllerInterface |
| | Host interface: audio access controller. As with all host interfaces, the function pointers in this struct must remain valid until all document controllers on the plug-in side that use it have been destroyed. More...
|
| |
|
|
typedef struct ARAAudioAccessControllerHostRefMarkupType * | ARAAudioAccessControllerHostRef |
| | Reference to the host side representation of an audio access controller (opaque to the plug-in).
|
| |
|
typedef struct ARAAudioReaderHostRefMarkupType * | ARAAudioReaderHostRef |
| | Reference to the host side representation of an audio reader (opaque to the plug-in).
|
| |
◆ ARAAudioAccessControllerInterface
| struct ARAAudioAccessControllerInterface |
Host interface: audio access controller. As with all host interfaces, the function pointers in this struct must remain valid until all document controllers on the plug-in side that use it have been destroyed.
Size-based struct versioning |
See Versioned structs.
|
|
ARASize | structSize |
| |
Synchronous reading: blocking until data is available |
|
ARAAudioReaderHostRef(* | createAudioReaderForSource )(ARAAudioAccessControllerHostRef controllerHostRef, ARAAudioSourceHostRef audioSourceHostRef, ARABool use64BitSamples) |
| | Create audio reader instance to access sample data in an audio source. The format of the data is matching the format of the audio source, with a choice of reading samples as 32 bit or 64 bit (hosts must support both formats). Similar to the rules for creating content readers, the plug-in may call these functions only from calls in the "Audio Source Management" section of ARADocumentControllerInterface for the particular audio source the call is referring to, or from ARADocumentControllerInterface::endEditing() for any audio source. Contrary to content readers, audio readers are long-living objects that are not bound to a certain stack frame.
|
| |
|
ARABool(* | readAudioSamples )(ARAAudioAccessControllerHostRef controllerHostRef, ARAAudioReaderHostRef audioReaderHostRef, ARASamplePosition samplePosition, ARASampleCount samplesPerChannel, void *const buffers[]) |
| | Read audio samples. The samples are provided in non-interleaved buffers of double or float data, depending on whether use64BitSamples was set when creating the reader. The channel count equals the channel count of the audio source. The data alignment and byte order always matches the machine's native layout. If the requested sample range extends beyond the start or end of the audio source, the out-of-range samples should be filled with silence. This should not be treated as an error. This potentially blocking function may be called from any non-realtime thread (including threads for offline rendering), but not from more than one thread per reader at the same time. The host may decide to let the thread sleep until the requested data is available, the plug-in must be designed to deal with this without triggering priority inversion. The target buffer(s) are provided by the caller. Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being read from a server. In case of failing in this call, the buffers must be filled with silence and the host must notify the user about the problem in an appropriate way. The plug-in must deal gracefully with any such I/O errors, both during analysis and rendering.
|
| |
|
void(* | destroyAudioReader )(ARAAudioAccessControllerHostRef controllerHostRef, ARAAudioReaderHostRef audioReaderHostRef) |
| | Destroy given audio reader created by the host. The caller must guarantee that the reader is currently not in use in some other thread. See ARAAudioAccessControllerInterface::createAudioReaderForSource() about the restrictions when to call this.
|
| |