Wrappers for the interfaces used to communicate with and control ARA plug-ins.
Classes | |
| class | ARA::Host::DocumentController |
| Wrapper class for the plug-in ARADocumentControllerInterface. More... | |
| class | ARA::Host::DocumentControllerInstance |
| Optional wrapper class for the plug-in binary ARADocumentControllerInstance. More... | |
| class | ARA::Host::PlaybackRenderer |
| Wrapper class for the ARAPlaybackRendererInterface provided by the plug-in. More... | |
| class | ARA::Host::EditorRenderer |
| Wrapper class for the ARAEditorRendererInterface provided by the plug-in. More... | |
| class | ARA::Host::EditorView |
| Wrapper class for the ARAEditorViewInterface provided by the plug-in. More... | |
Typedefs | |
| template<ARAContentType contentType> | |
| using | ARA::Host::ContentReader = ARA::ContentReader< contentType, DocumentController, ARAContentReaderRef > |
| Wrapper class for convenient and type safe content reading. More... | |
| class ARA::Host::DocumentController |
Wrapper class for the plug-in ARADocumentControllerInterface.
Destruction | |
| void | destroyDocumentController () noexcept |
| 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 | |
| const ARAFactory * | getFactory () noexcept |
| 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. More... | |
Update Management | |
| void | beginEditing () noexcept |
| 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... | |
| void | endEditing () noexcept |
| 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... | |
| void | notifyModelUpdates () noexcept |
| 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 | |
| bool | beginRestoringDocumentFromArchive (ARAArchiveReaderHostRef archiveReaderHostRef) noexcept |
| 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. More... | |
| bool | endRestoringDocumentFromArchive (ARAArchiveReaderHostRef archiveReaderHostRef) noexcept |
| 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. More... | |
| bool | storeDocumentToArchive (ARAArchiveWriterHostRef archiveWriterHostRef) noexcept |
| 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. More... | |
| bool | supportsPartialPersistency () noexcept |
| If supporting both types of persistency, this call can be used to pick the appropriate type for the given plug-in. | |
| bool | restoreObjectsFromArchive (ARAArchiveReaderHostRef archiveReaderHostRef, const ARARestoreObjectsFilter *filter) noexcept |
| 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... | |
| bool | storeObjectsToArchive (ARAArchiveWriterHostRef archiveWriterHostRef, const ARAStoreObjectsFilter *filter) noexcept |
| 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... | |
| bool | supportsStoringAudioFileChunks () noexcept |
| Test whether storeAudioSourceToAudioFileChunk () is supported by the plug-in. | |
| bool | storeAudioSourceToAudioFileChunk (ARAArchiveWriterHostRef archiveWriterHostRef, ARAAudioSourceRef audioSourceRef, ARAPersistentID *documentArchiveID, bool *openAutomatically) noexcept |
| 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 | |
| void | updateDocumentProperties (const ARADocumentProperties *properties) noexcept |
| 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 | |
| ARAMusicalContextRef | createMusicalContext (ARAMusicalContextHostRef hostRef, const ARAMusicalContextProperties *properties) noexcept |
| Create a new musical context associated with the controller's document. More... | |
| void | updateMusicalContextProperties (ARAMusicalContextRef musicalContextRef, const ARAMusicalContextProperties *properties) noexcept |
| Update the properties of a given musical context. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| void | updateMusicalContextContent (ARAMusicalContextRef musicalContextRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept |
| 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... | |
| void | destroyMusicalContext (ARAMusicalContextRef musicalContextRef) noexcept |
| 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 | |
| ARARegionSequenceRef | createRegionSequence (ARARegionSequenceHostRef hostRef, const ARARegionSequenceProperties *properties) noexcept |
| Create a new region sequence associated with the controller's document. More... | |
| void | updateRegionSequenceProperties (ARARegionSequenceRef regionSequenceRef, const ARARegionSequenceProperties *properties) noexcept |
| Update the properties of a given region sequence. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| void | destroyRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept |
| 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 | |
| ARAAudioSourceRef | createAudioSource (ARAAudioSourceHostRef hostRef, const ARAAudioSourceProperties *properties) noexcept |
| 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... | |
| void | updateAudioSourceProperties (ARAAudioSourceRef audioSourceRef, const ARAAudioSourceProperties *properties) noexcept |
| 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... | |
| void | updateAudioSourceContent (ARAAudioSourceRef audioSourceRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept |
| 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... | |
| void | enableAudioSourceSamplesAccess (ARAAudioSourceRef audioSourceRef, bool enable) noexcept |
| 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... | |
| void | deactivateAudioSourceForUndoHistory (ARAAudioSourceRef audioSourceRef, bool deactivate) noexcept |
| 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... | |
| void | destroyAudioSource (ARAAudioSourceRef audioSourceRef) noexcept |
| 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 | |
| ARAAudioModificationRef | createAudioModification (ARAAudioSourceRef audioSourceRef, ARAAudioModificationHostRef hostRef, const ARAAudioModificationProperties *properties) noexcept |
| Create a new audio modification associated with the given audio source. More... | |
| ARAAudioModificationRef | cloneAudioModification (ARAAudioModificationRef audioModificationRef, ARAAudioModificationHostRef hostRef, const ARAAudioModificationProperties *properties) noexcept |
| 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... | |
| void | updateAudioModificationProperties (ARAAudioModificationRef audioModificationRef, const ARAAudioModificationProperties *properties) noexcept |
| Update the properties of a given audio modification. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| bool | supportsIsAudioModificationPreservingAudioSourceSignal () noexcept |
| Test whether isAudioModificationPreservingAudioSourceSignal () is supported by the plug-in. | |
| bool | isAudioModificationPreservingAudioSourceSignal (ARAAudioModificationRef audioModificationRef) noexcept |
| 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... | |
| void | deactivateAudioModificationForUndoHistory (ARAAudioModificationRef audioModificationRef, bool deactivate) noexcept |
| 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... | |
| void | destroyAudioModification (ARAAudioModificationRef audioModificationRef) noexcept |
| 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 | |
(getPlaybackRegionHeadAndTailTime () resolves to no-op for pre-ARA-2.0 plug-ins and always returns 0.0 as times) | |
| ARAPlaybackRegionRef | createPlaybackRegion (ARAAudioModificationRef audioModificationRef, ARAPlaybackRegionHostRef hostRef, const ARAPlaybackRegionProperties *properties) noexcept |
| Create a new playback region associated with the given audio modification. More... | |
| void | updatePlaybackRegionProperties (ARAPlaybackRegionRef playbackRegionRef, const ARAPlaybackRegionProperties *properties) noexcept |
| Update the properties of a given playback region. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| void | getPlaybackRegionHeadAndTailTime (ARAPlaybackRegionRef playbackRegionRef, ARATimeDuration *headTime, ARATimeDuration *tailTime) noexcept |
| 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... | |
| void | destroyPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept |
| 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... | |
Content Reader Management | |
See ContentReader<> class below which conveniently wraps some of these calls. | |
| bool | isAudioSourceContentAvailable (ARAAudioSourceRef audioSourceRef, ARAContentType type) noexcept |
| Query whether the given content type is currently available for the given audio source. More... | |
| ARAContentGrade | getAudioSourceContentGrade (ARAAudioSourceRef audioSourceRef, ARAContentType type) noexcept |
| Query the current quality of the information provided for the given audio source and content type. More... | |
| ARAContentReaderRef | createAudioSourceContentReader (ARAAudioSourceRef audioSourceRef, ARAContentType type, const ARAContentTimeRange *range) noexcept |
| 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... | |
| bool | isAudioModificationContentAvailable (ARAAudioModificationRef audioModificationRef, ARAContentType type) noexcept |
| 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... | |
| ARAContentGrade | getAudioModificationContentGrade (ARAAudioModificationRef audioModificationRef, ARAContentType type) noexcept |
| 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... | |
| ARAContentReaderRef | createAudioModificationContentReader (ARAAudioModificationRef audioModificationRef, ARAContentType type, const ARAContentTimeRange *range) noexcept |
| 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... | |
| bool | isPlaybackRegionContentAvailable (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type) noexcept |
| Query whether the given content type is currently available for the given playback region. More... | |
| ARAContentGrade | getPlaybackRegionContentGrade (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type) noexcept |
| Query the current quality of the information provided for the given playback region and content type. More... | |
| ARAContentReaderRef | createPlaybackRegionContentReader (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type, const ARAContentTimeRange *range) noexcept |
| 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... | |
| ARAInt32 | getContentReaderEventCount (ARAContentReaderRef contentReaderRef) noexcept |
| Query how many events the given reader exposes. More... | |
| const void * | getContentReaderDataForEvent (ARAContentReaderRef contentReaderRef, ARAInt32 eventIndex) noexcept |
| 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... | |
| void | destroyContentReader (ARAContentReaderRef contentReaderRef) noexcept |
| Destroy the given content reader. More... | |
Controlling Analysis | |
| bool | isAudioSourceContentAnalysisIncomplete (ARAAudioSourceRef audioSourceRef, ARAContentType contentType) noexcept |
| 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... | |
| void | requestAudioSourceContentAnalysis (ARAAudioSourceRef audioSourceRef, ARASize contentTypesCount, const ARAContentType contentTypes[]) noexcept |
| 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... | |
| bool | supportsProcessingAlgorithms () noexcept |
| Test whether the plug-in supports managing processing algorithms. | |
| ARAInt32 | getProcessingAlgorithmsCount () noexcept |
| 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... | |
| const ARAProcessingAlgorithmProperties * | getProcessingAlgorithmProperties (ARAInt32 algorithmIndex) noexcept |
| 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... | |
| ARAInt32 | getProcessingAlgorithmForAudioSource (ARAAudioSourceRef audioSourceRef) noexcept |
| 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... | |
| void | requestProcessingAlgorithmForAudioSource (ARAAudioSourceRef audioSourceRef, ARAInt32 algorithmIndex) noexcept |
| 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 | |
| bool | isLicensedForCapabilities (bool runModalActivationDialogIfNeeded, ARASize contentTypesCount, const ARAContentType contentTypes[], ARAPlaybackTransformationFlags transformationFlags) noexcept |
| 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... | |
Additional Inherited Members | |
Public Member Functions inherited from ARA::InterfaceInstance< ARADocumentControllerRef, ARADocumentControllerInterface > | |
| ARADocumentControllerRef | getRef () const noexcept |
Retrieve the ARA reference associated with Interface. | |
| const SizedStructPtr< ARADocumentControllerInterface > & | getInterface () const noexcept |
Retrieve the underlying Interface pointer. | |
| bool | isProvided () const noexcept |
| Returns whether or not an implementation of the interface was provided. | |
Protected Types inherited from ARA::InterfaceInstance< ARADocumentControllerRef, ARADocumentControllerInterface > | |
| using | BaseType = InterfaceInstance |
InterfaceInstance alias, to allow derived classes to easily reference their templated base class. | |
Protected Member Functions inherited from ARA::InterfaceInstance< ARADocumentControllerRef, ARADocumentControllerInterface > | |
| InterfaceInstance (ARADocumentControllerRef ref, const ARADocumentControllerInterface *ifc) noexcept | |
Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor. | |
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
Create a new audio modification associated with the given audio source.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
Create a new musical context associated with the controller's document.
|
noexcept |
Create a new playback region associated with the given audio modification.
|
noexcept |
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.
|
noexcept |
Create a new region sequence associated with the controller's document.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
Destroy the given content reader.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
Destroy a given region sequence. The region sequence must no longer be referred to by any playback region when making this call.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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().
|
noexcept |
Query the current quality of the information provided for the given audio source and content type.
|
noexcept |
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.
|
noexcept |
Query how many events the given reader exposes.
|
noexcept |
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.
|
noexcept |
Query the current quality of the information provided for the given playback region and content type.
|
noexcept |
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).
|
noexcept |
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.
|
noexcept |
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.
Supporting processing algorithms is optional, make sure to test supportsProcessingAlgorithms() before calling this function.
|
noexcept |
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.
|
noexcept |
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().
|
noexcept |
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.
|
noexcept |
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).
|
noexcept |
Query whether the given content type is currently available for the given audio source.
|
noexcept |
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.
Returns true if plug-in does not support the optional license management.
|
noexcept |
Query whether the given content type is currently available for the given playback region.
|
noexcept |
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().
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
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().
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
Update the properties of a given audio modification. All properties must be specified, the plug-in will determine which have actually changed.
|
noexcept |
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.
|
noexcept |
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.
|
noexcept |
Update the properties of the controller's document. All properties must be specified, the plug-in will determine which have actually changed.
|
noexcept |
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.
|
noexcept |
Update the properties of a given musical context. All properties must be specified, the plug-in will determine which have actually changed.
|
noexcept |
Update the properties of a given playback region. All properties must be specified, the plug-in will determine which have actually changed.
|
noexcept |
Update the properties of a given region sequence. All properties must be specified, the plug-in will determine which have actually changed.
| class ARA::Host::DocumentControllerInstance |
Optional wrapper class for the plug-in binary ARADocumentControllerInstance.
Deprecated
Hosts should to instead use DocumentController directly.
| class ARA::Host::PlaybackRenderer |
Wrapper class for the ARAPlaybackRendererInterface provided by the plug-in.
Assigning the playback region(s) for playback rendering | |
For details, see ARAPlaybackRendererInterface. | |
| void | addPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept |
| void | removePlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept |
Additional Inherited Members | |
Public Member Functions inherited from ARA::InterfaceInstance< ARAPlaybackRendererRef, ARAPlaybackRendererInterface > | |
| ARAPlaybackRendererRef | getRef () const noexcept |
Retrieve the ARA reference associated with Interface. | |
| const SizedStructPtr< ARAPlaybackRendererInterface > & | getInterface () const noexcept |
Retrieve the underlying Interface pointer. | |
| bool | isProvided () const noexcept |
| Returns whether or not an implementation of the interface was provided. | |
Protected Types inherited from ARA::InterfaceInstance< ARAPlaybackRendererRef, ARAPlaybackRendererInterface > | |
| using | BaseType = InterfaceInstance |
InterfaceInstance alias, to allow derived classes to easily reference their templated base class. | |
Protected Member Functions inherited from ARA::InterfaceInstance< ARAPlaybackRendererRef, ARAPlaybackRendererInterface > | |
| InterfaceInstance (ARAPlaybackRendererRef ref, const ARAPlaybackRendererInterface *ifc) noexcept | |
Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor. | |
| class ARA::Host::EditorRenderer |
Wrapper class for the ARAEditorRendererInterface provided by the plug-in.
Assigning the playback region(s) for preview while editing | |
For details, see ARAEditorRendererInterface. | |
| void | addPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept |
| void | removePlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept |
| void | addRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept |
| void | removeRegionSequence (ARARegionSequenceRef regionSequenceRef) noexcept |
Additional Inherited Members | |
Public Member Functions inherited from ARA::InterfaceInstance< ARAEditorRendererRef, ARAEditorRendererInterface > | |
| ARAEditorRendererRef | getRef () const noexcept |
Retrieve the ARA reference associated with Interface. | |
| const SizedStructPtr< ARAEditorRendererInterface > & | getInterface () const noexcept |
Retrieve the underlying Interface pointer. | |
| bool | isProvided () const noexcept |
| Returns whether or not an implementation of the interface was provided. | |
Protected Types inherited from ARA::InterfaceInstance< ARAEditorRendererRef, ARAEditorRendererInterface > | |
| using | BaseType = InterfaceInstance |
InterfaceInstance alias, to allow derived classes to easily reference their templated base class. | |
Protected Member Functions inherited from ARA::InterfaceInstance< ARAEditorRendererRef, ARAEditorRendererInterface > | |
| InterfaceInstance (ARAEditorRendererRef ref, const ARAEditorRendererInterface *ifc) noexcept | |
Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor. | |
| class ARA::Host::EditorView |
Wrapper class for the ARAEditorViewInterface provided by the plug-in.
Host UI notifications | |
| void | notifySelection (const ARAViewSelection *selection) noexcept |
| 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... | |
| void | notifyHideRegionSequences (ARASize regionSequenceRefsCount, const ARARegionSequenceRef regionSequenceRefs[]) noexcept |
| 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... | |
Additional Inherited Members | |
Public Member Functions inherited from ARA::InterfaceInstance< ARAEditorViewRef, ARAEditorViewInterface > | |
| ARAEditorViewRef | getRef () const noexcept |
Retrieve the ARA reference associated with Interface. | |
| const SizedStructPtr< ARAEditorViewInterface > & | getInterface () const noexcept |
Retrieve the underlying Interface pointer. | |
| bool | isProvided () const noexcept |
| Returns whether or not an implementation of the interface was provided. | |
Protected Types inherited from ARA::InterfaceInstance< ARAEditorViewRef, ARAEditorViewInterface > | |
| using | BaseType = InterfaceInstance |
InterfaceInstance alias, to allow derived classes to easily reference their templated base class. | |
Protected Member Functions inherited from ARA::InterfaceInstance< ARAEditorViewRef, ARAEditorViewInterface > | |
| InterfaceInstance (ARAEditorViewRef ref, const ARAEditorViewInterface *ifc) noexcept | |
Constructor for derived classes to wrap a ref and interface pointer. The derived classes typically read these values from an instance struct which is passed to their public c'tor. | |
|
noexcept |
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.
|
noexcept |
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.
| using ARA::Host::ContentReader = typedef ARA::ContentReader<contentType, DocumentController, ARAContentReaderRef> |
Wrapper class for convenient and type safe content reading.
| contentType | The type of ARA content event that can be read. |