Skip to main content

aura_core/
plugin.rs

1//! User-facing plugin logic (minimal f32 leaf).
2
3use std::sync::Arc;
4
5use aura_params::Params;
6
7use crate::buffer::AudioBuffer;
8use crate::bus::BusLayout;
9use crate::config::AudioConfig;
10use crate::editor::Editor;
11use crate::info::PluginInfo;
12use crate::preset::FactoryPreset;
13use crate::process::{ProcessContext, ProcessStatus};
14
15/// One entry in a plugin's custom note-name table (`CLAP_EXT_NOTE_NAME`).
16///
17/// Set `port`, `channel`, or `key` to `-1` to match any value (wildcard).
18pub struct NoteNameEntry {
19    pub port: i16,
20    pub channel: i16,
21    pub key: i16,
22    pub name: &'static str,
23}
24
25/// What plugin authors implement for realtime DSP + optional GUI factory.
26///
27/// Format wrappers (CLAP/VST3/LV2) call these methods.
28pub trait PluginLogic: 'static {
29    type Params: Params + Default;
30
31    /// Mutable per-instance DSP state. Owned by the shell, not `Self`.
32    type DspState: Send + 'static;
33
34    /// Static plugin metadata (CLAP id, vendor, …).
35    fn info() -> PluginInfo;
36
37    /// Supported bus layouts (first entry is the default).
38    ///
39    /// Override with [`BusLayout::mono`], [`BusLayout::stereo_and_mono`],
40    /// `.with_sidechain` / `.with_aux` as needed. Process must tolerate every
41    /// declared width (loop over buffer channels; do not hardcode 2).
42    ///
43    /// **LV2** uses only the first entry (no runtime layout switch).
44    #[must_use]
45    fn bus_layouts() -> Vec<BusLayout> {
46        vec![BusLayout::stereo()]
47    }
48
49    /// Build initial DSP state.
50    fn init(params: &Self::Params, sample_rate: f64) -> Self::DspState;
51
52    /// Host (re)prepare — allocate / clear DSP for the new config.
53    fn reset(state: &mut Self::DspState, params: &Self::Params, config: &AudioConfig);
54
55    /// Audio thread process.
56    ///
57    /// **Automation timing differs by format:** CLAP applies `CHUNKED` params
58    /// sample-accurately (block splits). VST3 applies the last point per block.
59    /// LV2 updates from control ports once per `run`. Write DSP that tolerates
60    /// both, or document format-specific behavior in the product.
61    fn process(
62        state: &mut Self::DspState,
63        params: &Self::Params,
64        buffer: &mut AudioBuffer<'_, f32>,
65        context: &mut ProcessContext,
66    ) -> ProcessStatus;
67
68    /// Optional GUI. Default: no editor.
69    fn editor(_params: Arc<Self::Params>) -> Option<Box<dyn Editor>> {
70        None
71    }
72
73    /// Reporting delay in samples (PDC). Default `0` (zero-latency FX).
74    ///
75    /// Hosts read this via CLAP `clap.latency` / VST3 `getLatencySamples`.
76    /// If the value changes after activation, format wrappers notify the host
77    /// (restart / latency-changed) so delay compensation stays honest.
78    #[must_use]
79    fn latency(_state: &Self::DspState) -> u32 {
80        0
81    }
82
83    /// Processing tail length in samples after input goes silent.
84    ///
85    /// Hosts read this via CLAP `clap.tail` / VST3 `getTailSamples`.
86    /// Default `0` (no tail). Return a large value (e.g. `u32::MAX`) when
87    /// the tail is effectively infinite / unknown.
88    #[must_use]
89    fn tail_length(_state: &Self::DspState) -> u32 {
90        0
91    }
92
93    /// Bundled factory presets for CLAP host browsers (`preset-discovery`
94    /// + `preset-load` PLUGIN location). Empty = no discovery factory.
95    #[must_use]
96    fn factory_presets() -> &'static [FactoryPreset] {
97        &[]
98    }
99
100    /// Load a host-chosen preset file (CLAP `preset-load` FILE location).
101    /// Default: shared host blob ([`crate::decode_state`], v1 or v2).
102    ///
103    /// # Errors
104    ///
105    /// Returns an error if the file cannot be read or is not a valid state blob.
106    fn load_preset_from_file(params: &Self::Params, path: &std::path::Path) -> Result<(), String> {
107        crate::preset::load_preset_file(params, path)
108    }
109
110    /// Host tuning pool changed (`clap.tuning`). Audio thread, next block.
111    /// **CLAP-oriented**; VST3/LV2 do not call this. Default: no-op.
112    fn tuning_changed(_state: &mut Self::DspState, _params: &Self::Params) {}
113
114    /// Custom note names (`CLAP_EXT_NOTE_NAME`). Non-empty activates the
115    /// extension. **CLAP-oriented**; unused on VST3/LV2. Default: empty.
116    #[must_use]
117    fn note_names() -> &'static [NoteNameEntry] {
118        &[]
119    }
120
121    /// Hardware control mapping changed (`CLAP_EXT_PARAM_INDICATION`
122    /// `set_mapping`). Main thread. **CLAP-oriented**. Default: no-op.
123    fn on_param_mapping(_params: &Self::Params, _param_id: u32, _has_mapping: bool) {}
124
125    /// Automation indication changed (`CLAP_EXT_PARAM_INDICATION`
126    /// `set_automation`). Main thread. **CLAP-oriented**. Default: no-op.
127    fn on_param_automation(_params: &Self::Params, _param_id: u32, _automation_state: u32) {}
128}