Crate clack_host

Expand description

A low-level library to create CLAP audio hosts in safe Rust.

§Plugin Lifecycle

CLAP hosts and plugins go through a specific set of steps before they are able to process audio. The general lifecycle is explained below, with links to more detailed documentation for each step. Also see the example section below for a code snippet presenting how this lifecycle can be generally implemented using Clack.

Before starting to deal with the plugins themselves, CLAP hosts need implementations for all the different callbacks a plugin may use to interact with the host. This is done by implementing the Host trait, and its associated sub-types (one for each thread specification). See the host module documentation for more information about how to implement the Host trait, and on CLAP’s thread specifications model.

CLAP plugins are distributed in dynamic library files. These are prebuilt dynamically-loaded libraries (with a .clap extension), and can contain the implementations of multiple plugins. They expose an entry that can be loaded and initialized with the PluginEntry::load method. See the entry module documentation for more information.
Plugins’ entry points can expose multiple factories. These are singleton objects that can provide various functionality. The one of main interest is the PluginFactory, which exposes methods to list and instantiate plugins. It can be retrieved from a PluginEntry using the PluginEntry::get_plugin_factory method.

See the factory module documentation to learn more about factories.
The PluginFactory can be used to list PluginDescriptors, each of which contains various information (displayed name, author, etc.) about the plugins included in this entry, including their unique IDs. These can be displayed in a list for the user to chose from.
The selected plugin’s ID can now be used to create a new PluginInstance using its new method. This is also where the Host types come into play, as they need to be ready to handle the plugin instance’s callbacks.

See the PluginInstance::new method’s documentation for for more detail.
The plugin instance now needs to be activated for audio processing, using the activate method. This method receives the current PluginAudioConfiguration, which allows it to allocate its buffers with proper sizes depending on sample rate, for instance. This is also where the host should allocate its own audio and event buffers (see EventBuffers and AudioPorts), and also where the AudioProcessor type is created to handle audio processing callbacks.

If the plugin activation is successful, the plugin’s StoppedAudioProcessor is returned.

All of this allocation always happens on the main thread. Also, because the allocated buffers are dependent on the given configuration, plugins have to be deactivated and then re-activated whenever it changes.
Once the StoppedAudioProcessor is created and active, we can send it to another thread dedicated to audio processing, while the main instance type has to stay on the main thread (it is not Send, while the audio processor is). Once there, all we need to do is to indicate that continuous processing is about to start, using the start_processing method, which consumes the StoppedAudioProcessor and returns a StartedAudioProcessor.

Note that if this pattern of consuming the audio processors is too cumbersome, they can be converted into a PluginAudioProcessor using the Into trait, which handles switching between both states using only a &mut reference, at the cost of making the start_processing, process, and stop_processing operations fallible at runtime if the lifecycle isn’t properly handled. See the PluginAudioProcessor documentation for more information.
Perform the processing of a block of audio and events using the process method.

Because CLAP Audio and Event buffers are generic, some cheap, short-lived wrappers around the audio and event buffers must be crated for each process call, in order to be passed to the plugin’s process method.

Those buffer wrappers are InputEvents and OutputEvents for events, and InputAudioBuffers and OutputAudioBuffers for audio (obtained via a call to AudioPorts::with_input_buffers and. AudioPorts::with_output_buffers respectively).

See the documentation of those buffer types for more detail on what types they support, as well as the process method’s documentation for more information.
Once continuous processing has stopped, the host needs to call start_processing, in a similar fashion to Step 6 above.
The audio processor now has to be sent back to the main thread to be deactivated (in order to not perform de-allocations in the realtime audio thread). The PluginInstance::deactivate can then be used to consume the Audio Processor. Only then, the PluginInstance itself can be dropped to destroy the instance entirely.

§Example

Note that this example isn’t a full implementation and many details are left out: it is meant to give an overview of Clack’s APIs and how they relate to a CLAP plugin’s lifecycle.

