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}