Skip to main content

alpha2_model/
audio.rs

1use crate::{Animated, TrackId};
2use alpha2_time::{MediaTime, TICKS_PER_SECOND};
3use serde::{Deserialize, Serialize};
4
5pub(crate) const TICKS_PER_MS: u32 = 120;
6const _: () = assert!(TICKS_PER_SECOND == 1_000 * TICKS_PER_MS as i64);
7
8/// Largest linear amplitude accepted by any authored gain.
9pub const MAX_GAIN: f32 = 16.0;
10
11/// Most audio effects a project holds state for at once: the master's, the tracks', and
12/// those of clips holding state then (see [`AUDIO_EFFECT_STATE_MARGIN_MS`]). An equalizer is
13/// one effect regardless of bands.
14pub const MAX_AUDIO_EFFECTS: usize = 8_192;
15
16/// Most audio held in effect delay lines at once, in milliseconds, summed over the effects
17/// [`MAX_AUDIO_EFFECTS`] counts (a compressor's `lookahead_ms`, a reverb's
18/// [`REVERB_DELAY_MS`]). At the highest project rate this is under 100 MB of state.
19pub const MAX_AUDIO_DELAY_MS: u32 = 120_000;
20
21/// How long before its start, beyond its track's and its own compressor lookahead, a clip's
22/// effects count as holding state, in milliseconds. This covers one block of the largest size
23/// at the lowest project rate plus per-lookahead sample rounding. Effects count until the
24/// clip's end.
25pub const AUDIO_EFFECT_STATE_MARGIN_MS: u32 = 1_100;
26
27/// What one reverb counts toward [`MAX_AUDIO_DELAY_MS`]; its comb and allpass lines hold
28/// about 157 ms at any rate.
29pub const REVERB_DELAY_MS: u32 = 160;
30
31/// Largest peaking gain, in decibels either way, an EQ band renders.
32pub const MAX_EQ_GAIN_DB: f32 = 36.0;
33
34/// The resonances an EQ band renders.
35pub const EQ_Q_RANGE: std::ops::RangeInclusive<f32> = 0.05..=50.0;
36
37/// The frequencies an EQ band may name, in hertz: 10 Hz to just under the Nyquist frequency
38/// of the highest project rate. A band renders at most at 0.49 times the project's rate, so
39/// a higher band sounds at that limit.
40pub const EQ_FREQUENCY_RANGE_HZ: std::ops::RangeInclusive<f32> = 10.0..=47_040.0;
41
42/// Largest compressor ratio.
43pub const MAX_COMPRESSOR_RATIO: f32 = 100.0;
44
45/// Most effects one chain holds: a clip's, a track's, or the master's.
46pub const MAX_CHAIN_EFFECTS: usize = 16;
47
48/// Most bands one equalizer holds.
49pub const MAX_EQ_BANDS: usize = 16;
50
51/// The quietest compressor threshold or ducking depth, in decibels; both are at most 0 dB.
52pub const MIN_LEVEL_DB: f32 = -96.0;
53
54/// Longest compressor lookahead, in milliseconds.
55pub const MAX_LOOKAHEAD_MS: f32 = 100.0;
56
57/// Longest attack or release time, in milliseconds.
58pub const MAX_ENVELOPE_MS: f32 = 10_000.0;
59
60/// The filter shape of one equalizer band.
61#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
62#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
63#[serde(rename_all = "snake_case")]
64pub enum EqBandKind {
65    /// Bell-shaped parametric band.
66    Peaking,
67    /// Second-order low-pass.
68    LowPass,
69    /// Second-order high-pass.
70    HighPass,
71}
72
73/// A single equalizer section stored independently from its DSP implementation.
74#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
75#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
76#[serde(deny_unknown_fields)]
77pub struct EqBand {
78    /// Filter shape.
79    pub kind: EqBandKind,
80    /// Center or corner frequency in hertz, within [`EQ_FREQUENCY_RANGE_HZ`].
81    pub frequency_hz: f32,
82    /// Resonance, within [`EQ_Q_RANGE`]. Larger values produce narrower bands.
83    pub q: f32,
84    /// Peaking gain in decibels, at most [`MAX_EQ_GAIN_DB`] either way. Ignored by the pass
85    /// filters.
86    #[serde(default)]
87    pub gain_db: f32,
88}
89
90impl EqBand {
91    fn is_valid(self) -> bool {
92        EQ_FREQUENCY_RANGE_HZ.contains(&self.frequency_hz)
93            && EQ_Q_RANGE.contains(&self.q)
94            && self.gain_db.is_finite()
95            && self.gain_db.abs() <= MAX_EQ_GAIN_DB
96    }
97}
98
99/// A serializable single-input audio effect applied to a clip or track bus.
100///
101/// Sidechain ducking takes a second input, so it is authored per track through [`Ducking`].
102#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
103#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
104#[serde(deny_unknown_fields)]
105#[serde(tag = "type", rename_all = "snake_case")]
106pub enum AudioEffect {
107    /// Cascaded biquad sections.
108    Eq {
109        /// Ordered filter sections, 1 to [`MAX_EQ_BANDS`] of them.
110        #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_EQ_BANDS }>")]
111        #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_EQ_BANDS)))]
112        bands: Vec<EqBand>,
113    },
114    /// Lookahead dynamic range compression.
115    Compressor {
116        /// Level above which gain reduction begins, in decibels from [`MIN_LEVEL_DB`] to 0.
117        threshold_db: f32,
118        /// Downward ratio, from one (unity) to [`MAX_COMPRESSOR_RATIO`].
119        ratio: f32,
120        /// Attack time in milliseconds, positive and at most [`MAX_ENVELOPE_MS`].
121        attack_ms: f32,
122        /// Release time in milliseconds, positive and at most [`MAX_ENVELOPE_MS`].
123        release_ms: f32,
124        /// Lookahead in milliseconds, at most [`MAX_LOOKAHEAD_MS`]. Reported as graph latency.
125        #[serde(default)]
126        lookahead_ms: f32,
127    },
128    /// Schroeder reverberation.
129    Reverb {
130        /// Room size, in `0..=1`.
131        room_size: f32,
132        /// High-frequency damping, in `0..=1`.
133        damping: f32,
134        /// Wet mix, in `0..=1`.
135        mix: f32,
136    },
137}
138
139impl AudioEffect {
140    /// What this effect counts toward [`MAX_AUDIO_DELAY_MS`], in ticks (120 per millisecond),
141    /// rounded up. Tick counts are exact, so a project's effects sum the same in any order.
142    #[must_use]
143    pub fn delay_ticks(&self) -> u64 {
144        match self {
145            Self::Eq { .. } => 0,
146            Self::Compressor { .. } => self.lookahead_ticks(),
147            Self::Reverb { .. } => u64::from(REVERB_DELAY_MS) * u64::from(TICKS_PER_MS),
148        }
149    }
150
151    /// How early a mixer reads this effect's input, in ticks, rounded up: a compressor's
152    /// `lookahead_ms`.
153    #[must_use]
154    pub fn lookahead_ticks(&self) -> u64 {
155        match self {
156            // A 32-bit value times 120 is exact in 64 bits, so rounding it up is too.
157            #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
158            Self::Compressor { lookahead_ms, .. } if *lookahead_ms > 0.0 => {
159                (f64::from(*lookahead_ms) * f64::from(TICKS_PER_MS)).ceil() as u64
160            }
161            _ => 0,
162        }
163    }
164
165    pub(crate) fn is_valid(&self) -> bool {
166        match self {
167            Self::Eq { bands } => {
168                !bands.is_empty()
169                    && bands.len() <= MAX_EQ_BANDS
170                    && bands.iter().copied().all(EqBand::is_valid)
171            }
172            Self::Compressor {
173                threshold_db,
174                ratio,
175                attack_ms,
176                release_ms,
177                lookahead_ms,
178            } => {
179                threshold_db.is_finite()
180                    && (MIN_LEVEL_DB..=0.0).contains(threshold_db)
181                    && (1.0..=MAX_COMPRESSOR_RATIO).contains(ratio)
182                    && positive_ms(*attack_ms)
183                    && positive_ms(*release_ms)
184                    && lookahead_ms.is_finite()
185                    && (0.0..=MAX_LOOKAHEAD_MS).contains(lookahead_ms)
186            }
187            Self::Reverb {
188                room_size,
189                damping,
190                mix,
191            } => unit(*room_size) && unit(*damping) && unit(*mix),
192        }
193    }
194}
195
196/// Sidechain ducking authored on the track that is attenuated.
197#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
198#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
199#[serde(deny_unknown_fields)]
200pub struct Ducking {
201    /// Track whose mixed output drives the envelope follower.
202    pub sidechain_track: TrackId,
203    /// Linear level above which attenuation begins. Positive.
204    pub threshold: f32,
205    /// Maximum attenuation in decibels, from [`MIN_LEVEL_DB`] to 0.
206    pub depth_db: f32,
207    /// Attack time in milliseconds, positive and at most [`MAX_ENVELOPE_MS`].
208    pub attack_ms: f32,
209    /// Release time in milliseconds, positive and at most [`MAX_ENVELOPE_MS`].
210    pub release_ms: f32,
211}
212
213impl Ducking {
214    fn is_valid(&self) -> bool {
215        self.threshold.is_finite()
216            && self.threshold > 0.0
217            && self.depth_db.is_finite()
218            && (MIN_LEVEL_DB..=0.0).contains(&self.depth_db)
219            && positive_ms(self.attack_ms)
220            && positive_ms(self.release_ms)
221    }
222}
223
224/// Curve applied by a clip's fade in and fade out.
225#[derive(Copy, Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
226#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
227#[serde(rename_all = "snake_case")]
228pub enum FadeShape {
229    /// Amplitude moves linearly. Two linear fades over one overlap dip by 6 dB.
230    #[default]
231    Linear,
232    /// Amplitude follows a quarter sine. Two of these crossfade at constant power.
233    EqualPower,
234}
235
236impl FadeShape {
237    /// Maps linear fade progress in `0..=1` to an amplitude multiplier.
238    #[must_use]
239    pub fn amplitude(self, progress: f32) -> f32 {
240        let progress = progress.clamp(0.0, 1.0);
241        match self {
242            Self::Linear => progress,
243            Self::EqualPower => libm::sinf(progress * core::f32::consts::FRAC_PI_2),
244        }
245    }
246}
247
248/// Per-clip audio presentation controls.
249#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
250#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
251#[serde(deny_unknown_fields)]
252pub struct AudioProperties {
253    /// Animated linear amplitude constrained to `0..=MAX_GAIN`.
254    #[serde(default = "unit_gain")]
255    pub gain: Animated<f32>,
256    /// Animated stereo position from `-1` (left) to `1` (right).
257    #[serde(default = "center_pan")]
258    pub pan: Animated<f32>,
259    /// Fade-in duration measured from the clip's timeline start. Non-negative.
260    #[serde(default)]
261    pub fade_in: MediaTime,
262    /// Fade-out duration measured back from the clip's timeline end. Non-negative.
263    #[serde(default)]
264    pub fade_out: MediaTime,
265    /// Curve used by both fades.
266    #[serde(default)]
267    pub fade_shape: FadeShape,
268    /// Silences this clip without removing it.
269    #[serde(default)]
270    pub muted: bool,
271    /// Ordered single-input effects applied before the track bus, at most [`MAX_CHAIN_EFFECTS`].
272    #[serde(default)]
273    #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_CHAIN_EFFECTS }>")]
274    #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_CHAIN_EFFECTS)))]
275    pub effects: Vec<AudioEffect>,
276    /// Keeps the clip's pitch when its speed is not 1 by time-stretching instead of resampling.
277    /// No effect at speed 1, on loops or on freezes.
278    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
279    pub preserve_pitch: bool,
280    /// The source's audio stream the clip plays, counted from 0 over the file's audio streams in
281    /// container order. Absent plays the stream the host picks by default.
282    #[serde(default, skip_serializing_if = "Option::is_none")]
283    pub stream: Option<u32>,
284    /// The stream's channels the clip plays, by index. One index plays that channel as a mono
285    /// source; two play a stereo pair, left then right. Absent plays every channel, folded by
286    /// speaker position. At most two distinct indices.
287    #[serde(default, skip_serializing_if = "Option::is_none")]
288    #[serde(
289        deserialize_with = "crate::bounded::option_seq::<_, _, { crate::MAX_SELECTED_CHANNELS }>"
290    )]
291    #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_SELECTED_CHANNELS)))]
292    pub channels: Option<Vec<u32>>,
293}
294
295/// The most source channels [`AudioProperties::channels`] selects.
296pub const MAX_SELECTED_CHANNELS: usize = 2;
297
298impl Default for AudioProperties {
299    fn default() -> Self {
300        Self {
301            gain: unit_gain(),
302            pan: center_pan(),
303            fade_in: MediaTime::ZERO,
304            fade_out: MediaTime::ZERO,
305            fade_shape: FadeShape::Linear,
306            muted: false,
307            effects: Vec::new(),
308            preserve_pitch: false,
309            stream: None,
310            channels: None,
311        }
312    }
313}
314
315impl AudioProperties {
316    /// Returns whether this clip can contribute signal at any timestamp.
317    #[must_use]
318    pub fn is_audible(&self) -> bool {
319        !self.muted
320            && match &self.gain {
321                Animated::Constant { value } => *value > 0.0,
322                Animated::Keyframes { keyframes } => {
323                    keyframes.iter().any(|keyframe| keyframe.value > 0.0)
324                }
325                Animated::Data(_) => true,
326            }
327    }
328
329    pub(crate) fn validate(&self) -> bool {
330        valid_gain(&self.gain)
331            && valid_pan(&self.pan)
332            && self.fade_in.ticks() >= 0
333            && self.fade_out.ticks() >= 0
334            && self.effects.len() <= MAX_CHAIN_EFFECTS
335            && self.effects.iter().all(AudioEffect::is_valid)
336            && self.channels.as_deref().is_none_or(valid_channel_selection)
337    }
338}
339
340fn valid_channel_selection(channels: &[u32]) -> bool {
341    (1..=MAX_SELECTED_CHANNELS).contains(&channels.len())
342        && channels
343            .iter()
344            .all(|&channel| (channel as usize) < alpha2_media::MAX_AUDIO_CHANNELS)
345        && channels.first() != channels.get(1)
346}
347
348/// Per-track audio bus controls.
349#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
350#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
351#[serde(deny_unknown_fields)]
352pub struct TrackAudio {
353    /// Animated linear bus amplitude constrained to `0..=MAX_GAIN`.
354    #[serde(default = "unit_gain")]
355    pub gain: Animated<f32>,
356    /// Animated stereo position applied after the clip mix, from `-1` (left) to `1` (right).
357    #[serde(default = "center_pan")]
358    pub pan: Animated<f32>,
359    /// Silences this bus.
360    #[serde(default)]
361    pub muted: bool,
362    /// Restricts the mix to soloed buses when any track sets this.
363    #[serde(default)]
364    pub solo: bool,
365    /// Ordered single-input effects applied to the summed clip signal, at most
366    /// [`MAX_CHAIN_EFFECTS`].
367    #[serde(default)]
368    #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_CHAIN_EFFECTS }>")]
369    #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_CHAIN_EFFECTS)))]
370    pub effects: Vec<AudioEffect>,
371    /// Optional sidechain attenuation driven by another track.
372    #[serde(default)]
373    pub ducking: Option<Ducking>,
374}
375
376impl Default for TrackAudio {
377    fn default() -> Self {
378        Self {
379            gain: unit_gain(),
380            pan: center_pan(),
381            muted: false,
382            solo: false,
383            effects: Vec::new(),
384            ducking: None,
385        }
386    }
387}
388
389impl TrackAudio {
390    /// Whether this bus adds nothing to the mix: it is muted, or another track solos
391    /// (`any_solo`, [`crate::Timeline::any_solo`]) and this one does not.
392    #[must_use]
393    pub const fn is_silenced(&self, any_solo: bool) -> bool {
394        self.muted || (any_solo && !self.solo)
395    }
396
397    pub(crate) fn validate(&self) -> bool {
398        valid_gain(&self.gain)
399            && valid_pan(&self.pan)
400            && self.effects.len() <= MAX_CHAIN_EFFECTS
401            && self.effects.iter().all(AudioEffect::is_valid)
402            && self.ducking.as_ref().is_none_or(Ducking::is_valid)
403    }
404}
405
406/// Project-wide master bus settings.
407#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
408#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
409#[serde(deny_unknown_fields)]
410pub struct MasterAudio {
411    /// Animated linear master amplitude constrained to `0..=MAX_GAIN`.
412    #[serde(default = "unit_gain")]
413    pub gain: Animated<f32>,
414    /// Ordered single-input effects applied to the summed track buses, at most
415    /// [`MAX_CHAIN_EFFECTS`].
416    #[serde(default)]
417    #[serde(deserialize_with = "crate::bounded::seq::<_, _, { crate::MAX_CHAIN_EFFECTS }>")]
418    #[cfg_attr(feature = "schema", schemars(length(max = crate::MAX_CHAIN_EFFECTS)))]
419    pub effects: Vec<AudioEffect>,
420    /// Final peak limiter. Omitted means [`Limiter::default`]; an explicit `null` leaves the mix
421    /// unlimited.
422    #[serde(default = "default_limiter")]
423    pub limiter: Option<Limiter>,
424}
425
426impl Default for MasterAudio {
427    fn default() -> Self {
428        Self {
429            gain: unit_gain(),
430            effects: Vec::new(),
431            limiter: default_limiter(),
432        }
433    }
434}
435
436impl MasterAudio {
437    pub(crate) fn validate(&self) -> bool {
438        valid_gain(&self.gain)
439            && self.effects.len() <= MAX_CHAIN_EFFECTS
440            && self.effects.iter().all(AudioEffect::is_valid)
441            && self.limiter.is_none_or(Limiter::is_valid)
442    }
443}
444
445/// Final peak limiter placed at the end of the master bus.
446#[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
447#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
448#[serde(deny_unknown_fields)]
449pub struct Limiter {
450    /// Linear ceiling, positive and at most [`MAX_GAIN`]. One is full scale.
451    pub threshold: f32,
452    /// Release time in milliseconds, positive and at most [`MAX_ENVELOPE_MS`].
453    pub release_ms: f32,
454}
455
456impl Default for Limiter {
457    fn default() -> Self {
458        Self {
459            threshold: 1.0,
460            release_ms: 50.0,
461        }
462    }
463}
464
465impl Limiter {
466    fn is_valid(self) -> bool {
467        self.threshold.is_finite()
468            && self.threshold > 0.0
469            && self.threshold <= MAX_GAIN
470            && positive_ms(self.release_ms)
471    }
472}
473
474/// Serde default: a project without a `limiter` field keeps the safety ceiling.
475#[allow(clippy::unnecessary_wraps)]
476fn default_limiter() -> Option<Limiter> {
477    Some(Limiter::default())
478}
479
480fn unit_gain() -> Animated<f32> {
481    Animated::Constant { value: 1.0 }
482}
483
484fn center_pan() -> Animated<f32> {
485    Animated::Constant { value: 0.0 }
486}
487
488fn unit(value: f32) -> bool {
489    value.is_finite() && (0.0..=1.0).contains(&value)
490}
491
492fn positive_ms(value: f32) -> bool {
493    value.is_finite() && value > 0.0 && value <= MAX_ENVELOPE_MS
494}
495
496fn valid_gain(gain: &Animated<f32>) -> bool {
497    valid_range(gain, crate::Domain::GAIN)
498}
499
500fn valid_pan(pan: &Animated<f32>) -> bool {
501    valid_range(pan, crate::Domain::PAN)
502}
503
504fn valid_range(animation: &Animated<f32>, domain: crate::Domain) -> bool {
505    let valid = |value: f32| domain.contains(value);
506    match animation {
507        Animated::Constant { value } => valid(*value),
508        Animated::Keyframes { keyframes } => {
509            crate::animation::valid_keyframes(keyframes)
510                && keyframes.iter().all(|keyframe| valid(keyframe.value))
511        }
512        Animated::Data(_) => true,
513    }
514}