Host Interfaces

Detailed Description

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 Documentation

◆ ARA::Host::AudioAccessControllerInterface

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

Member Function Documentation

◆ createAudioReaderForSource()

virtual ARAAudioReaderHostRef ARA::Host::AudioAccessControllerInterface::createAudioReaderForSource ( ARAAudioSourceHostRef  audioSourceHostRef,
bool  use64BitSamples 
)
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.

◆ destroyAudioReader()

virtual void ARA::Host::AudioAccessControllerInterface::destroyAudioReader ( ARAAudioReaderHostRef  audioReaderHostRef)
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.

◆ readAudioSamples()

virtual bool ARA::Host::AudioAccessControllerInterface::readAudioSamples ( ARAAudioReaderHostRef  audioReaderHostRef,
ARASamplePosition  samplePosition,
ARASampleCount  samplesPerChannel,
void *const  buffers[] 
)
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.

◆ ARA::Host::ArchivingControllerInterface

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

Member Function Documentation

◆ getArchiveSize()

virtual ARASize ARA::Host::ArchivingControllerInterface::getArchiveSize ( ARAArchiveReaderHostRef  archiveReaderHostRef)
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).

◆ getDocumentArchiveID()

virtual ARAPersistentID ARA::Host::ArchivingControllerInterface::getDocumentArchiveID ( ARAArchiveReaderHostRef  archiveReaderHostRef)
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.

◆ notifyDocumentArchivingProgress()

virtual void ARA::Host::ArchivingControllerInterface::notifyDocumentArchivingProgress ( float  value)
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%.

◆ notifyDocumentUnarchivingProgress()

virtual void ARA::Host::ArchivingControllerInterface::notifyDocumentUnarchivingProgress ( float  value)
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%.

◆ readBytesFromArchive()

virtual bool ARA::Host::ArchivingControllerInterface::readBytesFromArchive ( ARAArchiveReaderHostRef  archiveReaderHostRef,
ARASize  position,
ARASize  length,
ARAByte  buffer[] 
)
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.

◆ writeBytesToArchive()

virtual bool ARA::Host::ArchivingControllerInterface::writeBytesToArchive ( ARAArchiveWriterHostRef  archiveWriterHostRef,
ARASize  position,
ARASize  length,
const ARAByte  buffer[] 
)
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.

◆ ARA::Host::ContentAccessControllerInterface

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

Member Function Documentation

◆ createAudioSourceContentReader()

virtual ARAContentReaderHostRef ARA::Host::ContentAccessControllerInterface::createAudioSourceContentReader ( ARAAudioSourceHostRef  audioSourceHostRef,
ARAContentType  type,
const ARAContentTimeRange *  range 
)
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.

◆ createMusicalContextContentReader()

virtual ARAContentReaderHostRef ARA::Host::ContentAccessControllerInterface::createMusicalContextContentReader ( ARAMusicalContextHostRef  musicalContextHostRef,
ARAContentType  type,
const ARAContentTimeRange *  range 
)
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.

◆ destroyContentReader()

virtual void ARA::Host::ContentAccessControllerInterface::destroyContentReader ( ARAContentReaderHostRef  contentReaderHostRef)
pure virtualnoexcept

Destroy the given content reader.

◆ getAudioSourceContentGrade()

virtual ARAContentGrade ARA::Host::ContentAccessControllerInterface::getAudioSourceContentGrade ( ARAAudioSourceHostRef  audioSourceHostRef,
ARAContentType  type 
)
pure virtualnoexcept

Query the current quality of the information provided for the given audio source and content type.

◆ getContentReaderDataForEvent()

virtual const void* ARA::Host::ContentAccessControllerInterface::getContentReaderDataForEvent ( ARAContentReaderHostRef  contentReaderHostRef,
ARAInt32  eventIndex 
)
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.

◆ getContentReaderEventCount()

virtual ARAInt32 ARA::Host::ContentAccessControllerInterface::getContentReaderEventCount ( ARAContentReaderHostRef  contentReaderHostRef)
pure virtualnoexcept

