Plug-In Interfaces

Detailed Description

Interfaces to be implemented by ARA plug-ins.

Classes

class  ARA::PlugIn::DocumentControllerInterface
 Base class for implementing ARADocumentControllerInterface. More...
 
class  ARA::PlugIn::DocumentControllerInstance
 Wrapper class for the ARADocumentControllerInstance. More...
 
class  ARA::PlugIn::PlaybackRendererInterface
 Base class for implementing ARAPlaybackRendererInterface. More...
 
class  ARA::PlugIn::EditorRendererInterface
 Base class for implementing ARAEditorRendererInterface. More...
 
class  ARA::PlugIn::EditorViewInterface
 Base class for implementing ARAEditorViewInterface. More...
 
class  ARA::PlugIn::PlugInExtensionInstance
 Wrapper class for ARAPlugInExtensionInstance. More...
 

Class Documentation

◆ ARA::PlugIn::DocumentControllerInterface

class ARA::PlugIn::DocumentControllerInterface

Base class for implementing ARADocumentControllerInterface.

Inheritance diagram for ARA::PlugIn::DocumentControllerInterface:
ARA::PlugIn::DocumentController

Destruction

virtual void destroyDocumentController () noexcept=0
 Destroy the controller and its associated document. The host must delete all objects associated with the document graph (audio sources, musical contexts etc.) before making this call. Note that the objects exported via the ARAPlugInExtensionInstance are not considered part of the document graph, their destruction may happen before or after destroying the document controller that they are bound to. More...
 

Factory

Query the static ARA factory that was used to create this controller. This provides a convenient traversal to the name of the plug-in, the description of its capabilities, its archive IDs etc.

virtual const ARAFactory * getFactory () const noexcept=0
 

Update Management

virtual void beginEditing () noexcept=0
 Start an editing session on a document. An editing session can contain an arbitrary set of modifications that belong together. Since many model edits can result in rather expensive updates on the plug-in side, this call allows for grouping the edits and postponing the updates until the new model state is final, which potentially saves some intermediate updates. More...
 
virtual void endEditing () noexcept=0
 End an editing session on a document. Note that when receiving this call, the plug-in will update any amount of internal state. These edits may lead to update notifications to the host, and the host may in turn read affected content from the plug-in and update its own model accordingly. One example for this the way that Melodyne maintains chords and scales associated with audio modifications. It copies this data from the musical context into the audio modifications, so that when editing regions the notes appear in the proper pitch grid. If moving playback regions in the song, these copies may need to be updated, and Melodyne will report the resulting audio modification content changes to the host. To ensure that any such follow-up updates are added to the same undo cycle, hosts that actively read plug-in content data should immediately (i.e. within the same undo frame) call notifyModelUpdates() after making this call. More...
 
virtual void notifyModelUpdates () noexcept=0
 Tell the plug-in to send all pending update notifications for the given document. This must be called periodically by the host whenever not editing nor restoring the document. Only when processing this call, the plug-in may call back into the host using ARAModelUpdateControllerInterface. Hosts must be aware after receiving beginEditing(), plug-ins may choose to postpone any subset of their internal state updates until the matching call to endEditing(). This means that if the host for some reason needs to wait for a specific update in the plug-in to occur (such as waiting for an analysis to finish) it must do so outside of pairs of beginEditing() and endEditing(). More...
 

Archiving

virtual bool restoreObjectsFromArchive (ARAArchiveReaderHostRef archiveReaderHostRef, const ARARestoreObjectsFilter *filter) noexcept=0
 Unarchive the internal state of the specified objects. This call can be used both for unarchiving entire documents and for importing arbitrary objects into an existing document. An unarchiving session is conceptually identical to an editing session: after starting the session, the host rebuilds the graph using the regular object creation calls, then makes this call to let the plug-in parse the archive and inject the archived internal state into the graph as indicated by the persistentIDs of the relevant objects. Similarly, when importing objects, the host will perform an editing session and either create new objects or re-use existing objects (potentially adjusting their persistentID), then make this call to inject the imported state.
The optional filter allows for restoring only a subset of the archived states into the graph. It can be NULL, in which case all archived states with matching persistentIDs will be restored. In that case, the call sequence beginEditing(), restoreObjectsFromArchive(), endEditing() is equivalent to the deprecated begin-/endRestoringDocumentFromArchive() for ARA 1, which has been superseded by this call. The host is not required to restore all objects in the archive. Any archived states that are either filtered explicitly, or for which there is no object with a matching persistent ID in the current graph are simply ignored. Since persistent IDs are only required to be unique per document (and not globally), hosts may encounter persistent ID conflicts when importing data from other documents. The optional ARARestoreObjectsFilter provided for this call therefore allows to map between the IDs used in the archive and those used in the current graph if needed.
The host can make multiple calls to restoreObjectsFromArchive() within the same editing session to import objects from multiple archives in one operation. It may even decide to implement its persistency based on partial archives entirely, using several calls to storeObjectsToArchive() with varying filters to split the document into slices appropriate to its implementation, see ARAStoreObjectsFilter::documentData.
Result is kARAFalse if the access to the archive reader failed while trying to read the archive, or if decoding the data failed, kARATrue otherwise. Potential reason for failure include data corruption due to storage hardware failures, or broken dependencies when restoring partial archives as discussed above. The plug-in should try to recover as much state as possible in all cases, and the host should notify the user of such errors. If a failure happened already while reading the archive, the host is aware of this and can augment its error message to the user accordingly. If the failure happens inside the plug-in when decoding the data, the plug-in is responsible for guiding the user as good as possible, e.g. by listing or marking the affected objects. Note that since versioning is expressed through the ARA factory, the host must deal with potential versioning conflicts before making this call, and provide proper UI too. More...
 
virtual bool storeObjectsToArchive (ARAArchiveWriterHostRef archiveWriterHostRef, const ARAStoreObjectsFilter *filter) noexcept=0
 Create a partial archive of the internal state of the specified objects. Archives may only be created from documents that are not being currently edited. The optional filter allows for storing only a subset of the document graph into the archive. It can be NULL, in which case all objects in the graph will be stored. In that case, the call is equivalent to the deprecated storeDocumentToArchive(), which has been superseded by this call. Result is kARAFalse if the access to the archive writer failed while trying to write the archive, kARATrue otherwise. The host is responsible for alerting the user about archive write errors, see ARAArchivingControllerInterface::writeBytesToArchive(). Note that for creating ARA audio file chunk archives, storeAudioSourceToAudioFileChunk() must be used instead, so that the plug-in can pick the correct encoding and return the corresponding (compatible) document archive ID. More...
 
virtual bool storeAudioSourceToAudioFileChunk (ARAArchiveWriterHostRef archiveWriterHostRef, ARAAudioSourceRef audioSourceRef, ARAPersistentID *documentArchiveID, bool *openAutomatically) noexcept=0
 Create an archive of the internal state of the specified audio source suitable to be embedded into the underlying audio file as ARA audio file chunks, see ARA Audio File Chunks. Hosts must check ARAFactory::supportsStoringAudioFileChunks before enabling users to store audio file chunks for the given plug-in. Archives may only be created from documents that are not being currently edited.
This call differs from using storeObjectsToArchive() with an ARAStoreObjectsFilter in that the plug-in may choose a different internal encoding more suitable for this use case, indicated by returning a documentArchiveID that is likely one of the ARAFactory::compatibleDocumentArchiveIDs rather than the ARAFactory::documentArchiveID. The plug-in also returns whether openAutomatically should be set in the audio file chunk. Result is kARAFalse if the access to the archive writer failed while trying to write the archive, kARATrue otherwise. The host is responsible for alerting the user about archive write errors, see ARAArchivingControllerInterface::writeBytesToArchive(). More...
 

Document Management

virtual void updateDocumentProperties (PropertiesPtr< ARADocumentProperties > properties) noexcept=0
 Update the properties of the controller's document. All properties must be specified, the plug-in will determine which have actually changed. More...
 

Musical Context Management

virtual ARAMusicalContextRef createMusicalContext (ARAMusicalContextHostRef hostRef, PropertiesPtr< ARAMusicalContextProperties > properties) noexcept=0
 Create a new musical context associated with the controller's document. More...
 
virtual void updateMusicalContextProperties (ARAMusicalContextRef musicalContextRef, PropertiesPtr< ARAMusicalContextProperties > properties) noexcept=0
 Update the properties of a given musical context. All properties must be specified, the plug-in will determine which have actually changed. More...
 
