truce_core/
info.rs

1/// Static metadata about a plugin.
2#[derive(Clone, Debug)]
3pub struct PluginInfo {
4    pub name: &'static str,
5    pub vendor: &'static str,
6    pub url: &'static str,
7    pub version: &'static str,
8    pub category: PluginCategory,
9
10    /// Short identifier (`bundle_id` in `truce.toml`). Used to derive
11    /// the LV2 plugin URI (`{vendor.url}/lv2/{bundle_id}`); also a
12    /// stable, vendor-agnostic key for "this plugin" that doesn't
13    /// drift with display-name changes the way `clap_id` does.
14    pub bundle_id: &'static str,
15
16    // Format-specific IDs
17    pub vst3_id: &'static str,
18    pub clap_id: &'static str,
19    pub fourcc: [u8; 4],
20    pub au_type: [u8; 4],
21    pub au_manufacturer: [u8; 4],
22    pub aax_id: Option<&'static str>,
23    /// AAX plugin category string (e.g. "EQ", "Dynamics", "Reverb").
24    /// Maps to `AAX_ePlugInCategory` constants.
25    pub aax_category: Option<&'static str>,
26    /// VST3 "Plugin Type Categories" secondary token. The wrapper
27    /// emits this after the primary token (`Fx|<sub>`,
28    /// `Instrument|<sub>`) so hosts like Cubase route to the right
29    /// submenu. Values from the VST3 SDK list: `Delay`, `Distortion`,
30    /// `Dynamics`, `EQ`, `Filter`, `Mastering`, `Modulation`,
31    /// `Pitch Shift`, `Restoration`, `Reverb`, `Analyzer`, `Tools`,
32    /// `Surround`. Optional; when `None` only the primary token is
33    /// emitted and Cubase will fall back to "Other".
34    pub vst3_subcategory: Option<&'static str>,
35
36    /// Per-format display-name overrides, populated by
37    /// `truce::plugin_info!()` from the matching `truce.toml` keys.
38    /// Format wrappers fall back to `name` when the override is `None`.
39    /// Baked at compile time so back-to-back plugin builds with
40    /// different overrides don't invalidate the format wrapper's
41    /// build fingerprint.
42    ///
43    /// `au3_name` is exposed for parity with the other formats and
44    /// for user introspection, but `truce-au`'s `resolved_plugin_name`
45    /// reads `au_name` for both v2 and v3 builds - the v3 host's
46    /// displayed label comes from the appex `Info.plist`'s `AUNAME`
47    /// (which `cargo truce install --au3` populates from `au3_name`),
48    /// not from `g_descriptor->name`.
49    pub vst3_name: Option<&'static str>,
50    pub clap_name: Option<&'static str>,
51    pub vst2_name: Option<&'static str>,
52    pub au_name: Option<&'static str>,
53    pub au3_name: Option<&'static str>,
54    pub aax_name: Option<&'static str>,
55    pub lv2_name: Option<&'static str>,
56
57    /// Standalone-only. Format wrappers MUST NOT read this - it
58    /// exists for preview hosts (truce-standalone, the iOS `AUv3`
59    /// container app) that need a TOML-driven way to mute the
60    /// plug-in's audio output while keeping `process()` ticking, so
61    /// editors that visualise an input signal (analyzers, tuners,
62    /// spectrum displays) update from mic / file input without
63    /// closing a mic → speakers feedback loop. Set from
64    /// `mute_preview_output` in `truce.toml`. Real DAW hosts own
65    /// their own output graph; consulting this flag from a wrapper
66    /// would let plug-in authors silence the DAW's mix bus, which
67    /// is never what they want.
68    #[doc(hidden)]
69    pub mute_preview_output: bool,
70
71    /// Sample-accurate automation chunking tunables. Read by the
72    /// `chunked_process::process_chunked` helper that every format
73    /// wrapper routes `process()` through. Populated by
74    /// `truce::plugin_info!()` from `truce.toml`'s `[automation]`
75    /// table; defaults to [`AutomationConfig::DEFAULT`] when the
76    /// table is absent.
77    pub automation: AutomationConfig,
78}
79
80/// Sample-accurate chunking tunables baked into [`PluginInfo`] at
81/// compile time. Mirrors `truce_build::AutomationConfig` (the
82/// derive-time view of the same TOML key) but lives in `truce-core`
83/// so wrappers can read it without a `truce-build` dep.
84///
85/// See `truce-docs/docs/internal/parameter-dependent-chunking.md`.
86#[derive(Clone, Copy, Debug, PartialEq, Eq)]
87pub struct AutomationConfig {
88    /// Smallest sub-block size in samples. The chunker only splits
89    /// the audio block at split-eligible events whose `sample_offset`
90    /// is at least `block_start + min_subblock_samples` past the
91    /// current sub-block start; closer events are coalesced. Default
92    /// 32 (set via [`AutomationConfig::DEFAULT`]).
93    pub min_subblock_samples: u32,
94}
95
96impl AutomationConfig {
97    /// Default used when `truce.toml` omits the `[automation]` table.
98    pub const DEFAULT: Self = Self {
99        min_subblock_samples: 32,
100    };
101}
102
103impl Default for AutomationConfig {
104    fn default() -> Self {
105        Self::DEFAULT
106    }
107}
108
109/// Resolve a format's display-name override. Each wrapper picks its
110/// own `<format>_name` field off `PluginInfo` and passes the result
111/// here along with the `PluginInfo::name` fallback. Empty overrides
112/// (unset or set to `""`) fall through to `fallback`.
113#[must_use]
114pub fn resolve_name_override(
115    override_value: Option<&'static str>,
116    fallback: &'static str,
117) -> &'static str {
118    match override_value {
119        Some(s) if !s.is_empty() => s,
120        _ => fallback,
121    }
122}
123
124#[derive(Clone, Copy, Debug, PartialEq, Eq)]
125pub enum PluginCategory {
126    Effect,
127    Instrument,
128    /// MIDI note effect (e.g., transpose, arpeggiator). Processes MIDI events.
129    NoteEffect,
130    Analyzer,
131    Tool,
132}
133
134/// Convert a category string to [`PluginCategory`] at compile time.
135/// Used by the `plugin_info!()` macro.
136#[must_use]
137pub const fn category_from_str(s: &str) -> PluginCategory {
138    match s.as_bytes() {
139        b"Instrument" => PluginCategory::Instrument,
140        b"NoteEffect" => PluginCategory::NoteEffect,
141        b"Analyzer" => PluginCategory::Analyzer,
142        b"Tool" => PluginCategory::Tool,
143        _ => PluginCategory::Effect,
144    }
145}
146
147/// Helper to convert a 4-char string literal to `[u8; 4]` at compile time.
148/// Panics if the string is not exactly 4 ASCII bytes.
149///
150/// # Panics
151///
152/// Panics at compile time when used in a `const` context (preferred)
153/// or at runtime if `s.len() != 4`. ASCII-ness isn't checked here -
154/// callers that need it should validate separately.
155#[must_use]
156pub const fn fourcc(s: &[u8]) -> [u8; 4] {
157    assert!(s.len() == 4, "FourCC must be exactly 4 bytes");
158    [s[0], s[1], s[2], s[3]]
159}
truce_core/info.rs

truce_core/
info.rs
