Customizable default implementation of DocumentControllerInterface.
Classes | |
| class | ARA::PlugIn::DocumentControllerDelegate |
Customization interface for DocumentController, separated into subclass to enhance clarity. Do not use directly, subclass DocumentController instead. Subclasses of DocumentController should implement these protected do/will/did functions as needed. For example, if subclassing AudioSource you should override doCreateAudioSource() and return a newly allocated instance of your custom AudioSource subclass. Functions named do.. are expected to perform the requested operation, whereas functions named will../did.. provide hooks to augment operations already performed by the SDK implementation. For example, if you'd like to know when an audio source's sample access has been enabled, you can override didEnableAudioSourceSamplesAccess(), which will be called directly after the sample access state changes. Accordingly, if you need to take some action before access is disabled, override willEnableAudioSourceSamplesAccess(). When overriding any of these functions, you don't need to call the base class implementation from your overrides. More... | |
| class | ARA::PlugIn::DocumentController |
| Customizable default implementation of DocumentControllerInterface. More... | |
| class ARA::PlugIn::DocumentControllerDelegate |
Customization interface for DocumentController, separated into subclass to enhance clarity. Do not use directly, subclass DocumentController instead. Subclasses of DocumentController should implement these protected do/will/did functions as needed. For example, if subclassing AudioSource you should override doCreateAudioSource() and return a newly allocated instance of your custom AudioSource subclass. Functions named do.. are expected to perform the requested operation, whereas functions named will../did.. provide hooks to augment operations already performed by the SDK implementation. For example, if you'd like to know when an audio source's sample access has been enabled, you can override didEnableAudioSourceSamplesAccess(), which will be called directly after the sample access state changes. Accordingly, if you need to take some action before access is disabled, override willEnableAudioSourceSamplesAccess(). When overriding any of these functions, you don't need to call the base class implementation from your overrides.
Plug-In Instance Management Hooks | |
These functions are conditionally called from createPlugInExtensionWithRoles(), depending on the roles fulfilled by the plug-in instance. | |
| virtual PlaybackRenderer * | doCreatePlaybackRenderer () noexcept=0 |
| Override to return a custom subclass instance of PlaybackRenderer. | |
| virtual void | doDestroyPlaybackRenderer (PlaybackRenderer *playbackRenderer) noexcept=0 |
| Override if not using plain new in doCreatePlaybackRenderer () or relying on reference counting for your subclass. | |
| virtual EditorRenderer * | doCreateEditorRenderer () noexcept=0 |
| Override to return a custom subclass instance of EditorRenderer. | |
| virtual void | doDestroyEditorRenderer (EditorRenderer *editorRenderer) noexcept=0 |
| Override if not using plain new in doCreateEditorRenderer () or relying on reference counting for your subclass. | |
| virtual EditorView * | doCreateEditorView () noexcept=0 |
| Override to return a custom subclass instance of EditorView. | |
| virtual void | doDestroyEditorView (EditorView *editorView) noexcept=0 |
| Override if not using plain new in doCreateEditorView () or relying on reference counting for your subclass. | |
| DocumentControllerDelegate (const PlugInEntry *entry) noexcept | |
| Override to return a custom subclass instance of PlaybackRenderer. | |
| virtual | ~DocumentControllerDelegate () |
| Override to return a custom subclass instance of PlaybackRenderer. | |
| const PlugInEntry * | getPlugInEntry () const noexcept |
| Override to return a custom subclass instance of PlaybackRenderer. | |
Update Management Hooks | |
| virtual void | willBeginEditing () noexcept |
| Override to customize behavior before a Document edit cycle begins. | |
| virtual void | didEndEditing () noexcept |
| Override to customize behavior after a Document edit cycle ends. | |
| virtual void | willNotifyModelUpdates () noexcept |
| Override to customize behavior before sending update notifications to the host. | |
| virtual void | didNotifyModelUpdates () noexcept |
| Override to customize behavior after sending update notifications to the host. | |
Archiving Hooks | |
| virtual bool | doRestoreObjectsFromArchive (HostArchiveReader *archiveReader, const RestoreObjectsFilter *filter) noexcept=0 |
| Override to implement restoreObjectsFromArchive(). | |
| virtual bool | doStoreObjectsToArchive (HostArchiveWriter *archiveWriter, const StoreObjectsFilter *filter) noexcept=0 |
| Override to implement storeObjectsToArchive(). | |
| virtual bool | doStoreAudioSourceToAudioFileChunk (HostArchiveWriter *archiveWriter, AudioSource *audioSource, ARAPersistentID *documentArchiveID, bool *openAutomatically) noexcept |
| Override to customize storeAudioSourceToAudioFileChunk() if needed. The default implementation calls doStoreObjectsToArchive() with an appropriate StoreObjectsFilter and sets openAutomatically to false - check if your internal data format allows for optimizing this according to the criteria documented for storeAudioSourceToAudioFileChunk(). | |
Document Management Hooks | |
| virtual Document * | doCreateDocument () noexcept=0 |
| Override to return a custom subclass instance of Document when initializing the DocumentController. | |
| virtual void | doDestroyDocument (Document *document) noexcept=0 |
| Override if not using plain new in doCreateDocument () or relying on reference counting for your subclass. | |
| virtual void | willUpdateDocumentProperties (Document *document, PropertiesPtr< ARADocumentProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateDocumentProperties(). | |
| virtual void | didUpdateDocumentProperties (Document *document) noexcept |
| Override to customize post-update behavior of updateDocumentProperties(). | |
| virtual void | didAddMusicalContextToDocument (Document *document, MusicalContext *musicalContext) noexcept |
Override to customize behavior after createMusicalContext() adds musicalContext to document. | |
| virtual void | willRemoveMusicalContextFromDocument (Document *document, MusicalContext *musicalContext) noexcept |
Override to customize behavior before destroyMusicalContext() removes musicalContext from document. | |
| virtual void | willReorderMusicalContextsInDocument (Document *document) noexcept |
Override to customize behavior before sorting all MusicalContext instances in document by ARAMusicalContextProperties::orderIndex. | |
| virtual void | didReorderMusicalContextsInDocument (Document *document) noexcept |
Override to customize behavior after sorting all MusicalContext instances in document by ARAMusicalContextProperties::orderIndex. | |
| virtual void | didAddRegionSequenceToDocument (Document *document, RegionSequence *regionSequence) noexcept |
Override to customize behavior after createRegionSequence() adds regionSequence to document. | |
| virtual void | willRemoveRegionSequenceFromDocument (Document *document, RegionSequence *regionSequence) noexcept |
Override to customize behavior before destroyRegionSequence() removes regionSequence from document. | |
| virtual void | willReorderRegionSequencesInDocument (Document *document) noexcept |
Override to customize behavior before sorting all RegionSequence instances in document by ARARegionSequenceProperties::orderIndex. | |
| virtual void | didReorderRegionSequencesInDocument (Document *document) noexcept |
Override to customize behavior after sorting all RegionSequence instances in document by ARARegionSequenceProperties::orderIndex. | |
| virtual void | didAddAudioSourceToDocument (Document *document, AudioSource *audioSource) noexcept |
Override to customize behavior after createAudioSource() adds audioSource to document. | |
| virtual void | willRemoveAudioSourceFromDocument (Document *document, AudioSource *audioSource) noexcept |
Override to customize behavior before destroyAudioSource() removes audioSource from document. | |
| virtual void | willDestroyDocument (Document *document) noexcept |
Override to customize behavior before document is destroyed during destroyDocumentController(). | |
Musical Context Management Hooks | |
| virtual MusicalContext * | doCreateMusicalContext (Document *document, ARAMusicalContextHostRef hostRef) noexcept=0 |
| Override to return a custom subclass instance of MusicalContext from createMusicalContext(). | |
| virtual void | doDestroyMusicalContext (MusicalContext *musicalContext) noexcept=0 |
| Override if not using plain new in doCreateMusicalContext () or relying on reference counting for your subclass. | |
| virtual void | willUpdateMusicalContextProperties (MusicalContext *musicalContext, PropertiesPtr< ARAMusicalContextProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateMusicalContextProperties(). | |
| virtual void | didUpdateMusicalContextProperties (MusicalContext *musicalContext) noexcept |
| Override to customize post-update behavior of updateMusicalContextProperties(). | |
| virtual void | doUpdateMusicalContextContent (MusicalContext *musicalContext, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Override to implement updateMusicalContextContent(). | |
| virtual void | didAddRegionSequenceToMusicalContext (MusicalContext *musicalContext, RegionSequence *regionSequence) noexcept |
Override to customize behavior after createRegionSequence() or updateRegionSequenceProperties() adds regionSequence to musicalContext. | |
| virtual void | willRemoveRegionSequenceFromMusicalContext (MusicalContext *musicalContext, RegionSequence *regionSequence) noexcept |
Override to customize behavior before destroyRegionSequence() or updateRegionSequenceProperties() removes regionSequence to musicalContext. | |
| virtual void | willReorderRegionSequencesInMusicalContext (MusicalContext *musicalContext) noexcept |
Override to customize behavior before sorting all RegionSequence instances in musicalContext by ARARegionSequenceProperties::orderIndex. | |
| virtual void | didReorderRegionSequencesInMusicalContext (MusicalContext *musicalContext) noexcept |
Override to customize behavior after sorting all RegionSequence instances in musicalContext by ARARegionSequenceProperties::orderIndex. | |
| virtual void | willDestroyMusicalContext (MusicalContext *musicalContext) noexcept |
Override to customize behavior before musicalContext is destroyed during destroyMusicalContext(). | |
Region Sequence Management Hooks | |
| virtual RegionSequence * | doCreateRegionSequence (Document *document, ARARegionSequenceHostRef hostRef) noexcept=0 |
| Override to return a custom subclass instance of RegionSequence from createRegionSequence(). | |
| virtual void | doDestroyRegionSequence (RegionSequence *regionSequence) noexcept=0 |
| Override if not using plain new in doCreateRegionSequence () or relying on reference counting for your subclass. | |
| virtual void | willUpdateRegionSequenceProperties (RegionSequence *regionSequence, PropertiesPtr< ARARegionSequenceProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateRegionSequenceProperties(). | |
| virtual void | didUpdateRegionSequenceProperties (RegionSequence *regionSequence) noexcept |
| Override to customize pre-update behavior of updateRegionSequenceProperties(). | |
| virtual void | didAddPlaybackRegionToRegionSequence (RegionSequence *regionSequence, PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior after createPlaybackRegion() or updatePlaybackRegionProperties() adds playbackRegion to regionSequence. | |
| virtual void | willRemovePlaybackRegionFromRegionSequence (RegionSequence *regionSequence, PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior before destroyPlaybackRegion() or updatePlaybackRegionProperties() removes playbackRegion from regionSequence. | |
| virtual void | willDestroyRegionSequence (RegionSequence *regionSequence) noexcept |
Override to customize behavior before regionSequence is destroyed during destroyRegionSequence(). | |
Audio Source Management Hooks | |
| virtual AudioSource * | doCreateAudioSource (Document *document, ARAAudioSourceHostRef hostRef) noexcept=0 |
| Override to return a custom subclass instance of AudioSource from createAudioSource(). | |
| virtual void | doDestroyAudioSource (AudioSource *audioSource) noexcept=0 |
| Override if not using plain new in doCreateAudioSource () or relying on reference counting for your subclass. | |
| virtual void | willUpdateAudioSourceProperties (AudioSource *audioSource, PropertiesPtr< ARAAudioSourceProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateAudioSourceProperties(). | |
| virtual void | didUpdateAudioSourceProperties (AudioSource *audioSource) noexcept |
| Override to customize pre-update behavior of updateAudioSourceProperties(). | |
| virtual void | doUpdateAudioSourceContent (AudioSource *audioSource, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Override to implement updateAudioSourceContent(). | |
| virtual void | willEnableAudioSourceSamplesAccess (AudioSource *audioSource, bool enable) noexcept=0 |
Override to customize behavior before enableAudioSourceSamplesAccess() changes audioSource's sample access state. | |
| virtual void | didEnableAudioSourceSamplesAccess (AudioSource *audioSource, bool enable) noexcept=0 |
Override to customize behavior after enableAudioSourceSamplesAccess() changes audioSource's sample access state. | |
| virtual void | willDeactivateAudioSourceForUndoHistory (AudioSource *audioSource, bool deactivate) noexcept |
Override to customize behavior before deactivateAudioSourceForUndoHistory() changes audioSource's activated state. | |
| virtual void | didDeactivateAudioSourceForUndoHistory (AudioSource *audioSource, bool deactivate) noexcept |
Override to customize behavior after deactivateAudioSourceForUndoHistory() changes audioSource's activated state. | |
| virtual void | didAddAudioModificationToAudioSource (AudioSource *audioSource, AudioModification *audioModification) noexcept |
Override to customize behavior after createAudioModification() or updateAudioModificationProperties() adds audioModification to audioSource. | |
| virtual void | willRemoveAudioModificationFromAudioSource (AudioSource *audioSource, AudioModification *audioModification) noexcept |
Override to customize behavior before destroyAudioModification() or updateAudioModificationProperties() removes audioModification from audioSource. | |
| virtual void | willDestroyAudioSource (AudioSource *audioSource) noexcept |
Override to customize behavior before audioSource is destroyed during destroyAudioSource(). | |
Audio Modification Management Hooks | |
| virtual AudioModification * | doCreateAudioModification (AudioSource *audioSource, ARAAudioModificationHostRef hostRef, const AudioModification *optionalModificationToClone) noexcept=0 |
| Override to return a custom subclass instance of AudioModification from createAudioModification() or cloneAudioModification(). optionalModificationToClone will be nullptr when creating new modifications with default state from scratch, or will point to a modification from which the internal state should be cloned into the new modification. | |
| virtual void | doDestroyAudioModification (AudioModification *audioModification) noexcept=0 |
| Override if not using plain new in doCreateAudioModification () or relying on reference counting for your subclass. | |
| virtual void | willUpdateAudioModificationProperties (AudioModification *audioModification, PropertiesPtr< ARAAudioModificationProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateAudioModificationProperties(). | |
| virtual void | didUpdateAudioModificationProperties (AudioModification *audioModification) noexcept |
| Override to customize post-update behavior of updateAudioModificationProperties(). | |
| virtual bool | doIsAudioModificationPreservingAudioSourceSignal (AudioModification *audioModification) noexcept |
| Override to implement isAudioModificationPreservingAudioSourceSignal(). | |
| virtual void | willDeactivateAudioModificationForUndoHistory (AudioModification *audioModification, bool deactivate) noexcept |
Override to customize behavior before deactivateAudioModificationForUndoHistory() changes audioModification's activated state. | |
| virtual void | didDeactivateAudioModificationForUndoHistory (AudioModification *audioModification, bool deactivate) noexcept |
Override to customize behavior after deactivateAudioModificationForUndoHistory() changes audioModification's activated state. | |
| virtual void | didAddPlaybackRegionToAudioModification (AudioModification *audioModification, PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior after createPlaybackRegion() adds playbackRegion to audioModification. | |
| virtual void | willRemovePlaybackRegionFromAudioModification (AudioModification *audioModification, PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior before destroyPlaybackRegion() removes playbackRegion from audioModification. | |
| virtual void | willDestroyAudioModification (AudioModification *audioModification) noexcept |
Override to customize behavior before audioModification is destroyed during destroyAudioModification(). | |
Playback Region Management Hooks | |
| virtual PlaybackRegion * | doCreatePlaybackRegion (AudioModification *modification, ARAPlaybackRegionHostRef hostRef) noexcept=0 |
| Override to return a custom subclass instance of PlaybackRegion. | |
| virtual void | doDestroyPlaybackRegion (PlaybackRegion *playbackRegion) noexcept=0 |
| Override if not using plain new in doCreatePlaybackRegion () or relying on reference counting for your subclass. | |
| virtual void | willUpdatePlaybackRegionProperties (PlaybackRegion *playbackRegion, PropertiesPtr< ARAPlaybackRegionProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updatePlaybackRegionProperties(). | |
| virtual void | didUpdatePlaybackRegionProperties (PlaybackRegion *playbackRegion) noexcept |
| Override to customize post-update behavior of updatePlaybackRegionProperties(). | |
| virtual void | doGetPlaybackRegionHeadAndTailTime (const PlaybackRegion *playbackRegion, ARATimeDuration *headTime, ARATimeDuration *tailTime) noexcept |
Override to define a content based fade for playbackRegion by assigning positive values to headTime and/or tailTime - see getPlaybackRegionHeadAndTailTime(). | |
| virtual void | willDestroyPlaybackRegion (PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior before playbackRegion is destroyed during destroyPlaybackRegion(). | |
Content Reader Management Hooks | |
| virtual bool | doIsAudioSourceContentAvailable (const AudioSource *audioSource, ARAContentType type) noexcept |
| Override to implement isAudioSourceContentAvailable() for all your supported content types - the default implementation always returns false, preventing any calls to doGetAudioSourceContentGrade() and doCreateAudioSourceContentReader(). | |
| virtual ARAContentGrade | doGetAudioSourceContentGrade (const AudioSource *audioSource, ARAContentType type) noexcept |
| Override to implement getAudioSourceContentGrade() for all your supported content types. | |
| virtual ContentReader * | doCreateAudioSourceContentReader (AudioSource *audioSource, ARAContentType type, const ARAContentTimeRange *range) noexcept |
Override to implement createAudioSourceContentReader() for all your supported content types, returning a custom subclass instance of ContentReader providing data of the requested type. | |
| virtual bool | doIsAudioModificationContentAvailable (const AudioModification *audioModification, ARAContentType type) noexcept |
| Override to implement isAudioModificationContentAvailable() for all your supported content types - the default implementation always returns false. For read-only data directly inherited from the underlying audio source you can just delegate the call to the audio source, but user-editable modification data must be specifically handled here. | |
| virtual ARAContentGrade | doGetAudioModificationContentGrade (const AudioModification *audioModification, ARAContentType type) noexcept |
| Override to implement getAudioModificationContentGrade() for all your supported content types. For read-only data directly inherited from the underlying audio source you can just delegate the call to the audio source, but user-editable modification data must be specifically handled here. | |
| virtual ContentReader * | doCreateAudioModificationContentReader (AudioModification *audioModification, ARAContentType type, const ARAContentTimeRange *range) noexcept |
Override to implement createAudioModificationContentReader() for all your supported content types, returning a custom subclass instance of ContentReader providing data of the requested type. For read-only data directly inherited from the underlying audio source you can just delegate the call to the audio source, but user-editable modification data must be specifically handled here. | |
| virtual bool | doIsPlaybackRegionContentAvailable (const PlaybackRegion *playbackRegion, ARAContentType type) noexcept |
| Override to implement isPlaybackRegionContentAvailable() for all your supported content types - the default implementation always returns false. Typically, this call can directly delegate to the underlying audio modification, since most plug-ins will apply their modification data to the playback region with a transformation that does not affect content availability. | |
| virtual ARAContentGrade | doGetPlaybackRegionContentGrade (const PlaybackRegion *playbackRegion, ARAContentType type) noexcept |
| Override to implement getPlaybackRegionContentGrade() for all your supported content types. Typically, this call can directly delegate to the underlying audio modification, since most plug-ins will apply their modification data to the playback region with a transformation that does not affect content grade. | |
| virtual ContentReader * | doCreatePlaybackRegionContentReader (PlaybackRegion *playbackRegion, ARAContentType type, const ARAContentTimeRange *range) noexcept |
Override to implement createPlaybackRegionContentReader() for all your supported content types, returning a custom subclass instance of ContentReader providing data of the requested type. | |
| virtual void | doDestroyContentReader (ContentReader *contentReader) noexcept |
| Override if not using plain new in doCreateAudioSourceContentReader (), doCreateAudioModificationContentReader () or doCreatePlaybackRegionContentReader () or relying on reference counting for your subclasses. | |
Controlling Analysis Hooks | |
| virtual bool | doIsAudioSourceContentAnalysisIncomplete (const AudioSource *audioSource, ARAContentType contentType) noexcept |
| Override to implement isAudioSourceContentAnalysisIncomplete(). | |
| virtual void | doRequestAudioSourceContentAnalysis (AudioSource *audioSource, std::vector< ARAContentType > const &contentTypes) noexcept |
| Override to implement requestAudioSourceContentAnalysis(). | |
| virtual ARAInt32 | doGetProcessingAlgorithmsCount () noexcept |
| Override to implement getProcessingAlgorithmsCount(). | |
| virtual const ARAProcessingAlgorithmProperties * | doGetProcessingAlgorithmProperties (ARAInt32 algorithmIndex) noexcept |
| Override to implement getProcessingAlgorithmProperties(). | |
| virtual ARAInt32 | doGetProcessingAlgorithmForAudioSource (const AudioSource *audioSource) noexcept |
| Override to implement getProcessingAlgorithmForAudioSource(). | |
| virtual void | doRequestProcessingAlgorithmForAudioSource (AudioSource *audioSource, ARAInt32 algorithmIndex) noexcept |
| Override to implement requestProcessingAlgorithmForAudioSource(). | |
License Management Hooks | |
| bool | doIsLicensedForContentAnalysisRequests (std::vector< ARAContentType > const &contentTypes) noexcept |
| Override to implement analysis request section of isLicensedForCapabilities(). | |
| bool | doIsLicensedForPlaybackTransformations (ARAPlaybackTransformationFlags transformationFlags) noexcept |
| Override to implement playback transformation section of isLicensedForCapabilities(). | |
| void | doRunModalLicenseActivationForCapabilities (std::vector< ARAContentType > const &contentTypes, ARAPlaybackTransformationFlags transformationFlags) noexcept |
| Override to implement runModalLicenseActivationForCapabilities(). | |
| class ARA::PlugIn::DocumentController |
Customizable default implementation of DocumentControllerInterface.
Protected Member Functions | |
| Document * | doCreateDocument () noexcept override |
| Override to return a custom subclass instance of Document when initializing the DocumentController. | |
| void | doDestroyDocument (Document *document) noexcept override |
| Override if not using plain new in doCreateDocument () or relying on reference counting for your subclass. | |
| MusicalContext * | doCreateMusicalContext (Document *document, ARAMusicalContextHostRef hostRef) noexcept override |
| Override to return a custom subclass instance of MusicalContext from createMusicalContext(). | |
| void | doDestroyMusicalContext (MusicalContext *musicalContext) noexcept override |
| Override if not using plain new in doCreateMusicalContext () or relying on reference counting for your subclass. | |
| RegionSequence * | doCreateRegionSequence (Document *document, ARARegionSequenceHostRef hostRef) noexcept override |
| Override to return a custom subclass instance of RegionSequence from createRegionSequence(). | |
| void | doDestroyRegionSequence (RegionSequence *regionSequence) noexcept override |
| Override if not using plain new in doCreateRegionSequence () or relying on reference counting for your subclass. | |
| AudioSource * | doCreateAudioSource (Document *document, ARAAudioSourceHostRef hostRef) noexcept override |
| Override to return a custom subclass instance of AudioSource from createAudioSource(). | |
| void | doDestroyAudioSource (AudioSource *audioSource) noexcept override |
| Override if not using plain new in doCreateAudioSource () or relying on reference counting for your subclass. | |
| AudioModification * | doCreateAudioModification (AudioSource *audioSource, ARAAudioModificationHostRef hostRef, const AudioModification *optionalModificationToClone) noexcept override |
| Override to return a custom subclass instance of AudioModification from createAudioModification() or cloneAudioModification(). optionalModificationToClone will be nullptr when creating new modifications with default state from scratch, or will point to a modification from which the internal state should be cloned into the new modification. | |
| void | doDestroyAudioModification (AudioModification *audioModification) noexcept override |
| Override if not using plain new in doCreateAudioModification () or relying on reference counting for your subclass. | |
| PlaybackRegion * | doCreatePlaybackRegion (AudioModification *modification, ARAPlaybackRegionHostRef hostRef) noexcept override |
| Override to return a custom subclass instance of PlaybackRegion. | |
| void | doDestroyPlaybackRegion (PlaybackRegion *playbackRegion) noexcept override |
| Override if not using plain new in doCreatePlaybackRegion () or relying on reference counting for your subclass. | |
| PlaybackRenderer * | doCreatePlaybackRenderer () noexcept override |
| Override to return a custom subclass instance of PlaybackRenderer. | |
| void | doDestroyPlaybackRenderer (PlaybackRenderer *playbackRenderer) noexcept override |
| Override if not using plain new in doCreatePlaybackRenderer () or relying on reference counting for your subclass. | |
| EditorRenderer * | doCreateEditorRenderer () noexcept override |
| Override to return a custom subclass instance of EditorRenderer. | |
| void | doDestroyEditorRenderer (EditorRenderer *editorRenderer) noexcept override |
| Override if not using plain new in doCreateEditorRenderer () or relying on reference counting for your subclass. | |
| EditorView * | doCreateEditorView () noexcept override |
| Override to return a custom subclass instance of EditorView. | |
| void | doDestroyEditorView (EditorView *editorView) noexcept override |
| Override if not using plain new in doCreateEditorView () or relying on reference counting for your subclass. | |
Protected Member Functions inherited from ARA::PlugIn::DocumentControllerDelegate | |
| DocumentControllerDelegate (const PlugInEntry *entry) noexcept | |
| Override to return a custom subclass instance of PlaybackRenderer. | |
| virtual | ~DocumentControllerDelegate () |
| Override to return a custom subclass instance of PlaybackRenderer. | |
| const PlugInEntry * | getPlugInEntry () const noexcept |
| Override to return a custom subclass instance of PlaybackRenderer. | |
| virtual void | willBeginEditing () noexcept |
| Override to customize behavior before a Document edit cycle begins. | |
| virtual void | didEndEditing () noexcept |
| Override to customize behavior after a Document edit cycle ends. | |
| virtual void | willNotifyModelUpdates () noexcept |
| Override to customize behavior before sending update notifications to the host. | |
| virtual void | didNotifyModelUpdates () noexcept |
| Override to customize behavior after sending update notifications to the host. | |
| virtual bool | doRestoreObjectsFromArchive (HostArchiveReader *archiveReader, const RestoreObjectsFilter *filter) noexcept=0 |
| Override to implement restoreObjectsFromArchive(). | |
| virtual bool | doStoreObjectsToArchive (HostArchiveWriter *archiveWriter, const StoreObjectsFilter *filter) noexcept=0 |
| Override to implement storeObjectsToArchive(). | |
| virtual bool | doStoreAudioSourceToAudioFileChunk (HostArchiveWriter *archiveWriter, AudioSource *audioSource, ARAPersistentID *documentArchiveID, bool *openAutomatically) noexcept |
| Override to customize storeAudioSourceToAudioFileChunk() if needed. The default implementation calls doStoreObjectsToArchive() with an appropriate StoreObjectsFilter and sets openAutomatically to false - check if your internal data format allows for optimizing this according to the criteria documented for storeAudioSourceToAudioFileChunk(). | |
| virtual void | willUpdateDocumentProperties (Document *document, PropertiesPtr< ARADocumentProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateDocumentProperties(). | |
| virtual void | didUpdateDocumentProperties (Document *document) noexcept |
| Override to customize post-update behavior of updateDocumentProperties(). | |
| virtual void | didAddMusicalContextToDocument (Document *document, MusicalContext *musicalContext) noexcept |
Override to customize behavior after createMusicalContext() adds musicalContext to document. | |
| virtual void | willRemoveMusicalContextFromDocument (Document *document, MusicalContext *musicalContext) noexcept |
Override to customize behavior before destroyMusicalContext() removes musicalContext from document. | |
| virtual void | willReorderMusicalContextsInDocument (Document *document) noexcept |
Override to customize behavior before sorting all MusicalContext instances in document by ARAMusicalContextProperties::orderIndex. | |
| virtual void | didReorderMusicalContextsInDocument (Document *document) noexcept |
Override to customize behavior after sorting all MusicalContext instances in document by ARAMusicalContextProperties::orderIndex. | |
| virtual void | didAddRegionSequenceToDocument (Document *document, RegionSequence *regionSequence) noexcept |
Override to customize behavior after createRegionSequence() adds regionSequence to document. | |
| virtual void | willRemoveRegionSequenceFromDocument (Document *document, RegionSequence *regionSequence) noexcept |
Override to customize behavior before destroyRegionSequence() removes regionSequence from document. | |
| virtual void | willReorderRegionSequencesInDocument (Document *document) noexcept |
Override to customize behavior before sorting all RegionSequence instances in document by ARARegionSequenceProperties::orderIndex. | |
| virtual void | didReorderRegionSequencesInDocument (Document *document) noexcept |
Override to customize behavior after sorting all RegionSequence instances in document by ARARegionSequenceProperties::orderIndex. | |
| virtual void | didAddAudioSourceToDocument (Document *document, AudioSource *audioSource) noexcept |
Override to customize behavior after createAudioSource() adds audioSource to document. | |
| virtual void | willRemoveAudioSourceFromDocument (Document *document, AudioSource *audioSource) noexcept |
Override to customize behavior before destroyAudioSource() removes audioSource from document. | |
| virtual void | willDestroyDocument (Document *document) noexcept |
Override to customize behavior before document is destroyed during destroyDocumentController(). | |
| virtual void | willUpdateMusicalContextProperties (MusicalContext *musicalContext, PropertiesPtr< ARAMusicalContextProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateMusicalContextProperties(). | |
| virtual void | didUpdateMusicalContextProperties (MusicalContext *musicalContext) noexcept |
| Override to customize post-update behavior of updateMusicalContextProperties(). | |
| virtual void | doUpdateMusicalContextContent (MusicalContext *musicalContext, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Override to implement updateMusicalContextContent(). | |
| virtual void | didAddRegionSequenceToMusicalContext (MusicalContext *musicalContext, RegionSequence *regionSequence) noexcept |
Override to customize behavior after createRegionSequence() or updateRegionSequenceProperties() adds regionSequence to musicalContext. | |
| virtual void | willRemoveRegionSequenceFromMusicalContext (MusicalContext *musicalContext, RegionSequence *regionSequence) noexcept |
Override to customize behavior before destroyRegionSequence() or updateRegionSequenceProperties() removes regionSequence to musicalContext. | |
| virtual void | willReorderRegionSequencesInMusicalContext (MusicalContext *musicalContext) noexcept |
Override to customize behavior before sorting all RegionSequence instances in musicalContext by ARARegionSequenceProperties::orderIndex. | |
| virtual void | didReorderRegionSequencesInMusicalContext (MusicalContext *musicalContext) noexcept |
Override to customize behavior after sorting all RegionSequence instances in musicalContext by ARARegionSequenceProperties::orderIndex. | |
| virtual void | willDestroyMusicalContext (MusicalContext *musicalContext) noexcept |
Override to customize behavior before musicalContext is destroyed during destroyMusicalContext(). | |
| virtual void | willUpdateRegionSequenceProperties (RegionSequence *regionSequence, PropertiesPtr< ARARegionSequenceProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateRegionSequenceProperties(). | |
| virtual void | didUpdateRegionSequenceProperties (RegionSequence *regionSequence) noexcept |
| Override to customize pre-update behavior of updateRegionSequenceProperties(). | |
| virtual void | didAddPlaybackRegionToRegionSequence (RegionSequence *regionSequence, PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior after createPlaybackRegion() or updatePlaybackRegionProperties() adds playbackRegion to regionSequence. | |
| virtual void | willRemovePlaybackRegionFromRegionSequence (RegionSequence *regionSequence, PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior before destroyPlaybackRegion() or updatePlaybackRegionProperties() removes playbackRegion from regionSequence. | |
| virtual void | willDestroyRegionSequence (RegionSequence *regionSequence) noexcept |
Override to customize behavior before regionSequence is destroyed during destroyRegionSequence(). | |
| virtual void | willUpdateAudioSourceProperties (AudioSource *audioSource, PropertiesPtr< ARAAudioSourceProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateAudioSourceProperties(). | |
| virtual void | didUpdateAudioSourceProperties (AudioSource *audioSource) noexcept |
| Override to customize pre-update behavior of updateAudioSourceProperties(). | |
| virtual void | doUpdateAudioSourceContent (AudioSource *audioSource, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Override to implement updateAudioSourceContent(). | |
| virtual void | willEnableAudioSourceSamplesAccess (AudioSource *audioSource, bool enable) noexcept=0 |
Override to customize behavior before enableAudioSourceSamplesAccess() changes audioSource's sample access state. | |
| virtual void | didEnableAudioSourceSamplesAccess (AudioSource *audioSource, bool enable) noexcept=0 |
Override to customize behavior after enableAudioSourceSamplesAccess() changes audioSource's sample access state. | |
| virtual void | willDeactivateAudioSourceForUndoHistory (AudioSource *audioSource, bool deactivate) noexcept |
Override to customize behavior before deactivateAudioSourceForUndoHistory() changes audioSource's activated state. | |
| virtual void | didDeactivateAudioSourceForUndoHistory (AudioSource *audioSource, bool deactivate) noexcept |
Override to customize behavior after deactivateAudioSourceForUndoHistory() changes audioSource's activated state. | |
| virtual void | didAddAudioModificationToAudioSource (AudioSource *audioSource, AudioModification *audioModification) noexcept |
Override to customize behavior after createAudioModification() or updateAudioModificationProperties() adds audioModification to audioSource. | |
| virtual void | willRemoveAudioModificationFromAudioSource (AudioSource *audioSource, AudioModification *audioModification) noexcept |
Override to customize behavior before destroyAudioModification() or updateAudioModificationProperties() removes audioModification from audioSource. | |
| virtual void | willDestroyAudioSource (AudioSource *audioSource) noexcept |
Override to customize behavior before audioSource is destroyed during destroyAudioSource(). | |
| virtual void | willUpdateAudioModificationProperties (AudioModification *audioModification, PropertiesPtr< ARAAudioModificationProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updateAudioModificationProperties(). | |
| virtual void | didUpdateAudioModificationProperties (AudioModification *audioModification) noexcept |
| Override to customize post-update behavior of updateAudioModificationProperties(). | |
| virtual bool | doIsAudioModificationPreservingAudioSourceSignal (AudioModification *audioModification) noexcept |
| Override to implement isAudioModificationPreservingAudioSourceSignal(). | |
| virtual void | willDeactivateAudioModificationForUndoHistory (AudioModification *audioModification, bool deactivate) noexcept |
Override to customize behavior before deactivateAudioModificationForUndoHistory() changes audioModification's activated state. | |
| virtual void | didDeactivateAudioModificationForUndoHistory (AudioModification *audioModification, bool deactivate) noexcept |
Override to customize behavior after deactivateAudioModificationForUndoHistory() changes audioModification's activated state. | |
| virtual void | didAddPlaybackRegionToAudioModification (AudioModification *audioModification, PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior after createPlaybackRegion() adds playbackRegion to audioModification. | |
| virtual void | willRemovePlaybackRegionFromAudioModification (AudioModification *audioModification, PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior before destroyPlaybackRegion() removes playbackRegion from audioModification. | |
| virtual void | willDestroyAudioModification (AudioModification *audioModification) noexcept |
Override to customize behavior before audioModification is destroyed during destroyAudioModification(). | |
| virtual void | willUpdatePlaybackRegionProperties (PlaybackRegion *playbackRegion, PropertiesPtr< ARAPlaybackRegionProperties > newProperties) noexcept |
| Override to customize pre-update behavior of updatePlaybackRegionProperties(). | |
| virtual void | didUpdatePlaybackRegionProperties (PlaybackRegion *playbackRegion) noexcept |
| Override to customize post-update behavior of updatePlaybackRegionProperties(). | |
| virtual void | doGetPlaybackRegionHeadAndTailTime (const PlaybackRegion *playbackRegion, ARATimeDuration *headTime, ARATimeDuration *tailTime) noexcept |
Override to define a content based fade for playbackRegion by assigning positive values to headTime and/or tailTime - see getPlaybackRegionHeadAndTailTime(). | |
| virtual void | willDestroyPlaybackRegion (PlaybackRegion *playbackRegion) noexcept |
Override to customize behavior before playbackRegion is destroyed during destroyPlaybackRegion(). | |
| virtual bool | doIsAudioSourceContentAvailable (const AudioSource *audioSource, ARAContentType type) noexcept |
| Override to implement isAudioSourceContentAvailable() for all your supported content types - the default implementation always returns false, preventing any calls to doGetAudioSourceContentGrade() and doCreateAudioSourceContentReader(). | |
| virtual ARAContentGrade | doGetAudioSourceContentGrade (const AudioSource *audioSource, ARAContentType type) noexcept |
| Override to implement getAudioSourceContentGrade() for all your supported content types. | |
| virtual ContentReader * | doCreateAudioSourceContentReader (AudioSource *audioSource, ARAContentType type, const ARAContentTimeRange *range) noexcept |
Override to implement createAudioSourceContentReader() for all your supported content types, returning a custom subclass instance of ContentReader providing data of the requested type. | |
| virtual bool | doIsAudioModificationContentAvailable (const AudioModification *audioModification, ARAContentType type) noexcept |
| Override to implement isAudioModificationContentAvailable() for all your supported content types - the default implementation always returns false. For read-only data directly inherited from the underlying audio source you can just delegate the call to the audio source, but user-editable modification data must be specifically handled here. | |
| virtual ARAContentGrade | doGetAudioModificationContentGrade (const AudioModification *audioModification, ARAContentType type) noexcept |
| Override to implement getAudioModificationContentGrade() for all your supported content types. For read-only data directly inherited from the underlying audio source you can just delegate the call to the audio source, but user-editable modification data must be specifically handled here. | |
| virtual ContentReader * | doCreateAudioModificationContentReader (AudioModification *audioModification, ARAContentType type, const ARAContentTimeRange *range) noexcept |
Override to implement createAudioModificationContentReader() for all your supported content types, returning a custom subclass instance of ContentReader providing data of the requested type. For read-only data directly inherited from the underlying audio source you can just delegate the call to the audio source, but user-editable modification data must be specifically handled here. | |
| virtual bool | doIsPlaybackRegionContentAvailable (const PlaybackRegion *playbackRegion, ARAContentType type) noexcept |
| Override to implement isPlaybackRegionContentAvailable() for all your supported content types - the default implementation always returns false. Typically, this call can directly delegate to the underlying audio modification, since most plug-ins will apply their modification data to the playback region with a transformation that does not affect content availability. | |
| virtual ARAContentGrade | doGetPlaybackRegionContentGrade (const PlaybackRegion *playbackRegion, ARAContentType type) noexcept |
| Override to implement getPlaybackRegionContentGrade() for all your supported content types. Typically, this call can directly delegate to the underlying audio modification, since most plug-ins will apply their modification data to the playback region with a transformation that does not affect content grade. | |
| virtual ContentReader * | doCreatePlaybackRegionContentReader (PlaybackRegion *playbackRegion, ARAContentType type, const ARAContentTimeRange *range) noexcept |
Override to implement createPlaybackRegionContentReader() for all your supported content types, returning a custom subclass instance of ContentReader providing data of the requested type. | |
| virtual void | doDestroyContentReader (ContentReader *contentReader) noexcept |
| Override if not using plain new in doCreateAudioSourceContentReader (), doCreateAudioModificationContentReader () or doCreatePlaybackRegionContentReader () or relying on reference counting for your subclasses. | |
| virtual bool | doIsAudioSourceContentAnalysisIncomplete (const AudioSource *audioSource, ARAContentType contentType) noexcept |
| Override to implement isAudioSourceContentAnalysisIncomplete(). | |
| virtual void | doRequestAudioSourceContentAnalysis (AudioSource *audioSource, std::vector< ARAContentType > const &contentTypes) noexcept |
| Override to implement requestAudioSourceContentAnalysis(). | |
| virtual ARAInt32 | doGetProcessingAlgorithmsCount () noexcept |
| Override to implement getProcessingAlgorithmsCount(). | |
| virtual const ARAProcessingAlgorithmProperties * | doGetProcessingAlgorithmProperties (ARAInt32 algorithmIndex) noexcept |
| Override to implement getProcessingAlgorithmProperties(). | |
| virtual ARAInt32 | doGetProcessingAlgorithmForAudioSource (const AudioSource *audioSource) noexcept |
| Override to implement getProcessingAlgorithmForAudioSource(). | |
| virtual void | doRequestProcessingAlgorithmForAudioSource (AudioSource *audioSource, ARAInt32 algorithmIndex) noexcept |
| Override to implement requestProcessingAlgorithmForAudioSource(). | |
| bool | doIsLicensedForContentAnalysisRequests (std::vector< ARAContentType > const &contentTypes) noexcept |
| Override to implement analysis request section of isLicensedForCapabilities(). | |
| bool | doIsLicensedForPlaybackTransformations (ARAPlaybackTransformationFlags transformationFlags) noexcept |
| Override to implement playback transformation section of isLicensedForCapabilities(). | |
| void | doRunModalLicenseActivationForCapabilities (std::vector< ARAContentType > const &contentTypes, ARAPlaybackTransformationFlags transformationFlags) noexcept |
| Override to implement runModalLicenseActivationForCapabilities(). | |
Sending content updates to the host | |
The implementation will internally enqueue the updates and later send them to the host from notifyModelUpdates (). Note that while the ARA API allows for specifying affected time ranges for content updates, this feature is not yet supported in our current plug-in implementation (since most hosts do not evaluate this either). | |
| void | notifyAudioSourceContentChanged (AudioSource *audioSource, ContentUpdateScopes scopeFlags) noexcept |
| void | notifyAudioModificationContentChanged (AudioModification *audioModification, ContentUpdateScopes scopeFlags) noexcept |
| void | notifyPlaybackRegionContentChanged (PlaybackRegion *playbackRegion, ContentUpdateScopes scopeFlags) noexcept |
| bool | canContentTypeBeAnalyzed (ARAContentType type) noexcept |
Global versioning | |
| ARAAPIGeneration | getUsedApiGeneration () const noexcept |
| Query the API version configured by the host via ARAInterfaceConfiguration::desiredApiGeneration. | |
Host Interface Access | |
| HostAudioAccessController * | getHostAudioAccessController () noexcept |
| Returns the audio access controller that the host has provided for this document controller. | |
| HostArchivingController * | getHostArchivingController () noexcept |
| Returns the archiving controller that the host has provided for this document controller. | |
| HostContentAccessController * | getHostContentAccessController () noexcept |
| Returns the optional content access controller that the host has provided for this document controller. | |
| HostModelUpdateController * | getHostModelUpdateController () noexcept |
| Returns the optional model update controller that the host has provided for this document controller. | |
| HostPlaybackController * | getHostPlaybackController () noexcept |
| Returns the optional playback controller that the host has provided for this document controller. | |
Document Access | |
Where applicable, use the optional template parameter to cast the returned instances to your custom subclass. | |
| template<typename Document_t = Document> | |
| Document_t * | getDocument () const noexcept |
| Retrieve the Document controlled by this instance. Note that during destruction phase, the document controller may have already deleted its document and associated graph - this call will then return nullptr. | |
| bool | isHostEditingDocument () const noexcept |
| Returns true if called between beginEditing() and endEditing(). | |
Bound Plug-In Instance Management | |
| template<typename PlaybackRenderer_t = PlaybackRenderer> | |
| std::vector< PlaybackRenderer_t * > const & | getPlaybackRenderers () const noexcept |
| Retrieve the current list of bound PlaybackRenderer instances. | |
| template<typename EditorRenderer_t = EditorRenderer> | |
| std::vector< EditorRenderer_t * > const & | getEditorRenderers () const noexcept |
| Retrieve the current list of bound EditorRenderer instances. | |
| template<typename EditorView_t = EditorView> | |
| std::vector< EditorView_t * > const & | getEditorViews () const noexcept |
| Retrieve the current list of bound EditorView instances. | |
Sending analysis progress to the host | |
Contrary to most DocumentController functions, these calls can be made from any thread. The implementation will internally enqueue the updates in a non-blocking way and later send them to the host from notifyModelUpdates (). Note that calling code must ensure start and completion are always balanced, and must send the updates in ascending order. | |
| void | notifyAudioSourceAnalysisProgressStarted (AudioSource *audioSource) noexcept |
| void | notifyAudioSourceAnalysisProgressUpdated (AudioSource *audioSource, float progress) noexcept |
| void | notifyAudioSourceAnalysisProgressCompleted (AudioSource *audioSource) noexcept |
Additional Inherited Members | |
Public Member Functions inherited from ARA::PlugIn::DocumentControllerInterface | |
| virtual void | destroyDocumentController () noexcept=0 |
| Destroy the controller and its associated document. The host must delete all objects associated with the document graph (audio sources, musical contexts etc.) before making this call. Note that the objects exported via the ARAPlugInExtensionInstance are not considered part of the document graph, their destruction may happen before or after destroying the document controller that they are bound to. More... | |
| virtual const ARAFactory * | getFactory () const noexcept=0 |
| virtual void | beginEditing () noexcept=0 |
| Start an editing session on a document. An editing session can contain an arbitrary set of modifications that belong together. Since many model edits can result in rather expensive updates on the plug-in side, this call allows for grouping the edits and postponing the updates until the new model state is final, which potentially saves some intermediate updates. More... | |
| virtual void | endEditing () noexcept=0 |
| End an editing session on a document. Note that when receiving this call, the plug-in will update any amount of internal state. These edits may lead to update notifications to the host, and the host may in turn read affected content from the plug-in and update its own model accordingly. One example for this the way that Melodyne maintains chords and scales associated with audio modifications. It copies this data from the musical context into the audio modifications, so that when editing regions the notes appear in the proper pitch grid. If moving playback regions in the song, these copies may need to be updated, and Melodyne will report the resulting audio modification content changes to the host. To ensure that any such follow-up updates are added to the same undo cycle, hosts that actively read plug-in content data should immediately (i.e. within the same undo frame) call notifyModelUpdates() after making this call. More... | |
| virtual void | notifyModelUpdates () noexcept=0 |
| Tell the plug-in to send all pending update notifications for the given document. This must be called periodically by the host whenever not editing nor restoring the document. Only when processing this call, the plug-in may call back into the host using ARAModelUpdateControllerInterface. Hosts must be aware after receiving beginEditing(), plug-ins may choose to postpone any subset of their internal state updates until the matching call to endEditing(). This means that if the host for some reason needs to wait for a specific update in the plug-in to occur (such as waiting for an analysis to finish) it must do so outside of pairs of beginEditing() and endEditing(). More... | |
| virtual bool | restoreObjectsFromArchive (ARAArchiveReaderHostRef archiveReaderHostRef, const ARARestoreObjectsFilter *filter) noexcept=0 |
| Unarchive the internal state of the specified objects. This call can be used both for unarchiving entire documents and for importing arbitrary objects into an existing document. An unarchiving session is conceptually identical to an editing session: after starting the session, the host rebuilds the graph using the regular object creation calls, then makes this call to let the plug-in parse the archive and inject the archived internal state into the graph as indicated by the persistentIDs of the relevant objects. Similarly, when importing objects, the host will perform an editing session and either create new objects or re-use existing objects (potentially adjusting their persistentID), then make this call to inject the imported state. The optional filter allows for restoring only a subset of the archived states into the graph. It can be NULL, in which case all archived states with matching persistentIDs will be restored. In that case, the call sequence beginEditing(), restoreObjectsFromArchive(), endEditing() is equivalent to the deprecated begin-/endRestoringDocumentFromArchive() for ARA 1, which has been superseded by this call. The host is not required to restore all objects in the archive. Any archived states that are either filtered explicitly, or for which there is no object with a matching persistent ID in the current graph are simply ignored. Since persistent IDs are only required to be unique per document (and not globally), hosts may encounter persistent ID conflicts when importing data from other documents. The optional ARARestoreObjectsFilter provided for this call therefore allows to map between the IDs used in the archive and those used in the current graph if needed. The host can make multiple calls to restoreObjectsFromArchive() within the same editing session to import objects from multiple archives in one operation. It may even decide to implement its persistency based on partial archives entirely, using several calls to storeObjectsToArchive() with varying filters to split the document into slices appropriate to its implementation, see ARAStoreObjectsFilter::documentData. Result is kARAFalse if the access to the archive reader failed while trying to read the archive, or if decoding the data failed, kARATrue otherwise. Potential reason for failure include data corruption due to storage hardware failures, or broken dependencies when restoring partial archives as discussed above. The plug-in should try to recover as much state as possible in all cases, and the host should notify the user of such errors. If a failure happened already while reading the archive, the host is aware of this and can augment its error message to the user accordingly. If the failure happens inside the plug-in when decoding the data, the plug-in is responsible for guiding the user as good as possible, e.g. by listing or marking the affected objects. Note that since versioning is expressed through the ARA factory, the host must deal with potential versioning conflicts before making this call, and provide proper UI too. More... | |
| virtual bool | storeObjectsToArchive (ARAArchiveWriterHostRef archiveWriterHostRef, const ARAStoreObjectsFilter *filter) noexcept=0 |
| Create a partial archive of the internal state of the specified objects. Archives may only be created from documents that are not being currently edited. The optional filter allows for storing only a subset of the document graph into the archive. It can be NULL, in which case all objects in the graph will be stored. In that case, the call is equivalent to the deprecated storeDocumentToArchive(), which has been superseded by this call. Result is kARAFalse if the access to the archive writer failed while trying to write the archive, kARATrue otherwise. The host is responsible for alerting the user about archive write errors, see ARAArchivingControllerInterface::writeBytesToArchive(). Note that for creating ARA audio file chunk archives, storeAudioSourceToAudioFileChunk() must be used instead, so that the plug-in can pick the correct encoding and return the corresponding (compatible) document archive ID. More... | |
| virtual bool | storeAudioSourceToAudioFileChunk (ARAArchiveWriterHostRef archiveWriterHostRef, ARAAudioSourceRef audioSourceRef, ARAPersistentID *documentArchiveID, bool *openAutomatically) noexcept=0 |
| Create an archive of the internal state of the specified audio source suitable to be embedded into the underlying audio file as ARA audio file chunks, see ARA Audio File Chunks. Hosts must check ARAFactory::supportsStoringAudioFileChunks before enabling users to store audio file chunks for the given plug-in. Archives may only be created from documents that are not being currently edited. This call differs from using storeObjectsToArchive() with an ARAStoreObjectsFilter in that the plug-in may choose a different internal encoding more suitable for this use case, indicated by returning a documentArchiveID that is likely one of the ARAFactory::compatibleDocumentArchiveIDs rather than the ARAFactory::documentArchiveID. The plug-in also returns whether openAutomatically should be set in the audio file chunk. Result is kARAFalse if the access to the archive writer failed while trying to write the archive, kARATrue otherwise. The host is responsible for alerting the user about archive write errors, see ARAArchivingControllerInterface::writeBytesToArchive(). More... | |
| virtual void | updateDocumentProperties (PropertiesPtr< ARADocumentProperties > properties) noexcept=0 |
| Update the properties of the controller's document. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| virtual ARAMusicalContextRef | createMusicalContext (ARAMusicalContextHostRef hostRef, PropertiesPtr< ARAMusicalContextProperties > properties) noexcept=0 |
| Create a new musical context associated with the controller's document. More... | |
| virtual void | updateMusicalContextProperties (ARAMusicalContextRef musicalContextRef, PropertiesPtr< ARAMusicalContextProperties > properties) noexcept=0 |
| Update the properties of a given musical context. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| virtual void | updateMusicalContextContent (ARAMusicalContextRef musicalContextRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Tell the plug-in to update the information obtainable via content readers for a given musical context. The time range may be NULL, this means that the entire musical content is affected. Creating a new musical context implies an initial content update for it - the host will call this explicitly only for later content updates. More... | |
| virtual void | destroyMusicalContext (ARAMusicalContextRef musicalContextRef) noexcept=0 |
| Destroy a given musical context. Destroying a musical context also implies removing it from its document. The musical context must no longer be referred to by any playback region when making this call. More... | |
| virtual ARARegionSequenceRef | createRegionSequence (ARARegionSequenceHostRef hostRef, PropertiesPtr< ARARegionSequenceProperties > properties) noexcept=0 |
| Create a new region sequence associated with the controller's document. More... | |
| virtual void | updateRegionSequenceProperties (ARARegionSequenceRef regionSequence, PropertiesPtr< ARARegionSequenceProperties > properties) noexcept=0 |
| Update the properties of a given region sequence. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| virtual void | destroyRegionSequence (ARARegionSequenceRef regionSequence) noexcept=0 |
| Destroy a given region sequence. The region sequence must no longer be referred to by any playback region when making this call. More... | |
| virtual ARAAudioSourceRef | createAudioSource (ARAAudioSourceHostRef hostRef, PropertiesPtr< ARAAudioSourceProperties > properties) noexcept=0 |
| Create a new audio source associated with the controller's document. The newly created audio source has its sample data access initially disabled, an explicit call to enableAudioSourceSamplesAccess() is needed. More... | |
| virtual void | updateAudioSourceProperties (ARAAudioSourceRef audioSourceRef, PropertiesPtr< ARAAudioSourceProperties > properties) noexcept=0 |
| Update the properties of a given audio source. Depending on which properties are changed (see documentation of ARAAudioSourceProperties), the host may not be able to make this call while the plug-in is reading data - in that case, use enableAudioSourceSamplesAccess() accordingly. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| virtual void | updateAudioSourceContent (ARAAudioSourceRef audioSourceRef, const ARAContentTimeRange *range, ContentUpdateScopes scopeFlags) noexcept=0 |
| Tell the plug-in that the sample data or content information for the given audio source has changed. Not to be called in response to ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged(). The time range may be NULL, this means that the entire audio source is affected. When implementing this call, remember to also flush any caches of the sampled data if needed (see kARAContentUpdateSignalScopeRemainsUnchanged). Creating a new audio source always implies an initial content update for it, i.e. the host will call this function only for later content updates. Since audio sources are persistent, plug-ins should preferably postpone the initial content reading until endEditing() - if the host is restoring the audio source, this will remove the need to read initial content. More... | |
| virtual void | enableAudioSourceSamplesAccess (ARAAudioSourceRef audioSourceRef, bool enable) noexcept=0 |
| Enable or disable access to a given audio source. This call allows the host to control the time when the plug-in may access sample data from the given audio source. Disabling access forces the plug-in to destroy all audio readers it currently has created for the affected audio source. This is a synchronous call, blocking until all currently executing reads of the audio source are finished. Access is disabled by default, hosts must explicitly enable it after creating an audio source. Since this call does not modify the model graph, it may be called outside the usual beginEditing() and endEditing() scope. Note that disabling access will also abort any analysis currently being executed for the audio source, making it necessary to start it from scratch when the access is enabled again. This means that enableAudioSourceSamplesAccess() is an expensive call that only should be made when necessary. It should not be (ab-)used to simply "pause ARA" whenever convenient. More... | |
| virtual void | deactivateAudioSourceForUndoHistory (ARAAudioSourceRef audioSourceRef, bool deactivate) noexcept=0 |
| Deactivate the given audio source because it has become part of the undo history and is no longer used actively. The plug-in will cancel any pending analysis for this audio source and may free memory that is only needed when the audio source can be edited or rendered. Before deactivating an audio source, the host must deactivate all associated audio modifications, and the opposite order is required when re-activating upon redo. When deactivated, updating the properties or content of the audio source or reading its content is no longer valid. Like properties, deactivation is not necessarily persistent in the plug-in, so the host must call this explicitly when restoring deactivated audio sources. Note that with the introduction of partial persistency with ARA 2.0, hosts likely will prefer to simply create partial archives of deleted audio sources and manage these in their undo history rather than utilizing this call. More... | |
| virtual void | destroyAudioSource (ARAAudioSourceRef audioSourceRef) noexcept=0 |
| Destroy a given audio source. Destroying an audio source also implies removing it from its document. The host must delete all objects associated with the audio source (audio modifications etc.) before deleting the audio source. The host does not need to explicitly disable access to the audio source before making this call. More... | |
| virtual ARAAudioModificationRef | createAudioModification (ARAAudioSourceRef audioSourceRef, ARAAudioModificationHostRef hostRef, PropertiesPtr< ARAAudioModificationProperties > properties) noexcept=0 |
| Create a new audio modification associated with the given audio source. More... | |
| virtual ARAAudioModificationRef | cloneAudioModification (ARAAudioModificationRef audioModificationRef, ARAAudioModificationHostRef hostRef, PropertiesPtr< ARAAudioModificationProperties > properties) noexcept=0 |
| Create a new audio modification that copies the state of another given audio modification. The new modification will be associated with the same audio source. This call is used to create independent variations of the audio as opposed to creating aliases by merely adding playback regions to a given audio modification. More... | |
| virtual void | updateAudioModificationProperties (ARAAudioModificationRef audioModificationRef, PropertiesPtr< ARAAudioModificationProperties > properties) noexcept=0 |
| Update the properties of a given audio modification. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| virtual bool | isAudioModificationPreservingAudioSourceSignal (ARAAudioModificationRef audioModificationRef) noexcept=0 |
| Some hosts such as Pro Tools provide indicators whether a given plug-in's current settings cause it to alter the sound of the original audio source, or preserve it so that bypassing/removing the plug-in would not change the perceived audible result (note that actual rendering involves using a playback region, which still may apply time-stretching or pitch-shifting to the audio modification's potentially unaltered output). Changes to this state are tracked via ARAModelUpdateControllerInterface::notifyAudioModificationContentChanged() with kARAContentUpdateSignalScopeRemainsUnchanged == false. Note that it is possible to perform other edits such as reassigning the chords associated with the audio modification which would not affect this state. It is valid for plug-in implementations to deliver false negatives here to reasonably limit the cost of maintaining the state. For example, if the plug-in does some threshold-based processing, but the signal happens to never actually reach the threshold, the plug-in still may report to alter the sound. Another example is pitch&time editing in a Melodyne-like plug-in: if notes are moved to a different pitch or time position so that this flag is cleared, but later the user manually moves them back to the original location, this might not cause this flag to turn back on. If however the user invokes undo, or some explicit reset command instead of the manual adjustment, then the plug-in should maintain this state properly. More... | |
| virtual void | deactivateAudioModificationForUndoHistory (ARAAudioModificationRef audioModificationRef, bool deactivate) noexcept=0 |
| Deactivate the given audio modification because it has become part of the undo history and is no longer used actively. The plug-in may free some memory that is only needed when the audio modification can be edited or rendered. Before deactivating an audio modification, the host must destroy all associated playback regions, and the opposite order is required when re-activating upon redo. When deactivated, updating the properties of the audio modification or reading its content is no longer valid. Like properties, deactivation is not necessarily persistent in the plug-in, so the host must call this explicitly when restoring deactivated audio modifications. Note that with the introduction of partial persistency with ARA 2.0, hosts likely will prefer to simply create partial archives of deleted audio modifications and manage these in their undo history rather than utilizing this call. More... | |
| virtual void | destroyAudioModification (ARAAudioModificationRef audioModificationRef) noexcept=0 |
| Destroy a given audio modification. Destroying an audio modification also implies removing it from its audio source. The host must delete all objects associated with the audio modification (playback regions etc.) before deleting the audio modification. More... | |
| virtual ARAPlaybackRegionRef | createPlaybackRegion (ARAAudioModificationRef audioModificationRef, ARAPlaybackRegionHostRef hostRef, PropertiesPtr< ARAPlaybackRegionProperties > properties) noexcept=0 |
| Create a new playback region associated with the given audio modification. More... | |
| virtual void | updatePlaybackRegionProperties (ARAPlaybackRegionRef playbackRegionRef, PropertiesPtr< ARAPlaybackRegionProperties > properties) noexcept=0 |
| Update the properties of a given playback region. All properties must be specified, the plug-in will determine which have actually changed. More... | |
| virtual void | destroyPlaybackRegion (ARAPlaybackRegionRef playbackRegionRef) noexcept=0 |
| Destroy a given playback region. Destroying a playback region also implies removing it from its audio modification. The playback region must no longer be referred to by any plug-in extension when making this call. More... | |
| virtual void | getPlaybackRegionHeadAndTailTime (ARAPlaybackRegionRef playbackRegionRef, ARATimeDuration *headTime, ARATimeDuration *tailTime) noexcept=0 |
| Query the current head and tail time of a given playback region. Note that when a plug-in optimizes region transitions, the head and tail of any given region can change upon any model edit, even if it is not directly affected by the edit. Also, in order to properly track interaction between regions, plug-ins may lazily update this information upon endEditing(). Plug-ins will call notifyPlaybackRegionContentChanged() whenever these values change. headTime and tailTime must not be NULL. Host may query this often, so plug-ins should cache the value if there's any expensive calculation involved. Note that most companion APIs also feature a tail time concept. For playback renderer plug-in instances, the tail time reported via the companion API should be equal to or greater than the maximum of the tail times of all playback regions currently associated with the given renderer (i.e. the tail for any given playback region may be somewhat shorter then the companion API tail, depending on the region's content). More... | |
| virtual bool | isAudioSourceContentAvailable (ARAAudioSourceRef audioSourceRef, ARAContentType type) noexcept=0 |
| Query whether the given content type is currently available for the given audio source. More... | |
| virtual ARAContentGrade | getAudioSourceContentGrade (ARAAudioSourceRef audioSourceRef, ARAContentType type) noexcept=0 |
| Query the current quality of the information provided for the given audio source and content type. More... | |
| virtual ARAContentReaderRef | createAudioSourceContentReader (ARAAudioSourceRef audioSourceRef, ARAContentType type, const ARAContentTimeRange *range) noexcept=0 |
| Create a content reader for the given audio source and content type. This should only be called after availability has been confirmed using isAudioSourceContentAvailable(). The time range may be NULL, which means that the entire audio source shall be read. If a time range is specified, all events that at least partially intersect with the range will be read. More... | |
| virtual bool | isAudioModificationContentAvailable (ARAAudioModificationRef audioModificationRef, ARAContentType type) noexcept=0 |
| Query whether the given content type is currently available for the given audio modification. Note that since ARA 2.0, reading at playback region level is recommended for most content types, see createAudioModificationContentReader(). More... | |
| virtual ARAContentGrade | getAudioModificationContentGrade (ARAAudioModificationRef audioModificationRef, ARAContentType type) noexcept=0 |
| Query the current quality of the information provided for a given audio modification and content type. Note that since ARA 2.0, reading at playback region level is recommended for most content types, see createAudioModificationContentReader(). More... | |
| virtual ARAContentReaderRef | createAudioModificationContentReader (ARAAudioModificationRef audioModificationRef, ARAContentType type, const ARAContentTimeRange *range) noexcept=0 |
| Create a content reader for the given audio modification and content type. This should only be called after availability has been confirmed using isAudioModificationContentAvailable(). The time range may be NULL, which means that the entire audio modification shall be read. If a time range is specified, all events that at least partially intersect with the range will be read. Note that with the introduction of region transitions in ARA 2.0, the content of a given playback region can no longer be externally calculated by the host based on the content of its underlying audio modification and the transformation flags. Instead, hosts should read such content directly at region level. This particularly applies to kARAContentTypeNotes - notes at borders will be adjusted on a per-region basis when using content based fades. Playback region content reading is available in ARA 1.0 already, thus such an implementation will be fully backwards compatible. Reading content at audio modification (or audio source) level is still valid and useful if the host needs access to the content in its original state, not transformed by a playback region, e.g. when implementing features such as tempo and signature detection through ARA. More... | |
| virtual bool | isPlaybackRegionContentAvailable (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type) noexcept=0 |
| Query whether the given content type is currently available for the given playback region. More... | |
| virtual ARAContentGrade | getPlaybackRegionContentGrade (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type) noexcept=0 |
| Query the current quality of the information provided for the given playback region and content type. More... | |
| virtual ARAContentReaderRef | createPlaybackRegionContentReader (ARAPlaybackRegionRef playbackRegionRef, ARAContentType type, const ARAContentTimeRange *range) noexcept=0 |
| Create a content reader for the given playback region and content type. This should only be called after availability has been confirmed using isPlaybackRegionContentAvailable(). The time range may be NULL, which means that the entire playback region shall be read, including its potential head and tail time. If a time range is specified, all events that at least partially intersect with the range will be read. The time range must be given in playback time, and the time stamps provided by the content reader are in playback time as well. More... | |
| virtual ARAInt32 | getContentReaderEventCount (ARAContentReaderRef contentReaderRef) noexcept=0 |
| Query how many events the given reader exposes. More... | |
| virtual const void * | getContentReaderDataForEvent (ARAContentReaderRef contentReaderRef, ARAInt32 eventIndex) noexcept=0 |
| Query data of the given event of the given reader. The returned pointer is owned by the plug-in and must remain valid until either getContentReaderDataForEvent() is called again or the content reader is destroyed. More... | |
| virtual void | destroyContentReader (ARAContentReaderRef contentReaderRef) noexcept=0 |
| Destroy the given content reader. More... | |
| virtual bool | isAudioSourceContentAnalysisIncomplete (ARAAudioSourceRef audioSourceRef, ARAContentType contentType) noexcept=0 |
| Query whether an analysis of the given content type has been done for the given audio source. This call will typically be used when the host uses the plug-in as a detection engine in the background (i.e. without presenting the UI to the user). In that scenario, the host will trigger the analysis of the desired content types using requestAudioSourceContentAnalysis() and then wait until the plug-in calls ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged(). From that call, the host will query the plug-in via isAudioSourceContentAnalysisIncomplete() to determine which of the analysis requests have completed. If the host did request a specific algorithm to be used, then the plug-in should return kARATrue here until the request was satisfied (or rejected). More... | |
| virtual void | requestAudioSourceContentAnalysis (ARAAudioSourceRef audioSourceRef, ARASize contentTypesCount, const ARAContentType contentTypes[]) noexcept=0 |
| Explicitly trigger a certain analysis. If the host wants to use the plug-in as detection engine, it needs to explicitly trigger the desired analysis, since otherwise the plug-in may postpone any analysis as suitable. To allow for optimizing the analysis on the plug-in side, all content types that are of interest for the host should be specified in a single call if possible. Note that the plug-in may choose to perform any additional analysis at any point in time if this is appropriate for its design. It will call ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged() if such an analysis concludes successfully so that the host can update accordingly. The provided content types must be a non-empty subset of the plug-in's ARAFactory::analyzeableContentTypes. To request all analysis types exported by the plug-in, hosts can directly pass analyzeableContentTypes and -Count from the plug-in's ARAFactory. The contentTypes pointer may be only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere. Note that ARA 2.0 adds the capability for the host to also request the use of a certain processing algorithm via requestProcessingAlgorithmForAudioSource() - if both are used then the algorithm must be selected before requesting the analysis. More... | |
| virtual ARAInt32 | getProcessingAlgorithmsCount () noexcept=0 |
| Return the count of processing algorithms provided by the plug-in. If this optional method is not implemented or the call returns 0, then the plug-in does not support algorithm selection through the host and the other related functions below must not be called. More... | |
| virtual const ARAProcessingAlgorithmProperties * | getProcessingAlgorithmProperties (ARAInt32 algorithmIndex) noexcept=0 |
| List of processing algorithms provided by the plug-in, described by their properties. This method must be implemented if getProcessingAlgorithmsCount() is implemented. Provides a unique identifier and a user-readable name of the algorithm as displayed in the plug-in. The host should present the algorithms to the user in the order of this list, e.g. in a menu. For a given version of the plug-in, the count and the order and values of the persistentIDs must be the same, while the names may depend on localization settings that can be different on different machines or between individual runs of the host. The list may however change between different versions of the plug-in. Both hosts and plug-ins must implement fallbacks for loading a document that contains an processing algorithm persistentID which is no longer supported by the plug-in. The pointers returned by this calls must remain valid until the document controller is destroyed. More... | |
| virtual ARAInt32 | getProcessingAlgorithmForAudioSource (ARAAudioSourceRef audioSourceRef) noexcept=0 |
| Query currently used processing algorithm for a given audio source. This method must be implemented if getProcessingAlgorithmsCount() is implemented. After the plug-in has concluded an analysis (as indicated via ARAModelUpdateControllerInterface::notifyAudioSourceContentChanged()), the host can query which processing algorithm was used and update its UI accordingly. This is particularly relevant if the host did explicitly request an analysis with a specific algorithm, but the plug-in was unable to satisfy this request for some reason. Similarly, the user may have changed the algorithm through the plug-in's UI. Note that until the first analysis has completed (i.e. as long as isAudioSourceContentAnalysisIncomplete() returns kARATrue), the value returned here may be an abstract default, not related to the actual audio source content. This will e.g. typically be the case in Melodyne, which uses an "automatic mode" as default until the first analysis has determined the actual processing algorithm that is suitable for the material. The call should not be made while isAudioSourceContentAnalysisIncomplete() returns kARATrue, because the returned value is likely stale. More... | |
| virtual void | requestProcessingAlgorithmForAudioSource (ARAAudioSourceRef audioSourceRef, ARAInt32 algorithmIndex) noexcept=0 |
| Request that any future analysis of the given audio source should use the given processing algorithm. This method must be implemented if getProcessingAlgorithmsCount() is implemented. This both affects any analysis requested by the host via requestAudioSourceContentAnalysis() as well as any analysis done by the plug-in on demand. Since this typically results in a model graph edit, calling this functions must be guarded by beginEditing() and endEditing(). Note that the plug-in is not required to heed this request if its internal state suggest otherwise, or if the user switches actively to a different algorithm. Also, some algorithms may be "meta" algorithms that will be replaced by a different actual algorithm, such as the "automatic" default algorithm in Melodyne which will pick an appropriate algorithm from the remaining list of algorithms when doing the initial analysis. More... | |
| virtual bool | isLicensedForCapabilities (bool runModalActivationDialogIfNeeded, ARASize contentTypesCount, const ARAContentType contentTypes[], ARAPlaybackTransformationFlags transformationFlags) noexcept=0 |
| With this optional call, hosts can test whether the current license state of the plug-in allows for requesting analysis of the given content types and rendering the given playback transformations (see requestAudioSourceContentAnalysis() and ARAPlaybackRegionProperties::transformationFlags). The host can also optionally instruct the plug-in to run a modal licensing dialog if the current license is not sufficient to perform the selected engine tasks, so that the user can review and adjust the licensing accordingly, such downloading a license from their respective user account or even purchase an upgrade that enables the requested features. The provided content types must be a subset of the plug-in's ARAFactory::analyzeableContentTypes. To request all analysis types exported by the plug-in, hosts can directly pass analyzeableContentTypes and -Count from the ARAFactory. The contentTypes pointer may be only valid for the duration of the call, it must be evaluated inside the call, and the pointer must not be stored anywhere. If not intending to use analysis, the count should be 0 and the array pointer NULL. The transformationFlags must be a subset of the plug-in's ARAFactory::supportedPlaybackTransformationFlags, and may be kARAPlaybackTransformationNoChanges if not intending to use transformations. The call returns kARATrue if the (potentially updated) license is sufficient to perform the requested tasks. More... | |