Trait DocumentController 

pub trait DocumentController {
    // Required methods
    fn destroy(&mut self);
    fn get_factory(&self) -> *const ARAFactory;
    fn begin_editing(&mut self);
    fn end_editing(&mut self);
    fn notify_model_updates(&mut self);
    fn update_document_properties(&mut self, properties: &ARADocumentProperties);
    fn create_audio_source(
        &mut self,
        host_ref: ARAAudioSourceHostRef,
        properties: &ARAAudioSourceProperties,
    ) -> ARAAudioSourceRef;
    fn update_audio_source_properties(
        &mut self,
        source: ARAAudioSourceRef,
        properties: &ARAAudioSourceProperties,
    );
    fn update_audio_source_content(
        &mut self,
        source: ARAAudioSourceRef,
        range: Option<&ARAContentTimeRange>,
        flags: ARAContentUpdateFlags,
    );
    fn enable_audio_source_samples_access(
        &mut self,
        source: ARAAudioSourceRef,
        enable: ARABool,
    );
    fn deactivate_audio_source_for_undo_history(
        &mut self,
        source: ARAAudioSourceRef,
        deactivate: ARABool,
    );
    fn destroy_audio_source(&mut self, source: ARAAudioSourceRef);
    fn request_audio_source_content_analysis(
        &mut self,
        source: ARAAudioSourceRef,
        count: ARASize,
        content_types: *const ARAContentType,
    ) -> ARABool;
    fn is_audio_source_content_available(
        &self,
        source: ARAAudioSourceRef,
        content_type: ARAContentType,
    ) -> ARABool;
    fn create_musical_context(
        &mut self,
        host_ref: ARAMusicalContextHostRef,
        properties: &ARAMusicalContextProperties,
    ) -> ARAMusicalContextRef;
    fn update_musical_context_properties(
        &mut self,
        ctx: ARAMusicalContextRef,
        properties: &ARAMusicalContextProperties,
    );
    fn update_musical_context_content(
        &mut self,
        ctx: ARAMusicalContextRef,
        range: Option<&ARAContentTimeRange>,
        flags: ARAContentUpdateFlags,
    );
    fn destroy_musical_context(&mut self, ctx: ARAMusicalContextRef);
    fn create_region_sequence(
        &mut self,
        host_ref: ARARegionSequenceHostRef,
        properties: &ARARegionSequenceProperties,
    ) -> ARARegionSequenceRef;
    fn update_region_sequence_properties(
        &mut self,
        seq: ARARegionSequenceRef,
        properties: &ARARegionSequenceProperties,
    );
    fn destroy_region_sequence(&mut self, seq: ARARegionSequenceRef);
    fn create_playback_region(
        &mut self,
        host_ref: ARAPlaybackRegionHostRef,
        audio_modification_ref: ARAAudioModificationRef,
        properties: &ARAPlaybackRegionProperties,
    ) -> ARAPlaybackRegionRef;
    fn update_playback_region_properties(
        &mut self,
        region: ARAPlaybackRegionRef,
        properties: &ARAPlaybackRegionProperties,
    );
    fn destroy_playback_region(&mut self, region: ARAPlaybackRegionRef);
    fn store_objects_to_archive(
        &mut self,
        archive_writer_host_ref: ARAArchiveWriterHostRef,
        filter: *const ARAStoreObjectsFilter,
    ) -> ARABool;
    fn restore_objects_from_archive(
        &mut self,
        archive_reader_host_ref: ARAArchiveReaderHostRef,
        filter: *const ARARestoreObjectsFilter,
    ) -> ARABool;
}

Plugin-side document controller.

Created once per DAW document. Manages audio sources, musical contexts, region sequences, playback regions, persistence, and undo history.

The DAW calls these methods through the function pointer vtable built by build_document_controller_instance.

Lifecycle

1. DAW creates a document → calls your ARAFactory callback
2. You return an ARADocumentControllerInstance
3. DAW calls begin_editing() → you set up internal state
4. DAW calls create_audio_source(), create_musical_context(), etc.
5. DAW calls request_audio_source_content_analysis() → you analyze
6. DAW calls end_editing() → you commit changes
7. DAW calls store_objects_to_archive() → you serialize to project
8. DAW calls destroy() → you free resources

Required Methods

fn destroy(&mut self)

Destroy the controller and free all resources.

Called by the DAW when the document is closed. After this call, no further callbacks will be received.

fn get_factory(&self) -> *const ARAFactory

Return a pointer to the static ARAFactory that created this controller.

The returned pointer must remain valid for the lifetime of the controller. This is how the DAW discovers the plugin’s capabilities (name, version, supported content types, archive IDs).

fn begin_editing(&mut self)

Begin an editing session.

All model changes between begin_editing and end_editing are treated as a single undoable operation. The plugin may defer expensive updates until end_editing is called.

fn end_editing(&mut self)

End an editing session.

The plugin should now perform any deferred updates and notify the host of changes via ARAModelUpdateControllerInterface.

fn notify_model_updates(&mut self)