virtual void updateMusicalContextContent (ARAMusicalContextRef musicalContextRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0
 Tell the plug-in to update the information obtainable via content readers for a given musical context. The time range may be NULL, this means that the entire musical content is affected. Creating a new musical context implies an initial content update for it - the host will call this explicitly only for later content updates. More...
 
virtual void destroyMusicalContext (ARAMusicalContextRef musicalContextRef) noexcept=0
 Destroy a given musical context. Destroying a musical context also implies removing it from its document. The musical context must no longer be referred to by any playback region when making this call. More...
 

Region Sequence Management

virtual ARARegionSequenceRef createRegionSequence (ARARegionSequenceHostRef hostRef, PropertiesPtr< ARARegionSequenceProperties > properties) noexcept=0
 Create a new region sequence associated with the controller's document. More...
 
virtual void updateRegionSequenceProperties (ARARegionSequenceRef regionSequence, PropertiesPtr< ARARegionSequenceProperties > properties) noexcept=0
 Update the properties of a given region sequence. All properties must be specified, the plug-in will determine which have actually changed. More...
 
virtual void destroyRegionSequence (ARARegionSequenceRef regionSequence) noexcept=0
 Destroy a given region sequence. The region sequence must no longer be referred to by any playback region when making this call. More...
 

Audio Source Management

virtual ARAAudioSourceRef createAudioSource (ARAAudioSourceHostRef hostRef, PropertiesPtr< ARAAudioSourceProperties > properties) noexcept=0
 Create a new audio source associated with the controller's document. The newly created audio source has its sample data access initially disabled, an explicit call to enableAudioSourceSamplesAccess() is needed. More...
 
virtual void updateAudioSourceProperties (ARAAudioSourceRef audioSourceRef, PropertiesPtr< ARAAudioSourceProperties > properties) noexcept=0
 Update the properties of a given audio source. Depending on which properties are changed (see documentation of ARAAudioSourceProperties), the host may not be able to make this call while the plug-in is reading data - in that case, use enableAudioSourceSamplesAccess() accordingly. All properties must be specified, the plug-in will determine which have actually changed. More...
 
virtual void updateAudioSourceContent (ARAAudioSourceRef audioSourceRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0
 Tell the plug-in that the sample data or content information for the given audio source has changed. Not to be called in response to ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged(). The time range may be NULL, this means that the entire audio source is affected. When implementing this call, remember to also flush any caches of the sampled data if needed (see kARAContentUpdateSignalScopeRemainsUnchanged). Creating a new audio source always implies an initial content update for it, i.e. the host will call this function only for later content updates. Since audio sources are persistent, plug-ins should preferably postpone the initial content reading until endEditing() - if the host is restoring the audio source, this will remove the need to read initial content. More...
 
virtual void enableAudioSourceSamplesAccess (ARAAudioSourceRef audioSourceRef, bool enable) noexcept=0
 Enable or disable access to a given audio source. This call allows the host to control the time when the plug-in may access sample data from the given audio source. Disabling access forces the plug-in to destroy all audio readers it currently has created for the affected audio source. This is a synchronous call, blocking until all currently executing reads of the audio source are finished. Access is disabled by default, hosts must explicitly enable it after creating an audio source. Since this call does not modify the model graph, it may be called outside the usual beginEditing() and endEditing() scope. Note that disabling access will also abort any analysis currently being executed for the audio source, making it necessary to start it from scratch when the access is enabled again. This means that enableAudioSourceSamplesAccess() is an expensive call that only should be made when necessary. It should not be (ab-)used to simply "pause ARA" whenever convenient. More...
 
virtual void deactivateAudioSourceForUndoHistory (ARAAudioSourceRef audioSourceRef, bool deactivate) noexcept=0
 Deactivate the given audio source because it has become part of the undo history and is no longer used actively. The plug-in will cancel any pending analysis for this audio source and may free memory that is only needed when the audio source can be edited or rendered. Before deactivating an audio source, the host must deactivate all associated audio modifications, and the opposite order is required when re-activating upon redo. When deactivated, updating the properties or content of the audio source or reading its content is no longer valid. Like properties, deactivation is not necessarily persistent in the plug-in, so the host must call this explicitly when restoring deactivated audio sources. Note that with the introduction of partial persistency with ARA 2.0, hosts likely will prefer to simply create partial archives of deleted audio sources and manage these in their undo history rather than utilizing this call. More...
 
virtual void destroyAudioSource (ARAAudioSourceRef audioSourceRef) noexcept=0
 Destroy a given audio source. Destroying an audio source also implies removing it from its document. The host must delete all objects associated with the audio source (audio modifications etc.) before deleting the audio source. The host does not need to explicitly disable access to the audio source before making this call. More...
 

Audio Modification Management

virtual ARAAudioModificationRef createAudioModification (ARAAudioSourceRef audioSourceRef, ARAAudioModificationHostRef hostRef, PropertiesPtr< ARAAudioModificationProperties > properties) noexcept=0
 Create a new audio modification associated with the given audio source. More...
 
virtual ARAAudioModificationRef cloneAudioModification (ARAAudioModificationRef audioModificationRef, ARAAudioModificationHostRef hostRef, PropertiesPtr< ARAAudioModificationProperties > properties) noexcept=0
 Create a new audio modification that copies the state of another given audio modification. The new modification will be associated with the same audio source. This call is used to create independent variations of the audio as opposed to creating aliases by merely adding playback regions to a given audio modification. More...
 
virtual void updateAudioModificationProperties (ARAAudioModificationRef audioModificationRef, PropertiesPtr< ARAAudioModificationProperties > properties) noexcept=0
 Update the properties of a given audio modification. All properties must be specified, the plug-in will determine which have actually changed. More...
 
virtual bool isAudioModificationPreservingAudioSourceSignal (ARAAudioModificationRef audioModificationRef) noexcept=0
 Some hosts such as Pro Tools provide indicators whether a given plug-in's current settings cause it to alter the sound of the original audio source, or preserve it so that bypassing/removing the plug-in would not change the perceived audible result (note that actual rendering involves using a playback region, which still may apply time-stretching or pitch-shifting to the audio modification's potentially unaltered output).
Changes to this state are tracked via ARAModelUpdateControllerInterface::notifyAudioModificationContentChanged() with kARAContentUpdateSignalScopeRemainsUnchanged == false. Note that it is possible to perform other edits such as reassigning the chords associated with the audio modification which would not affect this state.
It is valid for plug-in implementations to deliver false negatives here to reasonably limit the cost of maintaining the state. For example, if the plug-in does some threshold-based processing, but the signal happens to never actually reach the threshold, the plug-in still may report to alter the sound. Another example is pitch&time editing in a Melodyne-like plug-in: if notes are moved to a different pitch or time position so that this flag is cleared, but later the user manually moves them back to the original location, this might not cause this flag to turn back on. If however the user invokes undo, or some explicit reset command instead of the manual adjustment, then the plug-in should maintain this state properly. More...
 
virtual void deactivateAudioModificationForUndoHistory (ARAAudioModificationRef audioModificationRef, bool deactivate) noexcept=0
 Deactivate the given audio modification because it has become part of the undo history and is no longer used actively. The plug-in may free some memory that is only needed when the audio modification can be edited or rendered. Before deactivating an audio modification, the host must destroy all associated playback regions, and the opposite order is required when re-activating upon redo. When deactivated, updating the properties of the audio modification or reading its content is no longer valid. Like properties, deactivation is not necessarily persistent in the plug-in, so the host must call this explicitly when restoring deactivated audio modifications. Note that with the introduction of partial persistency with ARA 2.0, hosts likely will prefer to simply create partial archives of deleted audio modifications and manage these in their undo history rather than utilizing this call. More...
 
virtual void destroyAudioModification (ARAAudioModificationRef audioModificationRef) noexcept=0
 Destroy a given audio modification. Destroying an audio modification also implies removing it from its audio source. The host must delete all objects associated with the audio modification (playback regions etc.) before deleting the audio modification. More...
 

Playback Region Management

virtual ARAPlaybackRegionRef createPlaybackRegion (ARAAudioModificationRef audioModificationRef, ARAPlaybackRegionHostRef hostRef, PropertiesPtr< ARAPlaybackRegionProperties > properties) noexcept=0
 Create a new playback region associated with the given audio modification. More...
 
virtual void updatePlaybackRegionProperties (ARAPlaybackRegionRef playbackRegionRef, PropertiesPtr< ARAPlaybackRegionProperties > properties) noexcept=0
 Update the properties of a given playback region. All properties must be specified, the plug-in will determine which have actually changed. More...
 
virtual void destroyPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 Destroy a given playback region. Destroying a playback region also implies removing it from its audio modification. The playback region must no longer be referred to by any plug-in extension when making this call. More...
 
virtual void getPlaybackRegionHeadAndTailTime (ARAPlaybackRegionRef playbackRegionRef, ARATimeDuration *headTime, ARATimeDuration *tailTime) noexcept=0
 Query the current head and tail time of a given playback region. Note that when a plug-in optimizes region transitions, the head and tail of any given region can change upon any model edit, even if it is not directly affected by the edit. Also, in order to properly track interaction between regions, plug-ins may lazily update this information upon endEditing(). Plug-ins will call notifyPlaybackRegionContentChanged() whenever these values change. headTime and tailTime must not be NULL. Host may query this often, so plug-ins should cache the value if there's any expensive calculation involved. Note that most companion APIs also feature a tail time concept. For playback renderer plug-in instances, the tail time reported via the companion API should be equal to or greater than the maximum of the tail times of all playback regions currently associated with the given renderer (i.e. the tail for any given playback region may be somewhat shorter then the companion API tail, depending on the region's content). More...
 

