ARA model objects are created and managed by the ARA Document Controller provided by the plug-in. The host uses the factory and management functions of the Document Controller to create a partial copy of its model translated into the ARA world. It is created using a factory which can be either retrieved by scanning the plug-in binaries for a dedicated factory or by requesting it from a living companion plug-in instance. The host is responsible for keeping the document controller alive as long as any objects created through it are still living (kind of implicit ref-counting). This means that its live time is independent of the companion plug-in instances - they may all be gone at some point but the ARA graph may still be accessed through its document controller. The host must also keep the document controller alive as long as any companion plug-in instance which it has bound to it is actively used. The actual destruction of the plug-in instance may be done later (to ease reference counting implementation), but rendering the plug-in, accessing its state or showing its UI is only valid as long as the ARA document controller it has been bound is still alive. Except for some rare, explicitly documented functions like getPlaybackRegionHeadAndTailTime(), the document controller interface must always be called from the same thread - usually hosts will manage their internal model as well as the attached ARA graph from the application's main thread, triggered from the main run loop. If a host decides to use a different thread for maintaining the ARA model, it may need to implement some sort of locking so that its updates on the ARA model thread do not interfere concurrently with the main run loop's event processing as it drives the plug-in's UI code and notification system.
Plug-in developers using C++ ARA Library can implement the ARA::PlugIn::DocumentControllerInterface, or extend the already implemented ARA::PlugIn::DocumentController class as needed. For host developers this interface is wrapped by the ARA::Host::DocumentController.
Classes | |
| struct | ARADocumentControllerInterface |
| Plug-in interface: document controller. The function pointers in this struct must remain valid until the document controller is destroyed by the host. More... | |
Typedefs | |
| typedef struct ARADocumentControllerRefMarkupType * | ARADocumentControllerRef |
| Reference to the plug-in side representation of a document controller (opaque to the host). | |
| struct ARADocumentControllerInterface |
Plug-in interface: document controller. The function pointers in this struct must remain valid until the document controller is destroyed by the host.
Size-based struct versioning | |
See Versioned structs. | |
| ARASize | structSize |
Destruction | |
| void(* | destroyDocumentController )(ARADocumentControllerRef controllerRef) |
| 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. | |
Link back to the factory | |
| const ARAFactory *(* | getFactory )(ARADocumentControllerRef controllerRef) |
| 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. | |
Update management | |
| void(* | beginEditing )(ARADocumentControllerRef controllerRef) |
| 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. | |
| void(* | endEditing )(ARADocumentControllerRef controllerRef) |
| 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. | |
| void(* | notifyModelUpdates )(ARADocumentControllerRef controllerRef) |
| 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(). | |
Document Persistency (extended in ARA 2.0) | |
| ARABool(* | beginRestoringDocumentFromArchive )(ARADocumentControllerRef controllerRef, ARAArchiveReaderHostRef archiveReaderHostRef) |
| Begin an unarchiving session of the document and its associated objects. Deprecated Since version 2_0_Final this call has been superseded by the combination of beginEditing() and restoreObjectsFromArchive(). This allows for optional filtering, but also simplifies both host and plug-in implementation. | |
| ARABool(* | endRestoringDocumentFromArchive )(ARADocumentControllerRef controllerRef, ARAArchiveReaderHostRef archiveReaderHostRef) |
| End an unarchiving session of the document and its associated objects. Deprecated Since version 2_0_Final this call has been superseded by the combination of endEditing() and restoreObjectsFromArchive(). This allows for optional filtering, but also simplifies both host and plug-in implementation. When using API generation 1 or older and using this call, the host must pass the same archiveReaderHostRef as used for beginRestoringDocumentFromArchive(). This way, plug-ins can choose to evaluate the archive upon beginRestoring() or endRestoring(), or even upon both calls if needed. | |
| ARABool(* | storeDocumentToArchive )(ARADocumentControllerRef controllerRef, ARAArchiveWriterHostRef archiveWriterHostRef) |
| Create an archive of the internal state of a given document and all its associated objects. Deprecated Since version 2_0_Final this call has been superseded by storeObjectsToArchive(), which allows for optional filtering, but is otherwise identical. | |
| ARABool(* | restoreObjectsFromArchive )(ARADocumentControllerRef controllerRef, ARAArchiveReaderHostRef archiveReaderHostRef, const ARARestoreObjectsFilter *filter) |
| 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. | |
| ARABool(* | storeObjectsToArchive )(ARADocumentControllerRef controllerRef, ARAArchiveWriterHostRef archiveWriterHostRef, const ARAStoreObjectsFilter *filter) |
| 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. | |
| ARABool(* | storeAudioSourceToAudioFileChunk )(ARADocumentControllerRef controllerRef, ARAArchiveWriterHostRef archiveWriterHostRef, ARAAudioSourceRef audioSourceRef, ARAPersistentID *documentArchiveID, ARABool *openAutomatically) |
| 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(). | |
Document Management | |
As with all model graph edits, calling these functions must be guarded by beginEditing() and endEditing(). | |
| void(* | updateDocumentProperties )(ARADocumentControllerRef controllerRef, const ARADocumentProperties *properties) |
| Update the properties of the controller's document. All properties must be specified, the plug-in will determine which have actually changed. | |
Musical Context Management | |
As with all model graph edits, calling these functions must be guarded by beginEditing() and endEditing(). | |
| ARAMusicalContextRef(* | createMusicalContext )(ARADocumentControllerRef controllerRef, ARAMusicalContextHostRef hostRef, const ARAMusicalContextProperties *properties) |
| Create a new musical context associated with the controller's document. | |
| void(* | updateMusicalContextProperties )(ARADocumentControllerRef controllerRef, ARAMusicalContextRef musicalContextRef, const ARAMusicalContextProperties *properties) |
| Update the properties of a given musical context. All properties must be specified, the plug-in will determine which have actually changed. | |
| void(* | updateMusicalContextContent )(ARADocumentControllerRef controllerRef, ARAMusicalContextRef musicalContextRef, const ARAContentTimeRange *range, ARAContentUpdateFlags flags) |
| 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. | |
| void(* | destroyMusicalContext )(ARADocumentControllerRef controllerRef, ARAMusicalContextRef musicalContextRef) |
| 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. | |
Audio Source Management | |
As with all model graph edits, calling these functions must be guarded by beginEditing() and endEditing(), with the exception of enableAudioSourceSamplesAccess() (which is no model graph edit, but but still has to occur on the ARA model thread). | |
| ARAAudioSourceRef(* | createAudioSource )(ARADocumentControllerRef controllerRef, ARAAudioSourceHostRef hostRef, const ARAAudioSourceProperties *properties) |
| 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. | |
| void(* | updateAudioSourceProperties )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, const ARAAudioSourceProperties *properties) |
| 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. | |
| void(* | updateAudioSourceContent )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, const ARAContentTimeRange *range, ARAContentUpdateFlags flags) |
| 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. | |
| void(* | enableAudioSourceSamplesAccess )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARABool enable) |
| 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. | |
| void(* | deactivateAudioSourceForUndoHistory )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARABool deactivate) |
| 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. | |
| void(* | destroyAudioSource )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef) |
| 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. | |
Audio Modification Management | |
| ARAAudioModificationRef(* | createAudioModification )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARAAudioModificationHostRef hostRef, const ARAAudioModificationProperties *properties) |
| Create a new audio modification associated with the given audio source. | |
| ARAAudioModificationRef(* | cloneAudioModification )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef, ARAAudioModificationHostRef hostRef, const ARAAudioModificationProperties *properties) |
| 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. | |
| void(* | updateAudioModificationProperties )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef, const ARAAudioModificationProperties *properties) |
| Update the properties of a given audio modification. All properties must be specified, the plug-in will determine which have actually changed. | |
| void(* | deactivateAudioModificationForUndoHistory )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef, ARABool deactivate) |
| 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. | |
| void(* | destroyAudioModification )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef) |
| 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. | |
| ARABool(* | isAudioModificationPreservingAudioSourceSignal )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef) |
| 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. | |
Playback Region Management | |
As with all model graph edits, calling these functions must be guarded by beginEditing() and endEditing(). | |
| ARAPlaybackRegionRef(* | createPlaybackRegion )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef, ARAPlaybackRegionHostRef hostRef, const ARAPlaybackRegionProperties *properties) |
| Create a new playback region associated with the given audio modification. | |
| void(* | updatePlaybackRegionProperties )(ARADocumentControllerRef controllerRef, ARAPlaybackRegionRef playbackRegionRef, const ARAPlaybackRegionProperties *properties) |
| Update the properties of a given playback region. All properties must be specified, the plug-in will determine which have actually changed. | |
| void(* | destroyPlaybackRegion )(ARADocumentControllerRef controllerRef, ARAPlaybackRegionRef playbackRegionRef) |
| 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. | |
Content Reader Management | |
Content readers are not model objects but rather auxiliary objects to parse content without extensive data copying, following a standard iterator pattern. As is common with iterators, no changes may be made to the model graph while reading content. Prior to the final release of ARA 2.0, this meant that making any of the content related calls was limited to be done outside of pairs of beginEditing() and endEditing(). Since version 2_0_Final, it is also valid to use them while the document is in editing state, but no other call to this document controller may be made in-between a series of content related calls (except for getFactory() and getPlaybackRegionHeadAndTailTime()). For example for a given audio source such a series of calls typically would be isAudioSourceContentAvailable(), getAudioSourceContentGrade(), createAudioSourceContentReader(), getContentReaderEventCount(), n times getContentReaderDataForEvent(), destroyContentReader(). Typically, content readers are temporary local objects on the stack of the ARA model thread, which naturally satisfies these conditions. This change is mainly intended to support partial persistency introduced with ARA 2.0, since it allows hosts to read content of imported audio sources/modifications to adjust the playback regions accordingly without toggling the editing state of the document back and forth. | |
| ARABool(* | isAudioSourceContentAvailable )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARAContentType contentType) |
| Query whether the given content type is currently available for the given audio source. | |
| ARABool(* | isAudioSourceContentAnalysisIncomplete )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARAContentType contentType) |
| 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). | |
| void(* | requestAudioSourceContentAnalysis )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARASize contentTypesCount, const ARAContentType contentTypes[]) |
| 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. | |
| ARAContentGrade(* | getAudioSourceContentGrade )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARAContentType contentType) |
| Query the current quality of the information provided for the given audio source and content type. | |
| ARAContentReaderRef(* | createAudioSourceContentReader )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARAContentType contentType, const ARAContentTimeRange *range) |
| 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. | |
| ARABool(* | isAudioModificationContentAvailable )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef, ARAContentType contentType) |
| 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(). | |
| ARAContentGrade(* | getAudioModificationContentGrade )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef, ARAContentType contentType) |
| 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(). | |
| ARAContentReaderRef(* | createAudioModificationContentReader )(ARADocumentControllerRef controllerRef, ARAAudioModificationRef audioModificationRef, ARAContentType contentType, const ARAContentTimeRange *range) |
| 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. | |
| ARABool(* | isPlaybackRegionContentAvailable )(ARADocumentControllerRef controllerRef, ARAPlaybackRegionRef playbackRegionRef, ARAContentType contentType) |
| Query whether the given content type is currently available for the given playback region. | |
| ARAContentGrade(* | getPlaybackRegionContentGrade )(ARADocumentControllerRef controllerRef, ARAPlaybackRegionRef playbackRegionRef, ARAContentType contentType) |
| Query the current quality of the information provided for the given playback region and content type. | |
| ARAContentReaderRef(* | createPlaybackRegionContentReader )(ARADocumentControllerRef controllerRef, ARAPlaybackRegionRef playbackRegionRef, ARAContentType contentType, const ARAContentTimeRange *range) |
| 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. | |
| ARAInt32(* | getContentReaderEventCount )(ARADocumentControllerRef controllerRef, ARAContentReaderRef contentReaderRef) |
| Query how many events the given reader exposes. | |
| const void *(* | getContentReaderDataForEvent )(ARADocumentControllerRef controllerRef, ARAContentReaderRef contentReaderRef, ARAInt32 eventIndex) |
| 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. | |
| void(* | destroyContentReader )(ARADocumentControllerRef controllerRef, ARAContentReaderRef contentReaderRef) |
| Destroy the given content reader. | |
Region Sequence Management (added in ARA 2.0) | |
As with all model graph edits, calling these functions must be guarded by beginEditing() and endEditing(). | |
| ARARegionSequenceRef(* | createRegionSequence )(ARADocumentControllerRef controllerRef, ARARegionSequenceHostRef hostRef, const ARARegionSequenceProperties *properties) |
| Create a new region sequence associated with the controller's document. | |
| void(* | updateRegionSequenceProperties )(ARADocumentControllerRef controllerRef, ARARegionSequenceRef regionSequenceRef, const ARARegionSequenceProperties *properties) |
| Update the properties of a given region sequence. All properties must be specified, the plug-in will determine which have actually changed. | |
| void(* | destroyRegionSequence )(ARADocumentControllerRef controllerRef, ARARegionSequenceRef regionSequenceRef) |
| Destroy a given region sequence. The region sequence must no longer be referred to by any playback region when making this call. | |
Playback Region Head and Tail Time (added in ARA 2.0) | |
Depending on the specific DSP performed by the plug-in, the resulting signal for any region may exceed the region borders. Among other use cases such as delays, this will typically happen when the content based fades are enabled. Reporting this potential excess of signal both at start and end of a region allows for the host to adjust their rendering so that it includes head and tail time, or else fade the signal at the region borders to avoid crackles. This function can be called either from the model thread or from any (realtime or offline) audio rendering thread. If edits that the host performs on the model affect the head or tail times (such as toggling content based fades on or off), the new values can only be reliably queried on the model thread once endEditing() has returned. On audio threads, they can only be reliably queried until all render calls that may have occurred concurrently with endEditing() have returned. | |
| void(* | getPlaybackRegionHeadAndTailTime )(ARADocumentControllerRef controllerRef, ARAPlaybackRegionRef playbackRegionRef, ARATimeDuration *headTime, ARATimeDuration *tailTime) |
| 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). | |
Processing Algorithm Selection (added in ARA 2.0) | |
Many plug-ins feature a set of different processing algorithms, each suited for a given kind of audio material. When analyzing the audio, plug-ins either try to automatically determine the appropriate algorithm that best matches the nature of the given material, or delegate this decision to the user. This fundamental selection may affect all further processing of the audio source - in addition to the analysis results, internal editing and rendering parameters and even the entire UI may change. Accordingly, changing this selection may invalidate some or all edits done by the user in the audio modifications based on the audio source. To avoid such data loss, making this selection appropriately should always be the first step when working with audio sources. By exporting the list of processing algorithms here, hosts can implement this selection, based on their knowledge about the origin of the audio material. Some hosts allow for configuring their built-in detection in a very similar way on a per-track basis, usually via a menu. They can use this technique for compatible ARA plug-ins as well. Host might also be able to implicitly deduce an appropriate processing algorithm. For example, when adding a new audio source to a region sequence that already refers to a set of previously analyzed audio sources which all use the same detection algorithm, this algorithm is likely appropriate for the new audio source as well. Along the same lines, when recording a new take of some material that already has been analyzed by the plug-in, it is reasonable to use the same algorithm for the new take. Note that each processing algorithm must implement detection for all content types exported by the plug-in, albeit the detection quality may likely be different for some types. Plug-ins should keep the list of available processing algorithms restricted to the smallest reasonable set - after all, in an ideal (but currently not achievable) implementation, a single detection algorithm would be powerful enough to cover all types of material flawlessly. | |
| ARAInt32(* | getProcessingAlgorithmsCount )(ARADocumentControllerRef controllerRef) |
| 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. | |
| const ARAProcessingAlgorithmProperties *(* | getProcessingAlgorithmProperties )(ARADocumentControllerRef controllerRef, ARAInt32 algorithmIndex) |
| 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. | |
| ARAInt32(* | getProcessingAlgorithmForAudioSource )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef) |
| 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. | |
| void(* | requestProcessingAlgorithmForAudioSource )(ARADocumentControllerRef controllerRef, ARAAudioSourceRef audioSourceRef, ARAInt32 algorithmIndex) |
| 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. | |
License Management (added in ARA 2.0) | |
If using ARA plug-ins for regular editing, their UI is shown and they can implement all license handling fully transparent for the host within their regular UI. If however the host is using the plug-in as internal engine for analysis (e.g. audio-to-MIDI conversion) or for time-stretching, it will typically not open the plug-in UI, and accordingly must then deal with potentially missing licenses that the plug-in requires to perform the desired tasks. As an example, Melodyne's analysis capabilities are only available when running Melodyne essential or higher, i.e. they are not supported by an unlicensed "playback-only" installation. | |
| ARABool(* | isLicensedForCapabilities )(ARADocumentControllerRef controllerRef, ARABool runModalActivationDialogIfNeeded, ARASize contentTypesCount, const ARAContentType contentTypes[], ARAPlaybackTransformationFlags transformationFlags) |
| 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. | |