Send all pending model update notifications to the host.

Called periodically by the DAW when not editing. The plugin may call back into the host using ARAModelUpdateControllerInterface during this call.

fn update_document_properties(&mut self, properties: &ARADocumentProperties)

Handle a change to the document’s properties (name, etc.).

fn create_audio_source( &mut self, host_ref: ARAAudioSourceHostRef, properties: &ARAAudioSourceProperties, ) -> ARAAudioSourceRef

Create a new audio source associated with this document.

Audio sources represent the raw audio data that playback regions reference. Sample data access is initially disabled — call enable_audio_source_samples_access to grant access.

Returns an opaque reference that identifies the source in future callbacks.

fn update_audio_source_properties( &mut self, source: ARAAudioSourceRef, properties: &ARAAudioSourceProperties, )

Update properties of an existing audio source.

Called when sample rate, channel count, or name changes. All properties are provided; the plugin determines which changed.

fn update_audio_source_content( &mut self, source: ARAAudioSourceRef, range: Option<&ARAContentTimeRange>, flags: ARAContentUpdateFlags, )

Called when audio sample data or content information for a source changes.

range is None if the entire source is affected. The plugin should invalidate any cached analysis for the affected range.

fn enable_audio_source_samples_access( &mut self, source: ARAAudioSourceRef, enable: ARABool, )

Grant or revoke access to audio sample data for a source.

When enable is non-zero, the plugin may read audio samples through the host’s audio access controller. When zero, sample access is revoked and any cached samples should be freed.

fn deactivate_audio_source_for_undo_history( &mut self, source: ARAAudioSourceRef, deactivate: ARABool, )

Manage undo history state for an audio source.

deactivate is non-zero when the host is about to purge undo history that references this source.

fn destroy_audio_source(&mut self, source: ARAAudioSourceRef)

Destroy an audio source and free its resources.

fn request_audio_source_content_analysis( &mut self, source: ARAAudioSourceRef, count: ARASize, content_types: *const ARAContentType, ) -> ARABool

Host requests analysis of specific content types for an audio source.

This is where you plug in your analysis engine. The content types are a subset of the plugin’s analyzeableContentTypes from the ARAFactory. When analysis completes, notify the host via ARAModelUpdateControllerInterface.

count is the number of entries in content_types.

fn is_audio_source_content_available( &self, source: ARAAudioSourceRef, content_type: ARAContentType, ) -> ARABool

Check whether analysis data is available for a given content type.

Returns non-zero if the plugin has analysis results ready.

fn create_musical_context( &mut self, host_ref: ARAMusicalContextHostRef, properties: &ARAMusicalContextProperties, ) -> ARAMusicalContextRef

Create a musical context (tempo, time signature, key).

fn update_musical_context_properties( &mut self, ctx: ARAMusicalContextRef, properties: &ARAMusicalContextProperties, )

Update properties of an existing musical context.

fn update_musical_context_content( &mut self, ctx: ARAMusicalContextRef, range: Option<&ARAContentTimeRange>, flags: ARAContentUpdateFlags, )

Called when musical context content changes.

fn destroy_musical_context(&mut self, ctx: ARAMusicalContextRef)

Destroy a musical context.

fn create_region_sequence( &mut self, host_ref: ARARegionSequenceHostRef, properties: &ARARegionSequenceProperties, ) -> ARARegionSequenceRef

Create a region sequence (time-ordered regions on a track).

fn update_region_sequence_properties( &mut self, seq: ARARegionSequenceRef, properties: &ARARegionSequenceProperties, )

Update properties of an existing region sequence.

fn destroy_region_sequence(&mut self, seq: ARARegionSequenceRef)

Destroy a region sequence.

fn create_playback_region( &mut self, host_ref: ARAPlaybackRegionHostRef, audio_modification_ref: ARAAudioModificationRef, properties: &ARAPlaybackRegionProperties, ) -> ARAPlaybackRegionRef

Create a playback region linked to an audio modification.

Playback regions define where and how audio modifications appear in the DAW timeline. Each playback region references an audio modification, which in turn references an audio source.

fn update_playback_region_properties( &mut self, region: ARAPlaybackRegionRef, properties: &ARAPlaybackRegionProperties, )

Update properties of an existing playback region.

fn destroy_playback_region(&mut self, region: ARAPlaybackRegionRef)

Destroy a playback region.

fn store_objects_to_archive( &mut self, archive_writer_host_ref: ARAArchiveWriterHostRef, filter: *const ARAStoreObjectsFilter, ) -> ARABool

Serialize document state for DAW project save.

Write analysis data through the provided archive writer. filter is None if all objects should be stored, or a filter specifying which objects to include.

Returns non-zero on success.

fn restore_objects_from_archive( &mut self, archive_reader_host_ref: ARAArchiveReaderHostRef, filter: *const ARARestoreObjectsFilter, ) -> ARABool

Deserialize document state from DAW project load.

Read analysis data through the provided archive reader. filter is None if all objects should be restored, or a filter specifying which objects to include.

Returns non-zero on success.

Implementors