Query how many events the given reader exposes.

◆ getMusicalContextContentGrade()

virtual ARAContentGrade ARA::Host::ContentAccessControllerInterface::getMusicalContextContentGrade ( ARAMusicalContextHostRef  musicalContextHostRef,
ARAContentType  type 
)
pure virtualnoexcept

Query the current quality of the information provided for the given musical context and content type.

◆ isAudioSourceContentAvailable()

virtual bool ARA::Host::ContentAccessControllerInterface::isAudioSourceContentAvailable ( ARAAudioSourceHostRef  audioSourceHostRef,
ARAContentType  type 
)
pure virtualnoexcept

Query whether the given content type is currently available for the given audio source.

◆ isMusicalContextContentAvailable()

virtual bool ARA::Host::ContentAccessControllerInterface::isMusicalContextContentAvailable ( ARAMusicalContextHostRef  musicalContextHostRef,
ARAContentType  type 
)
pure virtualnoexcept

Query whether the given content type is currently available for the given musical context.

◆ ARA::Host::ModelUpdateControllerInterface

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

Member Function Documentation

◆ notifyAudioModificationContentChanged()

virtual void ARA::Host::ModelUpdateControllerInterface::notifyAudioModificationContentChanged ( ARAAudioModificationHostRef  audioModificationHostRef,
const ARAContentTimeRange *  range,
ContentUpdateScopes  scopeFlags 
)
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).

◆ notifyAudioSourceAnalysisProgress()

virtual void ARA::Host::ModelUpdateControllerInterface::notifyAudioSourceAnalysisProgress ( ARAAudioSourceHostRef  audioSourceHostRef,
ARAAnalysisProgressState  state,
float  value 
)
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.

◆ notifyAudioSourceContentChanged()

virtual void ARA::Host::ModelUpdateControllerInterface::notifyAudioSourceContentChanged ( ARAAudioSourceHostRef  audioSourceHostRef,
const ARAContentTimeRange *  range,
ContentUpdateScopes  scopeFlags 
)
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).

◆ notifyPlaybackRegionContentChanged()

virtual void ARA::Host::ModelUpdateControllerInterface::notifyPlaybackRegionContentChanged ( ARAPlaybackRegionHostRef  playbackRegionHostRef,
const ARAContentTimeRange *  range,
ContentUpdateScopes  scopeFlags 
)
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.

◆ ARA::Host::PlaybackControllerInterface

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

Member Function Documentation

◆ requestEnableCycle()

virtual void ARA::Host::PlaybackControllerInterface::requestEnableCycle ( bool  enable)
pure virtualnoexcept

Message to the host to enable or disable the playback cycle of our document.

◆ requestSetCycleRange()

virtual void ARA::Host::PlaybackControllerInterface::requestSetCycleRange ( ARATimePosition  startTime,
ARATimeDuration  duration 
)
pure virtualnoexcept

Message to the host to set the playback cycle range of our document.

◆ requestSetPlaybackPosition()

virtual void ARA::Host::PlaybackControllerInterface::requestSetPlaybackPosition ( ARATimePosition  timePosition)
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.

◆ requestStartPlayback()

virtual void ARA::Host::PlaybackControllerInterface::requestStartPlayback ( )
pure virtualnoexcept

Message to the host to start playback of our document.

◆ requestStopPlayback()

virtual void ARA::Host::PlaybackControllerInterface::requestStopPlayback ( )
pure virtualnoexcept

Message to the host to stop playback of our document.

◆ ARA::Host::DocumentControllerHostInstance

class ARA::Host::DocumentControllerHostInstance

Wrapper class for the ARADocumentControllerHostInstance.

Inheritance diagram for ARA::Host::DocumentControllerHostInstance:
ARA::SizedStruct< ARA_STRUCT_MEMBER(ARADocumentControllerHostInstance, playbackControllerInterface)>