For more details instruction on how to create a full, correct Clack host implementation, refer to the submodules’ and types’ documentation on each topic linked above.

 use clack_host::events::event_types::*;
 use clack_host::prelude::*;

 // Prepare our (extremely basic) host implementation

 struct MyHostShared;

 impl<'a> SharedHandler<'a> for MyHostShared {
   /* ... */
 }

 struct MyHost;
 impl HostHandlers for MyHost {
     type Shared<'a> = MyHostShared;

     type MainThread<'a> = ();
     type AudioProcessor<'a> = ();
 }

 // Information about our totally legit host.
 let host_info = HostInfo::new("Legit Studio", "Legit Ltd.", "https://example.com", "4.3.2")?;

 // Step 1: Load the entry in memory.
 let entry = PluginEntry::load("/home/user/.clap/u-he/libdiva.so")?;

 // Step 2: Get the Plugin factory of this entry.
 let plugin_factory = entry.get_plugin_factory().unwrap();

 // Step 3: Find the descriptor of plugin we're interested in.
 let plugin_descriptor = plugin_factory.plugin_descriptors()
     // We're assuming this specific plugin is in this entry for this example.
     // A real host would store all descriptors in a list and show them to the user.
     .find(|d| d.id().unwrap().to_bytes() == b"com.u-he.diva")
     .unwrap();

 // Let's check we are indeed loading the right plugin.
 assert_eq!(plugin_descriptor.name().unwrap().to_bytes(), b"Diva");

 // Step 4: Create the plugin instance
 let mut plugin_instance = PluginInstance::<MyHost>::new(
     |_| MyHostShared,
     |_| (),
     &entry,
     plugin_descriptor.id().unwrap(),
     &host_info
 )?;

 // Step 5: Activate the plugin (allocating the audio processor),
 // and allocate associated buffers.

 // In this example, we will only process 4 samples at a time
 let audio_configuration = PluginAudioConfiguration {
     sample_rate: 48_000.0,
     min_frames_count: 4,
     max_frames_count: 4,
 };
 let audio_processor = plugin_instance.activate(|_, _| (), audio_configuration)?;

 // Event buffers
 // For this example, we'll only have a single input event.
 let note_on_event = NoteOnEvent::new(0, Pckn::new(0u16, 0u16, 12u16, 60u32), 4.2);
 let input_events_buffer = [note_on_event];
 let mut output_events_buffer = EventBuffer::new();

 // Audio buffers
 let mut input_audio_buffers = [[0.0f32; 4]; 2]; // 2 channels (stereo), 1 port
 let mut output_audio_buffers = [[0.0f32; 4]; 2];

 // Audio port buffers
 let mut input_ports = AudioPorts::with_capacity(2, 1); // 2 channels (stereo), 1 port
 let mut output_ports = AudioPorts::with_capacity(2, 1);

 // Let's send the audio processor to a dedicated audio processing thread.
 let audio_processor = std::thread::scope(|s| s.spawn(|| {
    // Step 6: Start the audio processor.
    let mut audio_processor = audio_processor.start_processing().unwrap();

    // Step 7: Process audio and events.
    // Borrow all buffers, and wrap them in cheap CLAP-compatible structs.
    let input_events = InputEvents::from_buffer(&input_events_buffer);
    let mut output_events = OutputEvents::from_buffer(&mut output_events_buffer);

    let mut input_audio = input_ports.with_input_buffers([AudioPortBuffer {
        latency: 0,
        // We only use F32 (32-bit floating point) audio
        channels: AudioPortBufferType::f32_input_only(
            // These buffers can be marked constant, as they only contain zeros
            input_audio_buffers.iter_mut().map(|b| InputChannel::constant(b))
        )
    }]);

    let mut output_audio = output_ports.with_output_buffers([AudioPortBuffer {
        latency: 0,
        channels: AudioPortBufferType::f32_output_only(
            output_audio_buffers.iter_mut().map(|b| b.as_mut_slice())
        )
    }]);

    // Finally do the processing itself.
    let status = audio_processor.process(
        &input_audio,
        &mut output_audio,
        &input_events,
        &mut output_events,
        None,
        None
    ).unwrap();

    // This plugin has finished processing and requests to be put to sleep.
    assert_eq!(status, ProcessStatus::Sleep);

    // Step 8: if requested by the plugin or required to by the host or user, stop processing
    let audio_processor = audio_processor.stop_processing();

    // Send the audio processor back to be deallocated by the main thread.
    audio_processor
 }).join().unwrap());

 // A real host implementation might forward the results to an output device,
 // or pass it along a processing chain.
 // Here, we are only going to check the results manually.


 // The raw audio for each channel
 assert_eq!(&[42.0f32, 69.0, 21.0, 34.5], &output_audio_buffers[0]);
 assert_eq!(&[42.0f32, 69.0, 21.0, 34.5], &output_audio_buffers[1]);

 // The input note event has been passed through
 assert_eq!(output_events_buffer.get(0).unwrap(), &note_on_event);
 assert_eq!(output_events_buffer.len(), 1);

 // Step 9: stop and deactivate the plugin.

 plugin_instance.deactivate(audio_processor);

Modules§

entry: Loading and handling of CLAP plugin entry files.
events: Audio-processing events and related utilities.
extensions: The host side of the Clack extension system.
factory: Factory types and associated utilities.
host: Core types and traits to implement CLAP host callback handlers.
plugin: Core types and traits to instantiate and interact with CLAP plugins.
prelude: A helpful prelude re-exporting all the types related to host implementation.
process: Plugin audio processing types and related utilities.
stream: CLAP I/O stream utilities.
utils: Various CLAP-related utilities.

Crate clack_host

Crate clack_host Copy item path

§Plugin Lifecycle

§Example

Modules§

Crate clack_host