Interfaces to be implemented by ARA hosts.
Classes | |
| class | ARA::Host::AudioAccessControllerInterface |
| Base class for implementing ARAAudioAccessControllerInterface. More... | |
| class | ARA::Host::ArchivingControllerInterface |
| Base class for implementing ARAArchivingControllerInterface. More... | |
| class | ARA::Host::ContentAccessControllerInterface |
| Base class for implementing ARAContentAccessControllerInterface. More... | |
| class | ARA::Host::ModelUpdateControllerInterface |
| Base class for implementing ARAModelUpdateControllerInterface. More... | |
| class | ARA::Host::PlaybackControllerInterface |
| Base class for implementing ARAPlaybackControllerInterface. More... | |
| class | ARA::Host::DocumentControllerHostInstance |
| Wrapper class for the ARADocumentControllerHostInstance. More... | |
| class ARA::Host::AudioAccessControllerInterface |
Base class for implementing ARAAudioAccessControllerInterface.
Public Member Functions | |
| virtual ARAAudioReaderHostRef | createAudioReaderForSource (ARAAudioSourceHostRef audioSourceHostRef, bool use64BitSamples) noexcept=0 |
| 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. More... | |
| virtual bool | readAudioSamples (ARAAudioReaderHostRef audioReaderHostRef, ARASamplePosition samplePosition, ARASampleCount samplesPerChannel, void *const buffers[]) noexcept=0 |
| 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. More... | |
| virtual void | destroyAudioReader (ARAAudioReaderHostRef audioReaderHostRef) noexcept=0 |
| 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. More... | |
|
pure virtualnoexcept |
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.
|
pure virtualnoexcept |
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.
|
pure virtualnoexcept |
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.
| class ARA::Host::ArchivingControllerInterface |
Base class for implementing ARAArchivingControllerInterface.
Public Member Functions | |
| virtual ARASize | getArchiveSize (ARAArchiveReaderHostRef archiveReaderHostRef) noexcept=0 |
| Query the size of the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. Plug-ins must respect this size when reading the archive, reading beyond the end of the data is a programming error (and should thus be asserted by the host). More... | |
| virtual bool | readBytesFromArchive (ARAArchiveReaderHostRef archiveReaderHostRef, ARASize position, ARASize length, ARAByte buffer[]) noexcept=0 |
| Read bytes. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. 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 host must notify the user about the problem in some appropriate way. The archive will not be restored by the plug-in then, it'll fall back into some proper initial state for the affected objects. More... | |
| virtual bool | writeBytesToArchive (ARAArchiveWriterHostRef archiveWriterHostRef, ARASize position, ARASize length, const ARAByte buffer[]) noexcept=0 |
| Write bytes. This may only be called from storeObjectsToArchive() or the deprecated storeDocumentToArchive(). 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 written to a server. In case of failing in this call, the host must notify the user about the problem in an appropriate way. Note that a plug-in should strive to write the data consecutively in a stream-like manner. Nevertheless, repositioning is needed to support chunk-style archives where the chunk length must be specified at the start of the chunk, but is not known until the chunk data has been fully created (and possibly compressed). In that case, the plug-in will need to "rewind" to the chunk size entry in the chunk header after writing the chunk and update it accordingly. As in most file APIs, any range of bytes that was skipped when writing should be filled with 0 by the host. More... | |
| virtual void | notifyDocumentArchivingProgress (float value) noexcept=0 |
| Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from storeObjectsToArchive() or from the deprecated storeDocumentToArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%. More... | |
| virtual void | notifyDocumentUnarchivingProgress (float value) noexcept=0 |
| Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() and the associated model object creation/update calls guarded by them. In the deprecated form, the first call should be made from begin- and the last call from endRestoringDocumentFromArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%. More... | |
| virtual ARAPersistentID | getDocumentArchiveID (ARAArchiveReaderHostRef archiveReaderHostRef) noexcept=0 |
| Query the document archive ID that the plug-in's factory provided when saving the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(). Plug-ins can use this information to optimize their unarchiving code in case different archive formats are used depending on document archive ID. The returned pointer is owned by the host and must remain valid until the archive reader is destroyed. All hosts that support kARAAPIGeneration_2_0_Final or newer must implement this call. More... | |
|
pure virtualnoexcept |
Query the size of the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. Plug-ins must respect this size when reading the archive, reading beyond the end of the data is a programming error (and should thus be asserted by the host).
|
pure virtualnoexcept |
Query the document archive ID that the plug-in's factory provided when saving the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(). Plug-ins can use this information to optimize their unarchiving code in case different archive formats are used depending on document archive ID. The returned pointer is owned by the host and must remain valid until the archive reader is destroyed. All hosts that support kARAAPIGeneration_2_0_Final or newer must implement this call.
|
pure virtualnoexcept |
Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from storeObjectsToArchive() or from the deprecated storeDocumentToArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%.
|
pure virtualnoexcept |
Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() and the associated model object creation/update calls guarded by them. In the deprecated form, the first call should be made from begin- and the last call from endRestoringDocumentFromArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%.
|
pure virtualnoexcept |
Read bytes. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. 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 host must notify the user about the problem in some appropriate way. The archive will not be restored by the plug-in then, it'll fall back into some proper initial state for the affected objects.
|
pure virtualnoexcept |
Write bytes. This may only be called from storeObjectsToArchive() or the deprecated storeDocumentToArchive(). 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 written to a server. In case of failing in this call, the host must notify the user about the problem in an appropriate way.
Note that a plug-in should strive to write the data consecutively in a stream-like manner. Nevertheless, repositioning is needed to support chunk-style archives where the chunk length must be specified at the start of the chunk, but is not known until the chunk data has been fully created (and possibly compressed). In that case, the plug-in will need to "rewind" to the chunk size entry in the chunk header after writing the chunk and update it accordingly. As in most file APIs, any range of bytes that was skipped when writing should be filled with 0 by the host.
| class ARA::Host::ContentAccessControllerInterface |
Base class for implementing ARAContentAccessControllerInterface.
Public Member Functions | |
| virtual bool | isMusicalContextContentAvailable (ARAMusicalContextHostRef musicalContextHostRef, ARAContentType type) noexcept=0 |
| Query whether the given content type is currently available for the given musical context. More... | |
| virtual ARAContentGrade | getMusicalContextContentGrade (ARAMusicalContextHostRef musicalContextHostRef, ARAContentType type) noexcept=0 |
| Query the current quality of the information provided for the given musical context and content type. More... | |
| virtual ARAContentReaderHostRef | createMusicalContextContentReader (ARAMusicalContextHostRef musicalContextHostRef, ARAContentType type, const ARAContentTimeRange *range) noexcept=0 |
| Create a content reader for the given musical context and content type. This should only be called after availability has been confirmed using isMusicalContextContentAvailable(), and is mainly used to communicate the song timeline to the plug-in. The time range may be NULL, which means that the entire musical context shall be read. If a time range is specified, all events that at least partially intersect with the range will be read. More... | |
| virtual bool | isAudioSourceContentAvailable (ARAAudioSourceHostRef audioSourceHostRef, ARAContentType type) noexcept=0 |
| Query whether the given content type is currently available for the given audio source. More... | |
| virtual ARAContentGrade | getAudioSourceContentGrade (ARAAudioSourceHostRef audioSourceHostRef, ARAContentType type) noexcept=0 |
| Query the current quality of the information provided for the given audio source and content type. More... | |
| virtual ARAContentReaderHostRef | createAudioSourceContentReader (ARAAudioSourceHostRef audioSourceHostRef, ARAContentType type, const ARAContentTimeRange *range) noexcept=0 |
| Create a content reader for the given audio source and content type. This should only be called after availability has been confirmed using isAudioSourceContentAvailable(). The host may be able to provide meta-information such as a known tempo or a known set of notes used in the material, which may enable the plug-in to speed up or even skip completely certain analysis passes (often depending on the content grade of the information). The time range may be NULL, which means that the entire audio source shall be read. If a time range is specified, all events that at least partially intersect with the range will be read. More... | |
| virtual ARAInt32 | getContentReaderEventCount (ARAContentReaderHostRef contentReaderHostRef) noexcept=0 |
| Query how many events the given reader exposes. More... | |
| virtual const void * | getContentReaderDataForEvent (ARAContentReaderHostRef contentReaderHostRef, ARAInt32 eventIndex) noexcept=0 |
| Query data of the given event of the given reader. The returned pointer is owned by the host and must remain valid until either getContentReaderDataForEvent() is called again or the content reader is destroyed. More... | |
| virtual void | destroyContentReader (ARAContentReaderHostRef contentReaderHostRef) noexcept=0 |
| Destroy the given content reader. More... | |
|
pure virtualnoexcept |
Create a content reader for the given audio source and content type. This should only be called after availability has been confirmed using isAudioSourceContentAvailable(). The host may be able to provide meta-information such as a known tempo or a known set of notes used in the material, which may enable the plug-in to speed up or even skip completely certain analysis passes (often depending on the content grade of the information). The time range may be NULL, which means that the entire audio source shall be read. If a time range is specified, all events that at least partially intersect with the range will be read.
|
pure virtualnoexcept |
Create a content reader for the given musical context and content type. This should only be called after availability has been confirmed using isMusicalContextContentAvailable(), and is mainly used to communicate the song timeline to the plug-in. The time range may be NULL, which means that the entire musical context shall be read. If a time range is specified, all events that at least partially intersect with the range will be read.
|
pure virtualnoexcept |
Destroy the given content reader.
|
pure virtualnoexcept |
Query the current quality of the information provided for the given audio source and content type.
|
pure virtualnoexcept |
Query data of the given event of the given reader. The returned pointer is owned by the host and must remain valid until either getContentReaderDataForEvent() is called again or the content reader is destroyed.
|
pure virtualnoexcept |
Query how many events the given reader exposes.
|
pure virtualnoexcept |
Query the current quality of the information provided for the given musical context and content type.
|
pure virtualnoexcept |
Query whether the given content type is currently available for the given audio source.
|
pure virtualnoexcept |
Query whether the given content type is currently available for the given musical context.
| class ARA::Host::ModelUpdateControllerInterface |
Base class for implementing ARAModelUpdateControllerInterface.
Public Member Functions | |
| virtual void | notifyAudioSourceAnalysisProgress (ARAAudioSourceHostRef audioSourceHostRef, ARAAnalysisProgressState state, float value) noexcept=0 |
| Message to the host signaling analysis progress, value ranges from 0.0f to 1.0f. The first message must be marked with kARAAnalysisProgressStarted, the last with kARAAnalysisProgressCompleted. This notification is intended solely for displaying a progress indication if desired, but not to trigger content reading for updating content information. That is instead done when receiving notifyAudioSourceContentChanged(), see below. Note that since the updates are polled by the host, any analysis may already have progressed somewhat by the time the start notification is actually delivered, so it may start with a progress larger than 0. It is even possible that an analysis fully completes before its start is notified, in which case the plug-in may choose not notify it at all. If the plug-in internally executes multiple analysis task per audio source simultaneously (for example because it splits them by content type), it must merge all internal progress into a single outer progress. More... | |
| virtual void | notifyAudioSourceContentChanged (ARAAudioSourceHostRef audioSourceHostRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Message to the host when content of the given audio source changes. Not to be called if the change was explicitly triggered by the host, e.g. when restoring audio source state or if the host calls ARADocumentControllerInterface::updateAudioSourceContent(). When restoring state, plug-ins shall only make this call if the object state after loading is not equal to the archived state. This can happen e.g when unarchiving encounters errors, or when state is imported from older versions and converted to some updated model state. The time range may be NULL, this means that the entire audio source is affected. Note that this notification is what hosts will listen to when determining whether the state returned by isAudioSourceContentAnalysisIncomplete() has changed. In other words, the completion state of the analysis itself is considered to be a part of the overall content. Thus, if it changes, the overall content has changed, even if neither the grade nor the data for content readers did change (e.g. because an analysis failed to provide proper results). More... | |
| virtual void | notifyAudioModificationContentChanged (ARAAudioModificationHostRef audioModificationHostRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Message to the host when content of the given audio modification changes. Not to be called if the change was explicitly triggered by the host, e.g. when restoring audio modification state. When restoring state, plug-ins will only make this call if the object state after loading is not equal to the archived state. This can happen e.g when unarchiving encounters errors, or when state is imported from older versions and converted to some updated model state. The time range may be NULL, this means that the entire audio modification is affected. Whenever this notification is received, all playback regions for the given modification are affected as well if their range in modification time intersects with the given time range. Because of this, there was no separate change notification for playback region in ARA 1. This changed with the introduction of content-based fades in ARA 2.0, because playback region content can now change without any audio modification changes. For many use cases, hosts that implement ARA 2 do no longer concern themselves with this call (unless they are also hosting ARA 1 plug-ins and implement an according ARA 2 adapter). More... | |
| virtual void | notifyPlaybackRegionContentChanged (ARAPlaybackRegionHostRef playbackRegionHostRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Message to the host when content of the given playback region changes (added in ARA 2.0). In ARA 1, region content updates were implicitly derived from audio modification updates, (see notifyAudioModificationContentChanged()), based on the assumption that the content of a playback region did depend only on the modification content and the transformation described in the playback region properties. Since ARA 2.0 however, plug-ins use the grouping provided by the region sequences to derive further parameters for the transformation, which enables them to perform content based fades or other custom adjustments. This means the content of any given region can change even if its modification and region properties remain unchanged, and that the host can no longer calculate the content of a region based on the content of its modification. Note that when kARAContentUpdateSignalScopeRemainsUnchanged is not set, this message also indicates that the host needs to update any cached copies of the rendered signal it may hold, and needs to query getPlaybackRegionHeadAndTailTime() for potential updates. The time range is specified in playback time and potentially covers head and tail time too. The time range may be NULL, this means that the entire playback region (including its head and tail time, which may be updated at the same time) is affected. More... | |
|
pure virtualnoexcept |
Message to the host when content of the given audio modification changes. Not to be called if the change was explicitly triggered by the host, e.g. when restoring audio modification state. When restoring state, plug-ins will only make this call if the object state after loading is not equal to the archived state. This can happen e.g when unarchiving encounters errors, or when state is imported from older versions and converted to some updated model state. The time range may be NULL, this means that the entire audio modification is affected. Whenever this notification is received, all playback regions for the given modification are affected as well if their range in modification time intersects with the given time range. Because of this, there was no separate change notification for playback region in ARA 1. This changed with the introduction of content-based fades in ARA 2.0, because playback region content can now change without any audio modification changes. For many use cases, hosts that implement ARA 2 do no longer concern themselves with this call (unless they are also hosting ARA 1 plug-ins and implement an according ARA 2 adapter).
|
pure virtualnoexcept |
Message to the host signaling analysis progress, value ranges from 0.0f to 1.0f. The first message must be marked with kARAAnalysisProgressStarted, the last with kARAAnalysisProgressCompleted. This notification is intended solely for displaying a progress indication if desired, but not to trigger content reading for updating content information. That is instead done when receiving notifyAudioSourceContentChanged(), see below. Note that since the updates are polled by the host, any analysis may already have progressed somewhat by the time the start notification is actually delivered, so it may start with a progress larger than 0. It is even possible that an analysis fully completes before its start is notified, in which case the plug-in may choose not notify it at all. If the plug-in internally executes multiple analysis task per audio source simultaneously (for example because it splits them by content type), it must merge all internal progress into a single outer progress.
|
pure virtualnoexcept |
Message to the host when content of the given audio source changes. Not to be called if the change was explicitly triggered by the host, e.g. when restoring audio source state or if the host calls ARADocumentControllerInterface::updateAudioSourceContent(). When restoring state, plug-ins shall only make this call if the object state after loading is not equal to the archived state. This can happen e.g when unarchiving encounters errors, or when state is imported from older versions and converted to some updated model state. The time range may be NULL, this means that the entire audio source is affected. Note that this notification is what hosts will listen to when determining whether the state returned by isAudioSourceContentAnalysisIncomplete() has changed. In other words, the completion state of the analysis itself is considered to be a part of the overall content. Thus, if it changes, the overall content has changed, even if neither the grade nor the data for content readers did change (e.g. because an analysis failed to provide proper results).
|
pure virtualnoexcept |
Message to the host when content of the given playback region changes (added in ARA 2.0). In ARA 1, region content updates were implicitly derived from audio modification updates, (see notifyAudioModificationContentChanged()), based on the assumption that the content of a playback region did depend only on the modification content and the transformation described in the playback region properties. Since ARA 2.0 however, plug-ins use the grouping provided by the region sequences to derive further parameters for the transformation, which enables them to perform content based fades or other custom adjustments. This means the content of any given region can change even if its modification and region properties remain unchanged, and that the host can no longer calculate the content of a region based on the content of its modification. Note that when kARAContentUpdateSignalScopeRemainsUnchanged is not set, this message also indicates that the host needs to update any cached copies of the rendered signal it may hold, and needs to query getPlaybackRegionHeadAndTailTime() for potential updates. The time range is specified in playback time and potentially covers head and tail time too. The time range may be NULL, this means that the entire playback region (including its head and tail time, which may be updated at the same time) is affected.
| class ARA::Host::PlaybackControllerInterface |
Base class for implementing ARAPlaybackControllerInterface.
Public Member Functions | |
| virtual void | requestStartPlayback () noexcept=0 |
| Message to the host to start playback of our document. More... | |
| virtual void | requestStopPlayback () noexcept=0 |
| Message to the host to stop playback of our document. More... | |
| virtual void | requestSetPlaybackPosition (ARATimePosition timePosition) noexcept=0 |
| Message to the host to set the playback position of our document. Note that this may be called both when playing back or when stopped. More... | |
| virtual void | requestSetCycleRange (ARATimePosition startTime, ARATimeDuration duration) noexcept=0 |
| Message to the host to set the playback cycle range of our document. More... | |
| virtual void | requestEnableCycle (bool enable) noexcept=0 |
| Message to the host to enable or disable the playback cycle of our document. More... | |
|
pure virtualnoexcept |
Message to the host to enable or disable the playback cycle of our document.
|
pure virtualnoexcept |
Message to the host to set the playback cycle range of our document.
|
pure virtualnoexcept |
Message to the host to set the playback position of our document. Note that this may be called both when playing back or when stopped.
|
pure virtualnoexcept |
Message to the host to start playback of our document.
|
pure virtualnoexcept |
Message to the host to stop playback of our document.
| class ARA::Host::DocumentControllerHostInstance |
Wrapper class for the ARADocumentControllerHostInstance.