Content Reader Management

virtual bool isAudioSourceContentAvailable (ARAAudioSourceRef audioSourceRef, ARAContentType type) noexcept=0
 Query whether the given content type is currently available for the given audio source. More...
 
virtual ARAContentGrade getAudioSourceContentGrade (ARAAudioSourceRef audioSourceRef, ARAContentType type) noexcept=0
 Query the current quality of the information provided for the given audio source and content type. More...
 
virtual ARAContentReaderRef createAudioSourceContentReader (ARAAudioSourceRef audioSourceRef, 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 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 bool isAudioModificationContentAvailable (ARAAudioModificationRef audioModificationRef, ARAContentType type) noexcept=0
 Query whether the given content type is currently available for the given audio modification. Note that since ARA 2.0, reading at playback region level is recommended for most content types, see createAudioModificationContentReader(). More...
 
virtual ARAContentGrade getAudioModificationContentGrade (ARAAudioModificationRef audioModificationRef, ARAContentType type) noexcept=0
 Query the current quality of the information provided for a given audio modification and content type. Note that since ARA 2.0, reading at playback region level is recommended for most content types, see createAudioModificationContentReader(). More...
 
virtual ARAContentReaderRef createAudioModificationContentReader (ARAAudioModificationRef audioModificationRef, ARAContentType type, const ARAContentTimeRange *range) noexcept=0
 Create a content reader for the given audio modification and content type. This should only be called after availability has been confirmed using isAudioModificationContentAvailable(). The time range may be NULL, which means that the entire audio modification shall be read. If a time range is specified, all events that at least partially intersect with the range will be read. Note that with the introduction of region transitions in ARA 2.0, the content of a given playback region can no longer be externally calculated by the host based on the content of its underlying audio modification and the transformation flags. Instead, hosts should read such content directly at region level. This particularly applies to kARAContentTypeNotes - notes at borders will be adjusted on a per-region basis when using content based fades. Playback region content reading is available in ARA 1.0 already, thus such an implementation will be fully backwards compatible. Reading content at audio modification (or audio source) level is still valid and useful if the host needs access to the content in its original state, not transformed by a playback region, e.g. when implementing features such as tempo and signature detection through ARA. More...
 
virtual bool isPlaybackRegionContentAvailable (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type) noexcept=0
 Query whether the given content type is currently available for the given playback region. More...
 
virtual ARAContentGrade getPlaybackRegionContentGrade (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type) noexcept=0
 Query the current quality of the information provided for the given playback region and content type. More...
 
virtual ARAContentReaderRef createPlaybackRegionContentReader (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type, const ARAContentTimeRange *range) noexcept=0
 Create a content reader for the given playback region and content type. This should only be called after availability has been confirmed using isPlaybackRegionContentAvailable(). The time range may be NULL, which means that the entire playback region shall be read, including its potential head and tail time. If a time range is specified, all events that at least partially intersect with the range will be read. The time range must be given in playback time, and the time stamps provided by the content reader are in playback time as well. More...
 
virtual ARAInt32 getContentReaderEventCount (ARAContentReaderRef contentReaderRef) noexcept=0
 Query how many events the given reader exposes. More...
 
virtual const void * getContentReaderDataForEvent (ARAContentReaderRef contentReaderRef, ARAInt32 eventIndex) noexcept=0
 Query data of the given event of the given reader. The returned pointer is owned by the plug-in and must remain valid until either getContentReaderDataForEvent() is called again or the content reader is destroyed. More...
 
virtual void destroyContentReader (ARAContentReaderRef contentReaderRef) noexcept=0
 Destroy the given content reader. More...
 

Controlling Analysis

virtual bool isAudioSourceContentAnalysisIncomplete (ARAAudioSourceRef audioSourceRef, ARAContentType contentType) noexcept=0
 Query whether an analysis of the given content type has been done for the given audio source. This call will typically be used when the host uses the plug-in as a detection engine in the background (i.e. without presenting the UI to the user). In that scenario, the host will trigger the analysis of the desired content types using requestAudioSourceContentAnalysis() and then wait until the plug-in calls ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged(). From that call, the host will query the plug-in via isAudioSourceContentAnalysisIncomplete() to determine which of the analysis requests have completed. If the host did request a specific algorithm to be used, then the plug-in should return kARATrue here until the request was satisfied (or rejected). More...
 
virtual void requestAudioSourceContentAnalysis (ARAAudioSourceRef audioSourceRef, ARASize contentTypesCount, const ARAContentType contentTypes[]) noexcept=0
 Explicitly trigger a certain analysis. If the host wants to use the plug-in as detection engine, it needs to explicitly trigger the desired analysis, since otherwise the plug-in may postpone any analysis as suitable. To allow for optimizing the analysis on the plug-in side, all content types that are of interest for the host should be specified in a single call if possible.
Note that the plug-in may choose to perform any additional analysis at any point in time if this is appropriate for its design. It will call ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged() if such an analysis concludes successfully so that the host can update accordingly.
The provided content types must be a non-empty subset of the plug-in's ARAFactory::analyzeableContentTypes. To request all analysis types exported by the plug-in, hosts can directly pass analyzeableContentTypes and -Count from the plug-in's ARAFactory. The contentTypes pointer may be only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere.
Note that ARA 2.0 adds the capability for the host to also request the use of a certain processing algorithm via requestProcessingAlgorithmForAudioSource() - if both are used then the algorithm must be selected before requesting the analysis. More...
 
virtual ARAInt32 getProcessingAlgorithmsCount () noexcept=0
 Return the count of processing algorithms provided by the plug-in. If this optional method is not implemented or the call returns 0, then the plug-in does not support algorithm selection through the host and the other related functions below must not be called. More...
 
virtual const ARAProcessingAlgorithmProperties * getProcessingAlgorithmProperties (ARAInt32 algorithmIndex) noexcept=0
 List of processing algorithms provided by the plug-in, described by their properties. This method must be implemented if getProcessingAlgorithmsCount() is implemented. Provides a unique identifier and a user-readable name of the algorithm as displayed in the plug-in. The host should present the algorithms to the user in the order of this list, e.g. in a menu. For a given version of the plug-in, the count and the order and values of the persistentIDs must be the same, while the names may depend on localization settings that can be different on different machines or between individual runs of the host. The list may however change between different versions of the plug-in. Both hosts and plug-ins must implement fallbacks for loading a document that contains an processing algorithm persistentID which is no longer supported by the plug-in. The pointers returned by this calls must remain valid until the document controller is destroyed. More...
 
virtual ARAInt32 getProcessingAlgorithmForAudioSource (ARAAudioSourceRef audioSourceRef) noexcept=0
 Query currently used processing algorithm for a given audio source. This method must be implemented if getProcessingAlgorithmsCount() is implemented. After the plug-in has concluded an analysis (as indicated via ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged()), the host can query which processing algorithm was used and update its UI accordingly. This is particularly relevant if the host did explicitly request an analysis with a specific algorithm, but the plug-in was unable to satisfy this request for some reason. Similarly, the user may have changed the algorithm through the plug-in's UI. Note that until the first analysis has completed (i.e. as long as isAudioSourceContentAnalysisIncomplete() returns kARATrue), the value returned here may be an abstract default, not related to the actual audio source content. This will e.g. typically be the case in Melodyne, which uses an "automatic mode" as default until the first analysis has determined the actual processing algorithm that is suitable for the material. The call should not be made while isAudioSourceContentAnalysisIncomplete() returns kARATrue, because the returned value is likely stale. More...
 
virtual void requestProcessingAlgorithmForAudioSource (ARAAudioSourceRef audioSourceRef, ARAInt32 algorithmIndex) noexcept=0
 Request that any future analysis of the given audio source should use the given processing algorithm. This method must be implemented if getProcessingAlgorithmsCount() is implemented. This both affects any analysis requested by the host via requestAudioSourceContentAnalysis() as well as any analysis done by the plug-in on demand. Since this typically results in a model graph edit, calling this functions must be guarded by beginEditing() and endEditing(). Note that the plug-in is not required to heed this request if its internal state suggest otherwise, or if the user switches actively to a different algorithm. Also, some algorithms may be "meta" algorithms that will be replaced by a different actual algorithm, such as the "automatic" default algorithm in Melodyne which will pick an appropriate algorithm from the remaining list of algorithms when doing the initial analysis. More...
 

License Management

virtual bool isLicensedForCapabilities (bool runModalActivationDialogIfNeeded, ARASize contentTypesCount, const ARAContentType contentTypes[], ARAPlaybackTransformationFlags transformationFlags) noexcept=0
 With this optional call, hosts can test whether the current license state of the plug-in allows for requesting analysis of the given content types and rendering the given playback transformations (see requestAudioSourceContentAnalysis() and ARAPlaybackRegionProperties::transformationFlags). The host can also optionally instruct the plug-in to run a modal licensing dialog if the current license is not sufficient to perform the selected engine tasks, so that the user can review and adjust the licensing accordingly, such downloading a license from their respective user account or even purchase an upgrade that enables the requested features.
The provided content types must be a subset of the plug-in's ARAFactory::analyzeableContentTypes. To request all analysis types exported by the plug-in, hosts can directly pass analyzeableContentTypes and -Count from the ARAFactory. The contentTypes pointer may be only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere. If not intending to use analysis, the count should be 0 and the array pointer NULL. The transformationFlags must be a subset of the plug-in's ARAFactory::supportedPlaybackTransformationFlags, and may be kARAPlaybackTransformationNoChanges if not intending to use transformations. The call returns kARATrue if the (potentially updated) license is sufficient to perform the requested tasks. More...
 

Member Function Documentation

◆ beginEditing()

virtual void ARA::PlugIn::DocumentControllerInterface::beginEditing ( )
pure virtualnoexcept

Start an editing session on a document. An editing session can contain an arbitrary set of modifications that belong together. Since many model edits can result in rather expensive updates on the plug-in side, this call allows for grouping the edits and postponing the updates until the new model state is final, which potentially saves some intermediate updates.

◆ cloneAudioModification()

virtual ARAAudioModificationRef ARA::PlugIn::DocumentControllerInterface::cloneAudioModification ( ARAAudioModificationRef  audioModificationRef,
ARAAudioModificationHostRef  hostRef,
PropertiesPtr< ARAAudioModificationProperties >  properties 
)
pure virtualnoexcept

Create a new audio modification that copies the state of another given audio modification. The new modification will be associated with the same audio source. This call is used to create independent variations of the audio as opposed to creating aliases by merely adding playback regions to a given audio modification.

◆ createAudioModification()

virtual ARAAudioModificationRef ARA::PlugIn::DocumentControllerInterface::createAudioModification ( ARAAudioSourceRef  audioSourceRef,
ARAAudioModificationHostRef  hostRef,
PropertiesPtr< ARAAudioModificationProperties >  properties 
)
pure virtualnoexcept

Create a new audio modification associated with the given audio source.

◆ createAudioModificationContentReader()

virtual ARAContentReaderRef ARA::PlugIn::DocumentControllerInterface::createAudioModificationContentReader ( ARAAudioModificationRef  audioModificationRef,
ARAContentType  type,
const ARAContentTimeRange *  range 
)
pure virtualnoexcept

Create a content reader for the given audio modification and content type. This should only be called after availability has been confirmed using isAudioModificationContentAvailable(). The time range may be NULL, which means that the entire audio modification shall be read. If a time range is specified, all events that at least partially intersect with the range will be read. Note that with the introduction of region transitions in ARA 2.0, the content of a given playback region can no longer be externally calculated by the host based on the content of its underlying audio modification and the transformation flags. Instead, hosts should read such content directly at region level. This particularly applies to kARAContentTypeNotes - notes at borders will be adjusted on a per-region basis when using content based fades. Playback region content reading is available in ARA 1.0 already, thus such an implementation will be fully backwards compatible. Reading content at audio modification (or audio source) level is still valid and useful if the host needs access to the content in its original state, not transformed by a playback region, e.g. when implementing features such as tempo and signature detection through ARA.

◆ createAudioSource()

virtual ARAAudioSourceRef ARA::PlugIn::DocumentControllerInterface::createAudioSource ( ARAAudioSourceHostRef  hostRef,
PropertiesPtr< ARAAudioSourceProperties >  properties 
)
pure virtualnoexcept

Create a new audio source associated with the controller's document. The newly created audio source has its sample data access initially disabled, an explicit call to enableAudioSourceSamplesAccess() is needed.

◆ createAudioSourceContentReader()

virtual ARAContentReaderRef ARA::PlugIn::DocumentControllerInterface::createAudioSourceContentReader ( ARAAudioSourceRef  audioSourceRef,
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 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.

◆ createMusicalContext()

virtual ARAMusicalContextRef ARA::PlugIn::DocumentControllerInterface::createMusicalContext ( ARAMusicalContextHostRef  hostRef,
PropertiesPtr< ARAMusicalContextProperties >  properties 
)
pure virtualnoexcept

Create a new musical context associated with the controller's document.

◆ createPlaybackRegion()

virtual ARAPlaybackRegionRef ARA::PlugIn::DocumentControllerInterface::createPlaybackRegion ( ARAAudioModificationRef  audioModificationRef,
ARAPlaybackRegionHostRef  hostRef,
PropertiesPtr< ARAPlaybackRegionProperties >  properties 
)
pure virtualnoexcept

Create a new playback region associated with the given audio modification.

◆ createPlaybackRegionContentReader()

virtual ARAContentReaderRef ARA::PlugIn::DocumentControllerInterface::createPlaybackRegionContentReader ( ARAPlaybackRegionRef  playbackRegionRef,
ARAContentType  type,
const ARAContentTimeRange *  range 
)
pure virtualnoexcept

Create a content reader for the given playback region and content type. This should only be called after availability has been confirmed using isPlaybackRegionContentAvailable(). The time range may be NULL, which means that the entire playback region shall be read, including its potential head and tail time. If a time range is specified, all events that at least partially intersect with the range will be read. The time range must be given in playback time, and the time stamps provided by the content reader are in playback time as well.

◆ createRegionSequence()

virtual ARARegionSequenceRef ARA::PlugIn::DocumentControllerInterface::createRegionSequence ( ARARegionSequenceHostRef  hostRef,
PropertiesPtr< ARARegionSequenceProperties >  properties 
)
pure virtualnoexcept

Create a new region sequence associated with the controller's document.

◆ deactivateAudioModificationForUndoHistory()

virtual void ARA::PlugIn::DocumentControllerInterface::deactivateAudioModificationForUndoHistory ( ARAAudioModificationRef  audioModificationRef,
bool  deactivate 
)
pure virtualnoexcept

Deactivate the given audio modification because it has become part of the undo history and is no longer used actively. The plug-in may free some memory that is only needed when the audio modification can be edited or rendered. Before deactivating an audio modification, the host must destroy all associated playback regions, and the opposite order is required when re-activating upon redo. When deactivated, updating the properties of the audio modification or reading its content is no longer valid. Like properties, deactivation is not necessarily persistent in the plug-in, so the host must call this explicitly when restoring deactivated audio modifications. Note that with the introduction of partial persistency with ARA 2.0, hosts likely will prefer to simply create partial archives of deleted audio modifications and manage these in their undo history rather than utilizing this call.

◆ deactivateAudioSourceForUndoHistory()

virtual void ARA::PlugIn::DocumentControllerInterface::deactivateAudioSourceForUndoHistory ( ARAAudioSourceRef  audioSourceRef,
bool  deactivate 
)
pure virtualnoexcept

Deactivate the given audio source because it has become part of the undo history and is no longer used actively. The plug-in will cancel any pending analysis for this audio source and may free memory that is only needed when the audio source can be edited or rendered. Before deactivating an audio source, the host must deactivate all associated audio modifications, and the opposite order is required when re-activating upon redo. When deactivated, updating the properties or content of the audio source or reading its content is no longer valid. Like properties, deactivation is not necessarily persistent in the plug-in, so the host must call this explicitly when restoring deactivated audio sources. Note that with the introduction of partial persistency with ARA 2.0, hosts likely will prefer to simply create partial archives of deleted audio sources and manage these in their undo history rather than utilizing this call.

◆ destroyAudioModification()

virtual void ARA::PlugIn::DocumentControllerInterface::destroyAudioModification ( ARAAudioModificationRef  audioModificationRef)
pure virtualnoexcept

Destroy a given audio modification. Destroying an audio modification also implies removing it from its audio source. The host must delete all objects associated with the audio modification (playback regions etc.) before deleting the audio modification.

◆ destroyAudioSource()

virtual void ARA::PlugIn::DocumentControllerInterface::destroyAudioSource ( ARAAudioSourceRef  audioSourceRef)
pure virtualnoexcept

Destroy a given audio source. Destroying an audio source also implies removing it from its document. The host must delete all objects associated with the audio source (audio modifications etc.) before deleting the audio source. The host does not need to explicitly disable access to the audio source before making this call.

◆ destroyContentReader()

virtual void ARA::PlugIn::DocumentControllerInterface::destroyContentReader ( ARAContentReaderRef  contentReaderRef)
pure virtualnoexcept

Destroy the given content reader.

◆ destroyDocumentController()

virtual void ARA::PlugIn::DocumentControllerInterface::destroyDocumentController ( )
pure virtualnoexcept

Destroy the controller and its associated document. The host must delete all objects associated with the document graph (audio sources, musical contexts etc.) before making this call. Note that the objects exported via the ARAPlugInExtensionInstance are not considered part of the document graph, their destruction may happen before or after destroying the document controller that they are bound to.

◆ destroyMusicalContext()

virtual void ARA::PlugIn::DocumentControllerInterface::destroyMusicalContext ( ARAMusicalContextRef  musicalContextRef)
pure virtualnoexcept

Destroy a given musical context. Destroying a musical context also implies removing it from its document. The musical context must no longer be referred to by any playback region when making this call.

◆ destroyPlaybackRegion()

virtual void ARA::PlugIn::DocumentControllerInterface::destroyPlaybackRegion ( ARAPlaybackRegionRef  playbackRegionRef)
pure virtualnoexcept

Destroy a given playback region. Destroying a playback region also implies removing it from its audio modification. The playback region must no longer be referred to by any plug-in extension when making this call.

◆ destroyRegionSequence()

virtual void ARA::PlugIn::DocumentControllerInterface::destroyRegionSequence ( ARARegionSequenceRef  regionSequence)
pure virtualnoexcept

Destroy a given region sequence. The region sequence must no longer be referred to by any playback region when making this call.

◆ enableAudioSourceSamplesAccess()

virtual void ARA::PlugIn::DocumentControllerInterface::enableAudioSourceSamplesAccess ( ARAAudioSourceRef  audioSourceRef,
bool  enable 
)
pure virtualnoexcept

Enable or disable access to a given audio source. This call allows the host to control the time when the plug-in may access sample data from the given audio source. Disabling access forces the plug-in to destroy all audio readers it currently has created for the affected audio source. This is a synchronous call, blocking until all currently executing reads of the audio source are finished. Access is disabled by default, hosts must explicitly enable it after creating an audio source. Since this call does not modify the model graph, it may be called outside the usual beginEditing() and endEditing() scope. Note that disabling access will also abort any analysis currently being executed for the audio source, making it necessary to start it from scratch when the access is enabled again. This means that enableAudioSourceSamplesAccess() is an expensive call that only should be made when necessary. It should not be (ab-)used to simply "pause ARA" whenever convenient.

◆ endEditing()

virtual void ARA::PlugIn::DocumentControllerInterface::endEditing ( )
pure virtualnoexcept

End an editing session on a document. Note that when receiving this call, the plug-in will update any amount of internal state. These edits may lead to update notifications to the host, and the host may in turn read affected content from the plug-in and update its own model accordingly. One example for this the way that Melodyne maintains chords and scales associated with audio modifications. It copies this data from the musical context into the audio modifications, so that when editing regions the notes appear in the proper pitch grid. If moving playback regions in the song, these copies may need to be updated, and Melodyne will report the resulting audio modification content changes to the host. To ensure that any such follow-up updates are added to the same undo cycle, hosts that actively read plug-in content data should immediately (i.e. within the same undo frame) call notifyModelUpdates() after making this call.

◆ getAudioModificationContentGrade()

virtual ARAContentGrade ARA::PlugIn::DocumentControllerInterface::getAudioModificationContentGrade ( ARAAudioModificationRef  audioModificationRef,
ARAContentType  type 
)
pure virtualnoexcept

Query the current quality of the information provided for a given audio modification and content type. Note that since ARA 2.0, reading at playback region level is recommended for most content types, see createAudioModificationContentReader().

◆ getAudioSourceContentGrade()

virtual ARAContentGrade ARA::PlugIn::DocumentControllerInterface::getAudioSourceContentGrade ( ARAAudioSourceRef  audioSourceRef,
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::PlugIn::DocumentControllerInterface::getContentReaderDataForEvent ( ARAContentReaderRef  contentReaderRef,
ARAInt32  eventIndex 
)
pure virtualnoexcept

Query data of the given event of the given reader. The returned pointer is owned by the plug-in and must remain valid until either getContentReaderDataForEvent() is called again or the content reader is destroyed.

◆ getContentReaderEventCount()

virtual ARAInt32 ARA::PlugIn::DocumentControllerInterface::getContentReaderEventCount ( ARAContentReaderRef  contentReaderRef)
pure virtualnoexcept

Query how many events the given reader exposes.

◆ getPlaybackRegionContentGrade()

virtual ARAContentGrade ARA::PlugIn::DocumentControllerInterface::getPlaybackRegionContentGrade ( ARAPlaybackRegionRef  playbackRegionRef,
ARAContentType  type 
)
pure virtualnoexcept

Query the current quality of the information provided for the given playback region and content type.

◆ getPlaybackRegionHeadAndTailTime()

virtual void ARA::PlugIn::DocumentControllerInterface::getPlaybackRegionHeadAndTailTime ( ARAPlaybackRegionRef  playbackRegionRef,
ARATimeDuration *  headTime,
ARATimeDuration *  tailTime 
)
pure virtualnoexcept

Query the current head and tail time of a given playback region. Note that when a plug-in optimizes region transitions, the head and tail of any given region can change upon any model edit, even if it is not directly affected by the edit. Also, in order to properly track interaction between regions, plug-ins may lazily update this information upon endEditing(). Plug-ins will call notifyPlaybackRegionContentChanged() whenever these values change. headTime and tailTime must not be NULL. Host may query this often, so plug-ins should cache the value if there's any expensive calculation involved. Note that most companion APIs also feature a tail time concept. For playback renderer plug-in instances, the tail time reported via the companion API should be equal to or greater than the maximum of the tail times of all playback regions currently associated with the given renderer (i.e. the tail for any given playback region may be somewhat shorter then the companion API tail, depending on the region's content).

◆ getProcessingAlgorithmForAudioSource()

virtual ARAInt32 ARA::PlugIn::DocumentControllerInterface::getProcessingAlgorithmForAudioSource ( ARAAudioSourceRef  audioSourceRef)
pure virtualnoexcept

Query currently used processing algorithm for a given audio source. This method must be implemented if getProcessingAlgorithmsCount() is implemented. After the plug-in has concluded an analysis (as indicated via ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged()), the host can query which processing algorithm was used and update its UI accordingly. This is particularly relevant if the host did explicitly request an analysis with a specific algorithm, but the plug-in was unable to satisfy this request for some reason. Similarly, the user may have changed the algorithm through the plug-in's UI. Note that until the first analysis has completed (i.e. as long as isAudioSourceContentAnalysisIncomplete() returns kARATrue), the value returned here may be an abstract default, not related to the actual audio source content. This will e.g. typically be the case in Melodyne, which uses an "automatic mode" as default until the first analysis has determined the actual processing algorithm that is suitable for the material. The call should not be made while isAudioSourceContentAnalysisIncomplete() returns kARATrue, because the returned value is likely stale.

◆ getProcessingAlgorithmProperties()

virtual const ARAProcessingAlgorithmProperties* ARA::PlugIn::DocumentControllerInterface::getProcessingAlgorithmProperties ( ARAInt32  algorithmIndex)
pure virtualnoexcept

List of processing algorithms provided by the plug-in, described by their properties. This method must be implemented if getProcessingAlgorithmsCount() is implemented. Provides a unique identifier and a user-readable name of the algorithm as displayed in the plug-in. The host should present the algorithms to the user in the order of this list, e.g. in a menu. For a given version of the plug-in, the count and the order and values of the persistentIDs must be the same, while the names may depend on localization settings that can be different on different machines or between individual runs of the host. The list may however change between different versions of the plug-in. Both hosts and plug-ins must implement fallbacks for loading a document that contains an processing algorithm persistentID which is no longer supported by the plug-in. The pointers returned by this calls must remain valid until the document controller is destroyed.

◆ getProcessingAlgorithmsCount()

virtual ARAInt32 ARA::PlugIn::DocumentControllerInterface::getProcessingAlgorithmsCount ( )
pure virtualnoexcept

Return the count of processing algorithms provided by the plug-in. If this optional method is not implemented or the call returns 0, then the plug-in does not support algorithm selection through the host and the other related functions below must not be called.

◆ isAudioModificationContentAvailable()

virtual bool ARA::PlugIn::DocumentControllerInterface::isAudioModificationContentAvailable ( ARAAudioModificationRef  audioModificationRef,
ARAContentType  type 
)
pure virtualnoexcept

Query whether the given content type is currently available for the given audio modification. Note that since ARA 2.0, reading at playback region level is recommended for most content types, see createAudioModificationContentReader().

◆ isAudioModificationPreservingAudioSourceSignal()

virtual bool ARA::PlugIn::DocumentControllerInterface::isAudioModificationPreservingAudioSourceSignal ( ARAAudioModificationRef  audioModificationRef)
pure virtualnoexcept

Some hosts such as Pro Tools provide indicators whether a given plug-in's current settings cause it to alter the sound of the original audio source, or preserve it so that bypassing/removing the plug-in would not change the perceived audible result (note that actual rendering involves using a playback region, which still may apply time-stretching or pitch-shifting to the audio modification's potentially unaltered output).
Changes to this state are tracked via ARAModelUpdateControllerInterface::notifyAudioModificationContentChanged() with kARAContentUpdateSignalScopeRemainsUnchanged == false. Note that it is possible to perform other edits such as reassigning the chords associated with the audio modification which would not affect this state.
It is valid for plug-in implementations to deliver false negatives here to reasonably limit the cost of maintaining the state. For example, if the plug-in does some threshold-based processing, but the signal happens to never actually reach the threshold, the plug-in still may report to alter the sound. Another example is pitch&time editing in a Melodyne-like plug-in: if notes are moved to a different pitch or time position so that this flag is cleared, but later the user manually moves them back to the original location, this might not cause this flag to turn back on. If however the user invokes undo, or some explicit reset command instead of the manual adjustment, then the plug-in should maintain this state properly.

◆ isAudioSourceContentAnalysisIncomplete()

virtual bool ARA::PlugIn::DocumentControllerInterface::isAudioSourceContentAnalysisIncomplete ( ARAAudioSourceRef  audioSourceRef,
ARAContentType  contentType 
)
pure virtualnoexcept

Query whether an analysis of the given content type has been done for the given audio source. This call will typically be used when the host uses the plug-in as a detection engine in the background (i.e. without presenting the UI to the user). In that scenario, the host will trigger the analysis of the desired content types using requestAudioSourceContentAnalysis() and then wait until the plug-in calls ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged(). From that call, the host will query the plug-in via isAudioSourceContentAnalysisIncomplete() to determine which of the analysis requests have completed. If the host did request a specific algorithm to be used, then the plug-in should return kARATrue here until the request was satisfied (or rejected).

◆ isAudioSourceContentAvailable()

virtual bool ARA::PlugIn::DocumentControllerInterface::isAudioSourceContentAvailable ( ARAAudioSourceRef  audioSourceRef,
ARAContentType  type 
)
pure virtualnoexcept

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

◆ isLicensedForCapabilities()

virtual bool ARA::PlugIn::DocumentControllerInterface::isLicensedForCapabilities ( bool  runModalActivationDialogIfNeeded,
ARASize  contentTypesCount,
const ARAContentType  contentTypes[],
ARAPlaybackTransformationFlags  transformationFlags 
)
pure virtualnoexcept

With this optional call, hosts can test whether the current license state of the plug-in allows for requesting analysis of the given content types and rendering the given playback transformations (see requestAudioSourceContentAnalysis() and ARAPlaybackRegionProperties::transformationFlags). The host can also optionally instruct the plug-in to run a modal licensing dialog if the current license is not sufficient to perform the selected engine tasks, so that the user can review and adjust the licensing accordingly, such downloading a license from their respective user account or even purchase an upgrade that enables the requested features.
The provided content types must be a subset of the plug-in's ARAFactory::analyzeableContentTypes. To request all analysis types exported by the plug-in, hosts can directly pass analyzeableContentTypes and -Count from the ARAFactory. The contentTypes pointer may be only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere. If not intending to use analysis, the count should be 0 and the array pointer NULL. The transformationFlags must be a subset of the plug-in's ARAFactory::supportedPlaybackTransformationFlags, and may be kARAPlaybackTransformationNoChanges if not intending to use transformations. The call returns kARATrue if the (potentially updated) license is sufficient to perform the requested tasks.

◆ isPlaybackRegionContentAvailable()

virtual bool ARA::PlugIn::DocumentControllerInterface::isPlaybackRegionContentAvailable ( ARAPlaybackRegionRef  playbackRegionRef,
ARAContentType  type 
)
pure virtualnoexcept

Query whether the given content type is currently available for the given playback region.

◆ notifyModelUpdates()

virtual void ARA::PlugIn::DocumentControllerInterface::notifyModelUpdates ( )
pure virtualnoexcept

Tell the plug-in to send all pending update notifications for the given document. This must be called periodically by the host whenever not editing nor restoring the document. Only when processing this call, the plug-in may call back into the host using ARAModelUpdateControllerInterface. Hosts must be aware after receiving beginEditing(), plug-ins may choose to postpone any subset of their internal state updates until the matching call to endEditing(). This means that if the host for some reason needs to wait for a specific update in the plug-in to occur (such as waiting for an analysis to finish) it must do so outside of pairs of beginEditing() and endEditing().

◆ requestAudioSourceContentAnalysis()

virtual void ARA::PlugIn::DocumentControllerInterface::requestAudioSourceContentAnalysis ( ARAAudioSourceRef  audioSourceRef,
ARASize  contentTypesCount,
const ARAContentType  contentTypes[] 
)
pure virtualnoexcept

Explicitly trigger a certain analysis. If the host wants to use the plug-in as detection engine, it needs to explicitly trigger the desired analysis, since otherwise the plug-in may postpone any analysis as suitable. To allow for optimizing the analysis on the plug-in side, all content types that are of interest for the host should be specified in a single call if possible.
Note that the plug-in may choose to perform any additional analysis at any point in time if this is appropriate for its design. It will call ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged() if such an analysis concludes successfully so that the host can update accordingly.
The provided content types must be a non-empty subset of the plug-in's ARAFactory::analyzeableContentTypes. To request all analysis types exported by the plug-in, hosts can directly pass analyzeableContentTypes and -Count from the plug-in's ARAFactory. The contentTypes pointer may be only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere.
Note that ARA 2.0 adds the capability for the host to also request the use of a certain processing algorithm via requestProcessingAlgorithmForAudioSource() - if both are used then the algorithm must be selected before requesting the analysis.

◆ requestProcessingAlgorithmForAudioSource()

virtual void ARA::PlugIn::DocumentControllerInterface::requestProcessingAlgorithmForAudioSource ( ARAAudioSourceRef  audioSourceRef,
ARAInt32  algorithmIndex 
)
pure virtualnoexcept

Request that any future analysis of the given audio source should use the given processing algorithm. This method must be implemented if getProcessingAlgorithmsCount() is implemented. This both affects any analysis requested by the host via requestAudioSourceContentAnalysis() as well as any analysis done by the plug-in on demand. Since this typically results in a model graph edit, calling this functions must be guarded by beginEditing() and endEditing(). Note that the plug-in is not required to heed this request if its internal state suggest otherwise, or if the user switches actively to a different algorithm. Also, some algorithms may be "meta" algorithms that will be replaced by a different actual algorithm, such as the "automatic" default algorithm in Melodyne which will pick an appropriate algorithm from the remaining list of algorithms when doing the initial analysis.

◆ restoreObjectsFromArchive()

virtual bool ARA::PlugIn::DocumentControllerInterface::restoreObjectsFromArchive ( ARAArchiveReaderHostRef  archiveReaderHostRef,
const ARARestoreObjectsFilter *  filter 
)
pure virtualnoexcept

Unarchive the internal state of the specified objects. This call can be used both for unarchiving entire documents and for importing arbitrary objects into an existing document. An unarchiving session is conceptually identical to an editing session: after starting the session, the host rebuilds the graph using the regular object creation calls, then makes this call to let the plug-in parse the archive and inject the archived internal state into the graph as indicated by the persistentIDs of the relevant objects. Similarly, when importing objects, the host will perform an editing session and either create new objects or re-use existing objects (potentially adjusting their persistentID), then make this call to inject the imported state.
The optional filter allows for restoring only a subset of the archived states into the graph. It can be NULL, in which case all archived states with matching persistentIDs will be restored. In that case, the call sequence beginEditing(), restoreObjectsFromArchive(), endEditing() is equivalent to the deprecated begin-/endRestoringDocumentFromArchive() for ARA 1, which has been superseded by this call. The host is not required to restore all objects in the archive. Any archived states that are either filtered explicitly, or for which there is no object with a matching persistent ID in the current graph are simply ignored. Since persistent IDs are only required to be unique per document (and not globally), hosts may encounter persistent ID conflicts when importing data from other documents. The optional ARARestoreObjectsFilter provided for this call therefore allows to map between the IDs used in the archive and those used in the current graph if needed.
The host can make multiple calls to restoreObjectsFromArchive() within the same editing session to import objects from multiple archives in one operation. It may even decide to implement its persistency based on partial archives entirely, using several calls to storeObjectsToArchive() with varying filters to split the document into slices appropriate to its implementation, see ARAStoreObjectsFilter::documentData.
Result is kARAFalse if the access to the archive reader failed while trying to read the archive, or if decoding the data failed, kARATrue otherwise. Potential reason for failure include data corruption due to storage hardware failures, or broken dependencies when restoring partial archives as discussed above. The plug-in should try to recover as much state as possible in all cases, and the host should notify the user of such errors. If a failure happened already while reading the archive, the host is aware of this and can augment its error message to the user accordingly. If the failure happens inside the plug-in when decoding the data, the plug-in is responsible for guiding the user as good as possible, e.g. by listing or marking the affected objects. Note that since versioning is expressed through the ARA factory, the host must deal with potential versioning conflicts before making this call, and provide proper UI too.

◆ storeAudioSourceToAudioFileChunk()

virtual bool ARA::PlugIn::DocumentControllerInterface::storeAudioSourceToAudioFileChunk ( ARAArchiveWriterHostRef  archiveWriterHostRef,
ARAAudioSourceRef  audioSourceRef,
ARAPersistentID *  documentArchiveID,
bool *  openAutomatically 
)
pure virtualnoexcept

Create an archive of the internal state of the specified audio source suitable to be embedded into the underlying audio file as ARA audio file chunks, see ARA Audio File Chunks. Hosts must check ARAFactory::supportsStoringAudioFileChunks before enabling users to store audio file chunks for the given plug-in. Archives may only be created from documents that are not being currently edited.
This call differs from using storeObjectsToArchive() with an ARAStoreObjectsFilter in that the plug-in may choose a different internal encoding more suitable for this use case, indicated by returning a documentArchiveID that is likely one of the ARAFactory::compatibleDocumentArchiveIDs rather than the ARAFactory::documentArchiveID. The plug-in also returns whether openAutomatically should be set in the audio file chunk. Result is kARAFalse if the access to the archive writer failed while trying to write the archive, kARATrue otherwise. The host is responsible for alerting the user about archive write errors, see ARAArchivingControllerInterface::writeBytesToArchive().

◆ storeObjectsToArchive()

virtual bool ARA::PlugIn::DocumentControllerInterface::storeObjectsToArchive ( ARAArchiveWriterHostRef  archiveWriterHostRef,
const ARAStoreObjectsFilter *  filter 
)
pure virtualnoexcept

Create a partial archive of the internal state of the specified objects. Archives may only be created from documents that are not being currently edited. The optional filter allows for storing only a subset of the document graph into the archive. It can be NULL, in which case all objects in the graph will be stored. In that case, the call is equivalent to the deprecated storeDocumentToArchive(), which has been superseded by this call. Result is kARAFalse if the access to the archive writer failed while trying to write the archive, kARATrue otherwise. The host is responsible for alerting the user about archive write errors, see ARAArchivingControllerInterface::writeBytesToArchive(). Note that for creating ARA audio file chunk archives, storeAudioSourceToAudioFileChunk() must be used instead, so that the plug-in can pick the correct encoding and return the corresponding (compatible) document archive ID.

◆ updateAudioModificationProperties()

virtual void ARA::PlugIn::DocumentControllerInterface::updateAudioModificationProperties ( ARAAudioModificationRef  audioModificationRef,
PropertiesPtr< ARAAudioModificationProperties >  properties 
)
pure virtualnoexcept

Update the properties of a given audio modification. All properties must be specified, the plug-in will determine which have actually changed.

◆ updateAudioSourceContent()

virtual void ARA::PlugIn::DocumentControllerInterface::updateAudioSourceContent ( ARAAudioSourceRef  audioSourceRef,
const ARAContentTimeRange *  range,
ContentUpdateScopes  scopeFlags 
)
pure virtualnoexcept

Tell the plug-in that the sample data or content information for the given audio source has changed. Not to be called in response to ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged(). The time range may be NULL, this means that the entire audio source is affected. When implementing this call, remember to also flush any caches of the sampled data if needed (see kARAContentUpdateSignalScopeRemainsUnchanged). Creating a new audio source always implies an initial content update for it, i.e. the host will call this function only for later content updates. Since audio sources are persistent, plug-ins should preferably postpone the initial content reading until endEditing() - if the host is restoring the audio source, this will remove the need to read initial content.

◆ updateAudioSourceProperties()

virtual void ARA::PlugIn::DocumentControllerInterface::updateAudioSourceProperties ( ARAAudioSourceRef  audioSourceRef,
PropertiesPtr< ARAAudioSourceProperties >  properties 
)
pure virtualnoexcept

Update the properties of a given audio source. Depending on which properties are changed (see documentation of ARAAudioSourceProperties), the host may not be able to make this call while the plug-in is reading data - in that case, use enableAudioSourceSamplesAccess() accordingly. All properties must be specified, the plug-in will determine which have actually changed.

◆ updateDocumentProperties()

virtual void ARA::PlugIn::DocumentControllerInterface::updateDocumentProperties ( PropertiesPtr< ARADocumentProperties >  properties)
pure virtualnoexcept

Update the properties of the controller's document. All properties must be specified, the plug-in will determine which have actually changed.

◆ updateMusicalContextContent()

virtual void ARA::PlugIn::DocumentControllerInterface::updateMusicalContextContent ( ARAMusicalContextRef  musicalContextRef,
const ARAContentTimeRange *  range,
ContentUpdateScopes  scopeFlags 
)
pure virtualnoexcept

Tell the plug-in to update the information obtainable via content readers for a given musical context. The time range may be NULL, this means that the entire musical content is affected. Creating a new musical context implies an initial content update for it - the host will call this explicitly only for later content updates.

◆ updateMusicalContextProperties()

virtual void ARA::PlugIn::DocumentControllerInterface::updateMusicalContextProperties ( ARAMusicalContextRef  musicalContextRef,
PropertiesPtr< ARAMusicalContextProperties >  properties 
)
pure virtualnoexcept

Update the properties of a given musical context. All properties must be specified, the plug-in will determine which have actually changed.

◆ updatePlaybackRegionProperties()

virtual void ARA::PlugIn::DocumentControllerInterface::updatePlaybackRegionProperties ( ARAPlaybackRegionRef  playbackRegionRef,
PropertiesPtr< ARAPlaybackRegionProperties >  properties 
)
pure virtualnoexcept

Update the properties of a given playback region. All properties must be specified, the plug-in will determine which have actually changed.

◆ updateRegionSequenceProperties()

virtual void ARA::PlugIn::DocumentControllerInterface::updateRegionSequenceProperties ( ARARegionSequenceRef  regionSequence,
PropertiesPtr< ARARegionSequenceProperties >  properties 
)
pure virtualnoexcept

Update the properties of a given region sequence. All properties must be specified, the plug-in will determine which have actually changed.

◆ ARA::PlugIn::DocumentControllerInstance

class ARA::PlugIn::DocumentControllerInstance

Wrapper class for the ARADocumentControllerInstance.

Inheritance diagram for ARA::PlugIn::DocumentControllerInstance:
ARA::SizedStruct< ARA_STRUCT_MEMBER(ARADocumentControllerInstance, documentControllerInterface)>

◆ ARA::PlugIn::PlaybackRendererInterface

class ARA::PlugIn::PlaybackRendererInterface

Base class for implementing ARAPlaybackRendererInterface.

Inheritance diagram for ARA::PlugIn::PlaybackRendererInterface:
ARA::PlugIn::PlaybackRenderer

Assigning the playback region(s) for playback rendering

For details, see ARAPlaybackRendererInterface.

virtual void addPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 
virtual void removePlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 

◆ ARA::PlugIn::EditorRendererInterface

class ARA::PlugIn::EditorRendererInterface

Base class for implementing ARAEditorRendererInterface.

Inheritance diagram for ARA::PlugIn::EditorRendererInterface:
ARA::PlugIn::EditorRenderer

Assigning the playback region(s) for preview while editing

For details, see ARAEditorRendererInterface.

virtual void addPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 
virtual void removePlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0
 
virtual void addRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept=0
 
virtual void removeRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept=0
 

◆ ARA::PlugIn::EditorViewInterface

class ARA::PlugIn::EditorViewInterface

Base class for implementing ARAEditorViewInterface.

Inheritance diagram for ARA::PlugIn::EditorViewInterface:
ARA::PlugIn::EditorView

Host UI notifications

virtual void notifySelection (SizedStructPtr< ARAViewSelection > selection) noexcept=0
 Apply the given host selection to all associated views. This ARA 2.0 addition allows hosts to translate the effects of their selection implementation to a selection of ARA objects that can be interpreted by the plug-in. The command is not strict a setter for the given selection state, it rather notifies the plug-in about relevant user interaction in the host so that it can adopt in whatever way provides the best user experience within the context of the given plug-in design. A plug-in may e.g. implement scrolling to relevant positions, select the playback regions in its inspector(s), or filter the provided objects further depending on user settings. The plug-in also remains free to modify its internal selection at any time through its build-in UI behavior. For example, a plug-in may design its UI around individual regions being edited, or around entire region sequences. Melodyne features both modes, switchable by the user. When editing an individual region, it will always pick the "most suitable" region from the selection, and ignore the other selected regions. Melodyne also implements various ways to switch the editable region sequence(s) or playback region at any time independently from the host selection, as well as a user option to temporarily ignore host selection changes to "pin" the current selection. The same "loose" coupling applies on the host side: the selection sent by the host is not necessarily equal to its actual selection, but rather the best representation of the users' intent. For example, the user may be able to select entities that are not directly represented in the ARA API, but relate to a set of playback regions in some meaningful way. In that case, those regions may be sent as selection. The selection command includes various optional entities that describe the selection on the host side, such as playback regions or region sequences. Host will only explicitly provide those objects that best describe their current selection, but plug-ins can often derive other selections from that, such as calculating a region selection based on sequence selection and time range. Most hosts offer both an object-based selection which typically centers around selected arrange events (playback regions) and tracks (region sequences) versus a time-range based selection that is independent of the arrange events but typically also includes track selection. Both modes shall be distinguished by providing a time range only in the latter case. Some hosts even allow to select multiple time ranges, this should be expressed by sending their union range across the API. For an object-based selection, the time range remains NULL, and plug-ins can calculate an implicit time range from the selected playback regions if desired. Arrange event selection may linked to track selection in a variety of ways. For example, selecting a track may select its events (often filter by playback cycle range), and selecting an event may select its associated track as well. The ARA selection must be always updated to reflect any such linking accordingly. In each object list, objects are ordered by importance, with the most relevant, "focused" object being first. So if a plug-in supports only a single region selection, it should use the first region. If it can only show a single region sequence at a time, it should use the first selected sequence, or if no sequences are included in the selection fall back to the sequence of the first selected region, etc. Each new selection call describes a full selection, i.e. replaces the previous selection. An empty selection is valid and should be communicated by the host, since some plug-ins may need to evaluate this in special cases. Being selected does not affect the life time of the objects - selected objects may be deleted without updating the selection status first. Note that a pointer to this struct and all pointers contained therein are only valid for the duration of the current call receiving the pointer - the data must be evaluated/copied inside the call, and the pointers must not be stored anywhere. More...
 
virtual void notifyHideRegionSequences (ARASize regionSequenceRefsCount, const ARARegionSequenceRef regionSequenceRefs[]) noexcept=0
 Reflect hiding of region sequences in all associated views. Some hosts offer the option to hide arrange tracks from view, so that they are no longer visible, while still being played back regularly. This can be communicated to the plug-in so that it follows suite. Each call implicitly unhides all previously hidden region sequences, so calling this with an empty list makes all sequences visible. The regionSequenceRefs pointer is only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere. It should be NULL if regionSequenceRefsCount is 0. More...
 

Member Function Documentation

◆ notifyHideRegionSequences()

virtual void ARA::PlugIn::EditorViewInterface::notifyHideRegionSequences ( ARASize  regionSequenceRefsCount,
const ARARegionSequenceRef  regionSequenceRefs[] 
)
pure virtualnoexcept

Reflect hiding of region sequences in all associated views. Some hosts offer the option to hide arrange tracks from view, so that they are no longer visible, while still being played back regularly. This can be communicated to the plug-in so that it follows suite. Each call implicitly unhides all previously hidden region sequences, so calling this with an empty list makes all sequences visible. The regionSequenceRefs pointer is only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere. It should be NULL if regionSequenceRefsCount is 0.

◆ notifySelection()

virtual void ARA::PlugIn::EditorViewInterface::notifySelection ( SizedStructPtr< ARAViewSelection >  selection)
pure virtualnoexcept

Apply the given host selection to all associated views. This ARA 2.0 addition allows hosts to translate the effects of their selection implementation to a selection of ARA objects that can be interpreted by the plug-in. The command is not strict a setter for the given selection state, it rather notifies the plug-in about relevant user interaction in the host so that it can adopt in whatever way provides the best user experience within the context of the given plug-in design. A plug-in may e.g. implement scrolling to relevant positions, select the playback regions in its inspector(s), or filter the provided objects further depending on user settings. The plug-in also remains free to modify its internal selection at any time through its build-in UI behavior. For example, a plug-in may design its UI around individual regions being edited, or around entire region sequences. Melodyne features both modes, switchable by the user. When editing an individual region, it will always pick the "most suitable" region from the selection, and ignore the other selected regions. Melodyne also implements various ways to switch the editable region sequence(s) or playback region at any time independently from the host selection, as well as a user option to temporarily ignore host selection changes to "pin" the current selection. The same "loose" coupling applies on the host side: the selection sent by the host is not necessarily equal to its actual selection, but rather the best representation of the users' intent. For example, the user may be able to select entities that are not directly represented in the ARA API, but relate to a set of playback regions in some meaningful way. In that case, those regions may be sent as selection. The selection command includes various optional entities that describe the selection on the host side, such as playback regions or region sequences. Host will only explicitly provide those objects that best describe their current selection, but plug-ins can often derive other selections from that, such as calculating a region selection based on sequence selection and time range. Most hosts offer both an object-based selection which typically centers around selected arrange events (playback regions) and tracks (region sequences) versus a time-range based selection that is independent of the arrange events but typically also includes track selection. Both modes shall be distinguished by providing a time range only in the latter case. Some hosts even allow to select multiple time ranges, this should be expressed by sending their union range across the API. For an object-based selection, the time range remains NULL, and plug-ins can calculate an implicit time range from the selected playback regions if desired. Arrange event selection may linked to track selection in a variety of ways. For example, selecting a track may select its events (often filter by playback cycle range), and selecting an event may select its associated track as well. The ARA selection must be always updated to reflect any such linking accordingly. In each object list, objects are ordered by importance, with the most relevant, "focused" object being first. So if a plug-in supports only a single region selection, it should use the first region. If it can only show a single region sequence at a time, it should use the first selected sequence, or if no sequences are included in the selection fall back to the sequence of the first selected region, etc. Each new selection call describes a full selection, i.e. replaces the previous selection. An empty selection is valid and should be communicated by the host, since some plug-ins may need to evaluate this in special cases. Being selected does not affect the life time of the objects - selected objects may be deleted without updating the selection status first. Note that a pointer to this struct and all pointers contained therein are only valid for the duration of the current call receiving the pointer - the data must be evaluated/copied inside the call, and the pointers must not be stored anywhere.

◆ ARA::PlugIn::PlugInExtensionInstance

class ARA::PlugIn::PlugInExtensionInstance

Wrapper class for ARAPlugInExtensionInstance.

Inheritance diagram for ARA::PlugIn::PlugInExtensionInstance:
ARA::SizedStruct< ARA_STRUCT_MEMBER(ARAPlugInExtensionInstance, editorViewInterface)>