Skip to main content

aura_core/
bus.rs

1//! Main-bus channel layouts for format wrappers.
2//!
3//! Plugins declare supported layouts via [`PluginLogic::bus_layouts`](crate::PluginLogic::bus_layouts).
4//! Default is stereo in/out. Mono-only or dual mono+stereo is opt-in.
5//! One optional sidechain input and one optional aux output can be declared per layout.
6
7/// Channel width of a main audio bus.
8#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
9pub enum ChannelConfig {
10    Mono,
11    Stereo,
12}
13
14impl ChannelConfig {
15    #[must_use]
16    pub const fn channel_count(self) -> u32 {
17        match self {
18            Self::Mono => 1,
19            Self::Stereo => 2,
20        }
21    }
22
23    #[must_use]
24    pub const fn name(self) -> &'static str {
25        match self {
26            Self::Mono => "Mono",
27            Self::Stereo => "Stereo",
28        }
29    }
30}
31
32/// One complete I/O layout (main in/out + optional sidechain in + optional aux out).
33///
34/// Instruments can use [`Self::output_only`]. Effects use [`Self::mono`] /
35/// [`Self::stereo`] / [`Self::stereo_and_mono`]. Add buses via
36/// [`Self::with_sidechain`] / [`Self::with_aux`].
37#[derive(Clone, Copy, Debug, PartialEq, Eq)]
38pub struct BusLayout {
39    /// Main input width. `None` = no audio input (generator / instrument).
40    pub main_in: Option<ChannelConfig>,
41    /// Main output width.
42    pub main_out: ChannelConfig,
43    /// Optional sidechain input bus. `None` = no sidechain.
44    pub sidechain_in: Option<ChannelConfig>,
45    /// Optional aux output bus. `None` = no aux out.
46    pub aux_out: Option<ChannelConfig>,
47}
48
49impl BusLayout {
50    #[must_use]
51    pub const fn mono() -> Self {
52        Self {
53            main_in: Some(ChannelConfig::Mono),
54            main_out: ChannelConfig::Mono,
55            sidechain_in: None,
56            aux_out: None,
57        }
58    }
59
60    #[must_use]
61    pub const fn stereo() -> Self {
62        Self {
63            main_in: Some(ChannelConfig::Stereo),
64            main_out: ChannelConfig::Stereo,
65            sidechain_in: None,
66            aux_out: None,
67        }
68    }
69
70    /// Output-only layout (instrument / generator).
71    #[must_use]
72    pub const fn output_only(out: ChannelConfig) -> Self {
73        Self {
74            main_in: None,
75            main_out: out,
76            sidechain_in: None,
77            aux_out: None,
78        }
79    }
80
81    /// Return a copy of this layout with the given sidechain input bus.
82    #[must_use]
83    pub const fn with_sidechain(self, sidechain: ChannelConfig) -> Self {
84        Self {
85            sidechain_in: Some(sidechain),
86            ..self
87        }
88    }
89
90    /// Return a copy of this layout with the given aux output bus.
91    #[must_use]
92    pub const fn with_aux(self, aux: ChannelConfig) -> Self {
93        Self {
94            aux_out: Some(aux),
95            ..self
96        }
97    }
98
99    /// Default effect set: stereo first (host default), then mono.
100    #[must_use]
101    pub fn stereo_and_mono() -> Vec<Self> {
102        vec![Self::stereo(), Self::mono()]
103    }
104
105    #[must_use]
106    pub const fn main_input_channels(self) -> u32 {
107        match self.main_in {
108            Some(c) => c.channel_count(),
109            None => 0,
110        }
111    }
112
113    #[must_use]
114    pub const fn sidechain_input_channels(self) -> u32 {
115        match self.sidechain_in {
116            Some(c) => c.channel_count(),
117            None => 0,
118        }
119    }
120
121    #[must_use]
122    pub const fn aux_output_channels(self) -> u32 {
123        match self.aux_out {
124            Some(c) => c.channel_count(),
125            None => 0,
126        }
127    }
128
129    /// CLAP/VST3 input *port* count (main + optional sidechain), not channels.
130    ///
131    /// Stereo sidechain is still one port with two channels. Using
132    /// [`Self::sidechain_input_channels`] here advertises extra ports with
133    /// duplicate ids and breaks host routing (Bitwig dry-passthrough).
134    #[must_use]
135    pub const fn input_port_count(self) -> u32 {
136        let main = if self.main_in.is_some() { 1 } else { 0 };
137        let sc = if self.sidechain_in.is_some() { 1 } else { 0 };
138        main + sc
139    }
140
141    /// CLAP/VST3 output *port* count (main + optional aux), not channels.
142    #[must_use]
143    pub const fn output_port_count(self) -> u32 {
144        if self.aux_out.is_some() { 2 } else { 1 }
145    }
146
147    /// Total audio input channels passed to [`AudioBuffer`](crate::AudioBuffer):
148    /// main inputs followed by sidechain inputs.
149    #[must_use]
150    pub const fn total_input_channels(self) -> u32 {
151        self.main_input_channels() + self.sidechain_input_channels()
152    }
153
154    #[must_use]
155    pub const fn main_output_channels(self) -> u32 {
156        self.main_out.channel_count()
157    }
158
159    /// Total audio output channels: main outputs followed by aux outputs.
160    #[must_use]
161    pub const fn total_output_channels(self) -> u32 {
162        self.main_output_channels() + self.aux_output_channels()
163    }
164
165    /// Human-readable config name for host menus (`clap.audio-ports-config`).
166    #[must_use]
167    pub fn config_name(self) -> String {
168        let base = match self.main_in {
169            Some(inn) if inn == self.main_out => inn.name().to_string(),
170            Some(inn) => format!("{} in / {} out", inn.name(), self.main_out.name()),
171            None => format!("{} out", self.main_out.name()),
172        };
173        let with_sc = match self.sidechain_in {
174            Some(sc) => format!("{base} + {} sidechain", sc.name()),
175            None => base,
176        };
177        match self.aux_out {
178            Some(aux) => format!("{with_sc} + {} aux", aux.name()),
179            None => with_sc,
180        }
181    }
182}
183
184/// Resolve a layout by index, defaulting to the first entry or stereo.
185#[must_use]
186pub fn layout_at(layouts: &[BusLayout], index: usize) -> BusLayout {
187    layouts
188        .get(index)
189        .copied()
190        .or_else(|| layouts.first().copied())
191        .unwrap_or_else(BusLayout::stereo)
192}
193
194#[cfg(test)]
195mod tests {
196    use super::*;
197
198    #[test]
199    fn mono_stereo_channel_counts() {
200        assert_eq!(BusLayout::mono().main_input_channels(), 1);
201        assert_eq!(BusLayout::mono().main_output_channels(), 1);
202        assert_eq!(BusLayout::stereo().main_input_channels(), 2);
203        assert_eq!(BusLayout::stereo().main_output_channels(), 2);
204        assert_eq!(
205            BusLayout::output_only(ChannelConfig::Stereo).main_input_channels(),
206            0
207        );
208    }
209
210    #[test]
211    fn stereo_and_mono_order() {
212        let v = BusLayout::stereo_and_mono();
213        assert_eq!(v, vec![BusLayout::stereo(), BusLayout::mono()]);
214    }
215
216    #[test]
217    fn layout_at_falls_back() {
218        assert_eq!(layout_at(&[], 0), BusLayout::stereo());
219        let v = BusLayout::stereo_and_mono();
220        assert_eq!(layout_at(&v, 1), BusLayout::mono());
221        assert_eq!(layout_at(&v, 99), BusLayout::stereo());
222    }
223
224    #[test]
225    fn sidechain_input_counts() {
226        let sc = BusLayout::stereo().with_sidechain(ChannelConfig::Mono);
227        assert_eq!(sc.main_input_channels(), 2);
228        assert_eq!(sc.sidechain_input_channels(), 1);
229        assert_eq!(sc.total_input_channels(), 3);
230        assert_eq!(sc.main_output_channels(), 2);
231        assert_eq!(sc.input_port_count(), 2);
232        assert_eq!(sc.output_port_count(), 1);
233        assert!(sc.config_name().contains("Mono sidechain"));
234    }
235
236    #[test]
237    fn stereo_sidechain_is_two_input_ports() {
238        let sc = BusLayout::stereo().with_sidechain(ChannelConfig::Stereo);
239        assert_eq!(sc.sidechain_input_channels(), 2);
240        assert_eq!(sc.total_input_channels(), 4);
241        assert_eq!(sc.input_port_count(), 2);
242    }
243
244    #[test]
245    fn aux_output_counts() {
246        let aux = BusLayout::stereo().with_aux(ChannelConfig::Stereo);
247        assert_eq!(aux.main_output_channels(), 2);
248        assert_eq!(aux.aux_output_channels(), 2);
249        assert_eq!(aux.total_output_channels(), 4);
250        assert_eq!(aux.output_port_count(), 2);
251        assert!(aux.config_name().contains("Stereo aux"));
252    }
253
254    #[test]
255    fn aux_and_sidechain() {
256        let both = BusLayout::stereo()
257            .with_sidechain(ChannelConfig::Mono)
258            .with_aux(ChannelConfig::Mono);
259        assert_eq!(both.input_port_count(), 2);
260        assert_eq!(both.output_port_count(), 2);
261        assert_eq!(both.total_input_channels(), 3);
262        assert_eq!(both.total_output_channels(), 3);
263    }
264}