From ef0f27a3066ffc08a088af10996a3299b73dd866 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 21:53:35 -0500 Subject: [PATCH 01/84] craft-math: stacked scripts in the linear format nest to the right (port of wordcraft#6083) a^b^c built (a^b)^c; Word builds a^(b^c), and the same for a_b_c and x^2^3. After a script operand, the same script operator now nests inside it. The chain stops at WRAP_DEPTH like every other wrap, so the #1456 guard holds. a_b^c, a^b_c and (a^b)^c are unchanged. From the PR's review: sin^2^3 on the function-name path nests to the right too (script_chain for the first script; a second script joins only when it is the other operator, log_2^3). A level that would make the whole tree too deep keeps its operator as text, as expr does at its own cap, and a ^ or _ the chain left at its cap isn't taken as the start of a function's operand. Ported from storytold/wordcraft#6083 (issue wordcraft#6074): its change to math_linear.rs and its tests/stacked_scripts.rs, with only paths and crate names changed. Its typing test (engine) and the docs/typing-parity.md note stay in WordCraft. --- crates/math/src/math_linear.rs | 48 +++++++++++++--- crates/math/tests/stacked_scripts.rs | 85 ++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+), 7 deletions(-) create mode 100644 crates/math/tests/stacked_scripts.rs diff --git a/crates/math/src/math_linear.rs b/crates/math/src/math_linear.rs index 39a25ab5d..fe8c8cd52 100644 --- a/crates/math/src/math_linear.rs +++ b/crates/math/src/math_linear.rs @@ -9,7 +9,9 @@ //! an operator or space; a parenthesised operand loses its parentheses). `^`/`_` with nothing //! before them are pre-scripts. A top-level `#` numbers the equation (`E=mc^2#(1)`). -use crate::math::{Arg, FracKind, MAX_DEPTH, MClass, MNode, MRun, ScriptKind, any_too_deep, is_nary_char, math_class, merge_runs, too_deep}; +use crate::math::{ + Arg, FracKind, MAX_DEPTH, MClass, MNode, MRun, ScriptKind, WRAP_DEPTH, any_too_deep, is_nary_char, math_class, merge_runs, too_deep, +}; /// Function names set upright and applied to the following operand. pub const FUNCTION_NAMES: &[&str] = &[ @@ -172,7 +174,7 @@ impl P { out.push(self.prescript(stops)); } else { self.i += 1; - let s = self.script_operand(stops); + let s = self.script_chain(c, stops, 0); if out.last().is_some_and(too_deep) { out.push(text(c)); out.extend(s); @@ -449,11 +451,14 @@ impl P { } Some(c @ ('^' | '_')) => { self.i += 1; - let s = self.script_operand(stops); + // `sin^2^3` nests to the right like any other script (#6074). + let s = self.script_chain(c, stops, 0); let mut n = attach_script(Some(MNode::Run(MRun::plain(word.clone()))), c == '^', s); - if let Some(c2 @ ('^' | '_')) = self.peek() { + // Only the other script joins it, and it nests the same way (`log_2^3`, `sin^2_a_b`); + // the same one again is what the chain left at its depth cap. + if let Some(c2 @ ('^' | '_')) = self.peek().filter(|&c2| c2 != c) { self.i += 1; - let s2 = self.script_operand(stops); + let s2 = self.script_chain(c2, stops, 0); n = attach_script(Some(n), c2 == '^', s2); } vec![n] @@ -465,7 +470,10 @@ impl P { self.i += 1; } let next = self.peek(); - let applies = next.is_some_and(|c| !stops.contains(&c) && !is_closer(c) && (!is_boundary(c) || c == '(' || matches!(c, '−' | '-' | '+'))); + // A `^`/`_` here is what the script chain left at its depth cap: text for `expr`, not an operand. + let applies = next.is_some_and(|c| { + !stops.contains(&c) && !is_closer(c) && !matches!(c, '^' | '_') && (!is_boundary(c) || c == '(' || matches!(c, '−' | '-' | '+')) + }); if !applies { return name; } @@ -584,7 +592,7 @@ impl P { } match c { '^' | '_' => { - let s = self.script_operand(stops); + let s = self.script_chain(c, stops, 0); let b = base(out); out.push(attach_script(b, c == '^', s)); } @@ -601,6 +609,32 @@ impl P { } } + /// A script operand, with the same script operator after it nested inside: `a^b^c` is + /// `a^(b^c)`, as Word builds it (#6074). The chain stops at `WRAP_DEPTH` like every other + /// wrap, so `x^1^1^1…` stays shallow (#1456) and the rest is left to the caller as text. The + /// cap holds for the whole tree too: when the operands are deep themselves, a level that would + /// make it too deep keeps its operator as text, as `expr` does. + fn script_chain(&mut self, op: char, stops: &[char], level: usize) -> Arg { + let s = self.script_operand(stops); + if self.peek() != Some(op) || s.is_empty() || level + 1 >= WRAP_DEPTH || self.tired() || any_too_deep(&s) { + return s; + } + self.i += 1; + self.depth += 1; + let inner = self.script_chain(op, stops, level + 1); + self.depth -= 1; + let (kind, sub, sup) = if op == '^' { (ScriptKind::Sup, Vec::new(), inner) } else { (ScriptKind::Sub, inner, Vec::new()) }; + let node = MNode::Script { kind, base: s, sub, sup }; + if !too_deep(&node) { + return vec![node]; + } + let MNode::Script { base: mut out, sub, sup, .. } = node else { return Vec::new() }; + out.push(text(op)); + out.extend(sub); + out.extend(sup); + out + } + /// A script or limit: a parenthesised group, a structure, a number, a signed operand, a run of /// letters (and digits) or one other character. fn script_operand(&mut self, stops: &[char]) -> Arg { diff --git a/crates/math/tests/stacked_scripts.rs b/crates/math/tests/stacked_scripts.rs new file mode 100644 index 000000000..9b3ffc3a2 --- /dev/null +++ b/crates/math/tests/stacked_scripts.rs @@ -0,0 +1,85 @@ +//! Stacked scripts in the linear format nest to the right, as Word builds them (#6074): the +//! superscript of `a^b^c` is `b^c`, so `a^b^c` is `a^(b^c)`. Mixed scripts still make one +//! sub-superscript, and brackets still group to the left. + +use craft_math::math::{MNode, MRun, ScriptKind, parse_linear}; + +fn a(t: &str) -> Vec { + vec![MNode::Run(MRun::new(t))] +} + +fn sup(base: Vec, s: Vec) -> MNode { + MNode::Script { kind: ScriptKind::Sup, base, sub: Vec::new(), sup: s } +} + +fn sub(base: Vec, s: Vec) -> MNode { + MNode::Script { kind: ScriptKind::Sub, base, sub: s, sup: Vec::new() } +} + +#[test] +fn stacked_scripts_nest_to_the_right() { + assert_eq!(parse_linear("a^b^c"), vec![sup(a("a"), vec![sup(a("b"), a("c"))])]); + assert_eq!(parse_linear("a_b_c"), vec![sub(a("a"), vec![sub(a("b"), a("c"))])]); + assert_eq!(parse_linear("x^2^3"), vec![sup(a("x"), vec![sup(a("2"), a("3"))])]); + assert_eq!(parse_linear("a^b^c^d"), vec![sup(a("a"), vec![sup(a("b"), vec![sup(a("c"), a("d"))])])]); +} + +#[test] +fn mixed_scripts_and_brackets_are_unchanged() { + // `a_b^c` and `a^b_c` are one sub-superscript, as in Word. + let subsup = vec![MNode::Script { kind: ScriptKind::SubSup, base: a("a"), sub: a("b"), sup: a("c") }]; + assert_eq!(parse_linear("a_b^c"), subsup); + let subsup = vec![MNode::Script { kind: ScriptKind::SubSup, base: a("a"), sub: a("c"), sup: a("b") }]; + assert_eq!(parse_linear("a^b_c"), subsup); + // Brackets group to the left, with a visible delimiter, as in Word. + let [MNode::Script { kind: ScriptKind::Sup, base, sup: c, .. }] = &parse_linear("(a^b)^c")[..] else { panic!() }; + assert_eq!(c, &a("c")); + assert!(matches!(&base[..], [MNode::Delim { beg: Some('('), elems, .. }] if elems[0] == vec![sup(a("a"), a("b"))]), "{base:?}"); +} + +#[test] +fn stacked_scripts_on_a_function_name_nest_to_the_right() { + let name = |s: &str| vec![MNode::Run(MRun::plain(s))]; + let func = |n: Vec| vec![MNode::Func { name: n, e: a("x") }]; + assert_eq!(parse_linear("sin^2^3 x"), func(vec![sup(name("sin"), vec![sup(a("2"), a("3"))])])); + assert_eq!(parse_linear("log_a_b x"), func(vec![sub(name("log"), vec![sub(a("a"), a("b"))])])); + // Mixed scripts on a name are still one sub-superscript. + let subsup = MNode::Script { kind: ScriptKind::SubSup, base: name("log"), sub: a("2"), sup: a("3") }; + assert_eq!(parse_linear("log_2^3 x"), func(vec![subsup])); + // The other script nests too, as `x^2_a_b` does, and `x` is still the operand. + let subsup = MNode::Script { kind: ScriptKind::SubSup, base: name("sin"), sub: vec![sub(a("a"), a("b"))], sup: a("2") }; + assert_eq!(parse_linear("sin^2_a_b x"), func(vec![subsup])); + let subsup = MNode::Script { kind: ScriptKind::SubSup, base: name("sin"), sub: a("a"), sup: vec![sup(a("2"), a("3"))] }; + assert_eq!(parse_linear("sin_a^2^3 x"), func(vec![subsup])); +} + +/// The whole chain stays within the parsers' depth cap (#1456), also when every operand is itself a +/// deep chain: the tree survives `serde_json` (its 128-level limit) and the rest is text. +#[test] +fn a_chain_of_deep_operands_stays_shallow() { + std::thread::Builder::new() + .stack_size(512 * 1024) + .spawn(|| { + let group = format!("({}c)", "b^".repeat(30)); + for s in [format!("a{}", format!("^{group}").repeat(40)), format!("sin{} x", format!("^{group}").repeat(40))] { + let n = parse_linear(&s); + let json = serde_json::to_string(&n).unwrap(); + let back: Vec = serde_json::from_str(&json).unwrap_or_else(|e| panic!("{e}")); + assert_eq!(back, n); + } + }) + .unwrap() + .join() + .unwrap(); +} + +/// A script operator the chain leaves at its cap stays text: it isn't taken as a function's operand. +#[test] +fn an_operator_left_at_the_cap_is_not_a_function_operand() { + let n = parse_linear(&format!("sin{} x", "^1".repeat(40))); + let operand_starts_with_a_script = |n: &MNode| match n { + MNode::Func { e, .. } => matches!(e.first(), Some(MNode::Run(r)) if r.text.starts_with(['^', '_'])), + _ => false, + }; + assert!(!n.iter().any(operand_starts_with_a_script), "{n:?}"); +} From 10f2625365620f57a7385151309bbf55b6840efe Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 21:52:48 -0500 Subject: [PATCH 02/84] craft-math: a script on a script prints back the same in linear text (port of wordcraft#6084) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit to_linear wrote a script base that isn't simple in parentheses, so sSup(sSup(a, b), c) came out as (a^b)^c and read back with a visible delimiter. It now writes 〖a^b〗^c, as Word does, and the parser takes a lone 〖…〗 group as the base itself, as Word builds 〖a+b〗^2, instead of an invisible delimiter. simple_operand is split out of lin_operand so both use one rule. From the PR's review: an invisible delimiter that is itself a script base gets an outer pair (〖〖a〗〗^2); a one-character operator base is written 〖⊗〗_i, since a script after an operator reads as a pre-script; and only a base just closed by 〗 (after_group) is unwrapped, so an explicit ├a┤^2 keeps its delimiter. Ported from storytold/wordcraft#6084 (issue wordcraft#6075): its changes to math.rs and math_linear.rs and its tests/linear_script_base.rs. In the function-name branch of the parser, where #6083 (stacked scripts) and this PR both change the `attach_script` calls, the stacked-script chain is kept and the calls pass this PR's new `group` argument (`false`). --- crates/math/src/math.rs | 40 ++++++++++--- crates/math/src/math_linear.rs | 30 ++++++++-- crates/math/tests/linear_script_base.rs | 74 +++++++++++++++++++++++++ 3 files changed, 130 insertions(+), 14 deletions(-) create mode 100644 crates/math/tests/linear_script_base.rs diff --git a/crates/math/src/math.rs b/crates/math/src/math.rs index dc09cd164..08d488b11 100644 --- a/crates/math/src/math.rs +++ b/crates/math/src/math.rs @@ -518,11 +518,9 @@ fn first_lin_char(n: &MNode) -> Option { } } -/// An argument as an operand: bare when it's a single simple atom, parenthesised otherwise. -fn lin_operand(a: &[MNode], s: &mut String, depth: usize) { - let mut inner = String::new(); - lin_arg(a, &mut inner, depth); - let simple = match a { +/// Whether `a` is written bare as an operand: a single simple atom. +fn simple_operand(a: &[MNode]) -> bool { + match a { [MNode::Run(r)] => { let mut cs = r.text.chars(); match (cs.next(), cs.next()) { @@ -532,8 +530,14 @@ fn lin_operand(a: &[MNode], s: &mut String, depth: usize) { } [MNode::Delim { .. }] => true, _ => false, - }; - if simple && !inner.is_empty() { + } +} + +/// An argument as an operand: bare when it's a single simple atom, parenthesised otherwise. +fn lin_operand(a: &[MNode], s: &mut String, depth: usize) { + let mut inner = String::new(); + lin_arg(a, &mut inner, depth); + if simple_operand(a) && !inner.is_empty() { s.push_str(&inner); } else { s.push('('); @@ -542,6 +546,26 @@ fn lin_operand(a: &[MNode], s: &mut String, depth: usize) { } } +/// A script base: bare when simple, else in invisible brackets `〖…〗`, as Word's Linear format +/// writes it. The parser reads them back as grouping only, so `〖a^b〗^c` keeps its tree, where +/// `(a^b)^c` would gain a visible delimiter (#6075). A base that is itself one invisible delimiter +/// (LaTeX `\left.a\right.`) gets an outer pair too, so the inner one reads back as that delimiter. +/// So does an operator (`⊗`, `×`, `<`…): a script after one reads as a pre-script, so `⊗_i` would +/// come back as `⊗` and a pre-script, where `〖⊗〗_i` keeps it the base. +fn lin_base(a: &[MNode], s: &mut String, depth: usize) { + let mut inner = String::new(); + lin_arg(a, &mut inner, depth); + let invisible = matches!(a, [MNode::Delim { beg: None, end: None, elems, .. }] if elems.len() == 1); + let operator = matches!(a, [MNode::Run(r)] if r.text.chars().all(crate::math_linear::is_boundary)); + if simple_operand(a) && !inner.is_empty() && !invisible && !operator { + s.push_str(&inner); + } else { + s.push('〖'); + s.push_str(&inner); + s.push('〗'); + } +} + /// A script or limit operand. The parser reads a run of letters and digits up to the next space or /// operator, so `V_dd` is written bare as Word's Linear format shows it (`V_(dd)` reads back the same). fn lin_script(a: &[MNode], s: &mut String, depth: usize) { @@ -586,7 +610,7 @@ fn lin_node(n: &MNode, s: &mut String, depth: usize) { lin_operand(base, s, depth); return; } - lin_operand(base, s, depth); + lin_base(base, s, depth); if matches!(kind, ScriptKind::Sub | ScriptKind::SubSup) { s.push('_'); lin_script(sub, s, depth); diff --git a/crates/math/src/math_linear.rs b/crates/math/src/math_linear.rs index fe8c8cd52..27fa08368 100644 --- a/crates/math/src/math_linear.rs +++ b/crates/math/src/math_linear.rs @@ -93,7 +93,7 @@ pub fn is_combining(c: char) -> bool { } /// Characters that end an operand. -fn is_boundary(c: char) -> bool { +pub(crate) fn is_boundary(c: char) -> bool { matches!(c, ' ' | '&' | '@' | '#' | '▒' | '│' | '/' | '⁄' | '∕' | '¦' | '\u{2061}') || is_closer(c) || matches!(math_class(c), MClass::Bin | MClass::Rel | MClass::Punct) @@ -173,6 +173,7 @@ impl P { if pre { out.push(self.prescript(stops)); } else { + let group = self.after_group(); self.i += 1; let s = self.script_chain(c, stops, 0); if out.last().is_some_and(too_deep) { @@ -180,7 +181,7 @@ impl P { out.extend(s); } else { let base = out.pop(); - out.push(attach_script(base, c == '^', s)); + out.push(attach_script(base, c == '^', s, group)); } } } @@ -248,6 +249,11 @@ impl P { vec![text(c)] } + /// The character just before the cursor closed a `〖…〗` group. + fn after_group(&self) -> bool { + self.i.checked_sub(1).and_then(|k| self.c.get(k)) == Some(&'〗') + } + /// A bracket group after its opening character; `closers` end it. fn group(&mut self, open: Option, closers: &[char]) -> MNode { let mut stops: Vec = closers.to_vec(); @@ -453,13 +459,13 @@ impl P { self.i += 1; // `sin^2^3` nests to the right like any other script (#6074). let s = self.script_chain(c, stops, 0); - let mut n = attach_script(Some(MNode::Run(MRun::plain(word.clone()))), c == '^', s); + let mut n = attach_script(Some(MNode::Run(MRun::plain(word.clone()))), c == '^', s, false); // Only the other script joins it, and it nests the same way (`log_2^3`, `sin^2_a_b`); // the same one again is what the chain left at its depth cap. if let Some(c2 @ ('^' | '_')) = self.peek().filter(|&c2| c2 != c) { self.i += 1; let s2 = self.script_chain(c2, stops, 0); - n = attach_script(Some(n), c2 == '^', s2); + n = attach_script(Some(n), c2 == '^', s2, false); } vec![n] } @@ -583,6 +589,7 @@ impl P { } // The base is already deep: the operator is text (see `too_deep`). let deep = if whole { any_too_deep(out) } else { out.last().is_some_and(too_deep) }; + let group = self.after_group(); self.i += 1; if deep { let s = if matches!(c, '^' | '_' | '┬' | '┴') { self.script_operand(stops) } else { Vec::new() }; @@ -594,7 +601,7 @@ impl P { '^' | '_' => { let s = self.script_chain(c, stops, 0); let b = base(out); - out.push(attach_script(b, c == '^', s)); + out.push(attach_script(b, c == '^', s, group)); } '┬' | '┴' => { let lim = self.script_operand(stops); @@ -717,10 +724,21 @@ pub fn strip_parens(mut a: Arg) -> Arg { a } -fn attach_script(base: Option, sup: bool, s: Arg) -> MNode { +/// `group`: the base was just closed by `〗`, so a characterless delimiter around it is that grouping +/// (and dropped), not an explicit `├…┤` one (kept). +fn attach_script(base: Option, sup: bool, s: Arg, group: bool) -> MNode { match base { Some(MNode::Script { kind: ScriptKind::Sub, base, sub, .. }) if sup => MNode::Script { kind: ScriptKind::SubSup, base, sub, sup: s }, Some(MNode::Script { kind: ScriptKind::Sup, base, sup: sp, .. }) if !sup => MNode::Script { kind: ScriptKind::SubSup, base, sub: s, sup: sp }, + // `〖…〗` only groups: as a script base it leaves no delimiter, as Word builds it (#6075). + Some(MNode::Delim { beg: None, end: None, mut elems, .. }) if group && elems.len() == 1 => { + let base = elems.pop().unwrap_or_default(); + if sup { + MNode::Script { kind: ScriptKind::Sup, base, sub: Vec::new(), sup: s } + } else { + MNode::Script { kind: ScriptKind::Sub, base, sub: s, sup: Vec::new() } + } + } b => { let base = b.map(|b| vec![b]).unwrap_or_default(); if sup { diff --git a/crates/math/tests/linear_script_base.rs b/crates/math/tests/linear_script_base.rs new file mode 100644 index 000000000..8a6505b14 --- /dev/null +++ b/crates/math/tests/linear_script_base.rs @@ -0,0 +1,74 @@ +//! A script whose base is itself a script survives linear text (#6075). `to_linear` puts a base that +//! isn't simple in invisible brackets, `〖a^b〗^c`, as Word linearizes it, and the parser treats +//! `〖…〗` as a script base as grouping only, as Word builds it: no delimiter is left. + +use craft_math::math::{MNode, MRun, ScriptKind, parse_linear, to_linear}; + +fn a(t: &str) -> Vec { + vec![MNode::Run(MRun::new(t))] +} + +fn sup(base: Vec, s: Vec) -> MNode { + MNode::Script { kind: ScriptKind::Sup, base, sub: Vec::new(), sup: s } +} + +#[test] +fn a_script_on_a_script_prints_back_the_same() { + // sSup(sSup(a, b), c), as Word files hold it. + let left = vec![sup(vec![sup(a("a"), a("b"))], a("c"))]; + assert_eq!(to_linear(&left), "〖a^b〗^c"); + assert_eq!(parse_linear(&to_linear(&left)), left); + // Subscripts and a longer base too. + let sub = + vec![MNode::Script { kind: ScriptKind::Sub, base: vec![sup(a("x"), a("2")), MNode::Run(MRun::new("+y"))], sub: a("i"), sup: Vec::new() }]; + assert_eq!(parse_linear(&to_linear(&sub)), sub, "{}", to_linear(&sub)); +} + +#[test] +fn invisible_brackets_only_group_a_script_base() { + assert_eq!(parse_linear("〖a+b〗^2"), vec![sup(a("a+b"), a("2"))]); + // Visible brackets stay. + let [MNode::Script { base, .. }] = &parse_linear("(a+b)^2")[..] else { panic!() }; + assert!(matches!(&base[..], [MNode::Delim { beg: Some('('), .. }]), "{base:?}"); +} + +#[test] +fn half_typed_scripts_print_back_the_same() { + for s in ["x^2^", "x_i_", "(a^b)^c", "a^b"] { + let n = parse_linear(s); + assert_eq!(parse_linear(&to_linear(&n)), n, "{s} → {}", to_linear(&n)); + } +} + +#[test] +fn an_invisible_delimiter_as_the_base_is_kept() { + // A base that is itself an invisible delimiter (LaTeX `\left.a\right.^2` makes one) is written + // `〖〖a〗〗^2`: the outer pair only groups, the inner one reads back as that delimiter. + let invisible = MNode::Delim { beg: None, end: None, sep: None, grow: true, shp_match: false, elems: vec![a("a")] }; + let n = vec![sup(vec![invisible], a("2"))]; + assert_eq!(parse_linear(&to_linear(&n)), n, "{}", to_linear(&n)); + let latex = craft_math::math_latex::parse_latex(r"\left.a\right.^2"); + assert!(matches!(&latex[..], [MNode::Script { base, .. }] if matches!(&base[..], [MNode::Delim { beg: None, end: None, .. }])), "{latex:?}"); + assert_eq!(parse_linear(&to_linear(&latex)), latex, "{}", to_linear(&latex)); +} + +#[test] +fn an_operator_as_the_base_prints_back_the_same() { + // A script after an operator reads as a pre-script, so an operator base is grouped: `〖⊗〗_i`. + for op in ["⊗", "×", "∗", "*", "<", "&", "#"] { + let n = vec![MNode::Script { kind: ScriptKind::Sub, base: a(op), sub: a("i"), sup: Vec::new() }]; + assert_eq!(parse_linear(&to_linear(&n)), n, "{op}: {}", to_linear(&n)); + let n = vec![sup(a(op), a("2"))]; + assert_eq!(parse_linear(&to_linear(&n)), n, "{op}: {}", to_linear(&n)); + } +} + +#[test] +fn an_explicit_delimiter_as_the_base_is_kept() { + // `├a┤` is an explicit (invisible) delimiter, not a grouping `〖a〗`: it stays the base. + let [MNode::Script { base, sup: two, .. }] = &parse_linear("├a┤^2")[..] else { panic!() }; + assert_eq!(two, &a("2")); + assert!(matches!(&base[..], [MNode::Delim { beg: None, end: None, elems, .. }] if elems == &vec![a("a")]), "{base:?}"); + // Grouping still leaves none. + assert_eq!(parse_linear("〖a〗^2"), vec![sup(a("a"), a("2"))]); +} From 8d2481a7481cb3bef81f5091f8e7f20abe98e4bb Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 21:53:35 -0500 Subject: [PATCH 03/84] craft-math: an empty shown n-ary limit survives linear text (port of wordcraft#6085) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit to_linear wrote a limit only when it wasn't empty, so half-typed ∑_ (an empty, shown lower limit) came out as ∑▒() and read back with both limits hidden. A shown limit is now written even when empty, as _() or ^(). Ported from storytold/wordcraft#6085 (issue wordcraft#6076): its change to math.rs and its tests/linear_empty_limits.rs, with only paths and crate names changed. --- crates/math/src/math.rs | 5 +++-- crates/math/tests/linear_empty_limits.rs | 24 ++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 2 deletions(-) create mode 100644 crates/math/tests/linear_empty_limits.rs diff --git a/crates/math/src/math.rs b/crates/math/src/math.rs index 08d488b11..11f07f6b4 100644 --- a/crates/math/src/math.rs +++ b/crates/math/src/math.rs @@ -634,11 +634,12 @@ fn lin_node(n: &MNode, s: &mut String, depth: usize) { } MNode::Nary { chr, sub_hide, sup_hide, sub, sup, e, .. } => { s.push(*chr); - if !sub_hide && !sub.is_empty() { + // A shown limit is written even when empty (`_()`): left out, it reads back hidden (#6076). + if !sub_hide { s.push('_'); lin_script(sub, s, depth); } - if !sup_hide && !sup.is_empty() { + if !sup_hide { s.push('^'); lin_script(sup, s, depth); } diff --git a/crates/math/tests/linear_empty_limits.rs b/crates/math/tests/linear_empty_limits.rs new file mode 100644 index 000000000..7fccb879e --- /dev/null +++ b/crates/math/tests/linear_empty_limits.rs @@ -0,0 +1,24 @@ +//! An n-ary operator's empty but shown limit survives linear text (#6076): half-typed `∑_` has an +//! empty lower limit that is shown, and `to_linear` writes it as `_()`. Left out, it reads back as a +//! hidden limit. + +use craft_math::math::{MNode, MRun, parse_linear, to_linear}; + +#[test] +fn an_empty_shown_limit_prints_back_the_same() { + for s in ["∑_", "∑^", "∫_0^▒x", "∑_()^n▒i"] { + let n = parse_linear(s); + assert_eq!(parse_linear(&to_linear(&n)), n, "{s} → {}", to_linear(&n)); + } +} + +#[test] +fn hidden_and_filled_limits_print_as_before() { + let nary = |sub_hide, sup_hide, sub: &str, sup: &str| { + let arg = |t: &str| if t.is_empty() { Vec::new() } else { vec![MNode::Run(MRun::new(t))] }; + vec![MNode::Nary { chr: '∑', lim_loc: None, grow: false, sub_hide, sup_hide, sub: arg(sub), sup: arg(sup), e: arg("x") }] + }; + assert_eq!(to_linear(&nary(true, true, "", "")), "∑▒x"); + assert_eq!(to_linear(&nary(false, false, "i", "n")), "∑_i^n▒x"); + assert_eq!(to_linear(&nary(false, true, "", "")), "∑_()▒x"); +} From cc63fb507477cf4b2eb7a2ad1985fe942edb70d5 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 21:59:46 -0500 Subject: [PATCH 04/84] craft-math: a multi-letter script base survives linear text (port of wordcraft#6230) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The parser attaches a script to the last character before it (mc^2 is m, c²), so a base of several letters from a Word or LibreOffice file, written bare, read back split. lin_base now writes such a base in invisible brackets, 〖mc〗^2, as Word linearizes it; a number (10^3, as Word writes it) and an upright function name stay bare. Ported from storytold/wordcraft#6230 (issue wordcraft#6228), which is stacked on wordcraft#6084: its own change to math.rs and its tests/linear_multichar_base.rs. The ODT test that pinned LibreOffice's E=mc^2 (mc…) moves with it: in craft-odf it now expects E=〖mc〗^2, as in the WordCraft PR. It runs only with craft-odf's `text` feature. --- crates/math/src/math.rs | 10 ++++-- crates/math/tests/linear_multichar_base.rs | 39 ++++++++++++++++++++++ crates/odf/src/text/tests.rs | 3 +- 3 files changed, 49 insertions(+), 3 deletions(-) create mode 100644 crates/math/tests/linear_multichar_base.rs diff --git a/crates/math/src/math.rs b/crates/math/src/math.rs index 11f07f6b4..83d232fd2 100644 --- a/crates/math/src/math.rs +++ b/crates/math/src/math.rs @@ -551,13 +551,19 @@ fn lin_operand(a: &[MNode], s: &mut String, depth: usize) { /// `(a^b)^c` would gain a visible delimiter (#6075). A base that is itself one invisible delimiter /// (LaTeX `\left.a\right.`) gets an outer pair too, so the inner one reads back as that delimiter. /// So does an operator (`⊗`, `×`, `<`…): a script after one reads as a pre-script, so `⊗_i` would -/// come back as `⊗` and a pre-script, where `〖⊗〗_i` keeps it the base. +/// come back as `⊗` and a pre-script, where `〖⊗〗_i` keeps it the base. And so does a run of several +/// letters: the parser attaches a script to the last character before it (`mc^2` is `m`, `c²`), so +/// `mc` is written `〖mc〗^2`, as Word linearizes it (#6228). A number (`10^3`, as Word writes it) and +/// an upright function name (`sin^2`, read whole as a name) stay bare. fn lin_base(a: &[MNode], s: &mut String, depth: usize) { let mut inner = String::new(); lin_arg(a, &mut inner, depth); let invisible = matches!(a, [MNode::Delim { beg: None, end: None, elems, .. }] if elems.len() == 1); let operator = matches!(a, [MNode::Run(r)] if r.text.chars().all(crate::math_linear::is_boundary)); - if simple_operand(a) && !inner.is_empty() && !invisible && !operator { + let number = |t: &str| t.chars().all(|c| c.is_ascii_digit() || c == '.'); + let name = |r: &MRun| r.sty == Some(MSty::Plain) && crate::math_linear::FUNCTION_NAMES.contains(&r.text.as_str()); + let letters = matches!(a, [MNode::Run(r)] if r.text.chars().nth(1).is_some() && !number(&r.text) && !name(r)); + if simple_operand(a) && !inner.is_empty() && !invisible && !operator && !letters { s.push_str(&inner); } else { s.push('〖'); diff --git a/crates/math/tests/linear_multichar_base.rs b/crates/math/tests/linear_multichar_base.rs new file mode 100644 index 000000000..3944f3102 --- /dev/null +++ b/crates/math/tests/linear_multichar_base.rs @@ -0,0 +1,39 @@ +//! A script base of several letters survives linear text (#6228). The parser attaches a script to the +//! last character before it (`ab^2` is `a`, `b²`), so `to_linear` writes such a base in invisible +//! brackets, `〖mc〗^2`, as Word linearizes it. Single characters, numbers and upright function +//! names stay bare. + +use craft_math::math::{MNode, MRun, ScriptKind, parse_linear, to_linear}; + +fn a(t: &str) -> Vec { + vec![MNode::Run(MRun::new(t))] +} + +fn sup(base: Vec, s: Vec) -> MNode { + MNode::Script { kind: ScriptKind::Sup, base, sub: Vec::new(), sup: s } +} + +#[test] +fn a_base_of_several_letters_prints_back_whole() { + for base in ["ab", "mc", "x1", "αβ"] { + let n = vec![sup(a(base), a("2"))]; + assert_eq!(to_linear(&n), format!("〖{base}〗^2")); + assert_eq!(parse_linear(&to_linear(&n)), n, "{base}"); + } + // After other text, and as the base of a base. + let e = vec![MNode::Run(MRun::new("E=")), sup(a("mc"), a("2"))]; + assert_eq!(to_linear(&e), "E=〖mc〗^2"); + assert_eq!(parse_linear(&to_linear(&e)), e); + let nested = vec![sup(vec![sup(a("ab"), a("2"))], a("3"))]; + assert_eq!(parse_linear(&to_linear(&nested)), nested, "{}", to_linear(&nested)); +} + +#[test] +fn single_characters_numbers_and_function_names_stay_bare() { + assert_eq!(to_linear(&[sup(a("x"), a("2"))]), "x^2"); + // Word writes a number base bare too (`10^3`). + assert_eq!(to_linear(&[sup(a("10"), a("3"))]), "10^3"); + assert_eq!(to_linear(&[sup(a("2.5"), a("2"))]), "2.5^2"); + let sin = vec![sup(vec![MNode::Run(MRun::plain("sin"))], a("2"))]; + assert_eq!(to_linear(&sin), "sin^2"); +} diff --git a/crates/odf/src/text/tests.rs b/crates/odf/src/text/tests.rs index 8d7af18dc..f88ba44ee 100644 --- a/crates/odf/src/text/tests.rs +++ b/crates/odf/src/text/tests.rs @@ -167,7 +167,8 @@ fn embedded_formula_object_reads_its_mathml() { .flat_map(|p| &p.inlines) .filter_map(|i| if let Inline::Equation { linear, display } = i { Some((linear.clone(), *display)) } else { None }) .collect(); - assert_eq!(eqs, vec![("E=mc^2".to_string(), true)]); + // The base is `mc` (`mc…`), so its linear form groups it, as Word writes it (#6228). + assert_eq!(eqs, vec![("E=〖mc〗^2".to_string(), true)]); } #[test] From 21f838c14e869e0a4fb13772c22b824472515a69 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 22:01:24 -0500 Subject: [PATCH 05/84] craft-math: a number is one item in the linear format (port of wordcraft#6236) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The parser pushed digits one character at a time, so a script took only the last digit as its base: 10^3 built 1 followed by 0³, where Word builds 10³. A number is now read as one atom, by the rule Word follows: digits, with a . or , continuing it only when a digit follows (2.5, 3.14, 1,000) and a leading . before a digit starting one (.5); a trailing point (2.) isn't part of it, and letters and signs are separate items. A script or a fraction operand takes the whole number (10^3, 2.5/3). A number script follows the same rule (x^.5, x_1,000; x^2. keeps the point out), keeping letters after the digits (#1609). Ported from storytold/wordcraft#6236 (issue wordcraft#6229): its change to math_linear.rs and its tests/number_bases.rs, with only paths and crate names changed. Its typing test (engine) and the docs/typing-parity.md note stay in WordCraft. --- crates/math/src/math_linear.rs | 39 ++++++++++++- crates/math/tests/number_bases.rs | 94 +++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 3 deletions(-) create mode 100644 crates/math/tests/number_bases.rs diff --git a/crates/math/src/math_linear.rs b/crates/math/src/math_linear.rs index 27fa08368..1dccd2c46 100644 --- a/crates/math/src/math_linear.rs +++ b/crates/math/src/math_linear.rs @@ -118,6 +118,23 @@ impl P { fn peek_at(&self, k: usize) -> Option { self.c.get(self.i + k).copied() } + /// Length of the number at the cursor (0 if none), as Word reads one: digits, where a `.` or `,` + /// continues it only when a digit follows (`2.5`, `3.14`, `1,000`), and a leading `.` before a + /// digit starts one (`.5`). A trailing point (`2.`) isn't part of it. + fn number_len(&self) -> usize { + let digit = |k: usize| self.peek_at(k).is_some_and(|c| c.is_ascii_digit()); + if !digit(0) && !(self.peek() == Some('.') && digit(1)) { + return 0; + } + let mut k = 0; + loop { + match self.peek_at(k) { + Some(c) if c.is_ascii_digit() => k += 1, + Some('.' | ',') if digit(k + 1) => k += 1, + _ => return k, + } + } + } fn tired(&mut self) -> bool { self.steps += 1; self.steps > MAX_STEPS || self.depth > MAX_DEPTH @@ -245,6 +262,14 @@ impl P { if c.is_ascii_alphabetic() { return self.word(stops); } + // A number is one item, so a script or a fraction takes all of it (`10^3`, `2.5/3`), as Word + // reads it (#6229). + let n = self.number_len(); + if n > 0 { + let t: String = self.c.get(self.i..self.i + n).unwrap_or(&[]).iter().collect(); + self.i += n; + return vec![MNode::Run(MRun::new(t))]; + } self.i += 1; vec![text(c)] } @@ -665,10 +690,18 @@ impl P { } } Some(c) if is_prefix(c) || closer(c).is_some() => self.atom(stops), - Some(c) if c.is_ascii_digit() => { + Some(c) if c.is_ascii_digit() || self.number_len() > 0 => { + // A number by `number_len`'s rule (`2.5`, `1,000`, `.5`; `x^2.` keeps the point out), + // and letters after it stay in the script (`V_10a`, #1609). let start = self.i; - while self.peek().is_some_and(|k| k.is_alphanumeric() || k == '.') { - self.i += 1; + while let Some(k) = self.peek() { + if k.is_alphanumeric() { + self.i += 1; + } else if matches!(k, '.' | ',') && self.peek_at(1).is_some_and(|n| n.is_ascii_digit()) { + self.i += 2; + } else { + break; + } } let t: String = self.c.get(start..self.i).unwrap_or(&[]).iter().collect(); vec![MNode::Run(MRun::new(t))] diff --git a/crates/math/tests/number_bases.rs b/crates/math/tests/number_bases.rs new file mode 100644 index 000000000..752253a66 --- /dev/null +++ b/crates/math/tests/number_bases.rs @@ -0,0 +1,94 @@ +//! A number is one item in the linear format, as Word reads it (#6229): the base of a script is the +//! whole number before it (`10^3` is `10³`, not `1`, `0³`), and so is a fraction's operand. A number is +//! a run of digits; a `.` or `,` continues it only when a digit follows (`2.5`, `1,000`), and a leading +//! `.` before a digit starts one (`.5`). Letters and signs are separate items. Every expected tree is the +//! one Word for Windows (build 16.0.20527) builds from the same text. + +use craft_math::math::{FracKind, MNode, MRun, ScriptKind, parse_linear}; + +fn r(t: &str) -> MNode { + MNode::Run(MRun::new(t)) +} + +fn a(t: &str) -> Vec { + vec![r(t)] +} + +fn sup(base: &str, s: &str) -> MNode { + MNode::Script { kind: ScriptKind::Sup, base: a(base), sub: Vec::new(), sup: a(s) } +} + +fn sub(base: &str, s: &str) -> MNode { + MNode::Script { kind: ScriptKind::Sub, base: a(base), sub: a(s), sup: Vec::new() } +} + +fn frac(num: &str, den: &str) -> MNode { + MNode::Frac { kind: FracKind::Bar, num: a(num), den: a(den) } +} + +#[track_caller] +fn parses(s: &str, want: Vec) { + assert_eq!(parse_linear(s), want, "{s}"); +} + +#[test] +fn a_whole_number_is_the_base() { + parses("10^3", vec![sup("10", "3")]); + parses("123^4", vec![sup("123", "4")]); + for n in ["2.5", "3.14", "0.5", ".5", "1,000", "1.2.3", "1,2,3"] { + parses(&format!("{n}^2"), vec![sup(n, "2")]); + } + parses("10_i", vec![sub("10", "i")]); + parses("10_i^2", vec![MNode::Script { kind: ScriptKind::SubSup, base: a("10"), sub: a("i"), sup: a("2") }]); + parses("10^3_i", vec![MNode::Script { kind: ScriptKind::SubSup, base: a("10"), sub: a("i"), sup: a("3") }]); + parses("10^-3", vec![sup("10", "-3")]); + parses("10^(3)", vec![sup("10", "3")]); +} + +#[test] +fn what_comes_before_the_number_stays_outside() { + parses("a10^2", vec![r("a"), sup("10", "2")]); + parses("x+10^3", vec![r("x+"), sup("10", "3")]); + parses("-10^2", vec![r("-"), sup("10", "2")]); + parses("1e10^2", vec![r("1e"), sup("10", "2")]); + // A point with no digit after it isn't part of the number. + parses("2.^2", vec![r("2"), sup(".", "2")]); +} + +#[test] +fn letters_after_a_number_are_their_own_base() { + parses("2x^2", vec![r("2"), sup("x", "2")]); + parses("10x^2", vec![r("10"), sup("x", "2")]); + parses("x2^3", vec![r("x"), sup("2", "3")]); + parses("3.14r^2", vec![r("3.14"), sup("r", "2")]); + parses("2.5x^2", vec![r("2.5"), sup("x", "2")]); +} + +#[test] +fn a_number_script_is_read_by_the_same_rule() { + parses("x^.5", vec![sup("x", ".5")]); + parses("x^2.5", vec![sup("x", "2.5")]); + parses("x^0.5", vec![sup("x", "0.5")]); + parses("x_1,000", vec![sub("x", "1,000")]); + parses("x_1.2.3", vec![sub("x", "1.2.3")]); + parses("x^2.", vec![sup("x", "2"), r(".")]); + // Letters after the digits stay in the script (#1609). + parses("x_10a", vec![sub("x", "10a")]); + parses("2^10", vec![sup("2", "10")]); +} + +#[test] +fn a_whole_number_is_a_fraction_operand() { + parses("2.5/3", vec![frac("2.5", "3")]); + parses("1,000/2", vec![frac("1,000", "2")]); + parses("x/2.5", vec![frac("x", "2.5")]); + parses("0.5/0.25", vec![frac("0.5", "0.25")]); + parses("10/2^3", vec![MNode::Frac { kind: FracKind::Bar, num: a("10"), den: vec![sup("2", "3")] }]); +} + +#[test] +fn a_comma_between_digits_in_brackets_joins_them() { + let [MNode::Run(f), MNode::Delim { beg: Some('('), elems, .. }] = &parse_linear("f(1,2^3)")[..] else { panic!() }; + assert_eq!(f.text, "f"); + assert_eq!(elems, &vec![vec![sup("1,2", "3")]]); +} From a5a8829a14e0fc51c3ead29d0fbb4d7c007a6351 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 22:02:35 -0500 Subject: [PATCH 06/84] craft-math: no m:sty or m:scr on normal text in an equation (port of wordcraft#6082) CT_RPR holds m:nor or m:scr/m:sty, not both, and Word keeps only the m:nor of such a run, so bold normal text lost its bold there. Normal text now writes neither; its bold and italic go in w:rPr (w:b/w:i), which the reader already reads back for normal text. Ported from storytold/wordcraft#6082 (issue wordcraft#6073). The writer change moves from WordCraft's docx/src/write/math.rs to omml/write.rs, where the OMML writer now lives. Its test saves and reopens a .docx, so it goes into craft-docx's integration tests (tests/it/math_normal_text.rs) with only the crate names changed. --- crates/docx/tests/it/main.rs | 1 + crates/docx/tests/it/math_normal_text.rs | 66 ++++++++++++++++++++++++ crates/math/src/omml/write.rs | 13 +++++ 3 files changed, 80 insertions(+) create mode 100644 crates/docx/tests/it/math_normal_text.rs diff --git a/crates/docx/tests/it/main.rs b/crates/docx/tests/it/main.rs index b0bab5833..726010a7a 100644 --- a/crates/docx/tests/it/main.rs +++ b/crates/docx/tests/it/main.rs @@ -24,6 +24,7 @@ mod legacy_forms; mod ligatures; mod line_numbering; mod malformed; +mod math_normal_text; mod missing_pictures; mod nested_block_controls; mod note_comments; diff --git a/crates/docx/tests/it/math_normal_text.rs b/crates/docx/tests/it/math_normal_text.rs new file mode 100644 index 000000000..6bb086752 --- /dev/null +++ b/crates/docx/tests/it/math_normal_text.rs @@ -0,0 +1,66 @@ +//! Normal text in an equation (`m:nor`) is saved without `m:scr`/`m:sty` (#6073). In the OMML +//! schema `CT_RPR` holds `m:nor` or `m:scr`/`m:sty`, not both, and Word keeps only the `m:nor` of +//! such a run, so the bold or italic of normal text goes in `w:rPr` (`w:b`/`w:i`), which the +//! reader takes back for normal text. + +use craft_math::math::{MNode, MRun, MScr, MSty, Math}; +use craft_wordmodel::InlineObject; +use craft_wordmodel::props::CharProps; +use craft_wordmodel::{Document, Paragraph, para_block}; + +/// Save an equation holding one normal-text run; the run's `m:r` XML and the reopened run. +fn save(run: MRun) -> (String, MRun) { + let math = Math { nodes: vec![MNode::Run(run)], ..Default::default() }; + let mut p = Paragraph::new(); + p.insert_object(0, InlineObject::Equation { linear: String::new(), display: false, math }, &CharProps::default()).unwrap(); + let mut doc = Document::new(); + doc.body = vec![para_block(p)]; + let bytes = craft_docx::write(&doc).unwrap(); + let mut zip = zip::ZipArchive::new(std::io::Cursor::new(&bytes)).unwrap(); + let mut xml = String::new(); + std::io::Read::read_to_string(&mut zip.by_name("word/document.xml").unwrap(), &mut xml).unwrap(); + let start = xml.find("").unwrap(); + let end = start + xml[start..].find("").unwrap() + "".len(); + let back = craft_docx::read(&bytes).unwrap(); + let math = back.body.iter().filter_map(|b| b.as_para()).flat_map(|p| p.objects.iter()).find_map(|o| match o { + InlineObject::Equation { math, .. } => Some(math.clone()), + _ => None, + }); + let Some(MNode::Run(r)) = math.unwrap().nodes.into_iter().next() else { panic!("no run") }; + (xml[start..end].to_string(), r) +} + +fn normal(sty: Option) -> MRun { + MRun { nor: true, sty, font: Some("Arial".into()), ..MRun::new("normal text") } +} + +#[test] +fn normal_text_has_no_math_style() { + for sty in [None, Some(MSty::Plain), Some(MSty::Bold), Some(MSty::Italic), Some(MSty::BoldItalic)] { + let (run, _) = save(normal(sty)); + assert!(run.contains(""), "{sty:?}: {run}"); + assert!(!run.contains("m:sty") && !run.contains("m:scr"), "{sty:?}: {run}"); + } + // A script style isn't written for normal text either. + let (run, _) = save(MRun { scr: MScr::Fraktur, ..normal(None) }); + assert!(!run.contains("m:scr"), "{run}"); +} + +#[test] +fn bold_and_italic_normal_text_survive_a_save() { + for (sty, b, i) in [(MSty::Bold, true, false), (MSty::Italic, false, true), (MSty::BoldItalic, true, true)] { + let (run, back) = save(normal(Some(sty))); + assert_eq!((run.contains(""), run.contains("")), (b, i), "{sty:?}: {run}"); + assert_eq!(back, normal(Some(sty)), "{sty:?}"); + } +} + +#[test] +fn math_runs_keep_their_style() { + for sty in [MSty::Plain, MSty::Bold, MSty::Italic, MSty::BoldItalic] { + let math = MRun { sty: Some(sty), ..MRun::new("x") }; + let (run, back) = save(math.clone()); + assert!(run.contains("m:sty") && !run.contains(""), "{sty:?}: {run}"); + assert_eq!(back, math); + } +} diff --git a/crates/math/src/omml/write.rs b/crates/math/src/omml/write.rs index 9f09aab67..046c4499a 100644 --- a/crates/math/src/omml/write.rs +++ b/crates/math/src/omml/write.rs @@ -434,7 +434,11 @@ fn run(w: &mut W, r: &MRun) { MSty::Italic => "i", MSty::BoldItalic => "bi", }); + // `CT_RPR` holds `m:nor` or `m:scr`/`m:sty`, not both, and Word drops the `m:sty` of a normal-text + // run: its bold and italic go in `w:rPr` below, where the reader takes them back (#6073). + let sty = sty.filter(|_| !r.nor); let scr = match r.scr { + _ if r.nor => None, MScr::Roman => None, MScr::Script => Some("script"), MScr::Fraktur => Some("fraktur"), @@ -466,6 +470,15 @@ fn run(w: &mut W, r: &MRun) { w.open("w:rPr", &[]); let font = r.font.as_deref().filter(|_| r.nor).unwrap_or("Cambria Math"); w.empty("w:rFonts", &[("w:ascii", font), ("w:hAnsi", font)]); + // Normal text's bold and italic (see `sty` above). + if r.nor { + if matches!(r.sty, Some(MSty::Bold | MSty::BoldItalic)) { + w.empty("w:b", &[]); + } + if matches!(r.sty, Some(MSty::Italic | MSty::BoldItalic)) { + w.empty("w:i", &[]); + } + } if let Some(c) = r.color { w.val("w:color", &c.hex()); } From 28bd7be18014d2af9f01e34a996ced53f7986d9f Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 22:09:54 -0500 Subject: [PATCH 07/84] craft-math, craft-docx: keep an equation's kept OMML only when it is one well-formed m:oMath (port of wordcraft#6081) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit write_equation writes Math::omml verbatim into the host document once a check passes, and documents saved as JSON carry that field, so a JSON → .docx conversion could write a document.xml that isn't well-formed, or any WordprocessingML verbatim. craft-math's check was a strict craft-xml read of text starting with in text, and characters XML 1.0 doesn't allow. The kept XML is now written only when it starts with (not m:oMathPara), passes the strict read (which also bounds the nesting), and then parses with roxmltree, a conforming parser, as exactly one element that is m:oMath by namespace. The canonical prefixes of kept OMML (m:, w:, mc:) are declared for that parse, as craft-math already documents them and the .docx root declares them; any other prefix is undeclared there. Otherwise the equation is written from its nodes. In craft-docx, Flat OPC's one_element (the gate for inlining kept bytes as pkg:xmlData) now also requires XML names and attribute values that unescape, as in the WordCraft PR. Ported from storytold/wordcraft#6081 (issue wordcraft#6072). The check differs from the PR's in where it lives: the PR combined flat::one_element, parse_strict and roxmltree in the DOCX writer, over the OMML wrapped in every namespace document.xml declares. Here the writer is in craft-math, which doesn't know the host's namespaces, so it declares the three canonical ones. Its tests go into craft-docx's integration tests (tests/it/kept_omml_check.rs), with only the crate names changed; all 22 malformed cases fail without this commit except the 11 craft-math already refused. roxmltree 0.21 is already in the lock as a dependency of other crates. Checked on the 72 .docx files with equations from earlier Word probes (488 equations with kept OMML, 35 files saved by Word): the same equations are written back verbatim as before, except one empty in a hand-made repro file, which is now written from its (empty) nodes. --- Cargo.lock | 1 + crates/docx/src/flat.rs | 36 ++++++++- crates/docx/tests/it/kept_omml_check.rs | 98 +++++++++++++++++++++++++ crates/docx/tests/it/main.rs | 1 + crates/math/Cargo.toml | 3 + crates/math/src/omml.rs | 22 +++++- crates/math/src/omml/write.rs | 2 +- 7 files changed, 159 insertions(+), 4 deletions(-) create mode 100644 crates/docx/tests/it/kept_omml_check.rs diff --git a/Cargo.lock b/Cargo.lock index cf0e0bd47..c60c92eeb 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1710,6 +1710,7 @@ version = "0.1.0" dependencies = [ "craft-xml", "proptest", + "roxmltree 0.21.2", "serde", "serde_json", ] diff --git a/crates/docx/src/flat.rs b/crates/docx/src/flat.rs index c257932cf..7c91f5516 100644 --- a/crates/docx/src/flat.rs +++ b/crates/docx/src/flat.rs @@ -448,7 +448,13 @@ fn one_element(s: &str) -> bool { r.config_mut().check_comments = true; let (mut depth, mut roots) = (0usize, 0usize); loop { - let attrs_ok = |e: &BytesStart| e.attributes().all(|a| a.is_ok()); + // Each attribute parses and its value unescapes: an undeclared entity (`x="&no;"`) isn't + // well-formed, and the reader would keep it raw (#6072). + // Names must be XML names too: the reader takes `` and `x?="1"` without complaint. + let attrs_ok = |e: &BytesStart| { + is_qname(e.name().as_ref()) + && e.attributes().all(|a| a.is_ok_and(|a| is_qname(a.key.as_ref()) && a.normalized_value(quick_xml::XmlVersion::Explicit1_0).is_ok())) + }; match r.read_event() { Ok(Event::Start(e)) => { if !attrs_ok(&e) || (depth == 0 && roots > 0) { @@ -480,6 +486,28 @@ fn one_element(s: &str) -> bool { } } +/// Whether `name` is an XML name with at most one colon, neither first nor last: a qualified name +/// in Namespaces in XML 1.0 (§4), with the name characters of XML 1.0 (Fifth Edition) §2.3. +fn is_qname(name: &[u8]) -> bool { + fn start(c: char) -> bool { + matches!(c, 'A'..='Z' | '_' | 'a'..='z' | '\u{C0}'..='\u{D6}' | '\u{D8}'..='\u{F6}' | '\u{F8}'..='\u{2FF}' | '\u{370}'..='\u{37D}' + | '\u{37F}'..='\u{1FFF}' | '\u{200C}'..='\u{200D}' | '\u{2070}'..='\u{218F}' | '\u{2C00}'..='\u{2FEF}' | '\u{3001}'..='\u{D7FF}' + | '\u{F900}'..='\u{FDCF}' | '\u{FDF0}'..='\u{FFFD}' | '\u{10000}'..='\u{EFFFF}') + } + fn more(c: char) -> bool { + start(c) || matches!(c, '-' | '.' | '0'..='9' | '\u{B7}' | '\u{300}'..='\u{36F}' | '\u{203F}'..='\u{2040}') + } + let ncname = |p: &str| { + let mut cs = p.chars(); + cs.next().is_some_and(start) && cs.all(more) + }; + let Ok(name) = std::str::from_utf8(name) else { return false }; + match name.split_once(':') { + Some((prefix, local)) => ncname(prefix) && ncname(local), + None => ncname(name), + } +} + #[cfg(test)] mod tests { use super::*; @@ -587,6 +615,12 @@ mod tests { "", "", "", + "", + "", + "", + "", + "", + "", ] { assert!(xml_fragment(ct, bad.as_bytes()).is_none(), "{bad}"); } diff --git a/crates/docx/tests/it/kept_omml_check.rs b/crates/docx/tests/it/kept_omml_check.rs new file mode 100644 index 000000000..e382cdb1b --- /dev/null +++ b/crates/docx/tests/it/kept_omml_check.rs @@ -0,0 +1,98 @@ +//! An equation's kept source OMML is written back verbatim only when it is exactly one well-formed +//! `m:oMath` (#6072). `Math::omml` also comes from `.json` documents, so anything else must not +//! reach `document.xml`: it is written from the equation's nodes instead. + +use craft_math::math::{MNode, MRun, Math}; +use craft_wordmodel::para::{InlineObject, OBJ}; +use craft_wordmodel::props::CharProps; +use craft_wordmodel::{Document, Paragraph, para_block}; + +/// Save a one-equation document whose equation keeps `omml` and has the nodes `NODES`. +fn save(omml: &str, display: bool) -> (String, Document) { + let math = Math { nodes: vec![MNode::Run(MRun::new("NODES"))], omml: omml.into(), ..Default::default() }; + let mut p = Paragraph::new(); + p.insert_object(0, InlineObject::Equation { linear: "NODES".into(), display, math }, &CharProps::default()).unwrap(); + let mut doc = Document::new(); + doc.body = vec![para_block(p)]; + let bytes = craft_docx::write(&doc).unwrap(); + let mut zip = zip::ZipArchive::new(std::io::Cursor::new(&bytes)).unwrap(); + let mut xml = String::new(); + std::io::Read::read_to_string(&mut zip.by_name("word/document.xml").unwrap(), &mut xml).unwrap(); + // The saved file must open again (the main part is read strictly). + let back = craft_docx::read(&bytes).unwrap_or_else(|e| panic!("{omml:?} doesn't reopen: {e}")); + (xml, back) +} + +/// The text of the reopened document's equations and paragraphs. +fn texts(doc: &Document) -> Vec { + let mut out = Vec::new(); + for b in &doc.body { + let Some(p) = b.as_para() else { continue }; + for o in &p.objects { + if let InlineObject::Equation { math, .. } = o { + out.push(craft_math::math::to_linear(&math.nodes)); + } + } + let text: String = p.text.chars().filter(|c| *c != OBJ).collect(); + if !text.trim().is_empty() { + out.push(text); + } + } + out +} + +#[test] +fn well_formed_kept_omml_is_written_back_unchanged() { + let kept = "KEPT"; + let (xml, back) = save(kept, false); + assert!(xml.contains(kept), "{xml}"); + assert_eq!(texts(&back), vec!["KEPT".to_string()]); +} + +#[test] +fn malformed_kept_omml_is_written_from_the_nodes() { + for kept in [ + // Unclosed, mismatched, an undefined entity. + "", + "", + "&bad;", + // Markup after the element, text after it, a second element. + "INJECTED", + "INJECTED", + "INJECTED", + // Not an m:oMath. + "INJECTED", + // An m:oMath in another namespace, and an unknown entity in an attribute. + "INJECTED", + "INJECTED", + // Names that aren't XML names, and prefixes that aren't declared. + "INJECTED", + "INJECTED", + "INJECTED", + "INJECTED", + "INJECTED", + // Two attributes with one expanded name (Namespaces in XML §6.3). + "INJECTED", + // A `<` in an attribute value, `]]>` in text. + "INJECTED", + "INJECTED]]>", + // Characters XML 1.0 doesn't allow, as references or as they are. + "INJECTED", + "INJECTED", + "INJECTED￿", + "INJECTED", + "INJECTED\u{1}", + ] { + let (xml, back) = save(kept, false); + assert!(!xml.contains("INJECTED") && !xml.contains("&bad;"), "{kept:?} was written: {xml}"); + assert_eq!(texts(&back), vec!["NODES".to_string()], "{kept:?}"); + } +} + +#[test] +fn a_kept_omath_para_is_not_nested_in_another() { + let kept = "P"; + let (xml, back) = save(kept, true); + assert!(!xml.contains(""), "{xml}"); + assert_eq!(texts(&back), vec!["NODES".to_string()]); +} diff --git a/crates/docx/tests/it/main.rs b/crates/docx/tests/it/main.rs index 726010a7a..1e57e583c 100644 --- a/crates/docx/tests/it/main.rs +++ b/crates/docx/tests/it/main.rs @@ -20,6 +20,7 @@ mod emphasis_marks; mod fixtures; mod glossary; mod heading_levels; +mod kept_omml_check; mod legacy_forms; mod ligatures; mod line_numbering; diff --git a/crates/math/Cargo.toml b/crates/math/Cargo.toml index 6cbc3251e..d7e4786ec 100644 --- a/crates/math/Cargo.toml +++ b/crates/math/Cargo.toml @@ -12,6 +12,9 @@ workspace = true [dependencies] craft-xml = { workspace = true } +# A conforming XML parser (names, namespaces, characters), for checking kept OMML before it is +# written verbatim; already in the lock as a dependency of other crates. +roxmltree = "0.21" serde = { workspace = true } [dev-dependencies] diff --git a/crates/math/src/omml.rs b/crates/math/src/omml.rs index 99024ec8b..dbcdc0cfd 100644 --- a/crates/math/src/omml.rs +++ b/crates/math/src/omml.rs @@ -58,9 +58,27 @@ fn parse_kept(xml: &str) -> Option { Options { ns_decls: false, ..Options::default() }.with_limits(limits).parse(xml.as_bytes()).ok() } -/// Is `xml` (kept OMML) well-formed enough to write back as it is? +/// Whether `xml` (kept OMML) can be written back as it is: exactly one well-formed `m:oMath` (not +/// `m:oMathPara`), with nothing around it. The writer copies it verbatim into the host document, +/// and [`Math::omml`] also comes from documents saved as JSON, so anything else (an unclosed or +/// mismatched tag, an unknown entity, markup or text after the element, an `m:oMathPara` that +/// would be nested in a second one) is written from the nodes instead (wordcraft#6072). +/// +/// The strict [`craft_xml`] read bounds the nesting and rejects bad tags, entities and trailing +/// content, but it is lenient about the rest of XML: names that aren't XML names, undeclared +/// prefixes, two attributes with one expanded name, a `<` in an attribute value, `]]>` in text, +/// characters XML 1.0 doesn't allow. A conforming parser rejects all of those, so it runs last, +/// with only the canonical prefixes of kept OMML declared (`m:`, `w:`, `mc:`, as the host +/// document's root declares them): any other prefix is undeclared there. The element must be +/// `m:oMath` by namespace, so an `m:` bound to another URI isn't one. fn is_well_formed(xml: &str) -> bool { - xml.starts_with("") || xml.starts_with("{xml}"); + let Ok(doc) = roxmltree::Document::parse(&wrapped) else { return false }; + let mut nodes = doc.root_element().children(); + matches!((nodes.next(), nodes.next()), (Some(e), None) if e.tag_name().namespace() == Some(MATH_NS) && e.tag_name().name() == "oMath") } /// An equation from OMML text ([`parse`]): an `m:oMathPara`'s first `m:oMath` with the diff --git a/crates/math/src/omml/write.rs b/crates/math/src/omml/write.rs index 046c4499a..4d8f2dd0c 100644 --- a/crates/math/src/omml/write.rs +++ b/crates/math/src/omml/write.rs @@ -44,7 +44,7 @@ pub fn write_equation(w: &mut W, linear: &str, display: bool, math: &Math, color w.close("m:oMathParaPr"); } } - if !math.omml.is_empty() && math.omml.starts_with(" Date: Thu, 12 Nov 2026 22:11:18 -0500 Subject: [PATCH 08/84] craft-math: tests for the OMML writer and the linear format (port of wordcraft#6080) The OMML writer (omml/write.rs) had no tests of its own, and the linear-format parser (math_linear.rs) none in its own module. - omml/write/tests.rs: every MNode variant and option, run properties, the three sources write_equation takes an equation from (kept OMML, nodes, linear text), the equation colour (#1467), display jc, resolve_numbers, m:mathPr and the matrix and depth caps (#4000) are written and read back with read_omath. What the reader gives back differently on purpose (merged runs, half-point sizes, matrix column alignments, an empty delimiter...) is stated as such. Element order, which a round trip can't see, is pinned by exact XML: each structure with its defaults and with every property on, a run, m:oMathPara and m:mathPr. The strings follow the ECMA-376 shared-math sequences. - math_linear/tests.rs: one case per construct of the module doc, the helpers (closer, is_combining, strip_parens), to_linear round trips and truncated input. Where Word builds the same text, the expected tree is Word's. Tests only; no behaviour change. Ported from storytold/wordcraft#6080 (issue wordcraft#6079), on top of the other ports in this series, which they pass with unchanged. The writer tests move from WordCraft's docx/src/write/math/tests.rs to omml/write/tests.rs, with craft-math's paths for what they used from WordCraft (read_omath, para_jc and read_math_pr from omml, each_run_mut from math_tree, map_args from math_linear), and OMML read back with omml::parse instead of WordCraft's xml::parse_strict over namespace-wrapped text. --- crates/math/src/math_linear.rs | 3 + crates/math/src/math_linear/tests.rs | 253 +++++++++++ crates/math/src/omml/write.rs | 3 + crates/math/src/omml/write/tests.rs | 601 +++++++++++++++++++++++++++ 4 files changed, 860 insertions(+) create mode 100644 crates/math/src/math_linear/tests.rs create mode 100644 crates/math/src/omml/write/tests.rs diff --git a/crates/math/src/math_linear.rs b/crates/math/src/math_linear.rs index 1dccd2c46..47634cbcf 100644 --- a/crates/math/src/math_linear.rs +++ b/crates/math/src/math_linear.rs @@ -845,3 +845,6 @@ pub fn map_args(n: MNode, f: &dyn Fn(Arg) -> Arg) -> MNode { MNode::Phant { show, zero_wid, zero_asc, zero_desc, e } => MNode::Phant { show, zero_wid, zero_asc, zero_desc, e: f(e) }, } } + +#[cfg(test)] +mod tests; diff --git a/crates/math/src/math_linear/tests.rs b/crates/math/src/math_linear/tests.rs new file mode 100644 index 000000000..236a6f74d --- /dev/null +++ b/crates/math/src/math_linear/tests.rs @@ -0,0 +1,253 @@ +//! The linear format (UnicodeMath) parser: one case per construct in the module doc. Where Word +//! builds the same text (observed with Word's build-up), the expected tree is the one Word builds; +//! where it differs, the case says so. + +use super::*; +use crate::math::{ColJc, to_linear}; + +fn r(t: &str) -> MNode { + MNode::Run(MRun::new(t)) +} + +fn a(t: &str) -> Arg { + vec![r(t)] +} + +fn up(t: &str) -> Arg { + vec![MNode::Run(MRun::plain(t))] +} + +fn sup(base: Arg, s: Arg) -> MNode { + MNode::Script { kind: ScriptKind::Sup, base, sub: Vec::new(), sup: s } +} + +fn sub(base: Arg, s: Arg) -> MNode { + MNode::Script { kind: ScriptKind::Sub, base, sub: s, sup: Vec::new() } +} + +fn frac(kind: FracKind, num: Arg, den: Arg) -> MNode { + MNode::Frac { kind, num, den } +} + +/// A delimiter as the parser makes it: one element has no separator. +fn delim(beg: Option, end: Option, elems: Vec) -> MNode { + let sep = (elems.len() > 1).then_some('|'); + MNode::Delim { beg, end, sep, grow: true, shp_match: false, elems } +} + +#[track_caller] +fn parses(s: &str, want: Arg) { + assert_eq!(parse(s), want, "{s}"); +} + +/// Linear text printed back from the tree parses to the same tree. +#[track_caller] +fn stable(s: &str) { + let n = parse(s); + let back = to_linear(&n); + assert_eq!(parse(&back), n, "{s} → {back}"); +} + +// --- Fractions. --------------------------------------------------------------------------------- + +#[test] +fn fraction_operators() { + parses("a/b+c", vec![frac(FracKind::Bar, a("a"), a("b")), r("+c")]); + parses("a⁄b", vec![frac(FracKind::Skewed, a("a"), a("b"))]); + parses("a∕b", vec![frac(FracKind::Linear, a("a"), a("b"))]); + parses("a¦b", vec![frac(FracKind::NoBar, a("a"), a("b"))]); + // A parenthesised operand loses its parentheses; `/` groups to the left (as in Word). + parses("(a+b)/(c+d)", vec![frac(FracKind::Bar, a("a+b"), a("c+d"))]); + parses("a/b/c", vec![frac(FracKind::Bar, vec![frac(FracKind::Bar, a("a"), a("b"))], a("c"))]); + // Placeholders are empty arguments; a missing denominator is empty. + parses("⬚/⬚", vec![frac(FracKind::Bar, vec![], vec![])]); + parses("a/", vec![frac(FracKind::Bar, a("a"), vec![])]); +} + +// --- Scripts. ----------------------------------------------------------------------------------- + +#[test] +fn scripts() { + parses("x^(-1)", vec![sup(a("x"), a("-1"))]); + parses("x_i^2", vec![MNode::Script { kind: ScriptKind::SubSup, base: a("x"), sub: a("i"), sup: a("2") }]); + // Either order makes one sub-superscript. + parses("a^b_c", vec![MNode::Script { kind: ScriptKind::SubSup, base: a("a"), sub: a("c"), sup: a("b") }]); + parses("x_(i_j)", vec![sub(a("x"), vec![sub(a("i"), a("j"))])]); +} + +/// `^`/`_` with nothing before them are pre-scripts (module doc). Word's build-up doesn't make an +/// `m:sPre` from this text. +#[test] +fn pre_scripts() { + parses("_1^n▒Y", vec![MNode::Script { kind: ScriptKind::Pre, base: a("Y"), sub: a("1"), sup: a("n") }]); +} + +// --- Radicals, n-ary operators, functions, limits. ---------------------------------------------- + +#[test] +fn radicals() { + parses("√x", vec![MNode::Rad { deg: vec![], deg_hide: true, e: a("x") }]); + parses("√(3&x)", vec![MNode::Rad { deg: a("3"), deg_hide: false, e: a("x") }]); + parses("√", vec![MNode::Rad { deg: vec![], deg_hide: true, e: vec![] }]); +} + +#[test] +fn nary_operators() { + let nary = |chr, sub, sup, e| MNode::Nary { chr, lim_loc: None, grow: false, sub_hide: false, sup_hide: false, sub, sup, e }; + parses("∑_(i=1)^n▒i^2", vec![nary('∑', a("i=1"), a("n"), vec![sup(a("i"), a("2"))])]); + parses("∫_0^1▒f(x)dx", vec![nary('∫', a("0"), a("1"), vec![r("f"), delim(Some('('), Some(')'), vec![a("x")]), r("dx")])]); +} + +#[test] +fn function_names() { + parses("sin x", vec![MNode::Func { name: up("sin"), e: a("x") }]); + parses("log_2 x", vec![MNode::Func { name: vec![sub(up("log"), a("2"))], e: a("x") }]); + parses("lim┬(n→∞) a_n", vec![MNode::Func { name: vec![MNode::Lim { upper: false, e: up("lim"), lim: a("n→∞") }], e: vec![sub(a("a"), a("n"))] }]); +} + +#[test] +fn limits_on_any_base() { + parses("x┬k", vec![MNode::Lim { upper: false, e: a("x"), lim: a("k") }]); + parses("x┴k", vec![MNode::Lim { upper: true, e: a("x"), lim: a("k") }]); + parses("a/b┬c", vec![frac(FracKind::Bar, a("a"), vec![MNode::Lim { upper: false, e: a("b"), lim: a("c") }])]); +} + +// --- Brackets. ---------------------------------------------------------------------------------- + +#[test] +fn brackets() { + parses("(a│b)", vec![delim(Some('('), Some(')'), vec![a("a"), a("b")])]); + parses("|x|+‖v‖", vec![delim(Some('|'), Some('|'), vec![a("x")]), r("+"), delim(Some('‖'), Some('‖'), vec![a("v")])]); + parses("f'(x)", vec![r("f'"), delim(Some('('), Some(')'), vec![a("x")])]); + // `├`…`┤` make one-sided or reversed brackets (module doc; Word's build-up leaves `├]a[┤` as + // text, but builds `{█(x@y)┤`). + parses("├]a[┤", vec![delim(Some(']'), Some('['), vec![a("a")])]); + parses("{█(x@y)┤", vec![delim(Some('{'), None, vec![vec![MNode::EqArr { rows: vec![a("x"), a("y")] }]])]); + // An unclosed bracket closes at the end; stray closers are text. + parses("(a", vec![delim(Some('('), None, vec![a("a")])]); + parses("a)", a("a)")); + parses("]x", a("]x")); + parses(")a(", vec![r(")a"), delim(Some('('), None, vec![vec![]])]); +} + +// --- Prefix structures and accents. ------------------------------------------------------------- + +#[test] +fn prefix_structures() { + parses("▭(a)", vec![MNode::BorderBox { hide: [false; 4], strike: [false; 4], e: a("a") }]); + parses("□(a)", vec![MNode::Boxed { e: a("a") }]); + parses("¯(ab)", vec![MNode::Bar { top: true, e: a("ab") }]); + parses("▁(ab)", vec![MNode::Bar { top: false, e: a("ab") }]); + parses("⏞(a+b)", vec![MNode::GroupChr { chr: '⏞', top: true, e: a("a+b") }]); + parses("⏟(a+b)", vec![MNode::GroupChr { chr: '⏟', top: false, e: a("a+b") }]); +} + +#[test] +fn combining_accents() { + parses("A\u{20D7}", vec![MNode::Acc { chr: '\u{20D7}', e: a("A") }]); + parses("x\u{302}", vec![MNode::Acc { chr: '\u{302}', e: a("x") }]); + assert!(is_combining('\u{302}') && is_combining('\u{20D7}')); + assert!(!is_combining('x') && !is_combining('^')); +} + +// --- Arrays and numbering. ---------------------------------------------------------------------- + +#[test] +fn arrays() { + parses("█(a=b@c=d)", vec![MNode::EqArr { rows: vec![a("a=b"), a("c=d")] }]); + parses("█(a@b", vec![MNode::EqArr { rows: vec![a("a"), a("b")] }]); + // Column alignments are left to the writer (it writes centred columns). + parses("■(a&b@c&d)", vec![MNode::Matrix { rows: vec![vec![a("a"), a("b")], vec![a("c"), a("d")]], col_jc: Vec::::new() }]); +} + +#[test] +fn a_top_level_hash_numbers_the_equation() { + let number = delim(Some('('), Some(')'), vec![a("1")]); + parses("E=mc^2#(1)", vec![MNode::EqArr { rows: vec![vec![r("E=m"), sup(a("c"), a("2")), r("#"), number]] }]); + assert!(matches!(&parse("a=b#")[..], [MNode::EqArr { rows }] if rows.len() == 1)); + assert!(!matches!(&parse("a=b")[..], [MNode::EqArr { .. }])); +} + +// --- Helpers. ----------------------------------------------------------------------------------- + +#[test] +fn closers_pair_with_openers() { + for (o, c) in [('(', ')'), ('[', ']'), ('{', '}'), ('⟨', '⟩'), ('〈', '〉'), ('⌈', '⌉'), ('⌊', '⌋'), ('⟦', '⟧'), ('〖', '〗')] + { + assert_eq!(closer(o), Some(c)); + assert!(is_closer(c)); + } + assert_eq!(closer('a'), None); + assert_eq!(closer('|'), None, "| closes itself, by matching"); +} + +#[test] +fn strip_parens_unwraps_one_plain_group() { + let inner = a("a+b"); + assert_eq!(strip_parens(vec![delim(Some('('), Some(')'), vec![inner.clone()])]), inner); + assert_eq!(strip_parens(vec![delim(None, None, vec![inner.clone()])]), inner, "invisible brackets"); + let square = vec![delim(Some('['), Some(']'), vec![inner.clone()])]; + assert_eq!(strip_parens(square.clone()), square, "only round or invisible brackets"); + let two = vec![delim(Some('('), Some(')'), vec![a("a"), a("b")])]; + assert_eq!(strip_parens(two.clone()), two, "only one element"); + let more = vec![delim(Some('('), Some(')'), vec![inner]), r("c")]; + assert_eq!(strip_parens(more.clone()), more, "only a lone group"); +} + +// --- Round trip through `to_linear`. ------------------------------------------------------------ + +#[test] +fn every_construct_prints_back_to_the_same_tree() { + for s in [ + "a/b+c", + "(a+b)/(c+d)", + "a/b/c", + "a⁄b", + "a∕b", + "a¦b", + "⬚/⬚", + "x_i^2", + "a^b_c", + "x^(-1)", + "x_(i_j)", + "_1^n▒Y", + "√x", + "√(3&x)", + "∑_(i=1)^n▒i^2", + "∫_0^1▒f(x)dx", + "sin x", + "log_2 x", + "lim┬(n→∞) a_n", + "x┬k", + "x┴k", + "a/b┬c", + "(a│b)", + "|x|+‖v‖", + "f'(x)", + "├]a[┤", + "{█(x@y)┤", + "(a", + ")a(", + "▭(a)", + "□(a)", + "¯(ab)", + "▁(ab)", + "⏞(a+b)", + "⏟(a+b)", + "A\u{20D7}", + "x\u{302}", + "█(a=b@c=d)", + "■(a&b@c&d)", + "E=mc^2#(1)", + ] { + stable(s); + } +} + +#[test] +fn truncated_input_parses() { + for s in ["√", "(a", "a/", "█(a@b", "x_", "■(", "├", "┤", "〖", "#", "▒", "/", "^", "_"] { + let n = parse(s); + assert_eq!(parse(&to_linear(&n)), n, "{s:?} → {:?}", to_linear(&n)); + } +} diff --git a/crates/math/src/omml/write.rs b/crates/math/src/omml/write.rs index 4d8f2dd0c..3f571fc96 100644 --- a/crates/math/src/omml/write.rs +++ b/crates/math/src/omml/write.rs @@ -491,3 +491,6 @@ fn run(w: &mut W, r: &MRun) { w.leaf("m:t", &[("xml:space", "preserve")], &r.text); w.close("m:r"); } + +#[cfg(test)] +mod tests; diff --git a/crates/math/src/omml/write/tests.rs b/crates/math/src/omml/write/tests.rs new file mode 100644 index 000000000..c828822ac --- /dev/null +++ b/crates/math/src/omml/write/tests.rs @@ -0,0 +1,601 @@ +//! The OMML writer: content and values are checked by writing a tree and reading it back with +//! [`crate::omml::read_omath`]; element order, which the reader can't see (it looks children +//! up by name), is checked against exact XML. The golden strings were checked against the +//! ECMA-376 shared-math schema (`CT_*` sequences); they come from this writer, not from Word. + +use super::*; +use crate::math::to_linear; + +const RED: Rgb = Rgb(0xFF, 0, 0); +const GREEN: Rgb = Rgb(0, 0x80, 0); +const BLUE: Rgb = Rgb(0, 0, 0xFF); + +fn r(t: &str) -> MNode { + MNode::Run(MRun::new(t)) +} + +fn a(t: &str) -> Arg { + vec![r(t)] +} + +fn delim(beg: Option, end: Option, elems: Vec) -> MNode { + MNode::Delim { beg, end, sep: Some('|'), grow: true, shp_match: false, elems } +} + +fn math(nodes: Arg) -> Math { + Math { nodes, ..Default::default() } +} + +/// `write_equation` into a fresh writer, without the XML declaration. +fn write(m: &Math, linear: &str, display: bool, color: Option) -> String { + let mut w = W::default(); + write_equation(&mut w, linear, display, m, color); + w.s +} + +fn xml(nodes: &Arg) -> String { + write(&math(nodes.clone()), "", false, None) +} + +/// Read written OMML back (inline or display), as the DOCX reader does. +fn read(xml: &str) -> Math { + let e = crate::omml::parse(xml).unwrap(); + match e.name.as_str() { + "m:oMathPara" => read_omath(e.find("m:oMath").unwrap(), crate::omml::para_jc(&e)), + _ => read_omath(&e, MathJc::CenterGroup), + } +} + +fn round_trip(nodes: &Arg) -> Arg { + read(&xml(nodes)).nodes +} + +#[track_caller] +fn assert_round_trip(label: &str, nodes: Arg) { + assert_eq!(round_trip(&nodes), nodes, "{label}: {}", xml(&nodes)); +} + +/// The equation's runs. +fn runs(nodes: &Arg) -> Vec { + let mut out = Vec::new(); + let mut n = nodes.clone(); + crate::math_tree::each_run_mut(&mut n, &mut |r| out.push(r.clone())); + out +} + +// --- Round trip: every structure and option comes back as written. ----------------------------- + +#[test] +fn every_structure_round_trips() { + use MNode::*; + for kind in [FracKind::Bar, FracKind::Skewed, FracKind::Linear, FracKind::NoBar] { + assert_round_trip("frac", vec![Frac { kind, num: a("a"), den: a("b") }]); + } + assert_round_trip("empty frac", vec![Frac { kind: FracKind::Bar, num: vec![], den: vec![] }]); + assert_round_trip("sup", vec![Script { kind: ScriptKind::Sup, base: a("x"), sub: vec![], sup: a("2") }]); + assert_round_trip("sub", vec![Script { kind: ScriptKind::Sub, base: a("x"), sub: a("i"), sup: vec![] }]); + assert_round_trip("subsup", vec![Script { kind: ScriptKind::SubSup, base: a("x"), sub: a("i"), sup: a("2") }]); + assert_round_trip("pre", vec![Script { kind: ScriptKind::Pre, base: a("x"), sub: a("i"), sup: a("2") }]); + assert_round_trip("sqrt", vec![Rad { deg: vec![], deg_hide: true, e: a("x") }]); + assert_round_trip("root", vec![Rad { deg: a("3"), deg_hide: false, e: a("x") }]); + assert_round_trip("empty degree shown", vec![Rad { deg: vec![], deg_hide: false, e: a("x") }]); + for (chr, lim_loc) in [('∫', None), ('∑', Some(LimLoc::UndOvr)), ('∏', Some(LimLoc::SubSup))] { + assert_round_trip("nary", vec![Nary { chr, lim_loc, grow: false, sub_hide: false, sup_hide: false, sub: a("i"), sup: a("n"), e: a("x") }]); + } + assert_round_trip( + "nary flags", + vec![Nary { chr: '∑', lim_loc: None, grow: true, sub_hide: true, sup_hide: true, sub: vec![], sup: vec![], e: a("x") }], + ); + assert_round_trip("parens", vec![delim(Some('('), Some(')'), vec![a("a")])]); + assert_round_trip("one-sided", vec![delim(Some('{'), None, vec![a("a")])]); + assert_round_trip("no opening", vec![delim(None, Some(']'), vec![a("a")])]); + assert_round_trip("empty element", vec![delim(Some('('), Some(')'), vec![vec![]])]); + assert_round_trip( + "brackets, separator, two elements", + vec![Delim { beg: Some('['), end: Some(']'), sep: Some(';'), grow: true, shp_match: false, elems: vec![a("a"), a("b")] }], + ); + assert_round_trip( + "no separator", + vec![Delim { beg: Some('('), end: Some(')'), sep: None, grow: true, shp_match: false, elems: vec![a("a"), a("b")] }], + ); + assert_round_trip( + "fixed size, matched shape", + vec![Delim { beg: Some('|'), end: Some('|'), sep: Some('|'), grow: false, shp_match: true, elems: vec![a("a")] }], + ); + assert_round_trip("func", vec![Func { name: vec![MNode::Run(MRun::plain("sin"))], e: a("x") }]); + assert_round_trip("lim low", vec![Lim { upper: false, e: vec![MNode::Run(MRun::plain("lim"))], lim: a("n→∞") }]); + assert_round_trip("lim upp", vec![Lim { upper: true, e: a("x"), lim: a("k") }]); + assert_round_trip("hat", vec![Acc { chr: '\u{302}', e: a("x") }]); + assert_round_trip("vector", vec![Acc { chr: '\u{20D7}', e: a("v") }]); + assert_round_trip("overbar", vec![Bar { top: true, e: a("x") }]); + assert_round_trip("underbar", vec![Bar { top: false, e: a("x") }]); + assert_round_trip("border box", vec![BorderBox { hide: [false; 4], strike: [false; 4], e: a("x") }]); + assert_round_trip("border box flags", vec![BorderBox { hide: [true, false, true, false], strike: [false, true, false, true], e: a("x") }]); + assert_round_trip("box", vec![Boxed { e: a("x") }]); + assert_round_trip("underbrace", vec![GroupChr { chr: '\u{23DF}', top: false, e: a("x") }]); + assert_round_trip("overbrace", vec![GroupChr { chr: '\u{23DE}', top: true, e: a("x") }]); + assert_round_trip("eqarr", vec![EqArr { rows: vec![a("a=b"), a("c=d")] }]); + assert_round_trip("numbered eqarr", vec![EqArr { rows: vec![a("a=b#(1)")] }]); + assert_round_trip("matrix", vec![Matrix { rows: vec![vec![a("a"), a("b")], vec![a("c"), a("d")]], col_jc: vec![ColJc::Left, ColJc::Right] }]); + assert_round_trip("phantom", vec![Phant { show: true, zero_wid: false, zero_asc: false, zero_desc: false, e: a("x") }]); + assert_round_trip("hidden phantom", vec![Phant { show: false, zero_wid: true, zero_asc: true, zero_desc: true, e: a("x") }]); +} + +#[test] +fn nested_structures_round_trip() { + let quadratic = parse_linear("x=(-b±√(b^2-4ac))/2a"); + assert_round_trip("quadratic", quadratic); + let sum = parse_linear("∑_(i=1)^n▒(i^2)/(n+1)"); + assert_round_trip("sum", sum); +} + +#[test] +fn run_properties_round_trip() { + let with = |f: &dyn Fn(&mut MRun)| { + let mut x = MRun::new("ab"); + f(&mut x); + vec![MNode::Run(x)] + }; + for s in [MSty::Plain, MSty::Bold, MSty::Italic, MSty::BoldItalic] { + assert_round_trip("sty", with(&|x| x.sty = Some(s))); + } + for s in [MScr::Script, MScr::Fraktur, MScr::DoubleStruck, MScr::SansSerif, MScr::Monospace] { + assert_round_trip("scr", with(&|x| x.scr = s)); + } + assert_round_trip("lit", with(&|x| x.lit = true)); + assert_round_trip( + "normal text in a font", + with(&|x| { + x.nor = true; + x.font = Some("Arial".into()); + }), + ); + assert_round_trip("size", with(&|x| x.size = Some(11.0))); + assert_round_trip("half-point size", with(&|x| x.size = Some(10.5))); + assert_round_trip("colour", with(&|x| x.color = Some(RED))); + assert_round_trip("break", with(&|x| x.brk = Some(0))); + assert_round_trip("aligned break", with(&|x| x.brk = Some(3))); + for t in ["af", " a b ", " ", "a\tb\nc", "𝑥𝟙", "\u{F061}"] { + assert_round_trip(t, a(t)); + } +} + +// --- Normalisation: what the reader gives back differently, on purpose. ------------------------ + +#[test] +fn reading_back_normalises_runs() { + // Equal neighbours merge (`merge_runs`); an empty run is no run. + assert_eq!(round_trip(&vec![r("a"), r("b")]), a("ab")); + assert_eq!(round_trip(&vec![r("a"), r(""), r("b")]), a("ab")); + assert_eq!(round_trip(&a("")), vec![]); + // Characters XML can't carry are dropped. + assert_eq!(round_trip(&a("a\u{1}b")), a("ab")); + // Sizes are half points, within 1–1638 pt. + let sized = |s: f32| vec![MNode::Run(MRun { size: Some(s), ..MRun::new("x") })]; + assert_eq!(round_trip(&sized(10.3)), sized(10.5)); + assert_eq!(round_trip(&sized(0.5)), sized(1.0)); + assert_eq!(round_trip(&sized(2000.0)), sized(1638.0)); + // A font belongs to normal text only; normal text without one is written in Cambria Math, + // as Word writes it (layout treats that as the text font). + let font = vec![MNode::Run(MRun { font: Some("Arial".into()), ..MRun::new("x") })]; + assert_eq!(round_trip(&font), a("x")); + let nor = vec![MNode::Run(MRun { nor: true, ..MRun::new("x") })]; + assert_eq!(round_trip(&nor), vec![MNode::Run(MRun { nor: true, font: Some("Cambria Math".into()), ..MRun::new("x") })]); +} + +#[test] +fn reading_back_normalises_structures() { + use MNode::*; + // A script keeps only the slots its kind has. + let stray = vec![Script { kind: ScriptKind::Sup, base: a("x"), sub: a("i"), sup: a("2") }]; + assert_eq!(round_trip(&stray), vec![Script { kind: ScriptKind::Sup, base: a("x"), sub: vec![], sup: a("2") }]); + // A delimiter has at least one element. + assert_eq!(round_trip(&vec![delim(Some('('), Some(')'), vec![])]), vec![delim(Some('('), Some(')'), vec![vec![]])]); + // A matrix gets one column alignment per column and rectangular rows (#3643). + let cells = vec![vec![a("a"), a("b")], vec![a("c")]]; + let padded = vec![vec![a("a"), a("b")], vec![a("c"), vec![]]]; + assert_eq!(round_trip(&vec![Matrix { rows: cells, col_jc: vec![] }]), vec![Matrix { rows: padded, col_jc: vec![ColJc::Center; 2] }]); + assert_eq!(round_trip(&vec![Matrix { rows: vec![], col_jc: vec![] }]), vec![Matrix { rows: vec![], col_jc: vec![ColJc::Center] }]); +} + +/// Every linear-format equation saves and reopens as the same tree, once matrices have their +/// column alignments filled in. +#[test] +fn linear_equations_survive_a_save() { + fn fill_col_jc(a: Arg) -> Arg { + a.into_iter() + .map(|n| match n { + MNode::Matrix { rows, col_jc } if col_jc.is_empty() => { + let cols = rows.iter().map(Vec::len).max().unwrap_or(0).max(1); + let rows = rows.into_iter().map(|row| row.into_iter().map(fill_col_jc).collect()).collect(); + MNode::Matrix { rows, col_jc: vec![ColJc::Center; cols] } + } + other => crate::math_linear::map_args(other, &fill_col_jc), + }) + .collect() + } + for s in [ + "x=(-b±√(b^2-4ac))/2a", + "〖a+b〗^2", + "├]a[┤", + "{█(x@y)┤", + "(a│b)", + "▭(a)+□(b)+¯(c)+▁(d)", + "⏞(a+b)+⏟(c+d)", + "⬚/⬚", + "a⁄b+a∕b+a¦b", + "_1^n▒Y", + "x┬k+x┴k", + "A⃗+x̂", + "log_2⁡x", + "lim┬(n→∞)⁡a_n", + ")a(", + "E=mc^2#(1)", + "■(a&b@c&d)", + "√(3&x)", + "∫_0^1▒f(x)dx", + "|x|+‖v‖", + ] { + let n = parse_linear(s); + assert_eq!(round_trip(&n), fill_col_jc(n.clone()), "{s} → {}", to_linear(&n)); + } +} + +// --- Where `write_equation` takes the equation from. -------------------------------------------- + +#[test] +fn kept_omml_is_written_back_unchanged() { + let kept = "KEPT"; + let m = Math { nodes: a("NODES"), omml: kept.into(), ..Default::default() }; + assert_eq!(write(&m, "linear", false, None), kept); +} + +#[test] +fn kept_xml_that_is_not_an_omath_is_rewritten_from_the_nodes() { + let m = Math { nodes: a("NODES"), omml: "X".into(), ..Default::default() }; + let out = write(&m, "linear", false, None); + assert_eq!(read(&out).nodes, a("NODES")); +} + +#[test] +fn without_nodes_the_linear_text_is_written() { + let out = write(&Math::default(), "a/b", false, None); + assert_eq!(read(&out).nodes, parse_linear("a/b")); + assert_eq!(write(&Math::default(), "", false, None), ""); +} + +#[test] +fn an_equation_colour_rewrites_the_kept_omml() { + let kept_red = r#"a"#; + let nodes = vec![r("a"), MNode::Run(MRun { color: Some(GREEN), ..MRun::new("g") })]; + let m = Math { nodes, omml: kept_red.into(), ..Default::default() }; + let colours = |c: Option| runs(&read(&write(&m, "", false, c)).nodes).into_iter().map(|r| (r.text, r.color)).collect::>(); + // The same colour keeps the source XML. + assert_eq!(write(&m, "", false, Some(RED)), kept_red); + // Another colour goes on every run without its own (#1467). + assert_eq!(colours(Some(BLUE)), vec![("a".to_string(), Some(BLUE)), ("g".to_string(), Some(GREEN))]); + // No colour takes the old one off. + assert_eq!(colours(None), vec![("a".to_string(), None), ("g".to_string(), Some(GREEN))]); +} + +#[test] +fn kept_omml_without_one_colour_is_kept_without_an_equation_colour() { + for kept in [ + "a", + r#"ab"#, + ] { + let m = Math { nodes: a("ab"), omml: kept.into(), ..Default::default() }; + assert_eq!(write(&m, "", false, None), kept); + } +} + +#[test] +fn display_justification_round_trips() { + for jc in [MathJc::CenterGroup, MathJc::Center, MathJc::Left, MathJc::Right] { + let out = write(&Math { nodes: a("x"), jc, ..Default::default() }, "", true, None); + assert_eq!(read(&out).jc, jc, "{out}"); + assert_eq!(out.contains("m:oMathParaPr"), jc != MathJc::CenterGroup, "{out}"); + } + assert!(!write(&math(a("x")), "", false, None).contains("oMathPara")); +} + +// --- Equation numbers. -------------------------------------------------------------------------- + +fn rows(rs: &[&str]) -> Math { + math(vec![MNode::EqArr { rows: rs.iter().map(|s| a(s)).collect() }]) +} + +#[test] +fn automatic_numbers_are_written_out() { + // A `#` with nothing after it gets the next number; a written number counts too, as in + // layout's `auto_numbers`. + let mut n = 0; + let out = resolve_numbers(&rows(&["a=b#", "c=d", "e=f#(9)", "g#"]), true, &mut n).unwrap(); + assert_eq!(n, 3); + assert_eq!(to_linear(&out.nodes), "█(a=b#(1)@c=d@e=f#(9)@g#(3))"); + assert!(out.omml.is_empty(), "the numbered copy is written from its nodes"); + // The counter carries on into the next equation. + let out = resolve_numbers(&rows(&["h#"]), true, &mut n).unwrap(); + assert_eq!((n, to_linear(&out.nodes)), (4, "h#(4)".to_string()), "a one-row array prints without █"); +} + +#[test] +fn equations_without_automatic_numbers_are_left_alone() { + let mut n = 5; + assert!(resolve_numbers(&rows(&["a=b#(7)"]), true, &mut n).is_none()); + assert_eq!(n, 6, "a written number still counts"); + let mut n = 0; + assert!(resolve_numbers(&rows(&["a#"]), false, &mut n).is_none(), "inline"); + assert!(resolve_numbers(&math(a("a=b#")), true, &mut n).is_none(), "not an equation array"); + let nested = math(vec![MNode::EqArr { rows: vec![vec![MNode::Frac { kind: FracKind::Bar, num: a("a#"), den: a("b") }]] }]); + assert!(resolve_numbers(&nested, true, &mut n).is_none(), "a # inside a structure isn't a number mark"); + assert_eq!(n, 0); +} + +// --- Settings: m:mathPr. ------------------------------------------------------------------------ + +fn math_pr_round_trip(m: &MathProps) -> MathProps { + let mut w = W::default(); + math_pr(&mut w, m); + let root = parse_kept(&w.s).unwrap(); + assert_eq!(root.name, "m:mathPr"); + crate::omml::read_math_pr(&root) +} + +#[test] +fn math_properties_round_trip() { + for m in [ + MathProps::default(), + MathProps { brk_bin: BrkBin::After, brk_bin_sub: BrkBinSub::PlusMinus, ..Default::default() }, + MathProps { brk_bin: BrkBin::Repeat, brk_bin_sub: BrkBinSub::MinusPlus, ..Default::default() }, + MathProps { wrap_indent: 0.0, ..Default::default() }, + MathProps { wrap_indent: 12.35, ..Default::default() }, + MathProps { wrap_right: true, ..Default::default() }, + ] { + assert_eq!(math_pr_round_trip(&m), m); + } +} + +#[test] +fn math_properties_are_clamped() { + let indent = |v: f32| math_pr_round_trip(&MathProps { wrap_indent: v, ..Default::default() }).wrap_indent; + assert_eq!(indent(5000.0), 1584.0); + assert_eq!(indent(-3.0), 0.0); + assert_eq!(indent(f32::NAN), crate::math::DEFAULT_WRAP_INDENT); + // `wrapIndent` and `wrapRight` are a choice: aligning right drops the indent. + let right = math_pr_round_trip(&MathProps { wrap_right: true, wrap_indent: 10.0, ..Default::default() }); + assert_eq!(right, MathProps { wrap_right: true, ..Default::default() }); +} + +// --- Limits. ------------------------------------------------------------------------------------ + +#[test] +fn matrix_caps_hold_on_save() { + let wide = vec![MNode::Matrix { rows: vec![vec![a("x"); MAX_MATRIX_COLS + 6]; 3], col_jc: vec![] }]; + let back = round_trip(&wide); + let [MNode::Matrix { rows, col_jc }] = &back[..] else { panic!("{back:?}") }; + assert_eq!((rows.len(), rows[0].len(), col_jc.len()), (3, MAX_MATRIX_COLS, MAX_MATRIX_COLS)); + let tall = vec![MNode::Matrix { rows: vec![vec![a("x")]; MAX_MATRIX_ROWS + 5], col_jc: vec![] }]; + let back = round_trip(&tall); + let [MNode::Matrix { rows, .. }] = &back[..] else { panic!("{back:?}") }; + assert_eq!(rows.len(), MAX_MATRIX_ROWS); +} + +fn fraction_chain(depth: usize) -> Arg { + let mut cur = a("LEAF"); + for _ in 0..depth { + cur = vec![MNode::Frac { kind: FracKind::Bar, num: cur, den: a("d") }]; + } + cur +} + +#[test] +fn a_tree_past_the_depth_cap_writes_well_formed_xml() { + for depth in [MAX_DEPTH, MAX_DEPTH + 1, 4 * MAX_DEPTH] { + let out = xml(&fraction_chain(depth)); + assert!(craft_xml::Options::default().strict().parse(out.as_bytes()).is_ok(), "depth {depth}"); + } + assert!(!xml(&fraction_chain(MAX_DEPTH + 1)).contains("LEAF"), "the writer stops at MAX_DEPTH"); +} + +// --- Golden XML: element order and what is left out. -------------------------------------------- + +const CTRL: &str = r#""#; + +/// `m:r` for `x` with no properties of its own. +fn rx(t: &str) -> String { + format!(r#"{t}"#) +} + +/// The golden string with `{C}` standing for [`CTRL`] and `{a}`… for [`rx`] runs. +fn expand(s: &str) -> String { + let mut out = s.replace("{C}", CTRL); + for t in ["a", "b", "c", "d", "x", "i", "n", "2", "3", "k"] { + out = out.replace(&format!("{{{t}}}"), &rx(t)); + } + format!("{out}") +} + +#[track_caller] +fn assert_golden(label: &str, nodes: Arg, expected: &str) { + assert_eq!(xml(&nodes), expand(expected), "{label}"); +} + +#[test] +fn golden_runs() { + assert_golden("plain run", a("x"), "{x}"); + let all = MRun { sty: Some(MSty::Bold), scr: MScr::Script, lit: true, brk: Some(2), color: Some(RED), size: Some(11.0), ..MRun::new("x") }; + assert_golden( + "every math run property", + vec![MNode::Run(all)], + r#"x"#, + ); + let nor = MRun { nor: true, font: Some("Arial".into()), brk: Some(0), ..MRun::new("x y") }; + assert_golden( + "normal text", + vec![MNode::Run(nor)], + r#"x y"#, + ); +} + +#[test] +fn golden_fractions_scripts_and_radicals() { + use MNode::*; + assert_golden( + "bar fraction", + vec![Frac { kind: FracKind::Bar, num: a("a"), den: a("b") }], + "{C}{a}{b}", + ); + assert_golden( + "skewed fraction, empty denominator", + vec![Frac { kind: FracKind::Skewed, num: a("a"), den: vec![] }], + r#"{C}{a}"#, + ); + assert_golden( + "sup", + vec![Script { kind: ScriptKind::Sup, base: a("x"), sub: vec![], sup: a("2") }], + "{C}{x}{2}", + ); + assert_golden( + "sub", + vec![Script { kind: ScriptKind::Sub, base: a("x"), sub: a("i"), sup: vec![] }], + "{C}{x}{i}", + ); + assert_golden( + "subsup", + vec![Script { kind: ScriptKind::SubSup, base: a("x"), sub: a("i"), sup: a("2") }], + "{C}{x}{i}{2}", + ); + // CT_SPre: sub, sup, then the base. + assert_golden( + "pre", + vec![Script { kind: ScriptKind::Pre, base: a("x"), sub: a("i"), sup: a("2") }], + "{C}{i}{2}{x}", + ); + assert_golden( + "square root", + vec![Rad { deg: vec![], deg_hide: true, e: a("x") }], + r#"{C}{x}"#, + ); + assert_golden( + "cube root", + vec![Rad { deg: a("3"), deg_hide: false, e: a("x") }], + "{C}{3}{x}", + ); +} + +#[test] +fn golden_operators_and_delimiters() { + use MNode::*; + let nary = |chr, lim_loc, on| Nary { chr, lim_loc, grow: on, sub_hide: on, sup_hide: on, sub: a("i"), sup: a("n"), e: a("x") }; + assert_golden( + "integral", + vec![nary('∫', None, false)], + "{C}{i}{n}{x}", + ); + assert_golden( + "sum, every property", + vec![nary('∑', Some(LimLoc::UndOvr), true)], + r#"{C}{i}{n}{x}"#, + ); + assert_golden("parentheses", vec![delim(Some('('), Some(')'), vec![a("x")])], "{C}{x}"); + assert_golden( + "delimiter, every property", + vec![Delim { beg: Some('['), end: None, sep: Some(';'), grow: false, shp_match: true, elems: vec![a("a"), a("b")] }], + r#"{C}{a}{b}"#, + ); + assert_golden( + "function", + vec![Func { name: a("a"), e: a("x") }], + "{C}{a}{x}", + ); + assert_golden( + "lower limit", + vec![Lim { upper: false, e: a("a"), lim: a("n") }], + "{C}{a}{n}", + ); + assert_golden( + "upper limit", + vec![Lim { upper: true, e: a("a"), lim: a("k") }], + "{C}{a}{k}", + ); +} + +#[test] +fn golden_accents_bars_and_boxes() { + use MNode::*; + assert_golden("accent", vec![Acc { chr: '\u{302}', e: a("x") }], "{C}{x}"); + assert_golden("overbar", vec![Bar { top: true, e: a("x") }], r#"{C}{x}"#); + assert_golden("underbar", vec![Bar { top: false, e: a("x") }], r#"{C}{x}"#); + assert_golden( + "border box", + vec![BorderBox { hide: [false; 4], strike: [false; 4], e: a("x") }], + "{C}{x}", + ); + assert_golden( + "border box, every property", + vec![BorderBox { hide: [true; 4], strike: [true; 4], e: a("x") }], + r#"{C}{x}"#, + ); + assert_golden("box", vec![Boxed { e: a("x") }], "{C}{x}"); + assert_golden( + "underbrace", + vec![GroupChr { chr: '\u{23DF}', top: false, e: a("x") }], + "{C}{x}", + ); + assert_golden( + "overbrace", + vec![GroupChr { chr: '\u{23DE}', top: true, e: a("x") }], + "{C}{x}", + ); + assert_golden( + "phantom", + vec![Phant { show: true, zero_wid: false, zero_asc: false, zero_desc: false, e: a("x") }], + r#"{C}{x}"#, + ); + assert_golden( + "phantom, every property", + vec![Phant { show: false, zero_wid: true, zero_asc: true, zero_desc: true, e: a("x") }], + r#"{C}{x}"#, + ); +} + +#[test] +fn golden_arrays() { + use MNode::*; + assert_golden("eqarr", vec![EqArr { rows: vec![a("a"), a("b")] }], "{C}{a}{b}"); + assert_golden( + "numbered eqarr", + vec![EqArr { rows: vec![vec![r("a"), r("#")]] }], + r#"{C}{a}#"#, + ); + assert_golden( + "matrix", + vec![Matrix { rows: vec![vec![a("a"), a("b")], vec![a("c")]], col_jc: vec![ColJc::Left] }], + r#"{C}{a}{b}{c}"#, + ); +} + +#[test] +fn golden_display_and_settings() { + let out = write(&Math { nodes: a("x"), jc: MathJc::Left, ..Default::default() }, "", true, None); + assert_eq!(out, format!(r#"{}"#, expand("{x}"))); + assert_eq!(write(&math(a("x")), "", true, None), format!("{}", expand("{x}"))); + let pr = |m: &MathProps| { + let mut w = W::default(); + math_pr(&mut w, m); + w.s + }; + assert_eq!(pr(&MathProps::default()), r#""#); + assert_eq!( + pr(&MathProps { brk_bin: BrkBin::After, brk_bin_sub: BrkBinSub::PlusMinus, wrap_right: true, ..Default::default() }), + r#""# + ); +} + +/// The run helper is used by every golden: a run with no properties is exactly `rx`. +#[test] +fn golden_helpers_match_the_writer() { + assert_eq!(xml(&a("x")), format!("{}", rx("x"))); + assert!(expand("{C}").contains("m:ctrlPr")); +} From ae00359d2b37245fd4157ebe838a42ae7011f2b6 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 22:36:13 -0500 Subject: [PATCH 09/84] craft-math: review fixes: number bases, a comma after a script, whitespace in kept OMML MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From the review of this series: - A base that is one number by the parser's rule (1,000 as well as 2.5 and .5) is written bare, 1,000^2 rather than 〖1,000〗^2. lin_base tested numbers with digits and points only, so a comma made it a multi-letter base. The rule is now is_number, the parser's number_len over the whole text; simple_operand, which fractions share, is unchanged. - A bare script followed by a comma and a digit is ended with a space: x^2 then ,3 was written x^2,3, and the number script read the ,3 back into the exponent. Only a comma before a digit gets one; x^2, y is written as before. - Kept OMML whose element name is followed by a tab, carriage return or line feed (all XML whitespace) is written back like one followed by a space, instead of from the nodes. Each new test fails without its fix. --- crates/docx/tests/it/kept_omml_check.rs | 11 ++++++++++ crates/math/src/math.rs | 24 ++++++++++++++++---- crates/math/src/omml.rs | 5 ++++- crates/math/tests/number_bases.rs | 29 +++++++++++++++++++++++++ 4 files changed, 64 insertions(+), 5 deletions(-) diff --git a/crates/docx/tests/it/kept_omml_check.rs b/crates/docx/tests/it/kept_omml_check.rs index e382cdb1b..8cd187635 100644 --- a/crates/docx/tests/it/kept_omml_check.rs +++ b/crates/docx/tests/it/kept_omml_check.rs @@ -49,6 +49,17 @@ fn well_formed_kept_omml_is_written_back_unchanged() { assert_eq!(texts(&back), vec!["KEPT".to_string()]); } +#[test] +fn xml_whitespace_after_the_element_name_is_kept() { + // XML allows any of space, tab, carriage return and line feed between a name and `>`. + for ws in [" ", "\t", "\r", "\n", "\r\n "] { + let kept = format!("KEPT"); + let (xml, back) = save(&kept, false); + assert!(xml.contains(&kept), "{ws:?}: {xml}"); + assert_eq!(texts(&back), vec!["KEPT".to_string()], "{ws:?}"); + } +} + #[test] fn malformed_kept_omml_is_written_from_the_nodes() { for kept in [ diff --git a/crates/math/src/math.rs b/crates/math/src/math.rs index 83d232fd2..8b1cbcc88 100644 --- a/crates/math/src/math.rs +++ b/crates/math/src/math.rs @@ -499,7 +499,12 @@ fn lin_arg(a: &[MNode], s: &mut String, depth: usize) { // A bare script or limit ends at a space: a letter, digit or period after it is its own item. if matches!(n, MNode::Script { kind, .. } if *kind != ScriptKind::Pre) || matches!(n, MNode::Lim { .. }) { let ends_bare = s.chars().next_back().is_some_and(|c| c.is_alphanumeric() || c == '.'); - if ends_bare && a.get(i + 1).and_then(first_lin_char).is_some_and(|c| c.is_alphanumeric() || c == '.') { + // So does a `,` before a digit: a number script reads it as part of the number (`x^2,3`). + let comma_digit = || { + let mut cs = a[i + 1..].iter().map_while(|n| if let MNode::Run(r) = n { Some(r.text.chars()) } else { None }).flatten(); + cs.next() == Some(',') && cs.next().is_some_and(|c| c.is_ascii_digit()) + }; + if ends_bare && (a.get(i + 1).and_then(first_lin_char).is_some_and(|c| c.is_alphanumeric() || c == '.') || comma_digit()) { s.push(' '); } } @@ -518,6 +523,16 @@ fn first_lin_char(n: &MNode) -> Option { } } +/// Whether `t` is one number as the linear-format parser reads it (`number_len`): digits, where a +/// `.` or `,` continues it only before a digit (`2.5`, `1,000`), and a leading `.` before a digit +/// starts one (`.5`). `2.` isn't one: the parser leaves the point out. +fn is_number(t: &str) -> bool { + let c: Vec = t.chars().collect(); + let digit = |k: usize| c.get(k).is_some_and(|c| c.is_ascii_digit()); + (digit(0) || (c.first() == Some(&'.') && digit(1))) + && c.iter().enumerate().all(|(k, &ch)| ch.is_ascii_digit() || (matches!(ch, '.' | ',') && digit(k + 1))) +} + /// Whether `a` is written bare as an operand: a single simple atom. fn simple_operand(a: &[MNode]) -> bool { match a { @@ -560,10 +575,11 @@ fn lin_base(a: &[MNode], s: &mut String, depth: usize) { lin_arg(a, &mut inner, depth); let invisible = matches!(a, [MNode::Delim { beg: None, end: None, elems, .. }] if elems.len() == 1); let operator = matches!(a, [MNode::Run(r)] if r.text.chars().all(crate::math_linear::is_boundary)); - let number = |t: &str| t.chars().all(|c| c.is_ascii_digit() || c == '.'); let name = |r: &MRun| r.sty == Some(MSty::Plain) && crate::math_linear::FUNCTION_NAMES.contains(&r.text.as_str()); - let letters = matches!(a, [MNode::Run(r)] if r.text.chars().nth(1).is_some() && !number(&r.text) && !name(r)); - if simple_operand(a) && !inner.is_empty() && !invisible && !operator && !letters { + // A number by the parser's rule (`1,000`, `2.5`, `.5`) is one item, so it stays bare too. + let number = matches!(a, [MNode::Run(r)] if is_number(&r.text)); + let letters = matches!(a, [MNode::Run(r)] if r.text.chars().nth(1).is_some() && !number && !name(r)); + if (simple_operand(a) || number) && !inner.is_empty() && !invisible && !operator && !letters { s.push_str(&inner); } else { s.push('〖'); diff --git a/crates/math/src/omml.rs b/crates/math/src/omml.rs index dbcdc0cfd..9416f11d8 100644 --- a/crates/math/src/omml.rs +++ b/crates/math/src/omml.rs @@ -72,7 +72,10 @@ fn parse_kept(xml: &str) -> Option { /// document's root declares them): any other prefix is undeclared there. The element must be /// `m:oMath` by namespace, so an `m:` bound to another URI isn't one. fn is_well_formed(xml: &str) -> bool { - if !(xml.starts_with("") || xml.starts_with("` or XML whitespace (XML 1.0 §2.3 S), not at `/>` (an empty equation) or + // a longer name (`m:oMathPara`). + let named = xml.strip_prefix("' | ' ' | '\t' | '\r' | '\n')); + if !named || Options::default().strict().parse(xml.as_bytes()).is_err() { return false; } let wrapped = format!("{xml}"); diff --git a/crates/math/tests/number_bases.rs b/crates/math/tests/number_bases.rs index 752253a66..c8ffae0c7 100644 --- a/crates/math/tests/number_bases.rs +++ b/crates/math/tests/number_bases.rs @@ -92,3 +92,32 @@ fn a_comma_between_digits_in_brackets_joins_them() { assert_eq!(f.text, "f"); assert_eq!(elems, &vec![vec![sup("1,2", "3")]]); } + +/// Linear text and back: the same tree. +#[track_caller] +fn prints_back(t: Vec, want: &str) { + let lin = craft_math::math::to_linear(&t); + assert_eq!(lin, want); + assert_eq!(parse_linear(&lin), t, "{lin}"); +} + +#[test] +fn a_number_base_prints_bare() { + // A number the parser reads as one item needs no brackets as a base, with a comma too. + for (base, want) in [("10", "10^2"), ("2.5", "2.5^2"), (".5", ".5^2"), ("1,000", "1,000^2")] { + prints_back(vec![sup(base, "2")], want); + } +} + +#[test] +fn a_comma_before_a_digit_after_a_script_stays_outside_it() { + // `x^2,3` would read `,3` into the number script, so a space ends the script first. + prints_back(vec![sup("x", "2"), r(",3")], "x^2 ,3"); + prints_back(vec![sup("x", "a"), r(",3")], "x^a ,3"); + // Also when the comma and the digit are separate runs (read back as one). + let lin = craft_math::math::to_linear(&[sup("x", "2"), r(","), r("3")]); + assert_eq!(lin, "x^2 ,3"); + assert_eq!(parse_linear(&lin), vec![sup("x", "2"), r(",3")]); + // A comma before anything else ends the script on its own: no space is added. + assert_eq!(craft_math::math::to_linear(&[sup("x", "2"), r(", y")]), "x^2, y"); +} From 4a5cb986512ff3af90f03c094d0f3e95ddc513ef Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 22:51:39 -0500 Subject: [PATCH 10/84] craft-math: review fixes: a number base after a number, a cap on kept OMML, is_number without a Vec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From the second review round: - A number base right after a digit, `.` or `,` keeps its brackets. Bare, it continued the number before it: `1` then `23^4` was written `123^4` and read back with 123 as the base, and the same for a one-digit base (`12^4`), `x.` then `5^2` and `1,` then `5^2`. This came with the bare number base, before the first review round. A number base after a letter or an operator stays bare (`a2^4`, `1+2^4`). - Both parses of kept OMML are capped at the elements the reader keeps (MAX_ELEMENTS × 2) instead of craft-xml's defaults, and roxmltree gets the same cap as `nodes_limit`. Kept OMML can come from a hostile JSON document; larger kept OMML is written from its nodes. The reader can't keep more than this, so OMML read from a file is unaffected. - is_number scans bytes instead of collecting a Vec: everything a number holds is ASCII. The two new tests fail without their fix. --- crates/math/src/math.rs | 15 ++++++++++----- crates/math/src/omml.rs | 10 ++++++++-- crates/math/src/omml/write/tests.rs | 12 ++++++++++++ crates/math/tests/number_bases.rs | 13 +++++++++++++ 4 files changed, 43 insertions(+), 7 deletions(-) diff --git a/crates/math/src/math.rs b/crates/math/src/math.rs index 8b1cbcc88..7ae964809 100644 --- a/crates/math/src/math.rs +++ b/crates/math/src/math.rs @@ -527,10 +527,11 @@ fn first_lin_char(n: &MNode) -> Option { /// `.` or `,` continues it only before a digit (`2.5`, `1,000`), and a leading `.` before a digit /// starts one (`.5`). `2.` isn't one: the parser leaves the point out. fn is_number(t: &str) -> bool { - let c: Vec = t.chars().collect(); - let digit = |k: usize| c.get(k).is_some_and(|c| c.is_ascii_digit()); - (digit(0) || (c.first() == Some(&'.') && digit(1))) - && c.iter().enumerate().all(|(k, &ch)| ch.is_ascii_digit() || (matches!(ch, '.' | ',') && digit(k + 1))) + // Every character of a number is ASCII, so the bytes do. + let b = t.as_bytes(); + let digit = |k: usize| b.get(k).is_some_and(u8::is_ascii_digit); + (digit(0) || (b.first() == Some(&b'.') && digit(1))) + && b.iter().enumerate().all(|(k, &c)| c.is_ascii_digit() || (matches!(c, b'.' | b',') && digit(k + 1))) } /// Whether `a` is written bare as an operand: a single simple atom. @@ -579,7 +580,11 @@ fn lin_base(a: &[MNode], s: &mut String, depth: usize) { // A number by the parser's rule (`1,000`, `2.5`, `.5`) is one item, so it stays bare too. let number = matches!(a, [MNode::Run(r)] if is_number(&r.text)); let letters = matches!(a, [MNode::Run(r)] if r.text.chars().nth(1).is_some() && !number && !name(r)); - if (simple_operand(a) || number) && !inner.is_empty() && !invisible && !operator && !letters { + // A base starting with a digit or `.` right after a digit, `.` or `,` would continue the number + // before it (`1` then `23^4` is `123^4`), so it keeps its brackets: `1〖23〗^4`. + let joins = s.chars().next_back().is_some_and(|c| c.is_ascii_digit() || matches!(c, '.' | ',')) + && inner.chars().next().is_some_and(|c| c.is_ascii_digit() || c == '.'); + if (simple_operand(a) || number) && !inner.is_empty() && !invisible && !operator && !letters && !joins { s.push_str(&inner); } else { s.push('〖'); diff --git a/crates/math/src/omml.rs b/crates/math/src/omml.rs index 9416f11d8..b10ec780a 100644 --- a/crates/math/src/omml.rs +++ b/crates/math/src/omml.rs @@ -75,11 +75,17 @@ fn is_well_formed(xml: &str) -> bool { // The name ends at `>` or XML whitespace (XML 1.0 §2.3 S), not at `/>` (an empty equation) or // a longer name (`m:oMathPara`). let named = xml.strip_prefix("' | ' ' | '\t' | '\r' | '\n')); - if !named || Options::default().strict().parse(xml.as_bytes()).is_err() { + // Both parses are capped as the reader caps what it keeps ([`parse`]): kept OMML can come from + // a hostile JSON document, and a larger one is written from its nodes. + let limits = craft_xml::Limits { max_nodes: MAX_ELEMENTS.saturating_mul(2), ..craft_xml::Limits::DEFAULT }; + if !named || Options::default().strict().with_limits(limits).parse(xml.as_bytes()).is_err() { return false; } let wrapped = format!("{xml}"); - let Ok(doc) = roxmltree::Document::parse(&wrapped) else { return false }; + // The wrapper and the document root are two more nodes. + let nodes_limit = u32::try_from(limits.max_nodes.saturating_add(2)).unwrap_or(u32::MAX); + let options = roxmltree::ParsingOptions { nodes_limit, ..roxmltree::ParsingOptions::default() }; + let Ok(doc) = roxmltree::Document::parse_with_options(&wrapped, options) else { return false }; let mut nodes = doc.root_element().children(); matches!((nodes.next(), nodes.next()), (Some(e), None) if e.tag_name().namespace() == Some(MATH_NS) && e.tag_name().name() == "oMath") } diff --git a/crates/math/src/omml/write/tests.rs b/crates/math/src/omml/write/tests.rs index c828822ac..2fb09c124 100644 --- a/crates/math/src/omml/write/tests.rs +++ b/crates/math/src/omml/write/tests.rs @@ -257,6 +257,18 @@ fn kept_xml_that_is_not_an_omath_is_rewritten_from_the_nodes() { assert_eq!(read(&out).nodes, a("NODES")); } +#[test] +fn kept_omml_larger_than_the_reader_keeps_is_rewritten_from_the_nodes() { + // The same cap as the reader's: one more element than it reads is written from the nodes, + // one fewer is kept. + let cap = crate::omml::MAX_ELEMENTS * 2; + let kept = |runs: usize| format!("{}", "".repeat(runs)); + let over = Math { nodes: a("NODES"), omml: kept(cap + 1), ..Default::default() }; + assert_eq!(read(&write(&over, "linear", false, None)).nodes, a("NODES")); + let under = Math { nodes: a("NODES"), omml: kept(cap - 10), ..Default::default() }; + assert!(write(&under, "linear", false, None).contains(&under.omml)); +} + #[test] fn without_nodes_the_linear_text_is_written() { let out = write(&Math::default(), "a/b", false, None); diff --git a/crates/math/tests/number_bases.rs b/crates/math/tests/number_bases.rs index c8ffae0c7..f0bf5aab5 100644 --- a/crates/math/tests/number_bases.rs +++ b/crates/math/tests/number_bases.rs @@ -121,3 +121,16 @@ fn a_comma_before_a_digit_after_a_script_stays_outside_it() { // A comma before anything else ends the script on its own: no space is added. assert_eq!(craft_math::math::to_linear(&[sup("x", "2"), r(", y")]), "x^2, y"); } + +#[test] +fn a_number_base_after_a_number_keeps_its_brackets() { + // Bare, the base would continue the number before it: `1` then `23^4` would read `123^4`. + for (before, base, want) in + [("1", "23", "1〖23〗^4"), ("1", "2", "1〖2〗^4"), ("x.", "5", "x.〖5〗^4"), ("1,", "5", "1,〖5〗^4"), ("1", ".5", "1〖.5〗^4")] + { + prints_back(vec![r(before), sup(base, "4")], want); + } + // After a letter or an operator it can't, so it stays bare. + prints_back(vec![r("a"), sup("2", "4")], "a2^4"); + prints_back(vec![r("1+"), sup("2", "4")], "1+2^4"); +} From 3e61d2e4360b4bef6a48e0ad52fb4fda1a8fa21f Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Mon, 16 Nov 2026 22:21:40 -0500 Subject: [PATCH 11/84] math: invisible brackets export to LaTeX as a TeX group MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A script whose base isn't simple prints as `〖a^b〗^c` in linear text (port of wordcraft#6084), and LaTeX export copied the brackets into the .tex, where the exporter's preamble can't set them. They are now a TeX group, `{a^b}^c`; one without its partner is dropped. Also pins that `〖a+b〗 ^2` keeps the delimiter. Port of the review fix on wordcraft#6084. --- crates/latex/src/tests.rs | 22 ++++++++++++++++++++++ crates/math/src/latex_text.rs | 13 ++++++++++++- crates/math/tests/linear_script_base.rs | 7 +++++++ 3 files changed, 41 insertions(+), 1 deletion(-) diff --git a/crates/latex/src/tests.rs b/crates/latex/src/tests.rs index ccf349c80..ebffe770e 100644 --- a/crates/latex/src/tests.rs +++ b/crates/latex/src/tests.rs @@ -437,3 +437,25 @@ fn a_tabular_row_keeps_the_cells_a_table_row_holds() { assert_eq!(t.rows.first().map(Vec::len), Some(craft_wordmodel::table::MAX_COLS)); assert_eq!(t.rows.get(1).map(Vec::len), Some(2)); } + +#[test] +fn a_script_on_a_script_exports_as_a_tex_group() { + use craft_math::math::{MNode, MRun, ScriptKind, to_linear}; + let a = |t: &str| vec![MNode::Run(MRun::new(t))]; + let sup = |base, s| MNode::Script { kind: ScriptKind::Sup, base, sub: Vec::new(), sup: s }; + // sSup(sSup(a, b), c), as Word files hold it: the docx reader keeps `to_linear` of it. + let linear = to_linear(&[sup(vec![sup(a("a"), a("b"))], a("c"))]); + assert_eq!(linear, "〖a^b〗^c"); + let mut d = Document::new(); + let mut p = craft_wordmodel::Paragraph::new(); + p.insert_object(0, craft_wordmodel::para::InlineObject::Equation { linear, display: false, math: Default::default() }, &Default::default()) + .unwrap(); + d.body = vec![craft_wordmodel::para_block(p)]; + let tex = export(&d); + // The preamble sets up no Unicode math font, so `〖` would stop pdflatex. + assert!(tex.contains("${a^b}^c$") && !tex.contains('〖') && !tex.contains('〗'), "{tex}"); + // Invisible brackets anywhere are a TeX group; one left unmatched is dropped. + for (linear, tex) in [("〖a+b〗^2", "{a+b}^2"), ("x^〖a〗", "x^{a}"), ("〖〖a〗^b〗^c", "{{a}^b}^c"), ("a〗b〖c", "abc")] { + assert_eq!(linear_to_latex(linear), tex, "{linear}"); + } +} diff --git a/crates/math/src/latex_text.rs b/crates/math/src/latex_text.rs index 5541a36c3..24d9638e8 100644 --- a/crates/math/src/latex_text.rs +++ b/crates/math/src/latex_text.rs @@ -235,6 +235,7 @@ pub fn linear_to_latex(linear: &str) -> String { fn linear_to_latex_at(linear: &str, depth: usize) -> String { let chars: Vec = linear.chars().collect(); let parens = closers(&chars, '(', ')'); + let brackets = closers(&chars, '〖', '〗'); let mut o = String::new(); let mut i = 0; let sub = |s: &str| if depth < MAX_NEST { linear_to_latex_at(s, depth + 1) } else { escape_math_text(s) }; @@ -309,6 +310,16 @@ fn linear_to_latex_at(linear: &str, depth: usize) -> String { o.push('\\'); o.push(c); } + // Invisible brackets (`〖a^b〗^c`, a script base that isn't simple) only group: a TeX + // group. One without its partner shows nothing and is dropped. + '〖' => { + if let Some((inner, end)) = balanced(&chars, &brackets, i) { + o.push_str(&format!("{{{}}}", sub(&inner))); + i = end; + continue; + } + } + '〗' => {} '{' => o.push_str("\\{"), '}' => o.push_str("\\}"), '~' => o.push_str("\\sim "), @@ -332,7 +343,7 @@ fn linear_to_latex_at(linear: &str, depth: usize) -> String { fn escape_math_text(s: &str) -> String { let mut o = String::new(); - for c in s.chars().filter(|c| !matches!(c, '{' | '}' | '\\' | '$' | '%' | '#' | '&') && !c.is_control()) { + for c in s.chars().filter(|c| !matches!(c, '{' | '}' | '\\' | '$' | '%' | '#' | '&' | '〖' | '〗') && !c.is_control()) { // Never `^^` (see `linear_to_latex_at`). if c == '^' && o.ends_with('^') { continue; diff --git a/crates/math/tests/linear_script_base.rs b/crates/math/tests/linear_script_base.rs index 8a6505b14..9c655ee4f 100644 --- a/crates/math/tests/linear_script_base.rs +++ b/crates/math/tests/linear_script_base.rs @@ -72,3 +72,10 @@ fn an_explicit_delimiter_as_the_base_is_kept() { // Grouping still leaves none. assert_eq!(parse_linear("〖a〗^2"), vec![sup(a("a"), a("2"))]); } + +#[test] +fn invisible_brackets_before_a_space_stay_a_delimiter() { + // Only `〗` right before `^`/`_` makes them a script base; after a space they are kept as typed. + let n = parse_linear("〖a+b〗 ^2"); + assert!(matches!(&n[..], [MNode::Delim { beg: None, end: None, .. }, ..]), "{n:?}"); +} From 5a0f8246787ee99083f0d652c162ad003fa6f0ae Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Mon, 16 Nov 2026 21:20:51 -0800 Subject: [PATCH 12/84] Add craft-audio-dsp: compressor, limiter, equalizer, loudness meter and other effects Adds crates/audio-dsp. It combines FilmCraft's crates/audio-dsp (3f137a7) and SoundCraft's crates/dsp (648ed9d): the AudioEffect trait and its registry, the effects, a BS.1770-4 / EBU R 128 loudness meter, panning, channel layouts, test signals, resampling, time stretch, offset search and ducking. NOTICE keeps both projects' copyright notices. - pan::direction_gains sends an ear-level direction to the height speakers at full level when a layout has no ear-level speakers, instead of returning silence. - realtime_factor_sanity compares processing time with the wall clock and is now ignored by default. - The crate inherits the workspace package fields and lints, and ATTRIBUTION.md lists it. --- ATTRIBUTION.md | 4 + Cargo.lock | 4 + Cargo.toml | 1 + crates/audio-dsp/Cargo.toml | 14 + crates/audio-dsp/NOTICE | 14 + crates/audio-dsp/README.md | 88 ++ crates/audio-dsp/src/biquad.rs | 510 +++++++++ crates/audio-dsp/src/channels.rs | 451 ++++++++ crates/audio-dsp/src/design.rs | 773 ++++++++++++++ crates/audio-dsp/src/ducking.rs | 309 ++++++ crates/audio-dsp/src/effects.rs | 346 +++++++ .../audio-dsp/src/effects/behavior_tests.rs | 673 ++++++++++++ crates/audio-dsp/src/effects/channel.rs | 345 +++++++ crates/audio-dsp/src/effects/declick.rs | 237 +++++ crates/audio-dsp/src/effects/dither.rs | 127 +++ crates/audio-dsp/src/effects/dynamics.rs | 904 ++++++++++++++++ crates/audio-dsp/src/effects/eq.rs | 644 ++++++++++++ crates/audio-dsp/src/effects/essential.rs | 823 +++++++++++++++ crates/audio-dsp/src/effects/filters.rs | 698 +++++++++++++ crates/audio-dsp/src/effects/generator.rs | 98 ++ crates/audio-dsp/src/effects/modulation.rs | 587 +++++++++++ crates/audio-dsp/src/effects/multiband.rs | 626 +++++++++++ crates/audio-dsp/src/effects/pitch.rs | 330 ++++++ crates/audio-dsp/src/effects/restoration.rs | 355 +++++++ crates/audio-dsp/src/effects/reverbs.rs | 752 ++++++++++++++ crates/audio-dsp/src/effects/special.rs | 971 ++++++++++++++++++ crates/audio-dsp/src/effects/stft.rs | 564 ++++++++++ crates/audio-dsp/src/effects/time.rs | 558 ++++++++++ crates/audio-dsp/src/effects/util.rs | 330 ++++++ crates/audio-dsp/src/fft.rs | 204 ++++ crates/audio-dsp/src/generator.rs | 246 +++++ crates/audio-dsp/src/lib.rs | 465 +++++++++ crates/audio-dsp/src/loudness.rs | 955 +++++++++++++++++ crates/audio-dsp/src/offline.rs | 312 ++++++ crates/audio-dsp/src/oversample.rs | 197 ++++ crates/audio-dsp/src/pan.rs | 436 ++++++++ crates/audio-dsp/src/resample.rs | 424 ++++++++ crates/audio-dsp/src/smooth.rs | 100 ++ crates/audio-dsp/src/stretch.rs | 231 +++++ crates/audio-dsp/src/sync.rs | 614 +++++++++++ 40 files changed, 16320 insertions(+) create mode 100644 crates/audio-dsp/Cargo.toml create mode 100644 crates/audio-dsp/NOTICE create mode 100644 crates/audio-dsp/README.md create mode 100644 crates/audio-dsp/src/biquad.rs create mode 100644 crates/audio-dsp/src/channels.rs create mode 100644 crates/audio-dsp/src/design.rs create mode 100644 crates/audio-dsp/src/ducking.rs create mode 100644 crates/audio-dsp/src/effects.rs create mode 100644 crates/audio-dsp/src/effects/behavior_tests.rs create mode 100644 crates/audio-dsp/src/effects/channel.rs create mode 100644 crates/audio-dsp/src/effects/declick.rs create mode 100644 crates/audio-dsp/src/effects/dither.rs create mode 100644 crates/audio-dsp/src/effects/dynamics.rs create mode 100644 crates/audio-dsp/src/effects/eq.rs create mode 100644 crates/audio-dsp/src/effects/essential.rs create mode 100644 crates/audio-dsp/src/effects/filters.rs create mode 100644 crates/audio-dsp/src/effects/generator.rs create mode 100644 crates/audio-dsp/src/effects/modulation.rs create mode 100644 crates/audio-dsp/src/effects/multiband.rs create mode 100644 crates/audio-dsp/src/effects/pitch.rs create mode 100644 crates/audio-dsp/src/effects/restoration.rs create mode 100644 crates/audio-dsp/src/effects/reverbs.rs create mode 100644 crates/audio-dsp/src/effects/special.rs create mode 100644 crates/audio-dsp/src/effects/stft.rs create mode 100644 crates/audio-dsp/src/effects/time.rs create mode 100644 crates/audio-dsp/src/effects/util.rs create mode 100644 crates/audio-dsp/src/fft.rs create mode 100644 crates/audio-dsp/src/generator.rs create mode 100644 crates/audio-dsp/src/lib.rs create mode 100644 crates/audio-dsp/src/loudness.rs create mode 100644 crates/audio-dsp/src/offline.rs create mode 100644 crates/audio-dsp/src/oversample.rs create mode 100644 crates/audio-dsp/src/pan.rs create mode 100644 crates/audio-dsp/src/resample.rs create mode 100644 crates/audio-dsp/src/smooth.rs create mode 100644 crates/audio-dsp/src/stretch.rs create mode 100644 crates/audio-dsp/src/sync.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 9d260300c..7225da061 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -111,6 +111,10 @@ The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper `crates/audio/src/wav_stream.rs` is extracted from AniCraft `crates/audio/src/wav.rs` at `d875a7feb250e6ab06aa28a37fb78a0699e88330` (MIT OR Apache-2.0). Tanish Manku is retained as the primary import author, from original commit `30c121d269a49d9abe54a3834ed4aa0201542535`. Odd-data padding accounting, shared API documentation and regression tests are subsequent Dylan M. Taylor changes. +## Audio DSP + +`crates/audio-dsp` is moved from StudioCraft's `crates/craft-audio-dsp` ([blamejs/StudioCraft](https://github.com/blamejs/StudioCraft) at `98224a9cc3e9eb353844908b2a676b2e6a9327d5`, MIT OR Apache-2.0). That crate combines FilmCraft `crates/audio-dsp` at `3f137a7ed420cac79b32145f5243b7f98b31f71c` and SoundCraft `crates/dsp` at `648ed9db9a0e98cc55643babffac381521a556c8` (both MIT OR Apache-2.0). `crates/audio-dsp/NOTICE` keeps the copyright notices of all three projects. + ## GIMP palette reader `crates/palette` extracts the GPL text parser from AniCraft `crates/doc/src/swatch.rs` at `d875a7feb250e6ab06aa28a37fb78a0699e88330` (MIT OR Apache-2.0), introduced by Tanish Manku in `a64130a9da9bdde545463b852d95d6a6774b1dfd` (AniCraft #270). The import preserves Tanish as primary author. Neutral RGB/name adaptation separates application display-name sanitization and the `Untitled` policy; validation tests and integration are subsequent Dylan M. Taylor changes. diff --git a/Cargo.lock b/Cargo.lock index 1ac11475f..46d23108b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1593,6 +1593,10 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-audio-dsp" +version = "0.1.0" + [[package]] name = "craft-ber" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 2c0f4dfea..3bdd62073 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-audio-dsp = { path = "crates/audio-dsp" } craft-palette = { path = "crates/palette" } craft-shx = { path = "crates/shx" } craft-http-url = { path = "crates/http-url" } diff --git a/crates/audio-dsp/Cargo.toml b/crates/audio-dsp/Cargo.toml new file mode 100644 index 000000000..5d192e9d3 --- /dev/null +++ b/crates/audio-dsp/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "craft-audio-dsp" +description = "Real-time and offline audio DSP for the Craft apps: BS.1770 / EBU R128 loudness metering, audio effects with a common effect trait, panning, test signals and resampling" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +# No dependencies: planar `&mut [f32]` slices in, planar slices out. +[dependencies] diff --git a/crates/audio-dsp/NOTICE b/crates/audio-dsp/NOTICE new file mode 100644 index 000000000..708b38d72 --- /dev/null +++ b/crates/audio-dsp/NOTICE @@ -0,0 +1,14 @@ +craft-audio-dsp +Copyright (c) 2026 The StudioCraft contributors. +Licensed under the MIT License or the Apache License, Version 2.0, at your option +(LICENSE-MIT and LICENSE-APACHE at the repository root). + +This crate contains code from the following projects, under the same licenses: + +FilmCraft (https://github.com/storytold/filmcraft), crates/audio-dsp +Copyright (c) 2026 ArtCraft Team and the FilmCraft contributors. +Licensed under the MIT License or the Apache License, Version 2.0, at your option. + +SoundCraft (https://github.com/storytold/soundcraft), crates/dsp +Copyright (c) 2026 ArtCraft Team and the SoundCraft contributors. +Licensed under the MIT License or the Apache License, Version 2.0, at your option. diff --git a/crates/audio-dsp/README.md b/crates/audio-dsp/README.md new file mode 100644 index 000000000..609fce7b3 --- /dev/null +++ b/crates/audio-dsp/README.md @@ -0,0 +1,88 @@ +# craft-audio-dsp + +Audio DSP for the Craft apps, in Rust with no dependencies. It builds for `wasm32-unknown-unknown` +and contains no `unsafe` code. + +## Contents + +- `AudioEffect`: the trait every effect implements, and `effects()`, the registry that lists each + effect's id, name, category and parameters (range, unit, default). `create_effect(id, rate, + channels)` builds one by id. +- Effects: equalizers (parametric, graphic, notch, scientific and FFT filters), dynamics + (compressor, expander and gate, limiter, maximizer, multiband and tube-modeled compressors), + delays and reverbs (including convolution and surround), modulation, restoration (denoise, + dehum, click remover, de-esser, de-reverb, speech enhancement), channel tools, distortion, + dither, a signal generator and a loudness meter. +- `loudness`: an ITU-R BS.1770-4 / EBU R128 meter with momentary, short-term and integrated + loudness, loudness range (EBU Tech 3342), sample peak and true peak. +- `pan`: stereo pan laws, a surround panner over any layout of up to 16 speakers, and first-order + ambisonic encoding and decoding. +- `channels`: channel layouts, ITU-R BS.775 upmix and downmix, and the 5.1 panner. +- `generator`: band-limited sine, square, saw and triangle oscillators, and white and pink noise. +- `resample`: streaming rate conversion for playback. `offline::resample` converts whole buffers. +- `stretch`: time stretch that keeps the pitch. +- `sync`: the offset between two recordings of one event. +- `ducking`: speech-activity regions in a trigger track and the volume keyframes that lower a + music track under them. +- `biquad` and `design`: biquad filters with their magnitude response, and IIR filter design from + Butterworth, Bessel, Chebyshev and elliptic prototypes. + +## Conventions + +Audio is planar `f32`: one slice per channel, all the same length. `AudioEffect::process`, +`process_keyed`, `set_param` and `reset` do not allocate; every buffer is sized when the effect is +created. When a parameter changes, gains, mix amounts and equalizer bands move to the new value +per sample. Other parameters, such as a compressor's threshold, ratio, knee and times or a +limiter's ceiling and release, take effect from the next sample. With the parameters held still, +the output does not depend on the block size. The convolution reverb is the one effect whose +`process` call can take much longer than a block: after a change to its impulse, room size or +damping, the next call rebuilds the impulse's partitions in buffers sized when the effect was +created. Non-finite input samples do not leave an effect's state at NaN. + +Constructors clamp the sample rate to `MIN_SAMPLE_RATE ..= MAX_SAMPLE_RATE` (1 kHz to 1.536 MHz, +with 48 kHz for a non-finite rate) and the channel count to `1 ..= MAX_CHANNELS` (64). + +Compressor, gate and limiter-type effects report their gain reduction in dB as a non-negative +number through `AudioEffect::gain_reduction_db`. The compressor and the gate take a key +(sidechain) input of up to two channels through `AudioEffect::process_keyed`. + +```rust +use craft_audio_dsp::{AudioEffect, effects::Compressor, loudness::LoudnessMeter}; + +let mut comp = Compressor::new(48_000.0, 2); +comp.set_param("threshold", -24.0); +let (mut left, mut right) = (vec![0.0f32; 1024], vec![0.0f32; 1024]); +comp.process(&mut [&mut left, &mut right]); + +let mut meter = LoudnessMeter::new(48_000.0, 2); +meter.process(&[&left, &right]); +let _integrated = meter.integrated(); +``` + +## API stability + +The items the crate exports are its API. Removing or changing one is a breaking change and bumps +the major version (the minor version while it is below 1.0). Effect ids and parameter ids are part +of the API, because hosts save them in their files. + +## Origin + +The crate combines two crates from the ArtCraft apps, with changes: + +- [storytold/filmcraft](https://github.com/storytold/filmcraft) `crates/audio-dsp` at + `3f137a7ed420cac79b32145f5243b7f98b31f71c`: the `AudioEffect` trait, the effects and their + registry, the loudness meter, the streaming resampler, time stretch, offset search and ducking. +- [storytold/soundcraft](https://github.com/storytold/soundcraft) `crates/dsp` at + `648ed9db9a0e98cc55643babffac381521a556c8`: the tail length, offline mode, events, saved state + and editor parts of the trait, the maximizer, dither, panning, the signal generator and the + offline resampler. + +`NOTICE` keeps the copyright notices of both projects. + +## License + +MIT OR Apache-2.0. + +Copyright (c) 2026 ArtCraft Team and the FilmCraft contributors. +Copyright (c) 2026 ArtCraft Team and the SoundCraft contributors. +Copyright (c) 2026 The StudioCraft contributors. diff --git a/crates/audio-dsp/src/biquad.rs b/crates/audio-dsp/src/biquad.rs new file mode 100644 index 000000000..cc108220a --- /dev/null +++ b/crates/audio-dsp/src/biquad.rs @@ -0,0 +1,510 @@ +//! Second-order IIR sections: RBJ "Audio EQ Cookbook" designs, transposed direct form II. + +use crate::flush; +use std::f64::consts::PI; + +/// Filter shape. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum FilterType { + Peaking, + LowShelf, + HighShelf, + LowPass, + HighPass, + Notch, + BandPass, + AllPass, + /// Constant-bandwidth cut: `1 + (g − 1)·BP(s)`. The −3 dB width of the band-pass stays + /// `f/Q` however deep the cut (`gain_db` ≤ 0), unlike the RBJ peaking filter whose cut + /// widens with depth. Used by the Notch Filter. + Cut, +} + +impl FilterType { + /// Order used by the parametric EQ's `type` choice parameter. + pub const ALL: [FilterType; 7] = [ + FilterType::Peaking, + FilterType::LowShelf, + FilterType::HighShelf, + FilterType::LowPass, + FilterType::HighPass, + FilterType::Notch, + FilterType::BandPass, + ]; + pub fn from_index(i: usize) -> FilterType { + Self::ALL[i.min(Self::ALL.len() - 1)] + } +} + +/// Normalized biquad coefficients (`a0 == 1`). +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Coeffs { + pub b0: f64, + pub b1: f64, + pub b2: f64, + pub a1: f64, + pub a2: f64, +} + +impl Coeffs { + /// Pass-through. + pub const IDENTITY: Coeffs = Coeffs { b0: 1.0, b1: 0.0, b2: 0.0, a1: 0.0, a2: 0.0 }; + + fn norm(b0: f64, b1: f64, b2: f64, a0: f64, a1: f64, a2: f64) -> Coeffs { + Coeffs { b0: b0 / a0, b1: b1 / a0, b2: b2 / a0, a1: a1 / a0, a2: a2 / a0 } + } + + /// RBJ cookbook design. `freq` in Hz (clamped below Nyquist), `q` > 0, `gain_db` used by + /// peaking and shelving types (shelves use `q` as the shelf "Q", S=1 ≙ Q=1/√2). An unusable + /// rate is replaced as [`crate::sane_sample_rate`] describes. + pub fn design(kind: FilterType, sample_rate: f64, freq: f64, q: f64, gain_db: f64) -> Coeffs { + let sample_rate = f64::from(crate::sane_sample_rate(sample_rate as f32)); + let f = freq.clamp(1.0, sample_rate * 0.49); + let q = q.max(1e-3); + let w0 = 2.0 * PI * f / sample_rate; + let (sn, cs) = w0.sin_cos(); + let alpha = sn / (2.0 * q); + let a = 10f64.powf(gain_db / 40.0); + match kind { + FilterType::LowPass => Self::norm((1.0 - cs) / 2.0, 1.0 - cs, (1.0 - cs) / 2.0, 1.0 + alpha, -2.0 * cs, 1.0 - alpha), + FilterType::HighPass => Self::norm((1.0 + cs) / 2.0, -(1.0 + cs), (1.0 + cs) / 2.0, 1.0 + alpha, -2.0 * cs, 1.0 - alpha), + FilterType::BandPass => Self::norm(alpha, 0.0, -alpha, 1.0 + alpha, -2.0 * cs, 1.0 - alpha), + FilterType::Notch => Self::norm(1.0, -2.0 * cs, 1.0, 1.0 + alpha, -2.0 * cs, 1.0 - alpha), + FilterType::AllPass => Self::norm(1.0 - alpha, -2.0 * cs, 1.0 + alpha, 1.0 + alpha, -2.0 * cs, 1.0 - alpha), + FilterType::Cut => { + let g = 10f64.powf(gain_db / 20.0); + Self::norm(1.0 + g * alpha, -2.0 * cs, 1.0 - g * alpha, 1.0 + alpha, -2.0 * cs, 1.0 - alpha) + } + FilterType::Peaking => Self::norm(1.0 + alpha * a, -2.0 * cs, 1.0 - alpha * a, 1.0 + alpha / a, -2.0 * cs, 1.0 - alpha / a), + FilterType::LowShelf => { + let k = 2.0 * a.sqrt() * alpha; + Self::norm( + a * ((a + 1.0) - (a - 1.0) * cs + k), + 2.0 * a * ((a - 1.0) - (a + 1.0) * cs), + a * ((a + 1.0) - (a - 1.0) * cs - k), + (a + 1.0) + (a - 1.0) * cs + k, + -2.0 * ((a - 1.0) + (a + 1.0) * cs), + (a + 1.0) + (a - 1.0) * cs - k, + ) + } + FilterType::HighShelf => { + let k = 2.0 * a.sqrt() * alpha; + Self::norm( + a * ((a + 1.0) + (a - 1.0) * cs + k), + -2.0 * a * ((a - 1.0) + (a + 1.0) * cs), + a * ((a + 1.0) + (a - 1.0) * cs - k), + (a + 1.0) - (a - 1.0) * cs + k, + 2.0 * ((a - 1.0) - (a + 1.0) * cs), + (a + 1.0) - (a - 1.0) * cs - k, + ) + } + } + } + + /// |H(e^{jω})| at `freq` Hz. + pub fn magnitude(&self, freq: f64, sample_rate: f64) -> f64 { + let w = 2.0 * PI * freq / sample_rate; + let (s1, c1) = w.sin_cos(); + let (s2, c2) = (2.0 * w).sin_cos(); + // H = (b0 + b1 z^-1 + b2 z^-2) / (1 + a1 z^-1 + a2 z^-2), z^-1 = e^{-jω}. + let nr = self.b0 + self.b1 * c1 + self.b2 * c2; + let ni = -(self.b1 * s1 + self.b2 * s2); + let dr = 1.0 + self.a1 * c1 + self.a2 * c2; + let di = -(self.a1 * s1 + self.a2 * s2); + ((nr * nr + ni * ni) / (dr * dr + di * di)).sqrt() + } + + /// Magnitude in dB. + pub fn magnitude_db(&self, freq: f64, sample_rate: f64) -> f64 { + 20.0 * self.magnitude(freq, sample_rate).log10() + } +} + +/// One biquad section's state (TDF-II), f64 internally. +#[derive(Clone, Copy, Debug, Default)] +pub struct Biquad { + s1: f64, + s2: f64, +} + +impl Biquad { + pub const fn new() -> Self { + Biquad { s1: 0.0, s2: 0.0 } + } + #[inline(always)] + pub fn tick(&mut self, c: &Coeffs, x: f64) -> f64 { + let y = c.b0 * x + self.s1; + self.s1 = flush(c.b1 * x - c.a1 * y + self.s2); + self.s2 = flush(c.b2 * x - c.a2 * y); + y + } + pub fn reset(&mut self) { + *self = Biquad::new(); + } + /// Exact zero state, including the sign of zero, for identity-filter fast paths. + pub(crate) fn is_clear(&self) -> bool { + self.s1.to_bits() == 0 && self.s2.to_bits() == 0 + } + /// Filter a buffer in place. + pub fn process(&mut self, c: &Coeffs, buf: &mut [f32]) { + for v in buf { + *v = self.tick(c, *v as f64) as f32; + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::*; + + const SR: f64 = 48000.0; + + fn measured_db(c: &Coeffs, freq: f64) -> f64 { + let n = SR as usize; + let mut x = sine(freq, 0.5, SR, n, 0.0); + let mut bq = Biquad::new(); + bq.process(c, &mut x); + // Skip the transient; measure over an integer number of periods-ish long tail. + let tail = &x[n / 2..]; + db(tone_amplitude(tail, freq, SR) / 0.5) + } + + #[test] + fn an_unusable_rate_gives_finite_coefficients() { + for sr in [0.0, -1.0, 1.5, f64::NAN, f64::INFINITY] { + let c = Coeffs::design(FilterType::LowPass, sr, 1000.0, 0.7, 0.0); + assert!([c.b0, c.b1, c.b2, c.a1, c.a2].iter().all(|v| v.is_finite()), "{sr}: {c:?}"); + } + } + + #[test] + fn peaking_hits_gain_at_center() { + let c = Coeffs::design(FilterType::Peaking, SR, 1000.0, 1.0, 6.0); + assert!((c.magnitude_db(1000.0, SR) - 6.0).abs() < 1e-9); + assert!(c.magnitude_db(20.0, SR).abs() < 0.05); + assert!((measured_db(&c, 1000.0) - 6.0).abs() < 0.05); + } + + #[test] + fn lowpass_highpass_minus_3db_at_cutoff() { + let q = std::f64::consts::FRAC_1_SQRT_2; + let lp = Coeffs::design(FilterType::LowPass, SR, 2000.0, q, 0.0); + let hp = Coeffs::design(FilterType::HighPass, SR, 2000.0, q, 0.0); + assert!((lp.magnitude_db(2000.0, SR) + 3.0103).abs() < 0.01); + assert!((hp.magnitude_db(2000.0, SR) + 3.0103).abs() < 0.01); + assert!(lp.magnitude_db(100.0, SR).abs() < 0.01); + assert!(hp.magnitude_db(15000.0, SR).abs() < 0.1); + // 12 dB/oct slope well past cutoff. + assert!(lp.magnitude_db(8000.0, SR) < -22.0); + assert!((measured_db(&lp, 2000.0) + 3.0103).abs() < 0.05); + assert!((measured_db(&hp, 500.0) - hp.magnitude_db(500.0, SR)).abs() < 0.05); + } + + #[test] + fn notch_is_deep_at_center() { + let c = Coeffs::design(FilterType::Notch, SR, 60.0, 10.0, 0.0); + assert!(c.magnitude(60.0, SR) < 1e-6); + assert!(c.magnitude_db(1000.0, SR).abs() < 0.01); + assert!(measured_db(&c, 60.0) < -40.0); + } + + #[test] + fn shelves_reach_their_gain() { + let q = std::f64::consts::FRAC_1_SQRT_2; + let ls = Coeffs::design(FilterType::LowShelf, SR, 200.0, q, 9.0); + let hs = Coeffs::design(FilterType::HighShelf, SR, 5000.0, q, -9.0); + assert!((ls.magnitude_db(10.0, SR) - 9.0).abs() < 0.05); + assert!((ls.magnitude_db(200.0, SR) - 4.5).abs() < 0.01); + assert!(ls.magnitude_db(10000.0, SR).abs() < 0.05); + assert!((hs.magnitude_db(23000.0, SR) + 9.0).abs() < 0.1); + assert!((hs.magnitude_db(5000.0, SR) + 4.5).abs() < 0.01); + assert!((measured_db(&ls, 40.0) - ls.magnitude_db(40.0, SR)).abs() < 0.05); + assert!((measured_db(&hs, 12000.0) - hs.magnitude_db(12000.0, SR)).abs() < 0.05); + } + + #[test] + fn bandpass_and_allpass() { + let bp = Coeffs::design(FilterType::BandPass, SR, 1000.0, 2.0, 0.0); + assert!(bp.magnitude_db(1000.0, SR).abs() < 1e-9); + let ap = Coeffs::design(FilterType::AllPass, SR, 1000.0, 2.0, 0.0); + for f in [50.0, 1000.0, 9000.0] { + assert!(ap.magnitude_db(f, SR).abs() < 1e-9); + } + } + + #[test] + fn state_flushes_to_zero_no_denormals() { + let c = Coeffs::design(FilterType::LowPass, SR, 100.0, 0.7, 0.0); + let mut bq = Biquad::new(); + bq.tick(&c, 1.0); + let mut last = 1.0; + for _ in 0..2_000_000 { + last = bq.tick(&c, 0.0); + assert!(!(last as f32).is_subnormal()); + } + assert_eq!(last, 0.0); + } + + // ----------------------------------------------------------------- non-finite input + + fn flush_reference(x: f64) -> f64 { + if x.abs() < 1e-30 { 0.0 } else { x } + } + + fn flush32_reference(x: f32) -> f32 { + if x.abs() < 1e-25 { 0.0 } else { x } + } + + #[test] + fn flush_is_unchanged_for_finite_values() { + let mut rng = Rng::new(21); + let mut xs = vec![0.0, -0.0, 1e-30, -1e-30, 1e-300, f64::MIN_POSITIVE, 5e-324, f64::MAX, f64::MIN, 1.0, -1.0]; + xs.extend([1e-30f64.next_down(), 1e-30f64.next_up(), (-1e-30f64).next_down(), (-1e-30f64).next_up()]); + for _ in 0..100_000 { + let m = rng.uniform() as f64; + let e = (rng.uniform() * 300.0) as i32; + xs.push(m * 10f64.powi(e)); + } + for &x in &xs { + assert_eq!(crate::flush(x).to_bits(), flush_reference(x).to_bits(), "{x:e}"); + let y = x as f32; + if y.is_finite() { + assert_eq!(crate::flush32(y).to_bits(), flush32_reference(y).to_bits(), "{y:e}"); + } + } + for y in [1e-25f32, 1e-25f32.next_down(), -1e-25f32, f32::MAX, f32::MIN, 1e-45] { + assert_eq!(crate::flush32(y).to_bits(), flush32_reference(y).to_bits(), "{y:e}"); + } + for x in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] { + assert_eq!(crate::flush(x), 0.0); + assert_eq!(crate::flush32(x as f32), 0.0); + } + } + + /// Run `tick` over noise with one non-finite sample at index 100 and return the output. + fn run_with_bad_sample(bad: f32, mut tick: impl FnMut(f32) -> f32) -> Vec { + let mut rng = Rng::new(4); + (0..4800) + .map(|i| { + let x = if i == 100 { bad } else { 0.5 * rng.uniform() }; + tick(x) + }) + .collect() + } + + #[test] + fn one_non_finite_sample_does_not_poison_filter_state() { + use crate::effects::util::{AllPass1, DcBlock, OnePole}; + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let c = Coeffs::design(FilterType::Peaking, SR, 1000.0, 1.0, 6.0); + let mut bq = Biquad::new(); + let mut lp = OnePole::default(); + let mut hp = OnePole::default(); + let a = OnePole::alpha(500.0, SR as f32); + let mut ap = AllPass1::default(); + let apc = AllPass1::coef(1000.0, SR as f32); + let mut dc = DcBlock::default(); + let r = DcBlock::r(SR as f32); + let outputs = [ + ("Biquad", run_with_bad_sample(bad, |x| bq.tick(&c, x as f64) as f32)), + ("OnePole lp", run_with_bad_sample(bad, |x| lp.lp(a, x))), + ("OnePole hp", run_with_bad_sample(bad, |x| hp.hp(a, x))), + ("AllPass1", run_with_bad_sample(bad, |x| ap.tick(apc, x as f64) as f32)), + ("DcBlock", run_with_bad_sample(bad, |x| dc.tick(r, x))), + ]; + for (name, y) in outputs { + assert!(y[..100].iter().all(|v| v.is_finite()), "{name} {bad}"); + assert!(y[102..].iter().all(|v| v.is_finite()), "{name} stays non-finite after {bad}"); + } + } + } + + #[test] + fn effects_recover_after_one_nan_sample() { + for id in ["parametric_eq", "simple_eq", "graphic_eq_10", "notch_filter"] { + let mut fx = crate::create_effect(id, SR as f32, 2).unwrap_or_else(|| panic!("{id}")); + for p in fx.params() { + if p.unit == crate::Unit::Decibels && p.id != "output" { + fx.set_param(p.id, 6.0); + } + } + let mut rng = Rng::new(8); + let mut l: Vec = (0..4800).map(|_| 0.5 * rng.uniform()).collect(); + let mut r: Vec = (0..4800).map(|_| 0.5 * rng.uniform()).collect(); + l[100] = f32::NAN; + fx.process(&mut [&mut l, &mut r]); + let mut l: Vec = (0..4800).map(|_| 0.5 * rng.uniform()).collect(); + let mut r: Vec = (0..4800).map(|_| 0.5 * rng.uniform()).collect(); + fx.process(&mut [&mut l, &mut r]); + assert!(l.iter().chain(&r).all(|v| v.is_finite()), "{id} stays NaN after one NaN input sample"); + } + } + + const RUN_LEN: usize = 2 * 48000; + + /// Parameter settings for the non-finite input sweeps. + #[derive(Clone, Copy, Debug)] + enum Setting { + Default, + /// Toggles on, last choice, other parameters at 37 % of their range. + Moved, + /// Toggles off, every other parameter at its minimum (e.g. no gate hold, multiband + /// bands neither bypassed nor linked). + Min, + } + + /// Process 2 s of noise in 512-sample blocks, with `bad` (if any) at input sample 1000 of + /// the left channel. Returns both output channels and the position of the bad sample's own + /// latency-delayed output. + fn run_effect(id: &str, setting: Setting, bad: Option) -> (Vec, Vec, usize) { + let mut fx = crate::create_effect(id, SR as f32, 2).unwrap_or_else(|| panic!("{id}")); + for p in fx.params() { + let v = match (setting, p.unit) { + (Setting::Default, _) => continue, + (Setting::Moved, crate::Unit::Toggle) => 1.0, + (Setting::Moved, crate::Unit::Choice) => p.max, + (Setting::Moved, _) => p.min + (p.max - p.min) * 0.37, + (Setting::Min, _) => p.min, + }; + fx.set_param(p.id, v); + } + run_fx(fx, bad) + } + + /// [`run_effect`] for an already configured effect. + fn run_fx(mut fx: Box, bad: Option) -> (Vec, Vec, usize) { + const BAD_AT: usize = 1000; + let mut rng = Rng::new(8); + let mut l: Vec = (0..RUN_LEN).map(|_| 0.5 * rng.uniform()).collect(); + let mut r: Vec = (0..RUN_LEN).map(|_| 0.5 * rng.uniform()).collect(); + if let Some(bad) = bad { + l[BAD_AT] = bad; + } + for (a, b) in l.chunks_mut(512).zip(r.chunks_mut(512)) { + fx.process(&mut [a, b]); + } + (l, r, BAD_AT + fx.latency()) + } + + /// Last output sample index (either channel) that is not finite, ignoring `own`. + fn last_non_finite_in(l: &[f32], r: &[f32], own: usize) -> Option { + l.iter().chain(r).enumerate().map(|(i, v)| (i % l.len(), v)).filter(|&(i, v)| i != own && !v.is_finite()).map(|(i, _)| i).max() + } + + /// RMS of the last 0.5 s of both channels. + fn tail_rms(l: &[f32], r: &[f32]) -> f64 { + let t = l.len() - 24000; + let s: f64 = l[t..].iter().chain(&r[t..]).map(|&v| (v as f64) * (v as f64)).sum(); + (s / 48000.0).sqrt() + } + + /// Every registered effect, at default, moved and minimum parameters, produces finite output + /// again within 0.5 s after one NaN, +inf or -inf input sample, and is not left muted: the + /// level of its last 0.5 s is at least half that of a run without the bad sample. + #[test] + fn every_effect_recovers_after_one_non_finite_sample() { + let mut failures = Vec::new(); + for e in crate::effects() { + for setting in [Setting::Default, Setting::Moved, Setting::Min] { + let (l, r, _) = run_effect(e.id, setting, None); + let clean = tail_rms(&l, &r); + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let (l, r, own) = run_effect(e.id, setting, Some(bad)); + let last = last_non_finite_in(&l, &r, own); + if last.is_some_and(|i| i >= own + 24000) { + failures.push(format!("{} ({setting:?}) still non-finite at sample {last:?} after {bad}", e.id)); + } + let level = tail_rms(&l, &r); + if level < 0.5 * clean { + failures.push(format!("{} ({setting:?}) level {level:e} after {bad}, {clean:e} without", e.id)); + } + } + } + } + assert!(failures.is_empty(), "{failures:#?}"); + } + + /// Effects whose state is cleaned outside `flush` recover from NaN and ±inf within two blocks. + #[test] + fn phaser_click_remover_binauralizer_recover_from_non_finite_input() { + for id in ["phaser", "click_remover", "binauralizer"] { + for setting in [Setting::Default, Setting::Moved] { + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let (l, r, own) = run_effect(id, setting, Some(bad)); + let last = last_non_finite_in(&l, &r, own); + assert!(last.is_none_or(|i| i < own + 1024), "{id} ({setting:?}) still non-finite at sample {last:?} after {bad}"); + } + } + } + } + + /// With the loudness maximiser on and the exciter off (which the sweep's settings do not + /// combine), an inf sample used to hold the limiter envelope at -inf dB: silence for good. + #[test] + fn mastering_limiter_recovers_from_inf() { + let make = || { + let mut fx = crate::create_effect("mastering", SR as f32, 2).unwrap(); + fx.set_param("loudness", 50.0); + fx + }; + let (l, r, _) = run_fx(make(), None); + let clean = tail_rms(&l, &r); + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let (l, r, own) = run_fx(make(), Some(bad)); + let last = last_non_finite_in(&l, &r, own); + assert!(last.is_none_or(|i| i < own + 1024), "still non-finite at sample {last:?} after {bad}"); + assert!(tail_rms(&l, &r) >= 0.5 * clean, "level {:e} after {bad}, {clean:e} without", tail_rms(&l, &r)); + } + } + + /// A NaN written to any parameter of any effect never reaches the output (`set_param` ignores NaN). + #[test] + fn nan_parameter_values_never_produce_non_finite_output() { + let mut bad = Vec::new(); + for e in crate::effects() { + let ids: Vec<&str> = crate::create_effect(e.id, SR as f32, 2).unwrap().params().iter().map(|p| p.id).collect(); + for id in ids { + let mut fx = crate::create_effect(e.id, SR as f32, 2).unwrap(); + fx.set_param(id, f32::NAN); + let (l, r, _) = run_fx(fx, None); + if l.iter().chain(&r).any(|v| !v.is_finite()) { + bad.push(format!("{}.{id}", e.id)); + } + } + } + assert!(bad.is_empty(), "{bad:?}"); + } + + /// Subnormal input samples (a decoder or a fade-out can deliver them) never make an effect + /// produce non-finite output, and once the input is silent again no effect keeps emitting + /// subnormals in its last 0.5 s. + #[test] + fn subnormal_input_stays_finite_and_decays() { + let mut bad = Vec::new(); + for e in crate::effects() { + for setting in [Setting::Default, Setting::Min] { + let mut fx = crate::create_effect(e.id, SR as f32, 2).unwrap(); + for p in fx.params() { + if let Setting::Min = setting { + fx.set_param(p.id, p.min); + } + } + let mut rng = Rng::new(5); + let (mut l, mut r) = (vec![0.0f32; RUN_LEN], vec![0.0f32; RUN_LEN]); + for (a, b) in l.iter_mut().zip(r.iter_mut()).take(RUN_LEN / 2) { + *a = 1e-40 * rng.uniform(); + *b = -1e-41 * rng.uniform(); + } + for (a, b) in l.chunks_mut(512).zip(r.chunks_mut(512)) { + fx.process(&mut [a, b]); + } + let t = RUN_LEN - 24000; + if l.iter().chain(&r).any(|v| !v.is_finite()) || l[t..].iter().chain(&r[t..]).any(|v| v.is_subnormal()) { + bad.push(format!("{} ({setting:?})", e.id)); + } + } + } + assert!(bad.is_empty(), "{bad:?}"); + } +} diff --git a/crates/audio-dsp/src/channels.rs b/crates/audio-dsp/src/channels.rs new file mode 100644 index 000000000..1db0c09a0 --- /dev/null +++ b/crates/audio-dsp/src/channels.rs @@ -0,0 +1,451 @@ +//! Channel layouts, format conversion (up/downmix) and the 5.1 surround panner. +//! +//! **Channel order.** 5.1 audio is always in the SMPTE / WAVE order **L, R, C, LFE, Ls, Rs** +//! ([`L`], [`R`], [`C`], [`LFE`], [`LS`], [`RS`]); stereo is L, R; mono is one channel. Codecs with a +//! different native order (AAC: C, L, R, Ls, Rs, LFE) reorder at the codec boundary. +//! +//! **Downmix** follows ITU-R BS.775 (Table 2, "3/2 source" rows), with `k = 1/√2` (−3 dB): +//! +//! | from → to | equations | +//! |---|---| +//! | 5.1 → 2.0 | `Lo = L + k·C + k·Ls`, `Ro = R + k·C + k·Rs` (LFE omitted) | +//! | 5.1 → 1.0 | `M = k·L + k·R + C + ½·Ls + ½·Rs` | +//! | 2.0 → 1.0 | `M = k·L + k·R` | +//! +//! The stereo downmix used for playback on stereo devices can be changed by the "5.1 Mixdown Type" +//! preference ([`Mixdown`]): Front Only drops the surrounds, the `+ LFE` variants add `k·LFE` to +//! both sides. +//! +//! **Upmix** places the source on the front speakers without inventing content: mono → C (5.1) or +//! both sides at unity (2.0); stereo → L, R. +//! +//! **5.1 panner** ([`Pan51`]): a puck at `(x, y)` in the listening square (x −1 left … +1 right, +//! y −1 rear … +1 front). A point source at `(x, y)` is split front/rear and left/right with the +//! sine/cosine constant-power law, and the front image is shared between the phantom L/R pair and +//! the center speaker by **Center %** (`k_c = center · (1 − |x|)` of the front power goes to C). The +//! gains of a point source always have unit power (`Σ g² = 1`). Multichannel sources keep their +//! layout around the puck: each source channel sits at its nominal speaker position moved by the +//! puck's offset from front-center (so the default puck (0, 1) at 100 % center maps 5.1 to itself +//! exactly). Stereo sources sit at the puck ± 1 in x. The LFE output is the source LFE (5.1) or +//! the mean of the source channels (mono/stereo) times the **LFE** gain. + +use std::f32::consts::{FRAC_1_SQRT_2, FRAC_PI_2, FRAC_PI_4}; + +/// −3 dB, the BS.775 downmix coefficient. +pub const K: f32 = FRAC_1_SQRT_2; + +/// 5.1 channel indices (SMPTE / WAVE order). +pub const L: usize = 0; +pub const R: usize = 1; +pub const C: usize = 2; +pub const LFE: usize = 3; +pub const LS: usize = 4; +pub const RS: usize = 5; + +/// Short names of the 5.1 channels in order. +pub const NAMES_51: [&str; 6] = ["L", "R", "C", "LFE", "Ls", "Rs"]; + +/// A channel layout. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum Layout { + Mono, + #[default] + Stereo, + /// 5.1 in L, R, C, LFE, Ls, Rs order. + Surround51, +} + +impl Layout { + pub fn channels(self) -> usize { + match self { + Layout::Mono => 1, + Layout::Stereo => 2, + Layout::Surround51 => 6, + } + } + /// The layout of a plain channel count (1, 2 or 6; anything else is treated as stereo). + pub fn from_channels(n: usize) -> Layout { + match n { + 1 => Layout::Mono, + 6 => Layout::Surround51, + _ => Layout::Stereo, + } + } + /// Channel names for display ("L", "R" …). + pub fn names(self) -> &'static [&'static str] { + match self { + Layout::Mono => &["M"], + Layout::Stereo => &["L", "R"], + Layout::Surround51 => &NAMES_51, + } + } +} + +/// How 5.1 is folded to stereo for playback. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum Mixdown { + /// L, R and C only. + Front, + /// L, R, C and the surrounds (ITU-R BS.775). + #[default] + FrontRear, + /// L, R, C and LFE. + FrontLfe, + /// Everything. + FrontRearLfe, +} + +impl Mixdown { + pub const ALL: [Mixdown; 4] = [Mixdown::Front, Mixdown::FrontRear, Mixdown::FrontLfe, Mixdown::FrontRearLfe]; + /// Preference value (`front`, `frontRear`, `frontLfe`, `frontRearLfe`). + pub fn id(self) -> &'static str { + match self { + Mixdown::Front => "front", + Mixdown::FrontRear => "frontRear", + Mixdown::FrontLfe => "frontLfe", + Mixdown::FrontRearLfe => "frontRearLfe", + } + } + pub fn from_id(s: &str) -> Option { + Self::ALL.into_iter().find(|m| m.id().eq_ignore_ascii_case(s)) + } + fn rear(self) -> bool { + matches!(self, Mixdown::FrontRear | Mixdown::FrontRearLfe) + } + fn lfe(self) -> bool { + matches!(self, Mixdown::FrontLfe | Mixdown::FrontRearLfe) + } +} + +/// Conversion matrix `m[out][in]` from `from` to `to`. Stereo downmixes of 5.1 use `mixdown` +/// ([`Mixdown::FrontRear`] is BS.775). +pub fn matrix(from: Layout, to: Layout, mixdown: Mixdown) -> Vec> { + let (ni, no) = (from.channels(), to.channels()); + let mut m = vec![vec![0.0f32; ni]; no]; + match (from, to) { + (Layout::Mono, Layout::Mono) | (Layout::Stereo, Layout::Stereo) | (Layout::Surround51, Layout::Surround51) => { + for (i, row) in m.iter_mut().enumerate() { + row[i] = 1.0; + } + } + (Layout::Mono, Layout::Stereo) => { + m[0][0] = 1.0; + m[1][0] = 1.0; + } + (Layout::Mono, Layout::Surround51) => m[C][0] = 1.0, + (Layout::Stereo, Layout::Mono) => m[0] = vec![K, K], + (Layout::Stereo, Layout::Surround51) => { + m[L][0] = 1.0; + m[R][1] = 1.0; + } + (Layout::Surround51, Layout::Mono) => { + m[0][L] = K; + m[0][R] = K; + m[0][C] = 1.0; + m[0][LS] = 0.5; + m[0][RS] = 0.5; + } + (Layout::Surround51, Layout::Stereo) => { + m[0][L] = 1.0; + m[1][R] = 1.0; + m[0][C] = K; + m[1][C] = K; + if mixdown.rear() { + m[0][LS] = K; + m[1][RS] = K; + } + if mixdown.lfe() { + m[0][LFE] = K; + m[1][LFE] = K; + } + } + } + m +} + +/// Apply a matrix `m[out][in]` to planar `input` (all channels the same length). +pub fn apply_matrix(m: &[Vec], input: &[&[f32]]) -> Vec> { + let n = input.first().map_or(0, |c| c.len()); + m.iter() + .map(|row| { + let mut out = vec![0.0f32; n]; + for (g, x) in row.iter().zip(input) { + if *g == 0.0 { + continue; + } + for (o, s) in out.iter_mut().zip(x.iter()) { + *o += g * s; + } + } + out + }) + .collect() +} + +/// Convert planar audio from one layout to another ([`matrix`]). +pub fn convert(input: &[&[f32]], from: Layout, to: Layout, mixdown: Mixdown) -> Vec> { + if from == to { + return input.iter().map(|c| c.to_vec()).collect(); + } + apply_matrix(&matrix(from, to, mixdown), input) +} + +/// Convert owned planar audio whose layout is given by its channel count. +pub fn convert_owned(input: Vec>, to: Layout, mixdown: Mixdown) -> Vec> { + let from = Layout::from_channels(input.len()); + if from == to && input.len() == to.channels() { + return input; + } + let refs: Vec<&[f32]> = input.iter().map(Vec::as_slice).collect(); + if input.len() != from.channels() { + // unusual channel counts: take the first channels that fit, pad with silence + let n = input.first().map_or(0, Vec::len); + let mut v: Vec> = input.iter().take(to.channels()).cloned().collect(); + v.resize(to.channels(), vec![0.0; n]); + return v; + } + convert(&refs, from, to, mixdown) +} + +// ------------------------------------------------------------------------------------- 5.1 panner + +/// The 5.1 panner of a track or send feeding a 5.1 bus. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Pan51 { + /// −1 (left) … +1 (right). + pub x: f32, + /// −1 (rear) … +1 (front). + pub y: f32, + /// Center %: 0 … 1, the share of the front image the center speaker takes at x = 0. + pub center: f32, + /// LFE gain (linear). + pub lfe: f32, +} + +impl Default for Pan51 { + /// Front center, 100 % center, LFE at unity. + fn default() -> Self { + Pan51 { x: 0.0, y: 1.0, center: 1.0, lfe: 1.0 } + } +} + +/// `v`, or `default` when `v` is not finite. +fn finite_or(v: f32, default: f32) -> f32 { + if v.is_finite() { v } else { default } +} + +/// Gains of a point source at `(x, y)` to the six 5.1 outputs (LFE is 0). `Σ g² = 1`. A +/// non-finite `x`, `y` or `center` reads as the default position: front center, 100 % center. +pub fn point_gains(x: f32, y: f32, center: f32) -> [f32; 6] { + let (x, y, center) = (finite_or(x, 0.0), finite_or(y, 1.0), finite_or(center, 1.0)); + let x = x.clamp(-1.0, 1.0); + let y = y.clamp(-1.0, 1.0); + let fb = (1.0 - y) * 0.5 * FRAC_PI_2; + let (f, b) = (fb.cos(), fb.sin()); + let lr = (x + 1.0) * FRAC_PI_4; + let (gl, gr) = (lr.cos(), lr.sin()); + let kc = (center.clamp(0.0, 1.0) * (1.0 - x.abs())).clamp(0.0, 1.0); + let ph = (1.0 - kc).sqrt(); + let mut g = [0.0f32; 6]; + g[L] = f * ph * gl; + g[R] = f * ph * gr; + g[C] = f * kc.sqrt(); + g[LS] = b * gl; + g[RS] = b * gr; + // f32 sin/cos at the quadrant ends are not exactly 0 / 1: snap them so speaker positions + // route bit-exactly (a 5.1 source through the default panner is the identity) + for v in g.iter_mut() { + if v.abs() < 1e-6 { + *v = 0.0; + } else if (*v - 1.0).abs() < 1e-6 { + *v = 1.0; + } + } + g +} + +/// Nominal source-channel positions relative to the puck's offset from front-center. +fn offsets(from: Layout) -> &'static [(f32, f32)] { + match from { + Layout::Mono => &[(0.0, 0.0)], + Layout::Stereo => &[(-1.0, 0.0), (1.0, 0.0)], + // L, R, C, LFE (not positioned), Ls, Rs + Layout::Surround51 => &[(-1.0, 0.0), (1.0, 0.0), (0.0, 0.0), (0.0, 0.0), (-1.0, -2.0), (1.0, -2.0)], + } +} + +/// Panning matrix `m[out][in]` (6 outputs) of a `from` source through the 5.1 panner. A +/// non-finite field of `p` reads as its [`Pan51::default`] value. +pub fn pan51_matrix(from: Layout, p: Pan51) -> Vec> { + let d = Pan51::default(); + let p = Pan51 { x: finite_or(p.x, d.x), y: finite_or(p.y, d.y), center: finite_or(p.center, d.center), lfe: finite_or(p.lfe, d.lfe) }; + let ni = from.channels(); + let mut m = vec![vec![0.0f32; ni]; 6]; + for (i, (ox, oy)) in offsets(from).iter().enumerate() { + if from == Layout::Surround51 && i == LFE { + m[LFE][i] = p.lfe; + continue; + } + let g = point_gains(p.x + ox, p.y + oy, p.center); + for (o, row) in m.iter_mut().enumerate() { + row[i] = g[o]; + } + if from != Layout::Surround51 { + m[LFE][i] = p.lfe / ni as f32; + } + } + m +} + +/// Peak level (linear) per channel. +pub fn peaks(input: &[&[f32]]) -> Vec { + input.iter().map(|c| c.iter().fold(0f32, |a, x| a.max(x.abs()))).collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + fn close(a: f32, b: f32) -> bool { + (a - b).abs() < 1e-6 + } + + #[test] + fn bs775_downmix_coefficients_are_exact() { + let k = std::f32::consts::FRAC_1_SQRT_2; + // 5.1 → 2.0 (L, R, C, LFE, Ls, Rs) + let m = matrix(Layout::Surround51, Layout::Stereo, Mixdown::FrontRear); + assert_eq!(m[0], vec![1.0, 0.0, k, 0.0, k, 0.0]); + assert_eq!(m[1], vec![0.0, 1.0, k, 0.0, 0.0, k]); + // 5.1 → 1.0 + let m = matrix(Layout::Surround51, Layout::Mono, Mixdown::FrontRear); + assert_eq!(m[0], vec![k, k, 1.0, 0.0, 0.5, 0.5]); + // 2.0 → 1.0 + assert_eq!(matrix(Layout::Stereo, Layout::Mono, Mixdown::FrontRear)[0], vec![k, k]); + // mixdown types + let f = matrix(Layout::Surround51, Layout::Stereo, Mixdown::Front); + assert_eq!(f[0], vec![1.0, 0.0, k, 0.0, 0.0, 0.0]); + let fl = matrix(Layout::Surround51, Layout::Stereo, Mixdown::FrontLfe); + assert_eq!(fl[1], vec![0.0, 1.0, k, k, 0.0, 0.0]); + let all = matrix(Layout::Surround51, Layout::Stereo, Mixdown::FrontRearLfe); + assert_eq!(all[0], vec![1.0, 0.0, k, k, k, 0.0]); + assert_eq!(Mixdown::from_id("frontRearLfe"), Some(Mixdown::FrontRearLfe)); + assert_eq!(Mixdown::default().id(), "frontRear"); + } + + #[test] + fn upmix_places_on_front_speakers() { + assert_eq!( + matrix(Layout::Mono, Layout::Surround51, Mixdown::FrontRear), + vec![vec![0.0], vec![0.0], vec![1.0], vec![0.0], vec![0.0], vec![0.0]] + ); + let s = matrix(Layout::Stereo, Layout::Surround51, Mixdown::FrontRear); + assert_eq!(s[L], vec![1.0, 0.0]); + assert_eq!(s[R], vec![0.0, 1.0]); + assert!(s[C..].iter().all(|r| r.iter().all(|g| *g == 0.0))); + assert_eq!(matrix(Layout::Mono, Layout::Stereo, Mixdown::FrontRear), vec![vec![1.0], vec![1.0]]); + // identity + for l in [Layout::Mono, Layout::Stereo, Layout::Surround51] { + let m = matrix(l, l, Mixdown::Front); + for (o, row) in m.iter().enumerate() { + for (i, g) in row.iter().enumerate() { + assert_eq!(*g, if o == i { 1.0 } else { 0.0 }); + } + } + } + } + + #[test] + fn convert_applies_the_matrix_per_sample() { + let ch: Vec> = (0..6).map(|c| vec![(c + 1) as f32 * 0.1; 4]).collect(); + let refs: Vec<&[f32]> = ch.iter().map(Vec::as_slice).collect(); + let st = convert(&refs, Layout::Surround51, Layout::Stereo, Mixdown::FrontRear); + let k = K; + assert!(close(st[0][3], 0.1 + k * 0.3 + k * 0.5)); + assert!(close(st[1][0], 0.2 + k * 0.3 + k * 0.6)); + let back = convert_owned(st.clone(), Layout::Stereo, Mixdown::FrontRear); + assert_eq!(back, st); + let up = convert_owned(vec![vec![0.5; 3]], Layout::Surround51, Mixdown::FrontRear); + assert_eq!(up.len(), 6); + assert_eq!(up[C], vec![0.5; 3]); + assert_eq!(up[L], vec![0.0; 3]); + } + + #[test] + fn panner_point_gains_are_equal_power() { + for xi in -10..=10 { + for yi in -10..=10 { + for c in [0.0, 0.3, 1.0] { + let g = point_gains(xi as f32 / 10.0, yi as f32 / 10.0, c); + let p: f32 = g.iter().map(|v| v * v).sum(); + assert!((p - 1.0).abs() < 1e-5, "({xi}, {yi}, {c}) power {p}"); + assert_eq!(g[LFE], 0.0); + assert!(g.iter().all(|v| *v >= -1e-7)); + } + } + } + let k = K; + // speaker positions + let at = |x, y, c| point_gains(x, y, c); + assert!(close(at(0.0, 1.0, 1.0)[C], 1.0)); + assert!(close(at(-1.0, 1.0, 1.0)[L], 1.0)); + assert!(close(at(1.0, 1.0, 0.5)[R], 1.0)); + assert!(close(at(-1.0, -1.0, 1.0)[LS], 1.0)); + assert!(close(at(1.0, -1.0, 1.0)[RS], 1.0)); + // phantom center at 0 % center: −3 dB each side + let g = at(0.0, 1.0, 0.0); + assert!(close(g[L], k) && close(g[R], k) && g[C] == 0.0); + // room center: −3 dB front/rear, then −3 dB left/right + let g = at(0.0, 0.0, 0.0); + assert!(close(g[L], 0.5) && close(g[R], 0.5) && close(g[LS], 0.5) && close(g[RS], 0.5)); + // 50 % center at front center: half the power to C + let g = at(0.0, 1.0, 0.5); + assert!(close(g[C] * g[C], 0.5) && close(g[L] * g[L] + g[R] * g[R], 0.5)); + } + + #[test] + fn panner_matrices() { + // 5.1 through the default panner is the identity + let m = pan51_matrix(Layout::Surround51, Pan51::default()); + for (o, row) in m.iter().enumerate() { + for (i, g) in row.iter().enumerate() { + assert!(close(*g, if o == i { 1.0 } else { 0.0 }), "out {o} in {i} = {g}"); + } + } + // stereo at front center: L → L, R → R + let m = pan51_matrix(Layout::Stereo, Pan51 { lfe: 0.0, ..Pan51::default() }); + assert!(close(m[L][0], 1.0) && close(m[R][1], 1.0) && m[C][0].abs() < 1e-6 && m[LFE][0] == 0.0); + // mono at the default puck: center only; LFE gain = mean of inputs + let m = pan51_matrix(Layout::Mono, Pan51 { lfe: 0.5, ..Pan51::default() }); + assert!(close(m[C][0], 1.0) && close(m[LFE][0], 0.5)); + let m = pan51_matrix(Layout::Stereo, Pan51 { lfe: 0.5, ..Pan51::default() }); + assert!(close(m[LFE][0], 0.25) && close(m[LFE][1], 0.25)); + // every source channel keeps unit power (LFE aside) + for l in [Layout::Mono, Layout::Stereo, Layout::Surround51] { + let p = Pan51 { x: 0.37, y: -0.21, center: 0.6, lfe: 0.0 }; + let m = pan51_matrix(l, p); + for i in 0..l.channels() { + if l == Layout::Surround51 && i == LFE { + continue; + } + let pw: f32 = (0..6).map(|o| m[o][i] * m[o][i]).sum(); + assert!((pw - 1.0).abs() < 1e-5); + } + } + // puck hard rear-left: 5.1 front channels collapse towards the rear left + let m = pan51_matrix(Layout::Surround51, Pan51 { x: -1.0, y: -1.0, center: 1.0, lfe: 1.0 }); + assert!(close(m[LS][L], 1.0) && close(m[LS][C], 1.0) && close(m[LS][LS], 1.0)); + } + + #[test] + fn non_finite_pan_values_read_as_the_default() { + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let p = Pan51 { x: bad, y: bad, center: bad, lfe: bad }; + for from in [Layout::Mono, Layout::Stereo, Layout::Surround51] { + let m = pan51_matrix(from, p); + assert_eq!(m, pan51_matrix(from, Pan51::default()), "{bad} from {from:?}"); + } + assert_eq!(point_gains(bad, bad, bad), point_gains(0.0, 1.0, 1.0)); + } + } +} diff --git a/crates/audio-dsp/src/design.rs b/crates/audio-dsp/src/design.rs new file mode 100644 index 000000000..afc6176a1 --- /dev/null +++ b/crates/audio-dsp/src/design.rs @@ -0,0 +1,773 @@ +//! IIR filter design from classical analog prototypes (Scientific Filter). +//! +//! Textbook method: a normalized low-pass prototype (zeros, poles, gain) is transformed to +//! low-pass / high-pass / band-pass / band-stop at pre-warped analog frequencies, mapped to +//! the z-plane with the bilinear transform and factored into second-order sections. The +//! prototypes are Butterworth, Bessel (roots of the reverse Bessel polynomial, normalized to +//! −3 dB at Ω = 1), Chebyshev type I and elliptic (Cauer; Landen-transformation formulation of +//! the Jacobi elliptic functions, after S. J. Orfanidis, *Lecture Notes on Elliptic Filter +//! Design*, 2006). +//! +//! Everything works on fixed-size arrays so a design never allocates (it runs from +//! `set_param` on the audio thread). + +use crate::biquad::Coeffs; +use std::f64::consts::PI; +use std::ops::{Add, Div, Mul, Neg, Sub}; + +/// Highest prototype order. +pub const MAX_ORDER: usize = 12; +/// Most second-order sections a design produces (band-pass/stop double the order). +pub const MAX_SECTIONS: usize = MAX_ORDER; +const MAX_ROOTS: usize = 2 * MAX_ORDER; + +/// Minimal complex number. +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct C { + pub re: f64, + pub im: f64, +} + +impl C { + pub const fn new(re: f64, im: f64) -> C { + C { re, im } + } + pub const fn real(re: f64) -> C { + C { re, im: 0.0 } + } + pub fn scale(self, s: f64) -> C { + C::new(self.re * s, self.im * s) + } + pub fn conj(self) -> C { + C::new(self.re, -self.im) + } + pub fn abs(self) -> f64 { + self.re.hypot(self.im) + } + pub fn sqrt(self) -> C { + let r = self.abs(); + let re = ((r + self.re) * 0.5).max(0.0).sqrt(); + let im = ((r - self.re) * 0.5).max(0.0).sqrt(); + C::new(re, if self.im < 0.0 { -im } else { im }) + } + pub fn exp(self) -> C { + let e = self.re.exp(); + C::new(e * self.im.cos(), e * self.im.sin()) + } + pub fn ln(self) -> C { + C::new(self.abs().ln(), self.im.atan2(self.re)) + } + pub fn cos(self) -> C { + C::new(self.re.cos() * self.im.cosh(), -self.re.sin() * self.im.sinh()) + } + pub fn sin(self) -> C { + C::new(self.re.sin() * self.im.cosh(), self.re.cos() * self.im.sinh()) + } + /// acos(w) = −j·ln(w + j·√(1 − w²)). + pub fn acos(self) -> C { + let one = C::real(1.0); + let s = one.sub(self.mul(self)).sqrt(); + let v = self.add(C::new(-s.im, s.re)).ln(); + C::new(v.im, -v.re) + } +} + +impl Add for C { + type Output = C; + fn add(self, o: C) -> C { + C::new(self.re + o.re, self.im + o.im) + } +} + +impl Sub for C { + type Output = C; + fn sub(self, o: C) -> C { + C::new(self.re - o.re, self.im - o.im) + } +} + +impl Mul for C { + type Output = C; + fn mul(self, o: C) -> C { + C::new(self.re * o.re - self.im * o.im, self.re * o.im + self.im * o.re) + } +} + +impl Div for C { + type Output = C; + fn div(self, o: C) -> C { + let d = o.re * o.re + o.im * o.im; + C::new((self.re * o.re + self.im * o.im) / d, (self.im * o.re - self.re * o.im) / d) + } +} + +impl Neg for C { + type Output = C; + fn neg(self) -> C { + C::new(-self.re, -self.im) + } +} + +/// Fixed-capacity root list. +#[derive(Clone, Copy, Debug)] +struct Roots { + v: [C; MAX_ROOTS], + n: usize, +} + +impl Roots { + const fn new() -> Roots { + Roots { v: [C { re: 0.0, im: 0.0 }; MAX_ROOTS], n: 0 } + } + fn push(&mut self, c: C) { + if self.n < MAX_ROOTS { + self.v[self.n] = c; + self.n += 1; + } + } + fn as_slice(&self) -> &[C] { + &self.v[..self.n] + } + fn prod_neg(&self) -> C { + self.as_slice().iter().fold(C::real(1.0), |a, &r| a.mul(r.neg())) + } +} + +/// Analog zeros/poles/gain. +#[derive(Clone, Copy, Debug)] +struct Zpk { + z: Roots, + p: Roots, + k: f64, +} + +/// Prototype family. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Family { + Bessel, + Butterworth, + Chebyshev, + Elliptic, +} + +/// Response type. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Band { + LowPass, + HighPass, + BandPass, + BandStop, +} + +/// A cascade of second-order sections. +#[derive(Clone, Copy, Debug)] +pub struct Sections { + pub c: [Coeffs; MAX_SECTIONS], + pub n: usize, +} + +impl Sections { + pub fn as_slice(&self) -> &[Coeffs] { + &self.c[..self.n] + } + /// Magnitude of the cascade in dB. + pub fn magnitude_db(&self, freq: f64, sample_rate: f64) -> f64 { + self.as_slice().iter().map(|c| c.magnitude_db(freq, sample_rate)).sum() + } +} + +// ------------------------------------------------------------------------------- prototypes + +fn butterworth(n: usize) -> Zpk { + let mut p = Roots::new(); + for k in 0..n { + let a = PI * (2 * k + n + 1) as f64 / (2 * n) as f64; + p.push(C::new(a.cos(), a.sin())); + } + Zpk { z: Roots::new(), p, k: 1.0 } +} + +fn chebyshev1(n: usize, rp: f64) -> Zpk { + let eps = (10f64.powf(rp / 10.0) - 1.0).sqrt(); + let mu = (1.0 / eps).asinh() / n as f64; + let mut p = Roots::new(); + for k in 0..n { + let th = PI * (2 * k + 1) as f64 / (2 * n) as f64; + p.push(C::new(-mu.sinh() * th.sin(), mu.cosh() * th.cos())); + } + let mut k = p.prod_neg().re; + if n.is_multiple_of(2) { + k /= (1.0 + eps * eps).sqrt(); + } + Zpk { z: Roots::new(), p, k } +} + +/// Roots of a monic polynomial (`c[i]` = coefficient of sⁱ, `c[n]` = 1) by Durand–Kerner. +fn poly_roots(c: &[f64], out: &mut Roots) { + let n = c.len() - 1; + let eval = |s: C| -> C { + let mut acc = C::real(c[n]); + for i in (0..n).rev() { + acc = acc.mul(s).add(C::real(c[i])); + } + acc + }; + // Initial guesses on a circle of the Cauchy-bound radius. + let radius = 1.0 + c[..n].iter().fold(0.0f64, |m, v| m.max(v.abs())).powf(1.0 / n as f64); + let mut r = [C::default(); MAX_ROOTS]; + for (i, ri) in r.iter_mut().enumerate().take(n) { + let a = 2.0 * PI * i as f64 / n as f64 + 0.4; + *ri = C::new(radius * a.cos(), radius * a.sin()); + } + for _ in 0..500 { + let mut delta = 0.0f64; + for i in 0..n { + let mut den = C::real(1.0); + for j in 0..n { + if j != i { + den = den.mul(r[i].sub(r[j])); + } + } + let step = eval(r[i]).div(den); + r[i] = r[i].sub(step); + delta = delta.max(step.abs()); + } + if delta < 1e-14 { + break; + } + } + out.n = 0; + for &ri in r.iter().take(n) { + out.push(ri); + } +} + +fn bessel(n: usize) -> Zpk { + // Reverse Bessel polynomial: a_k = (2n − k)! / (2^(n−k) k! (n − k)!), monic (a_n = 1). + let mut c = [0.0f64; MAX_ORDER + 1]; + let fact = |m: usize| -> f64 { (1..=m).fold(1.0, |a, v| a * v as f64) }; + for (k, ck) in c.iter_mut().enumerate().take(n + 1) { + *ck = fact(2 * n - k) / (2f64.powi((n - k) as i32) * fact(k) * fact(n - k)); + } + let mut p = Roots::new(); + poly_roots(&c[..=n], &mut p); + // H(s) = a0 / θ(s); find Ω where |H(jΩ)| = 1/√2 and normalize it to 1. + let a0 = c[0]; + let mag = |w: f64| -> f64 { + let s = C::new(0.0, w); + p.as_slice().iter().fold(C::real(1.0), |acc, &r| acc.mul(s.sub(r))).abs().recip() * a0 + }; + let (mut lo, mut hi) = (1e-3f64, 100.0f64); + for _ in 0..200 { + let mid = (lo * hi).sqrt(); + if mag(mid) > std::f64::consts::FRAC_1_SQRT_2 { lo = mid } else { hi = mid } + } + let w3 = (lo * hi).sqrt(); + for r in &mut p.v[..p.n] { + *r = r.scale(1.0 / w3); + } + let k = p.prod_neg().re; + Zpk { z: Roots::new(), p, k } +} + +// ---- Jacobi elliptic functions via Landen transformations (normalized argument u·K). + +const LANDEN_STEPS: usize = 10; + +/// Descending Landen sequence of moduli. +fn landen(k: f64) -> ([f64; LANDEN_STEPS], usize) { + let mut v = [0.0; LANDEN_STEPS]; + let mut n = 0; + let mut k = k; + while n < LANDEN_STEPS && k > 1e-16 { + k = (k / (1.0 + (1.0 - k * k).max(0.0).sqrt())).powi(2); + v[n] = k; + n += 1; + } + (v, n) +} + +/// Complete elliptic integral K(k). +#[cfg(test)] +fn ellip_k(k: f64) -> f64 { + if k >= 1.0 { + return f64::INFINITY; + } + let (v, n) = landen(k); + v[..n].iter().fold(PI / 2.0, |a, &vi| a * (1.0 + vi)) +} + +/// cd(u·K, k) for complex normalized u. +fn cde(u: C, k: f64) -> C { + let (v, n) = landen(k); + let mut w = u.scale(PI / 2.0).cos(); + for &vi in v[..n].iter().rev() { + w = w.scale(1.0 + vi).div(C::real(1.0).add(w.mul(w).scale(vi))); + } + w +} + +/// sn(u·K, k) for complex normalized u. +fn sne(u: C, k: f64) -> C { + let (v, n) = landen(k); + let mut w = u.scale(PI / 2.0).sin(); + for &vi in v[..n].iter().rev() { + w = w.scale(1.0 + vi).div(C::real(1.0).add(w.mul(w).scale(vi))); + } + w +} + +/// Inverse of [`cde`]: normalized u with cd(u·K, k) = w. +fn acde(w: C, k: f64) -> C { + let (v, n) = landen(k); + let mut w = w; + for i in 0..n { + let v1 = if i == 0 { k } else { v[i - 1] }; + let s = C::real(1.0).sub(w.mul(w).scale(v1 * v1)).sqrt(); + w = w.div(C::real(1.0).add(s)).scale(2.0 / (1.0 + v[i])); + } + w.acos().scale(2.0 / PI) +} + +/// Inverse of [`sne`]: sn(uK) = cd((1 − u)K). +fn asne(w: C, k: f64) -> C { + C::real(1.0).sub(acde(w, k)) +} + +fn elliptic(n: usize, rp: f64, rs: f64) -> Zpk { + let ep = (10f64.powf(rp / 10.0) - 1.0).sqrt(); + let es = (10f64.powf(rs / 10.0) - 1.0).sqrt(); + let k1 = ep / es; + let k1p = (1.0 - k1 * k1).sqrt(); + let l = n / 2; + // Degree equation: k' = k1'^N · Π sn⁴(u_i K', k1'). + let mut kp = k1p.powi(n as i32); + for i in 1..=l { + let ui = (2 * i - 1) as f64 / n as f64; + kp *= sne(C::real(ui), k1p).re.powi(4); + } + let k = (1.0 - kp * kp).max(0.0).sqrt(); + // v0 = −j·asn(j/εp, k1) / N (normalized). + let a = asne(C::new(0.0, 1.0 / ep), k1); + let v0 = C::new(a.im, -a.re).scale(1.0 / n as f64); // −j·a/N + let mut z = Roots::new(); + let mut p = Roots::new(); + for i in 1..=l { + let ui = (2 * i - 1) as f64 / n as f64; + let zeta = cde(C::real(ui), k); + let zi = C::new(0.0, 1.0).div(zeta.scale(k)); + z.push(zi); + z.push(zi.conj()); + // p_i = j·cd((u_i − j v0)K, k) + let arg = C::real(ui).sub(C::new(0.0, 1.0).mul(v0)); + let c = cde(arg, k); + let pi = C::new(-c.im, c.re); + p.push(pi); + p.push(pi.conj()); + } + if n % 2 == 1 { + // p0 = j·sn(j v0 K, k) + let s = sne(C::new(0.0, 1.0).mul(v0), k); + p.push(C::new(-s.im, s.re)); + // the result is real (negative); drop the numerical imaginary residue + let last = p.n - 1; + p.v[last].im = 0.0; + p.v[last].re = -p.v[last].re.abs(); + } + // Make sure all poles are in the left half plane. + for r in &mut p.v[..p.n] { + if r.re > 0.0 { + r.re = -r.re; + } + } + // Gain: H(0) = 1 (odd N) or 1/√(1+εp²) (even N). + let h0 = if n % 2 == 1 { 1.0 } else { 1.0 / (1.0 + ep * ep).sqrt() }; + let num = z.prod_neg(); + let den = p.prod_neg(); + let k = h0 * den.div(num).re; + Zpk { z, p, k } +} + +// ---------------------------------------------------------------------------- transforms + +fn lp_to_lp(f: &mut Zpk, wc: f64) { + for r in &mut f.z.v[..f.z.n] { + *r = r.scale(wc); + } + for r in &mut f.p.v[..f.p.n] { + *r = r.scale(wc); + } + f.k *= wc.powi((f.p.n - f.z.n) as i32); +} + +fn lp_to_hp(f: &mut Zpk, wc: f64) { + let ratio = f.z.prod_neg().div(f.p.prod_neg()).re; + let degree = f.p.n - f.z.n; + for r in &mut f.z.v[..f.z.n] { + *r = C::real(wc).div(*r); + } + for r in &mut f.p.v[..f.p.n] { + *r = C::real(wc).div(*r); + } + for _ in 0..degree { + f.z.push(C::real(0.0)); + } + f.k *= ratio; +} + +fn lp_to_bp(f: &mut Zpk, w0: f64, bw: f64) { + let degree = f.p.n - f.z.n; + let map = |src: &Roots| -> Roots { + let mut out = Roots::new(); + for &r in src.as_slice() { + let a = r.scale(bw / 2.0); + let d = a.mul(a).sub(C::real(w0 * w0)).sqrt(); + out.push(a.add(d)); + out.push(a.sub(d)); + } + out + }; + f.z = map(&f.z); + f.p = map(&f.p); + for _ in 0..degree { + f.z.push(C::real(0.0)); + } + f.k *= bw.powi(degree as i32); +} + +fn lp_to_bs(f: &mut Zpk, w0: f64, bw: f64) { + let degree = f.p.n - f.z.n; + let ratio = f.z.prod_neg().div(f.p.prod_neg()).re; + let map = |src: &Roots| -> Roots { + let mut out = Roots::new(); + for &r in src.as_slice() { + let a = C::real(bw / 2.0).div(r); + let d = a.mul(a).sub(C::real(w0 * w0)).sqrt(); + out.push(a.add(d)); + out.push(a.sub(d)); + } + out + }; + f.z = map(&f.z); + f.p = map(&f.p); + for _ in 0..degree { + f.z.push(C::new(0.0, w0)); + f.z.push(C::new(0.0, -w0)); + } + f.k *= ratio; +} + +fn bilinear(f: &mut Zpk, fs: f64) { + let fs2 = 2.0 * fs; + let degree = f.p.n - f.z.n; + let num = f.z.as_slice().iter().fold(C::real(1.0), |a, &r| a.mul(C::real(fs2).sub(r))); + let den = f.p.as_slice().iter().fold(C::real(1.0), |a, &r| a.mul(C::real(fs2).sub(r))); + for r in &mut f.z.v[..f.z.n] { + *r = C::real(fs2).add(*r).div(C::real(fs2).sub(*r)); + } + for r in &mut f.p.v[..f.p.n] { + *r = C::real(fs2).add(*r).div(C::real(fs2).sub(*r)); + } + for _ in 0..degree { + f.z.push(C::real(-1.0)); + } + f.k *= num.div(den).re; +} + +// ------------------------------------------------------------------------ factorization + +const REAL_EPS: f64 = 1e-7; + +/// Split roots into conjugate pairs (upper half plane members) and real roots. +fn split(r: &Roots) -> (Roots, Roots) { + let mut pairs = Roots::new(); + let mut reals = Roots::new(); + for &x in r.as_slice() { + if x.im.abs() <= REAL_EPS * (1.0 + x.abs()) { + reals.push(C::real(x.re)); + } else if x.im > 0.0 { + pairs.push(x); + } + } + (pairs, reals) +} + +fn take(r: &mut Roots, i: usize) -> C { + let v = r.v[i]; + r.v[i] = r.v[r.n - 1]; + r.n -= 1; + v +} + +fn closest(r: &Roots, to: C) -> Option { + (0..r.n).min_by(|&a, &b| r.v[a].sub(to).abs().total_cmp(&r.v[b].sub(to).abs())) +} + +fn take_closest(r: &mut Roots, to: C) -> C { + let i = closest(r, to).unwrap_or(0); + take(r, i) +} + +fn into_sections(f: &Zpk) -> Sections { + let (mut pp, mut pr) = split(&f.p); + let (mut zp, mut zr) = split(&f.z); + let mut out = Sections { c: [Coeffs::IDENTITY; MAX_SECTIONS], n: 0 }; + let mut push = |b: [f64; 3], a: [f64; 2]| { + if out.n < MAX_SECTIONS { + out.c[out.n] = Coeffs { b0: b[0], b1: b[1], b2: b[2], a1: a[0], a2: a[1] }; + out.n += 1; + } + }; + // An odd real pole first (it needs a single real zero). + if pr.n % 2 == 1 { + let i = (0..pr.n).max_by(|&a, &b| pr.v[a].re.abs().total_cmp(&pr.v[b].re.abs())).unwrap_or(0); + let p = take(&mut pr, i); + let b = match closest(&zr, p) { + Some(j) => { + let z = take(&mut zr, j); + [1.0, -z.re, 0.0] + } + None => [1.0, 0.0, 0.0], + }; + push(b, [-p.re, 0.0]); + } + // Second-order sections, highest-Q (closest to the unit circle) first. + loop { + let pole_pair = if pp.n > 0 { + let i = (0..pp.n).max_by(|&a, &b| pp.v[a].abs().total_cmp(&pp.v[b].abs())).unwrap_or(0); + let p = take(&mut pp, i); + Some([-2.0 * p.re, p.re * p.re + p.im * p.im, p.re, p.im]) + } else if pr.n >= 2 { + let p1 = take(&mut pr, 0); + let p2 = take(&mut pr, 0); + Some([-(p1.re + p2.re), p1.re * p2.re, (p1.re + p2.re) / 2.0, 0.0]) + } else { + None + }; + let Some([a1, a2, cre, cim]) = pole_pair else { break }; + let center = C::new(cre, cim); + // Zeros: best complex pair, else two reals, else none. + let b = if let Some(j) = closest(&zp, center) { + let use_pair = zr.n < 2 || zp.v[j].sub(center).abs() <= closest(&zr, center).map_or(f64::INFINITY, |k| zr.v[k].sub(center).abs()); + if use_pair { + let z = take(&mut zp, j); + [1.0, -2.0 * z.re, z.re * z.re + z.im * z.im] + } else { + let z1 = take_closest(&mut zr, center); + let z2 = take_closest(&mut zr, center); + [1.0, -(z1.re + z2.re), z1.re * z2.re] + } + } else if zr.n >= 2 { + let z1 = take_closest(&mut zr, center); + let z2 = take_closest(&mut zr, center); + [1.0, -(z1.re + z2.re), z1.re * z2.re] + } else if zr.n == 1 { + let z1 = take(&mut zr, 0); + [1.0, -z1.re, 0.0] + } else { + [1.0, 0.0, 0.0] + }; + push(b, [a1, a2]); + } + // Overall gain on the first section. + if out.n > 0 { + out.c[0].b0 *= f.k; + out.c[0].b1 *= f.k; + out.c[0].b2 *= f.k; + } + out +} + +/// Design parameters. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Spec { + pub family: Family, + pub band: Band, + /// Prototype order (1..=[`MAX_ORDER`]). + pub order: usize, + /// Low-pass / high-pass edge, or the lower edge for band-pass / band-stop (Hz). + pub f1: f64, + /// Upper edge for band-pass / band-stop (Hz). + pub f2: f64, + /// Pass-band ripple (dB, Chebyshev / elliptic). + pub ripple_db: f64, + /// Stop-band attenuation (dB, elliptic). + pub stop_db: f64, +} + +/// A normalized analog low-pass prototype (cache it: Bessel needs a root search). +#[derive(Clone, Copy, Debug)] +pub struct Prototype(Zpk); + +/// The analog prototype for a family, order, pass-band ripple and stop-band attenuation. +pub fn prototype(family: Family, order: usize, ripple_db: f64, stop_db: f64) -> Prototype { + let n = order.clamp(1, MAX_ORDER); + // A NaN ripple or attenuation takes the usual 1 dB / 60 dB. + let rp = if ripple_db.is_nan() { 1.0 } else { ripple_db.clamp(0.01, 10.0) }; + let rs = if stop_db.is_nan() { 60.0 } else { stop_db }.clamp(rp + 1.0, 150.0); + Prototype(match family { + Family::Butterworth => butterworth(n), + Family::Bessel => bessel(n), + Family::Chebyshev => chebyshev1(n, rp), + Family::Elliptic => elliptic(n, rp, rs), + }) +} + +/// Transform a prototype to `band` at `f1` (and `f2` for band-pass/stop) and digitize it. An +/// unusable rate is replaced as [`crate::sane_sample_rate`] describes. +pub fn realize(proto: &Prototype, band: Band, f1: f64, f2: f64, sample_rate: f64) -> Sections { + let sample_rate = f64::from(crate::sane_sample_rate(sample_rate as f32)); + let mut f = proto.0; + let nyq = sample_rate * 0.5; + let warp = |hz: f64| 2.0 * sample_rate * (PI * hz.clamp(1.0, nyq * 0.98) / sample_rate).tan(); + match band { + Band::LowPass => lp_to_lp(&mut f, warp(f1)), + Band::HighPass => lp_to_hp(&mut f, warp(f1)), + Band::BandPass | Band::BandStop => { + let (lo, hi) = if f1 <= f2 { (f1, f2) } else { (f2, f1) }; + let hi = hi.max(lo * 1.001); + let (w1, w2) = (warp(lo), warp(hi)); + let (w0, bw) = ((w1 * w2).sqrt(), (w2 - w1).max(1e-6)); + if band == Band::BandPass { lp_to_bp(&mut f, w0, bw) } else { lp_to_bs(&mut f, w0, bw) } + } + } + bilinear(&mut f, sample_rate); + into_sections(&f) +} + +/// Design a digital filter at `sample_rate`. +pub fn design(spec: &Spec, sample_rate: f64) -> Sections { + realize(&prototype(spec.family, spec.order, spec.ripple_db, spec.stop_db), spec.band, spec.f1, spec.f2, sample_rate) +} + +#[cfg(test)] +mod tests { + use super::*; + + const SR: f64 = 48000.0; + + fn spec(family: Family, band: Band, order: usize, f1: f64, f2: f64) -> Spec { + Spec { family, band, order, f1, f2, ripple_db: 1.0, stop_db: 60.0 } + } + + #[test] + fn butterworth_matches_closed_form() { + // |H| = 1/√(1 + (Ωa/Ωc)^(2N)) with pre-warped analog frequencies. + for n in 1..=8 { + let s = design(&spec(Family::Butterworth, Band::LowPass, n, 1000.0, 0.0), SR); + let wa = |f: f64| (PI * f / SR).tan(); + for f in [100.0, 500.0, 1000.0, 2000.0, 8000.0] { + let want = -10.0 * (1.0 + (wa(f) / wa(1000.0)).powi(2 * n as i32)).log10(); + let got = s.magnitude_db(f, SR); + assert!((got - want).abs() < 1e-6, "n={n} f={f}: {got} vs {want}"); + } + } + } + + #[test] + fn bessel_is_minus_3db_at_cutoff_and_monotonic() { + for n in 1..=10 { + let s = design(&spec(Family::Bessel, Band::LowPass, n, 2000.0, 0.0), SR); + assert!((s.magnitude_db(2000.0, SR) + 3.0103).abs() < 0.02, "n={n}: {}", s.magnitude_db(2000.0, SR)); + assert!(s.magnitude_db(1.0, SR).abs() < 1e-5, "n={n}: {}", s.magnitude_db(1.0, SR)); + let mut last = 1.0; + for i in 1..200 { + let m = s.magnitude_db(i as f64 * 100.0, SR); + assert!(m <= last + 1e-9, "Bessel must be monotonic"); + last = m; + } + } + } + + #[test] + fn chebyshev_ripple_bounds() { + for n in 2..=8 { + let s = design(&Spec { ripple_db: 0.5, ..spec(Family::Chebyshev, Band::LowPass, n, 1000.0, 0.0) }, SR); + let mut min = f64::INFINITY; + let mut max = f64::NEG_INFINITY; + for i in 1..100 { + let m = s.magnitude_db(i as f64 * 10.0, SR); + min = min.min(m); + max = max.max(m); + } + assert!(max < 1e-6 && min > -0.5 - 1e-6, "n={n} {min}..{max}"); + assert!(min < -0.45, "ripple reaches the bound (n={n}: {min})"); + assert!((s.magnitude_db(1000.0, SR) + 0.5).abs() < 1e-3); + } + } + + #[test] + fn elliptic_meets_ripple_and_stopband() { + for n in 2..=8 { + for (rp, rs) in [(1.0, 60.0), (0.1, 40.0), (0.5, 80.0)] { + let s = design(&Spec { ripple_db: rp, stop_db: rs, ..spec(Family::Elliptic, Band::LowPass, n, 1000.0, 0.0) }, SR); + let mut max = f64::NEG_INFINITY; + let mut min = f64::INFINITY; + for i in 1..=100 { + let m = s.magnitude_db(i as f64 * 10.0, SR); + min = min.min(m); + max = max.max(m); + } + assert!(max < 1e-6 && min > -rp - 1e-3, "n={n} rp={rp}: {min}..{max}"); + // Once the response first drops below −As it never rises above it again. + let mut below = false; + for i in 1..2390 { + let f = i as f64 * 10.0; + let m = s.magnitude_db(f, SR); + if m < -rs { + below = true; + } + if below { + assert!(m < -rs + 0.05, "n={n} rs={rs} f={f}: {m}"); + } + } + assert!(below, "n={n} rs={rs}: stop band reached"); + } + } + // Sharper than Butterworth of the same order. + let e = design(&spec(Family::Elliptic, Band::LowPass, 4, 1000.0, 0.0), SR); + let b = design(&spec(Family::Butterworth, Band::LowPass, 4, 1000.0, 0.0), SR); + assert!(e.magnitude_db(1500.0, SR) < b.magnitude_db(1500.0, SR) - 10.0); + } + + #[test] + fn highpass_bandpass_bandstop_shapes() { + for fam in [Family::Butterworth, Family::Chebyshev, Family::Elliptic, Family::Bessel] { + let hp = design(&spec(fam, Band::HighPass, 4, 1000.0, 0.0), SR); + assert!(hp.magnitude_db(10000.0, SR) > -1.1, "{fam:?} hp pass"); + assert!(hp.magnitude_db(100.0, SR) < -40.0, "{fam:?} hp stop"); + let bp = design(&spec(fam, Band::BandPass, 3, 500.0, 2000.0), SR); + assert!(bp.magnitude_db(1000.0, SR) > -3.5, "{fam:?} bp center {}", bp.magnitude_db(1000.0, SR)); + assert!(bp.magnitude_db(50.0, SR) < -30.0 && bp.magnitude_db(15000.0, SR) < -25.0, "{fam:?} bp stop"); + let bs = design(&spec(fam, Band::BandStop, 3, 500.0, 2000.0), SR); + assert!(bs.magnitude_db(1000.0, SR) < -20.0, "{fam:?} bs center {}", bs.magnitude_db(1000.0, SR)); + assert!(bs.magnitude_db(30.0, SR) > -1.1 && bs.magnitude_db(18000.0, SR) > -1.1, "{fam:?} bs pass"); + } + } + + #[test] + fn complex_helpers() { + let w = C::new(0.3, -0.7); + let back = w.acos().cos(); + assert!(back.sub(w).abs() < 1e-12); + assert!((C::new(-4.0, 0.0).sqrt().im - 2.0).abs() < 1e-12); + assert!((ellip_k(0.0) - PI / 2.0).abs() < 1e-12); + // sn(K, k) = 1; cd(0, k) = 1 + assert!((sne(C::real(1.0), 0.7).re - 1.0).abs() < 1e-9); + assert!((cde(C::real(0.0), 0.7).re - 1.0).abs() < 1e-9); + let u = asne(C::real(0.5), 0.7); + assert!((sne(u, 0.7).re - 0.5).abs() < 1e-9); + } + + #[test] + fn hostile_ripple_and_sample_rates_give_a_finite_filter() { + for family in [Family::Chebyshev, Family::Elliptic] { + let p = prototype(family, 4, f64::NAN, f64::NAN); + for sr in [0.0, -48_000.0, f64::NAN, f64::INFINITY] { + let s = realize(&p, Band::LowPass, 1000.0, 0.0, sr); + let db = s.magnitude_db(100.0, 48_000.0); + assert!(db.is_finite(), "{family:?} at {sr}: {db}"); + } + } + } +} diff --git a/crates/audio-dsp/src/ducking.rs b/crates/audio-dsp/src/ducking.rs new file mode 100644 index 000000000..263f6ab5c --- /dev/null +++ b/crates/audio-dsp/src/ducking.rs @@ -0,0 +1,309 @@ +//! Offline analysis for automatic ducking: level envelope of the trigger audio +//! (dialogue, SFX…), activity detection with blip removal and gap bridging, and the volume +//! keyframes that duck a music clip under the detected regions. +//! +//! Pure functions on plain slices; times are seconds, levels dBFS / dB. + +/// Level floor (dBFS) for silence. +pub const FLOOR_DB: f32 = -120.0; + +/// Samples [`envelope_db`] advances per value: `hop_s` rounded to whole samples, at least one. +fn hop_samples(sample_rate: f32, hop_s: f32) -> usize { + // `as usize` saturates and reads NaN as 0. + ((hop_s * sample_rate).round() as usize).max(1) +} + +/// The hop, in seconds, that [`envelope_db`] really advances by over `frames` frames at +/// `sample_rate`: `hop_s` rounded to whole samples, and no longer than the signal. Pass it to +/// [`activity`] so the regions line up with the audio. +pub fn envelope_hop_s(sample_rate: f32, hop_s: f32, frames: usize) -> f32 { + let sr = crate::sane_sample_rate(sample_rate); + (hop_samples(sr, hop_s).min(frames.max(1)) as f64 / sr as f64) as f32 +} + +/// RMS level (dBFS) per hop: value `k` is the RMS of the window of `window_s` seconds centered on +/// `k · hop` (clipped at the signal edges), where `hop` is `hop_s` rounded to whole samples +/// ([`envelope_hop_s`]), with the power averaged over channels. The result has `ceil(len / hop)` +/// entries; silence reads [`FLOOR_DB`]. +pub fn envelope_db(channels: &[&[f32]], sample_rate: f32, hop_s: f32, window_s: f32) -> Vec { + let len = channels.iter().map(|c| c.len()).min().unwrap_or(0); + if len == 0 || channels.is_empty() { + return Vec::new(); + } + let sample_rate = crate::sane_sample_rate(sample_rate); + // Neither width needs to exceed the signal. + let hop = hop_samples(sample_rate, hop_s).min(len); + let half = ((window_s * sample_rate / 2.0).round() as usize).clamp(1, len); + // prefix sums of the channel-averaged power + let nch = channels.len() as f64; + let mut pre = Vec::with_capacity(len + 1); + pre.push(0.0f64); + let mut acc = 0.0f64; + for i in 0..len { + // A non-finite sample counts as silence. + let p: f64 = channels.iter().map(|c| c[i] as f64).filter(|v| v.is_finite()).map(|v| v * v).sum::() / nch; + acc += p; + pre.push(acc); + } + (0..len.div_ceil(hop)) + .map(|k| { + let c = k * hop; + let (a, b) = (c.saturating_sub(half), (c + half).min(len)); + let ms = (pre[b] - pre[a]).max(0.0) / (b - a).max(1) as f64; + if ms <= 1e-12 { FLOOR_DB } else { ((10.0 * ms.log10()) as f32).max(FLOOR_DB) } + }) + .collect() +} + +/// Regions `(start_s, end_s)` where the envelope exceeds `threshold_db`. Gaps shorter than +/// `bridge_s` are merged first, then regions shorter than `min_on_s` are dropped. A frame `k` +/// covers `[k·hop, (k+1)·hop)`. For an envelope from [`envelope_db`], pass +/// [`envelope_hop_s`] as `hop_s`. +pub fn activity(env_db: &[f32], hop_s: f32, threshold_db: f32, min_on_s: f32, bridge_s: f32) -> Vec<(f64, f64)> { + // the f32 hop rounded to whole 10 ns, so 0.01 means exactly 0.01 s + let hop = (hop_s as f64 * 1e8).round() / 1e8; + let mut raw: Vec<(f64, f64)> = Vec::new(); + let mut start: Option = None; + for (k, &v) in env_db.iter().enumerate() { + match (v > threshold_db, start) { + (true, None) => start = Some(k), + (false, Some(s)) => { + raw.push((s as f64 * hop, k as f64 * hop)); + start = None; + } + _ => {} + } + } + if let Some(s) = start { + raw.push((s as f64 * hop, env_db.len() as f64 * hop)); + } + let mut merged: Vec<(f64, f64)> = Vec::new(); + for r in raw { + match merged.last_mut() { + Some(last) if r.0 - last.1 < bridge_s as f64 - 1e-9 => last.1 = r.1, + _ => merged.push(r), + } + } + merged.retain(|(a, b)| b - a >= min_on_s as f64 - 1e-9); + merged +} + +/// Ducking sensitivity (0…10) → detection threshold in dBFS: +/// `−20 − 4·s` (5 → −40 dBFS; higher sensitivity reacts to quieter triggers). +pub fn sensitivity_threshold_db(sensitivity: f32) -> f32 { + -20.0 - 4.0 * sensitivity.clamp(0.0, 10.0) +} + +/// Volume keyframes `(time_s, level_db)` that duck by `reduce_db` under each region: ramp from +/// `base_db` at `a − fade` down to `base_db − reduce_db` at `a`, hold until `b`, ramp back up to +/// `base_db` at `b + fade`. Regions whose ramps would overlap are merged (the level stays +/// ducked between them). Everything is clamped to `[clip_start_s, clip_end_s]`; a ramp cut by a +/// clip edge gets a keyframe at the edge with the ramp's value there (fully ducked when the region +/// itself reaches the edge). Times are strictly increasing; no regions → no keyframes. `fade_s` is +/// at least 1 ms so a ramp never collapses into two keyframes at the same time. +pub fn duck_keyframes(regions: &[(f64, f64)], clip_start_s: f64, clip_end_s: f64, base_db: f64, reduce_db: f64, fade_s: f64) -> Vec<(f64, f64)> { + let fade = if fade_s.is_finite() { fade_s.max(1e-3) } else { 1e-3 }; + let ducked = base_db - reduce_db.abs(); + // A region just outside the clip still counts when its ramp reaches into the clip. + let mut sorted: Vec<(f64, f64)> = regions.iter().copied().filter(|(a, b)| b > a && *b + fade > clip_start_s && *a - fade < clip_end_s).collect(); + sorted.sort_by(|x, y| x.0.total_cmp(&y.0)); + // merge regions whose ramps touch or overlap + let mut groups: Vec<(f64, f64)> = Vec::new(); + for r in sorted { + match groups.last_mut() { + Some(g) if r.0 - fade <= g.1 + fade => g.1 = g.1.max(r.1), + _ => groups.push(r), + } + } + let mut out: Vec<(f64, f64)> = Vec::new(); + let mut push = |t: f64, v: f64| { + if t < clip_start_s || t > clip_end_s { + return; + } + match out.last_mut() { + Some(last) if t <= last.0 + 1e-9 => { + last.1 = v; + } + _ => out.push((t, v)), + } + }; + // value of the down-ramp ending at `a` / up-ramp starting at `b`, at time t + let down = |a: f64, t: f64| base_db + (ducked - base_db) * ((t - (a - fade)) / fade).clamp(0.0, 1.0); + let up = |b: f64, t: f64| ducked + (base_db - ducked) * ((t - b) / fade).clamp(0.0, 1.0); + for (a, b) in groups { + if b < clip_start_s { + // Only the up-ramp reaches the clip. + push(clip_start_s, up(b, clip_start_s)); + if b + fade <= clip_end_s { + push(b + fade, base_db); + } else { + push(clip_end_s, up(b, clip_end_s)); + } + continue; + } + if a > clip_end_s { + // Only the down-ramp reaches the clip. + let ramp_start = a - fade; + push(ramp_start.max(clip_start_s), down(a, ramp_start.max(clip_start_s))); + push(clip_end_s, down(a, clip_end_s)); + continue; + } + let ramp_start = a - fade; + if ramp_start >= clip_start_s { + push(ramp_start, base_db); + } else { + push(clip_start_s, down(a, clip_start_s)); + } + push(a.max(clip_start_s), ducked); + if b < clip_end_s { + push(b, ducked); + if b + fade <= clip_end_s { + push(b + fade, base_db); + } else { + push(clip_end_s, up(b, clip_end_s)); + } + } else { + push(clip_end_s, ducked); + } + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn envelope_levels() { + let sr = 1000.0; + // 1 s silence, 1 s of a ±0.1 square wave (−20 dBFS RMS) + let x: Vec = (0..2000) + .map(|i| { + if i < 1000 { + 0.0 + } else if i % 2 == 0 { + 0.1 + } else { + -0.1 + } + }) + .collect(); + let e = envelope_db(&[&x, &x], sr, 0.01, 0.02); + assert_eq!(e.len(), 200); + assert_eq!(e[10], FLOOR_DB); + assert!((e[150] + 20.0).abs() < 0.01, "{}", e[150]); + // the window straddling the edge is in between + assert!(e[100] < -20.0 && e[100] > -30.0); + assert!(envelope_db(&[], sr, 0.01, 0.02).is_empty()); + } + + #[test] + fn activity_bridges_then_drops_blips() { + let hop = 0.01; + let mut env = vec![-80.0f32; 300]; + // speech 0.50–1.00 and 1.10–1.50 (gap 0.1 s → bridged), blip 2.00–2.03 (dropped) + for (a, b) in [(50, 100), (110, 150), (200, 203)] { + env[a..b].iter_mut().for_each(|v| *v = -20.0); + } + let r = activity(&env, hop, -40.0, 0.1, 0.2); + assert_eq!(r.len(), 1); + assert!((r[0].0 - 0.5).abs() < 1e-6 && (r[0].1 - 1.5).abs() < 1e-6, "{r:?}"); + // without bridging both remain, the blip still goes + let r = activity(&env, hop, -40.0, 0.1, 0.0); + assert_eq!(r.len(), 2); + // a region running to the end is closed at the end + let mut env2 = vec![-80.0f32; 10]; + env2[5..].iter_mut().for_each(|v| *v = 0.0); + assert_eq!(activity(&env2, 0.1, -40.0, 0.0, 0.0), vec![(0.5, 1.0)]); + } + + #[test] + fn sensitivity_mapping() { + assert_eq!(sensitivity_threshold_db(5.0), -40.0); + assert_eq!(sensitivity_threshold_db(0.0), -20.0); + assert_eq!(sensitivity_threshold_db(10.0), -60.0); + assert_eq!(sensitivity_threshold_db(99.0), -60.0); + } + + fn strictly_increasing(k: &[(f64, f64)]) -> bool { + k.windows(2).all(|w| w[1].0 > w[0].0) + } + + #[test] + fn duck_keyframes_basic_and_merge() { + let k = duck_keyframes(&[(2.0, 4.0)], 0.0, 10.0, 0.0, 15.0, 0.5); + assert_eq!(k, vec![(1.5, 0.0), (2.0, -15.0), (4.0, -15.0), (4.5, 0.0)]); + // ramps overlap (4.5 > 4.8 − 0.5 = 4.3) → stay ducked + let k = duck_keyframes(&[(2.0, 4.0), (4.8, 6.0)], 0.0, 10.0, -3.0, 12.0, 0.5); + assert_eq!(k, vec![(1.5, -3.0), (2.0, -15.0), (6.0, -15.0), (6.5, -3.0)]); + // separate regions + let k = duck_keyframes(&[(5.0, 6.0), (1.0, 2.0)], 0.0, 10.0, 0.0, 10.0, 0.25); + assert_eq!(k.len(), 8); + assert!(strictly_increasing(&k)); + assert!(duck_keyframes(&[], 0.0, 10.0, 0.0, 10.0, 0.5).is_empty()); + } + + #[test] + fn duck_keyframes_clamped_to_clip() { + // region starts before the clip: fully ducked at the start edge + let k = duck_keyframes(&[(-1.0, 2.0)], 0.0, 10.0, 0.0, 10.0, 0.5); + assert_eq!(k, vec![(0.0, -10.0), (2.0, -10.0), (2.5, 0.0)]); + // ramp partially before the clip: ramp value at the edge + let k = duck_keyframes(&[(0.25, 2.0)], 0.0, 10.0, 0.0, 10.0, 0.5); + assert_eq!(k[0], (0.0, -5.0)); + assert_eq!(k[1], (0.25, -10.0)); + // region runs past the end: ducked at the end edge + let k = duck_keyframes(&[(8.0, 12.0)], 0.0, 10.0, 0.0, 10.0, 0.5); + assert_eq!(k, vec![(7.5, 0.0), (8.0, -10.0), (10.0, -10.0)]); + // up-ramp cut by the end + let k = duck_keyframes(&[(8.0, 9.75)], 0.0, 10.0, 0.0, 10.0, 0.5); + assert_eq!(*k.last().unwrap(), (10.0, -5.0)); + // outside the clip: nothing; zero fade still strictly increasing + assert!(duck_keyframes(&[(11.0, 12.0)], 0.0, 10.0, 0.0, 10.0, 0.5).is_empty()); + let k = duck_keyframes(&[(2.0, 3.0)], 0.0, 10.0, 0.0, 10.0, 0.0); + assert!(strictly_increasing(&k) && k.len() == 4); + // A region just past the end: its down-ramp lowers the end of the clip. + let k = duck_keyframes(&[(10.2, 12.0)], 0.0, 10.0, 0.0, 10.0, 0.5); + assert_eq!(k.len(), 2); + assert!((k[0].0 - 9.7).abs() < 1e-12 && k[0].1 == 0.0, "{k:?}"); + assert!((k[1].0 - 10.0).abs() < 1e-12 && (k[1].1 + 6.0).abs() < 1e-9, "{k:?}"); + // A region just before the start: its up-ramp raises the start of the clip. + let k = duck_keyframes(&[(-2.0, -0.25)], 0.0, 10.0, 0.0, 10.0, 0.5); + assert_eq!(k, vec![(0.0, -5.0), (0.25, 0.0)]); + } + + #[test] + fn envelope_window_and_hop_of_any_size() { + let x = vec![0.5f32; 4_800]; + for (hop, win) in [(0.01, f32::INFINITY), (0.01, 1e30), (f32::INFINITY, 0.1), (f32::NAN, f32::NAN)] { + let e = envelope_db(&[&x], 48_000.0, hop, win); + assert!(!e.is_empty() && e.iter().all(|v| v.is_finite()), "hop {hop} window {win}: {e:?}"); + } + // A NaN or infinite sample does not hide the level after it. + let mut y = x.clone(); + y[100] = f32::NAN; + y[200] = f32::INFINITY; + let e = envelope_db(&[&y], 48_000.0, 0.01, 0.02); + assert!(e.iter().skip(2).all(|v| (v - 20.0 * 0.5f32.log10()).abs() < 0.1), "{e:?}"); + } + + #[test] + fn regions_stay_on_the_audio_when_the_hop_is_not_whole_samples() { + // 15 ms at 44.1 kHz is 661.5 samples; the envelope steps 662. + let sr = 44_100.0; + let start = 60 * 44_100; + let mut x = vec![0.0f32; start + 44_100]; + x[start..].iter_mut().for_each(|v| *v = 0.5); + let hop = envelope_hop_s(sr, 0.015, x.len()); + assert!((hop as f64 - 662.0 / 44_100.0).abs() < 1e-9, "{hop}"); + let env = envelope_db(&[&x], sr, 0.015, 0.03); + let r = activity(&env, hop, -40.0, 0.1, 0.0); + assert_eq!(r.len(), 1, "{r:?}"); + assert!((r[0].0 - 60.0).abs() < 0.016, "the region starts at {} s", r[0].0); + // A hop longer than the clip is the clip's length. + let clip = vec![0.5f32; 4_800]; + let hop = envelope_hop_s(48_000.0, 1.0, clip.len()); + let r = activity(&envelope_db(&[&clip], 48_000.0, 1.0, 0.02), hop, -40.0, 0.0, 0.0); + assert_eq!(r, vec![(0.0, 0.1)]); + } +} diff --git a/crates/audio-dsp/src/effects.rs b/crates/audio-dsp/src/effects.rs new file mode 100644 index 000000000..29c406d7a --- /dev/null +++ b/crates/audio-dsp/src/effects.rs @@ -0,0 +1,346 @@ +//! Audio effects and their registry. + +pub(crate) mod channel; +pub(crate) mod declick; +pub(crate) mod dither; +pub(crate) mod dynamics; +pub(crate) mod eq; +pub(crate) mod essential; +pub(crate) mod filters; +pub(crate) mod generator; +pub(crate) mod modulation; +pub(crate) mod multiband; +pub(crate) mod pitch; +pub(crate) mod restoration; +pub(crate) mod reverbs; +pub(crate) mod special; +mod stft; +pub(crate) mod time; +pub(crate) mod util; + +pub(crate) use channel::{Amplify, Balance, ChannelVolume, Invert, Route, Routing}; +pub(crate) use declick::ClickRemover; +pub use dither::Dither; +pub use dynamics::{Compressor, Gate, Limiter, Maximizer}; +pub(crate) use eq::{ParametricEq, SimpleEq}; +pub use essential::DeEsser; +pub(crate) use essential::{DeReverb, SpeechEnhance, StereoWidth}; +pub(crate) use filters::{FftFilter, FullParametricEq, GraphicEq, NotchFilter, ScientificFilter}; +pub use generator::SignalGenerator; +pub(crate) use modulation::{AnalogDelay, ChorusFlanger, Flanger, MultitapDelay, Phaser}; +pub(crate) use multiband::{DynamicsRack, MultibandCompressor, TubeCompressor}; +pub use pitch::PitchShifter; +pub(crate) use restoration::{DeHum, DeNoise}; +pub(crate) use reverbs::{ConvolutionReverb, SurroundReverb}; +pub use special::LoudnessMeterFx; +pub(crate) use special::{AmbisonicsPanner, Binauralizer, ChannelMixer, Distortion, GuitarSuite, Mastering, Mute, StereoExpander, VocalEnhancer}; +pub(crate) use time::{Delay, Reverb}; + +use crate::{AudioEffect, ParamSpec, sane_channels, sane_sample_rate}; + +/// Effect category, for grouping effects in menus. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum Category { + Filter, + Dynamics, + Time, + Channel, + Restoration, + Pitch, + Modulation, + Reverb, + Special, +} + +/// Registry entry describing one effect type. +#[derive(Clone, Copy)] +pub struct EffectInfo { + pub id: &'static str, + pub name: &'static str, + pub category: Category, + pub params: &'static [ParamSpec], + /// Construct an instance for `(sample_rate, channels)`. An unusable rate or channel count is + /// replaced as [`crate::sane_sample_rate`] and [`crate::sane_channels`] describe. + pub create: fn(f32, usize) -> Box, +} + +impl std::fmt::Debug for EffectInfo { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("EffectInfo") + .field("id", &self.id) + .field("name", &self.name) + .field("category", &self.category) + .field("params", &self.params.len()) + .finish() + } +} + +macro_rules! entry { + ($id:literal, $name:literal, $cat:ident, $ty:ty) => { + EffectInfo { + id: $id, + name: $name, + category: Category::$cat, + params: <$ty>::PARAMS, + create: |sr, ch| Box::new(<$ty>::new(sane_sample_rate(sr), sane_channels(ch))), + } + }; +} + +static REGISTRY: &[EffectInfo] = &[ + entry!("parametric_eq", "Parametric Equalizer", Filter, ParametricEq), + entry!("simple_eq", "Simple 3-Band EQ", Filter, SimpleEq), + entry!("compressor", "Compressor", Dynamics, Compressor), + entry!("gate", "Expander / Gate", Dynamics, Gate), + entry!("limiter", "Hard Limiter", Dynamics, Limiter), + entry!("maximizer", "Maximizer", Dynamics, Maximizer), + entry!("delay", "Delay", Time, Delay), + entry!("reverb", "Reverb", Time, Reverb), + entry!("amplify", "Amplify", Channel, Amplify), + entry!("channel_volume", "Channel Volume", Channel, ChannelVolume), + entry!("balance", "Balance / Pan", Channel, Balance), + entry!("invert", "Invert", Channel, Invert), + EffectInfo { + id: "swap_channels", + name: "Swap Channels", + category: Category::Channel, + params: Route::PARAMS, + create: |_, _| Box::new(Route::new(Routing::Swap)), + }, + EffectInfo { + id: "fill_left", + name: "Fill Left with Right", + category: Category::Channel, + params: Route::PARAMS, + create: |_, _| Box::new(Route::new(Routing::FillLeft)), + }, + EffectInfo { + id: "fill_right", + name: "Fill Right with Left", + category: Category::Channel, + params: Route::PARAMS, + create: |_, _| Box::new(Route::new(Routing::FillRight)), + }, + entry!("dehum", "DeHum", Restoration, DeHum), + entry!("denoise", "DeNoise", Restoration, DeNoise), + entry!("pitch_shifter", "Pitch Shifter", Pitch, PitchShifter), + entry!("deesser", "DeEsser", Restoration, DeEsser), + entry!("dereverb", "DeReverb", Restoration, DeReverb), + entry!("speech_enhance", "Enhance Speech", Filter, SpeechEnhance), + entry!("stereo_width", "Stereo Width", Channel, StereoWidth), + entry!("graphic_eq_10", "Graphic Equalizer (10 Bands)", Filter, GraphicEq<10>), + entry!("graphic_eq_20", "Graphic Equalizer (20 Bands)", Filter, GraphicEq<20>), + entry!("graphic_eq_30", "Graphic Equalizer (30 Bands)", Filter, GraphicEq<30>), + entry!("parametric_eq_full", "Parametric Equalizer (full)", Filter, FullParametricEq), + entry!("notch_filter", "Notch Filter", Filter, NotchFilter), + entry!("scientific_filter", "Scientific Filter", Filter, ScientificFilter), + entry!("fft_filter", "FFT Filter", Filter, FftFilter), + entry!("dynamics_rack", "Dynamics", Dynamics, DynamicsRack), + entry!("multiband_compressor", "Multiband Compressor", Dynamics, MultibandCompressor), + entry!("tube_compressor", "Tube-modeled Compressor", Dynamics, TubeCompressor), + entry!("chorus_flanger", "Chorus/Flanger", Modulation, ChorusFlanger), + entry!("flanger", "Flanger", Modulation, Flanger), + entry!("phaser", "Phaser", Modulation, Phaser), + entry!("analog_delay", "Analog Delay", Time, AnalogDelay), + entry!("multitap_delay", "Multitap Delay", Time, MultitapDelay), + entry!("convolution_reverb", "Convolution Reverb", Reverb, ConvolutionReverb), + entry!("surround_reverb", "Surround Reverb", Reverb, SurroundReverb), + entry!("click_remover", "Automatic Click Remover", Restoration, ClickRemover), + entry!("channel_mixer", "Channel Mixer", Channel, ChannelMixer), + entry!("distortion", "Distortion", Special, Distortion), + entry!("guitar_suite", "GuitarSuite", Special, GuitarSuite), + entry!("mastering", "Mastering", Special, Mastering), + entry!("vocal_enhancer", "Vocal Enhancer", Special, VocalEnhancer), + entry!("stereo_expander", "Stereo Expander", Channel, StereoExpander), + entry!("binauralizer", "Binauralizer - Ambisonics", Special, Binauralizer), + entry!("ambisonics_panner", "Panner - Ambisonics", Special, AmbisonicsPanner), + entry!("loudness_meter", "Loudness Meter", Special, LoudnessMeterFx), + entry!("mute", "Mute", Channel, Mute), + entry!("dither", "Dither", Special, Dither), + entry!("signal_generator", "Signal Generator", Special, SignalGenerator), +]; + +/// All registered effects. +pub fn effects() -> &'static [EffectInfo] { + REGISTRY +} + +/// Look up an effect by id. +pub fn effect_info(id: &str) -> Option<&'static EffectInfo> { + REGISTRY.iter().find(|e| e.id == id) +} + +/// Instantiate an effect by id. +pub fn create_effect(id: &str, sample_rate: f32, channels: usize) -> Option> { + effect_info(id).map(|e| (e.create)(sample_rate, channels)) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::Unit; + use crate::testutil::*; + + const SR: f32 = 48000.0; + + fn noise(seed: u64, n: usize, amp: f32) -> Vec { + let mut r = Rng::new(seed); + (0..n).map(|_| r.uniform() * amp).collect() + } + + /// A non-default setting for every parameter (to exercise real processing paths). + fn tweak(fx: &mut dyn AudioEffect) { + for p in fx.params() { + let v = match p.unit { + Unit::Toggle => 1.0, + Unit::Choice => p.max, + _ => p.min + (p.max - p.min) * 0.37, + }; + assert!(fx.set_param(p.id, v)); + } + } + + #[test] + fn registry_is_consistent() { + let mut ids = std::collections::HashSet::new(); + for e in effects() { + assert!(ids.insert(e.id), "duplicate id {}", e.id); + let fx = (e.create)(SR, 2); + assert_eq!(fx.id(), e.id); + assert_eq!(fx.params(), e.params); + let mut pids = std::collections::HashSet::new(); + for p in e.params { + assert!(pids.insert(p.id), "{}: duplicate param {}", e.id, p.id); + assert!(p.min <= p.default && p.default <= p.max, "{}.{}", e.id, p.id); + assert_eq!(fx.param(p.id), Some(p.default)); + if p.unit == Unit::Choice { + assert_eq!(p.choices.len() as f32, p.max + 1.0); + } + } + } + assert!(effect_info("reverb").is_some()); + assert!(create_effect("nope", SR, 2).is_none()); + let mut c = create_effect("compressor", SR, 2).unwrap(); + assert!(!c.set_param("nope", 1.0)); + assert!(c.set_param("ratio", 1000.0)); + assert_eq!(c.param("ratio"), Some(30.0)); + assert!(c.set_param("ratio", f32::NAN)); + assert_eq!(c.param("ratio"), Some(4.0)); + } + + #[test] + fn block_size_independence_with_param_changes() { + let n = 30000; + let src_l = noise(1, n, 0.7); + let src_r = noise(2, n, 0.7); + let change_at = 11111; + for e in effects() { + let run = |sizes: &mut dyn FnMut() -> usize| { + let mut fx = (e.create)(SR, 2); + let (mut l, mut r) = (src_l.clone(), src_r.clone()); + let mut pos = 0; + let mut changed = false; + while pos < n { + if !changed && pos == change_at { + tweak(fx.as_mut()); + changed = true; + } + let mut len = sizes().min(n - pos); + if !changed && pos + len > change_at { + len = change_at - pos; + } + fx.process(&mut [&mut l[pos..pos + len], &mut r[pos..pos + len]]); + pos += len; + } + (l, r) + }; + let big = run(&mut || usize::MAX); + let mut rng = Rng::new(5); + let small = run(&mut || match rng.next_u64() % 4 { + 0 => 0, + 1 => 1, + 2 => (rng.next_u64() % 64) as usize, + _ => (rng.next_u64() % 3000) as usize, + }); + for (a, b) in big.0.iter().chain(&big.1).zip(small.0.iter().chain(&small.1)) { + assert!((a - b).abs() <= 1e-6, "{}: block-size dependent output", e.id); + } + assert!(big.0.iter().chain(&big.1).all(|v| v.is_finite()), "{}", e.id); + } + } + + #[test] + fn zero_length_and_single_sample_blocks() { + for e in effects() { + let mut fx = (e.create)(SR, 2); + fx.process(&mut []); + fx.process(&mut [&mut [], &mut []]); + let (mut a, mut b) = ([0.25f32], [-0.25f32]); + fx.process(&mut [&mut a, &mut b]); + // Mono and more channels than configured don't panic. + fx.process(&mut [&mut [0.1f32; 3]]); + fx.process(&mut [&mut [0.1f32; 3], &mut [0.1; 3], &mut [0.1; 3]]); + assert!(a[0].is_finite() && b[0].is_finite(), "{}", e.id); + } + } + + #[test] + fn extreme_settings_stay_finite_and_denormal_free() { + // One thread per effect. The tail stays 40 s long: delays, reverbs and graphic EQs still + // produce output in its last second, some of it within 3x of the smallest normal f32. + std::thread::scope(|scope| { + for e in effects() { + scope.spawn(move || { + for setting in [0.0f32, 1.0] { + let mut fx = (e.create)(SR, 2); + for p in e.params { + fx.set_param(p.id, if setting == 0.0 { p.min } else { p.max }); + } + let mut l = noise(3, 24000, 4.0); + let mut r = noise(4, 24000, 4.0); + l[100] = 1e6; + r[200] = -1e6; + fx.process(&mut [&mut l, &mut r]); + assert!(l.iter().chain(&r).all(|v| v.is_finite()), "{} setting {setting}", e.id); + // Long silence afterwards: output decays without denormals. + fx.reset(); + let mut l = noise(3, 4800, 0.5); + let mut r = noise(4, 4800, 0.5); + fx.process(&mut [&mut l, &mut r]); + for _ in 0..40 { + let mut l = vec![0.0f32; 48000]; + let mut r = vec![0.0f32; 48000]; + fx.process(&mut [&mut l, &mut r]); + assert!( + l.iter().chain(&r).all(|v| v.is_finite() && !v.is_subnormal()), + "{} setting {setting}: denormal/NaN in tail", + e.id + ); + } + } + }); + } + }); + } + + #[test] + fn reset_restores_initial_behavior() { + for e in effects() { + let mut fx = (e.create)(SR, 2); + let x = noise(8, 6000, 0.5); + let (mut a1, mut a2) = (x.clone(), x.clone()); + fx.process(&mut [&mut a1, &mut a2]); + let (mut j1, mut j2) = (noise(9, 3000, 0.9), noise(10, 3000, 0.9)); + fx.process(&mut [&mut j1, &mut j2]); + fx.reset(); + let (mut b1, mut b2) = (x.clone(), x.clone()); + fx.process(&mut [&mut b1, &mut b2]); + for (p, q) in a1.iter().zip(&b1) { + assert!((p - q).abs() < 1e-6, "{}: reset didn't clear state", e.id); + } + } + } +} + +#[cfg(test)] +mod behavior_tests; diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs new file mode 100644 index 000000000..a4e574583 --- /dev/null +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -0,0 +1,673 @@ +//! Behavioral tests of the registered effects: neutral settings are (delayed) +//! identity, output is deterministic, latency is constant and correct, and each effect does +//! what it says on generated signals (tones, noise, impulses), plus a realtime-factor check. + +use super::*; +use crate::AudioEffect; +use crate::testutil::*; + +const SR: f32 = 48000.0; + +fn noise(seed: u64, n: usize, amp: f32) -> Vec { + let mut r = Rng::new(seed); + (0..n).map(|_| r.uniform() * amp).collect() +} + +fn fx(id: &str, params: &[(&str, f32)]) -> Box { + let mut e = create_effect(id, SR, 2).unwrap_or_else(|| panic!("no effect {id}")); + for (p, v) in params { + assert!(e.set_param(p, *v), "{id}.{p}"); + } + e.reset(); + e +} + +fn run(e: &mut dyn AudioEffect, l: &[f32], r: &[f32]) -> (Vec, Vec) { + let (mut a, mut b) = (l.to_vec(), r.to_vec()); + e.process(&mut [&mut a, &mut b]); + (a, b) +} + +/// Steady-state amplitude (relative, dB) of a tone through the effect (second half measured, +/// latency ignored because the tone is stationary). +fn tone_db(e: &mut dyn AudioEffect, freq: f64, amp: f32) -> f64 { + e.reset(); + let n = SR as usize; + let x = sine(freq, amp as f64, SR as f64, n, 0.0); + let (y, _) = run(e, &x, &x); + db(tone_amplitude(&y[n / 2..], freq, SR as f64) / amp as f64) +} + +/// Settings under which each effect must pass audio through unchanged (apart from latency). +fn neutral(id: &str) -> Option> { + Some(match id { + "graphic_eq_10" | "graphic_eq_20" | "graphic_eq_30" | "notch_filter" | "channel_mixer" | "stereo_expander" | "ambisonics_panner" + | "loudness_meter" | "mute" | "mastering" | "fft_filter" => vec![], + "parametric_eq_full" => vec![], + "dynamics_rack" => vec![("comp_on", 0.0)], + "multiband_compressor" => return None, // all-pass, not identity: see its own test + "tube_compressor" => return None, // saturation stage: near-identity at low level, tested separately + "chorus_flanger" | "flanger" | "phaser" | "multitap_delay" | "distortion" | "guitar_suite" | "binauralizer" | "convolution_reverb" => { + vec![("mix", 0.0)] + } + "analog_delay" => vec![("wet", 0.0), ("dry", 100.0)], + "surround_reverb" => vec![("wet", 0.0), ("dry", 100.0)], + "click_remover" => vec![("threshold", 100.0)], + "scientific_filter" => return None, + "vocal_enhancer" => return None, + _ => return None, + }) +} + +const NEW_IDS: &[&str] = &[ + "graphic_eq_10", + "graphic_eq_20", + "graphic_eq_30", + "parametric_eq_full", + "notch_filter", + "scientific_filter", + "fft_filter", + "dynamics_rack", + "multiband_compressor", + "tube_compressor", + "chorus_flanger", + "flanger", + "phaser", + "analog_delay", + "multitap_delay", + "convolution_reverb", + "surround_reverb", + "click_remover", + "channel_mixer", + "distortion", + "guitar_suite", + "mastering", + "vocal_enhancer", + "stereo_expander", + "binauralizer", + "ambisonics_panner", + "loudness_meter", + "mute", +]; + +#[test] +fn neutral_settings_are_delayed_identity() { + let n = 24000; + let l = noise(1, n, 0.25); + let r = noise(2, n, 0.25); + let mut checked = 0; + for id in NEW_IDS { + let Some(p) = neutral(id) else { continue }; + let mut e = fx(id, &p); + let lat = e.latency(); + let (a, b) = run(e.as_mut(), &l, &r); + let mut worst = 0.0f32; + for i in lat..n { + worst = worst.max((a[i] - l[i - lat]).abs()).max((b[i] - r[i - lat]).abs()); + } + assert!(worst < 2e-4, "{id}: neutral output differs by {worst}"); + checked += 1; + } + assert!(checked >= 20); +} + +#[test] +fn every_effect_is_deterministic_and_latency_is_constant() { + let n = 12000; + let l = noise(3, n, 0.5); + let r = noise(4, n, 0.5); + for e in effects() { + let mk = || { + let mut f = (e.create)(SR, 2); + for p in e.params { + let v = match p.unit { + crate::Unit::Toggle => 1.0 - p.default, + crate::Unit::Choice => p.max, + _ => p.min + (p.max - p.min) * 0.61, + }; + f.set_param(p.id, v); + } + f + }; + let lat0 = (e.create)(SR, 2).latency(); + let mut a = mk(); + let mut b = mk(); + assert_eq!(a.latency(), lat0, "{}: latency depends on parameters", e.id); + let ya = run(a.as_mut(), &l, &r); + let yb = run(b.as_mut(), &l, &r); + assert!(ya.0 == yb.0 && ya.1 == yb.1, "{}: not deterministic", e.id); + } +} + +#[test] +fn latency_is_where_the_impulse_lands() { + // Effects with latency: an impulse comes out exactly `latency` samples later at neutral + // settings (FFT filter / convolution / click remover / existing STFT effects). + for (id, p) in [("fft_filter", vec![]), ("convolution_reverb", vec![("mix", 0.0)]), ("click_remover", vec![("threshold", 100.0)])] { + let mut e = fx(id, &p); + let lat = e.latency(); + assert!(lat > 0, "{id}"); + let n = lat + 4000; + let mut l = vec![0.0f32; n]; + l[100] = 0.5; + let (a, _) = run(e.as_mut(), &l, &l); + let peak = a.iter().enumerate().max_by(|x, y| x.1.abs().total_cmp(&y.1.abs())).unwrap().0; + assert_eq!(peak, 100 + lat, "{id}"); + assert!((a[peak] - 0.5).abs() < 1e-3, "{id}: {}", a[peak]); + } +} + +#[test] +fn graphic_eq_bands_hit_their_gain() { + for (id, band, freq) in [("graphic_eq_10", "b6", 1000.0), ("graphic_eq_20", "b11", 1000.0), ("graphic_eq_30", "b17", 1000.0)] { + let mut e = fx(id, &[(band, 12.0)]); + let want = e.response_db(freq).unwrap(); + assert!((want - 12.0).abs() < 1.0, "{id}: analytic {want}"); + let got = tone_db(e.as_mut(), freq, 0.1); + assert!((got - want).abs() < 0.1, "{id}: measured {got} vs {want}"); + // An octave+ away the boost has mostly gone. + assert!(e.response_db(freq * 4.0).unwrap() < 1.0, "{id}"); + let mut flat = fx(id, &[("gain", -6.0)]); + assert!((tone_db(flat.as_mut(), 300.0, 0.1) + 6.0).abs() < 0.05, "{id}: master gain"); + } +} + +#[test] +fn parametric_eq_full_sections() { + // 24 dB/oct Butterworth high-pass: −3 dB at the corner, ≈ −48 dB two octaves down. + let hp = fx("parametric_eq_full", &[("hp_on", 1.0), ("hp_freq", 200.0), ("hp_slope", 1.0)]); + assert!((hp.response_db(200.0).unwrap() + 3.01).abs() < 0.05, "corner {}", hp.response_db(200.0).unwrap()); + assert!(hp.response_db(50.0).unwrap() < -45.0); + let mut e = fx("parametric_eq_full", &[("hp_on", 1.0), ("hp_freq", 200.0), ("hp_slope", 1.0), ("mid_gain", 9.0), ("master_gain", -3.0)]); + assert!((e.response_db(1000.0).unwrap() - 6.0).abs() < 0.05); + for f in [50.0, 200.0, 1000.0, 5000.0] { + let want = e.response_db(f).unwrap(); + let got = tone_db(e.as_mut(), f, 0.1); + assert!((got - want).abs() < 0.15, "{f} Hz: {got} vs {want}"); + } +} + +#[test] +fn notch_filter_removes_tones() { + let mut e = fx("notch_filter", &[("n1_on", 1.0), ("n1_freq", 1000.0), ("n1_gain", -60.0), ("width", 2.0)]); + assert!(tone_db(e.as_mut(), 1000.0, 0.3) < -50.0); + assert!(tone_db(e.as_mut(), 1200.0, 0.3).abs() < 0.5); +} + +#[test] +fn scientific_filter_matches_its_design() { + for (ty, mode) in [(3.0, 0.0), (1.0, 1.0), (2.0, 2.0), (0.0, 3.0)] { + let mut e = fx("scientific_filter", &[("type", ty), ("mode", mode), ("order", 4.0), ("cutoff", 800.0), ("high_cutoff", 3000.0)]); + for f in [200.0, 1000.0, 1500.0, 6000.0] { + let want = e.response_db(f).unwrap(); + let got = tone_db(e.as_mut(), f, 0.1); + if want > -60.0 { + assert!((got - want).abs() < 0.2, "type {ty} mode {mode} {f} Hz: {got} vs {want}"); + } else { + assert!(got < -55.0, "type {ty} mode {mode} {f} Hz: {got}"); + } + } + } +} + +#[test] +fn fft_filter_applies_its_curve() { + let mut e = fx("fft_filter", &[("p5_gain", -30.0), ("interp", 0.0)]); + assert!((e.response_db(1500.0).unwrap() + 30.0).abs() < 1e-3); + let got = tone_db(e.as_mut(), 1500.0, 0.3); + assert!((got + 30.0).abs() < 1.5, "{got}"); + assert!(tone_db(e.as_mut(), 100.0, 0.3).abs() < 0.3); +} + +#[test] +fn dynamics_rack_sections() { + // Compressor: −6 dBFS sine (peak), −20 dB threshold, 4:1 → ≈ −16.5 dB peak. + let mut e = fx("dynamics_rack", &[("comp_threshold", -20.0), ("comp_ratio", 4.0), ("comp_attack", 0.1), ("comp_release", 3000.0)]); + let want = e.transfer_db(0, -6.0).unwrap(); + assert!((want + 16.5).abs() < 1e-4); + let n = SR as usize; + let x = sine(1000.0, 0.5, SR as f64, n, 0.0); + let (y, _) = run(e.as_mut(), &x, &x); + let peak = y[n / 2..].iter().fold(0.0f32, |a, v| a.max(v.abs())); + assert!((gain_db(peak) - want).abs() < 0.3, "compressed peak {}", gain_db(peak)); + // Gate: a quiet tone under the gate threshold is closed by ≥ 60 dB. + let mut g = fx("dynamics_rack", &[("comp_on", 0.0), ("gate_on", 1.0), ("gate_threshold", -30.0)]); + let q = sine(1000.0, 0.01, SR as f64, n, 0.0); + let (yq, _) = run(g.as_mut(), &q, &q); + assert!(db(rms(&yq[n / 2..]) / rms(&q[n / 2..])) < -60.0); + // Limiter: hard ceiling. + let mut lim = fx("dynamics_rack", &[("comp_on", 0.0), ("lim_on", 1.0), ("lim_threshold", -6.0)]); + let loud = noise(5, n, 1.0); + let (yl, _) = run(lim.as_mut(), &loud, &loud); + assert!(yl.iter().all(|v| v.abs() <= db_to_gain(-6.0) + 1e-6)); + let mut sc = fx("dynamics_rack", &[("comp_on", 0.0), ("lim_on", 1.0), ("lim_threshold", -6.0), ("soft_clip", 1.0)]); + let (ys, _) = run(sc.as_mut(), &loud, &loud); + assert!(ys.iter().all(|v| v.abs() <= db_to_gain(-6.0) + 1e-6)); +} + +#[test] +fn multiband_crossovers_sum_flat_and_bands_compress_independently() { + let mut e = fx("multiband_compressor", &[("b1_ratio", 1.0), ("b2_ratio", 1.0), ("b3_ratio", 1.0), ("b4_ratio", 1.0)]); + for f in [40.0, 120.0, 700.0, 2000.0, 6000.0, 10000.0, 15000.0] { + let g = tone_db(e.as_mut(), f, 0.25); + assert!(g.abs() < 0.02, "crossover sum not flat at {f}: {g}"); + } + // Band 1 compresses a loud bass tone; a treble tone in band 3 is untouched. + let mut c = fx( + "multiband_compressor", + &[("b1_threshold", -30.0), ("b1_ratio", 4.0), ("b3_threshold", 0.0), ("b2_threshold", 0.0), ("b4_threshold", 0.0)], + ); + assert!(tone_db(c.as_mut(), 60.0, 0.5) < -10.0); + assert!(tone_db(c.as_mut(), 5000.0, 0.5).abs() < 0.1); + assert!((c.transfer_db(0, -6.0).unwrap() + 24.0).abs() < 1e-4); + // Solo band 4: low tones vanish. + let mut s = fx("multiband_compressor", &[("b4_solo", 1.0), ("b4_ratio", 1.0)]); + assert!(tone_db(s.as_mut(), 200.0, 0.25) < -40.0); + assert!(tone_db(s.as_mut(), 16000.0, 0.25).abs() < 0.5); +} + +#[test] +fn tube_compressor_levels() { + let mut e = fx("tube_compressor", &[("threshold", -30.0), ("ratio", 4.0)]); + // Low level: below the knee and practically linear. + assert!(tone_db(e.as_mut(), 1000.0, 0.005).abs() < 0.05); + // Above threshold: reduced roughly as the static curve says (RMS detector: sine RMS = peak − 3 dB). + let level_rms = -6.0 - 3.01; + let want = e.transfer_db(0, level_rms).unwrap() - level_rms; + let got = tone_db(e.as_mut(), 1000.0, 0.5); + assert!((got - want as f64).abs() < 1.5, "tube gain {got} vs static {want}"); +} + +#[test] +fn flanger_static_comb_notch() { + // initial = final: a fixed delay of d + 1 samples, mixed 50/50 → notch at fs / (2(d+1)). + let mut e = fx("flanger", &[("initial_delay", 1.0), ("final_delay", 1.0), ("feedback", 0.0), ("mix", 50.0)]); + let d = 48.0 + 1.0; + let notch = SR as f64 / (2.0 * d); + assert!(tone_db(e.as_mut(), notch, 0.3) < -30.0); + assert!(tone_db(e.as_mut(), 2.0 * notch, 0.3).abs() < 0.2); +} + +#[test] +fn chorus_flanger_and_phaser_modulate() { + for id in ["chorus_flanger", "phaser"] { + let mut e = fx(id, &[]); + let x = noise(7, SR as usize, 0.3); + let (y, _) = run(e.as_mut(), &x, &x); + let ratio = db(rms(&y) / rms(&x)); + assert!(ratio.abs() < 6.0, "{id}: level {ratio}"); + let diff: f64 = y.iter().zip(&x).map(|(a, b)| ((a - b) as f64).powi(2)).sum(); + assert!(diff > 1.0, "{id}: no effect"); + } + let mut cf = fx("chorus_flanger", &[("mode", 1.0)]); + let x = noise(8, 4800, 0.3); + let (y, _) = run(cf.as_mut(), &x, &x); + assert!(y.iter().all(|v| v.is_finite())); + // Static phaser (depth 0): 4 all-pass stages at 1 kHz, mixed 50/50 → a notch where the + // chain's phase is −180°, i.e. each stage −45°. + let mut ph = fx("phaser", &[("depth", 0.0), ("upper_freq", 1000.0), ("stages", 4.0), ("mix", 50.0)]); + let a = util::AllPass1::coef(1000.0, SR); + let phase = |f: f64| { + let w = 2.0 * std::f64::consts::PI * f / SR as f64; + // (a + e^{-jw}) / (1 + a e^{-jw}) + let (nr, ni) = (a + w.cos(), -w.sin()); + let (dr, di) = (1.0 + a * w.cos(), -a * w.sin()); + ni.atan2(nr) - di.atan2(dr) + }; + let (mut lo, mut hi) = (10.0, 1000.0); + for _ in 0..60 { + let mid = 0.5 * (lo + hi); + if 4.0 * phase(mid) > -std::f64::consts::PI { lo = mid } else { hi = mid } + } + assert!(tone_db(ph.as_mut(), lo, 0.3) < -25.0, "phaser notch at {lo}"); +} + +#[test] +fn delays_put_echoes_where_asked() { + let n = SR as usize; + let mut imp = vec![0.0f32; n]; + imp[0] = 1.0; + let mut e = fx("analog_delay", &[("delay", 100.0), ("feedback", 0.0), ("dry", 0.0), ("wet", 100.0), ("mode", 2.0)]); + let (y, _) = run(e.as_mut(), &imp, &imp); + let peak = y.iter().enumerate().max_by(|a, b| a.1.abs().total_cmp(&b.1.abs())).unwrap().0; + assert!((peak as i64 - 4800).abs() <= 3, "analog echo at {peak}"); + let mut m = fx( + "multitap_delay", + &[("delay1", 50.0), ("delay2", 120.0), ("level1", 0.0), ("level2", -6.0), ("level3", -96.0), ("level4", -96.0), ("mix", 100.0)], + ); + let (y, _) = run(m.as_mut(), &imp, &imp); + assert!((y[2400] - 1.0).abs() < 1e-4, "tap 1 {}", y[2400]); + assert!((y[5760] - db_to_gain(-6.0)).abs() < 1e-4, "tap 2 {}", y[5760]); + let elsewhere = y.iter().enumerate().filter(|(i, _)| *i != 2400 && *i != 5760).fold(0.0f32, |a, (_, v)| a.max(v.abs())); + assert!(elsewhere < 1e-6); + // Feedback repeats. + let mut f = fx( + "multitap_delay", + &[("delay1", 50.0), ("feedback1", 50.0), ("level1", 0.0), ("level2", -96.0), ("level3", -96.0), ("level4", -96.0), ("mix", 100.0)], + ); + let (y, _) = run(f.as_mut(), &imp, &imp); + assert!((y[4800] - 0.5).abs() < 1e-4 && (y[7200] - 0.25).abs() < 1e-4); +} + +/// RT60 by Schroeder backward integration (−5 … −25 dB fit, extrapolated). +fn rt60(ir: &[f32]) -> f64 { + let mut e: Vec = ir.iter().map(|&v| (v as f64) * (v as f64)).collect(); + for i in (0..e.len() - 1).rev() { + e[i] += e[i + 1]; + } + let total = e[0]; + let t = |level: f64| e.iter().position(|&v| 10.0 * (v / total).log10() < level).unwrap_or(e.len()) as f64 / SR as f64; + (t(-25.0) - t(-5.0)) * 3.0 +} + +#[test] +fn convolution_reverb_impulses() { + for (k, want_rt) in [(0usize, 0.45), (2, 1.9), (4, 1.6)] { + let mut e = fx("convolution_reverb", &[("impulse", k as f32), ("mix", 100.0), ("width", 100.0)]); + let lat = e.latency(); + let n = (SR * 4.0) as usize; + let mut imp = vec![0.0f32; n]; + imp[0] = 1.0; + let (l, r) = run(e.as_mut(), &imp, &imp); + let (l, r) = (&l[lat..], &r[lat..]); + let el: f64 = l.iter().map(|&v| (v as f64).powi(2)).sum(); + assert!((el - 1.0).abs() < 0.02, "impulse {k}: energy {el}"); + let rt = rt60(l); + assert!((rt - want_rt).abs() < want_rt * 0.25, "impulse {k}: RT60 {rt} vs {want_rt}"); + // Decorrelated stereo. + let c: f64 = l.iter().zip(r).map(|(a, b)| (*a as f64) * (*b as f64)).sum(); + assert!(c.abs() < 0.3, "impulse {k}: L/R correlation {c}"); + } + // Room size shortens the tail. + let mut a = fx("convolution_reverb", &[("impulse", 2.0), ("mix", 100.0), ("room_size", 40.0)]); + let n = (SR * 3.0) as usize; + let mut imp = vec![0.0f32; n]; + imp[0] = 1.0; + let (l, _) = run(a.as_mut(), &imp, &imp); + let rt = rt60(&l[a.latency()..]); + assert!((rt - 0.76).abs() < 0.25, "scaled RT60 {rt}"); +} + +#[test] +fn surround_reverb_tail_decays() { + let mut e = fx("surround_reverb", &[("decay", 1.0), ("dry", 0.0), ("wet", 100.0)]); + let n = (SR * 3.0) as usize; + let mut imp = vec![0.0f32; n]; + imp[0] = 1.0; + let (l, r) = run(e.as_mut(), &imp, &imp); + let seg = |s: f32, e: f32| rms(&l[(s * SR) as usize..(e * SR) as usize]); + assert!(seg(0.05, 0.3) > 1e-4); + let drop = db(seg(1.6, 1.9) / seg(0.1, 0.4)); + assert!(drop < -45.0 && drop > -120.0, "RT60≈1 s: 1.5 s later {drop} dB"); + assert!(r.iter().all(|v| v.is_finite())); +} + +#[test] +fn click_remover_repairs_clicks() { + let n = SR as usize * 2; + let clean: Vec = sine(440.0, 0.3, SR as f64, n, 0.0).iter().zip(noise(9, n, 0.01)).map(|(a, b)| a + b).collect(); + let mut dirty = clean.clone(); + for k in 0..30 { + let at = 3000 + k * 3001; + dirty[at] += 0.6; + dirty[at + 1] -= 0.4; + } + let mut e = fx("click_remover", &[]); + let lat = e.latency(); + let (y, _) = run(e.as_mut(), &dirty, &dirty); + let err = |s: &[f32], off: usize| -> f64 { (lat + 2000..n).map(|i| ((s[i] - clean[i - off]) as f64).powi(2)).sum::().sqrt() }; + let before = err(&dirty[..], 0); + let after = err(&y, lat); + assert!(db(after / before) < -20.0, "error {before} → {after}"); +} + +#[test] +fn channel_and_stereo_tools() { + let n = 4800; + let l = noise(10, n, 0.3); + let r = noise(11, n, 0.3); + let mut sw = fx("channel_mixer", &[("l_from_l", 0.0), ("l_from_r", 100.0), ("r_from_l", 100.0), ("r_from_r", 0.0), ("invert_r", 1.0)]); + let (a, b) = run(sw.as_mut(), &l, &r); + assert!(a.iter().zip(&r).all(|(x, y)| (x - y).abs() < 1e-6)); + assert!(b.iter().zip(&l).all(|(x, y)| (x + y).abs() < 1e-6)); + let mut mono = fx("stereo_expander", &[("expand", 0.0)]); + let (a, b) = run(mono.as_mut(), &l, &r); + assert!(a.iter().zip(&b).all(|(x, y)| (x - y).abs() < 1e-6)); + let mut wide = fx("stereo_expander", &[("expand", 200.0), ("center_pan", 100.0)]); + let (a, b) = run(wide.as_mut(), &l, &l); + // center fully right: identical L/R input → nothing left + assert!(a.iter().all(|v| v.abs() < 1e-6) && b.iter().zip(&l).all(|(x, y)| (x - y).abs() < 1e-6)); + // Mute ramps to silence. + let mut m = fx("mute", &[("mute", 1.0)]); + let (a, _) = run(m.as_mut(), &l, &r); + assert!(a.iter().all(|v| *v == 0.0)); +} + +#[test] +fn distortion_harmonics() { + let n = SR as usize; + let x = sine(500.0, 0.5, SR as f64, n, 0.0); + let mut sym = fx("distortion", &[("drive", 24.0), ("curve", 1.0)]); + let (y, _) = run(sym.as_mut(), &x, &x); + let h = |s: &[f32], k: f64| tone_amplitude(&s[n / 2..], 500.0 * k, SR as f64); + assert!(h(&y, 3.0) > 0.1 * h(&y, 1.0), "hard clip makes odd harmonics"); + assert!(h(&y, 2.0) < 1e-3 * h(&y, 1.0), "symmetric: no even harmonics"); + let mut asym = fx("distortion", &[("drive", 24.0), ("symmetry", 60.0)]); + let (y, _) = run(asym.as_mut(), &x, &x); + assert!(h(&y, 2.0) > 0.02 * h(&y, 1.0), "asymmetric: even harmonics"); + // GuitarSuite with everything off is near-transparent at low level. + let mut gs = fx("guitar_suite", &[("compressor", 0.0), ("distortion", 0.0), ("amp", 0.0), ("filter", 0.0)]); + assert!(tone_db(gs.as_mut(), 1000.0, 0.01).abs() < 0.05); + let mut gs2 = fx("guitar_suite", &[]); + let (y, _) = run(gs2.as_mut(), &x, &x); + assert!(y.iter().all(|v| v.is_finite()) && rms(&y) > 0.01); +} + +#[test] +fn mastering_and_vocal_enhancer() { + let mut e = fx("mastering", &[("eq_low", 6.0)]); + assert!((e.response_db(20.0).unwrap() - 6.0).abs() < 0.3); + assert!((tone_db(e.as_mut(), 30.0, 0.1) - e.response_db(30.0).unwrap()).abs() < 0.1); + let n = SR as usize; + let x = noise(12, n, 0.3); + let mut loud = fx("mastering", &[("loudness", 100.0)]); + let (y, _) = run(loud.as_mut(), &x, &x); + assert!(y.iter().all(|v| v.abs() <= db_to_gain(-0.3) + 1e-6)); + assert!(rms(&y) > 1.5 * rms(&x)); + let mut v = fx("vocal_enhancer", &[("mode", 0.0)]); + assert!(v.response_db(40.0).unwrap() < -6.0); + assert!(v.response_db(3000.0).unwrap() > 2.0); + // Below the compressor threshold the measured response is the EQ. + assert!((tone_db(v.as_mut(), 3000.0, 0.02) - v.response_db(3000.0).unwrap()).abs() < 0.1); + let mut music = fx("vocal_enhancer", &[("mode", 2.0)]); + assert!(music.response_db(1500.0).unwrap() < -3.0); + assert!((tone_db(music.as_mut(), 1500.0, 0.3) - music.response_db(1500.0).unwrap()).abs() < 0.1); +} + +#[test] +fn binaural_and_ambisonic_rendering() { + let n = SR as usize; + // A correlated low tone stays at unity. + let mut b = fx("binauralizer", &[]); + assert!(tone_db(b.as_mut(), 100.0, 0.3).abs() < 0.5); + // Left-only input reaches the right ear later (interaural time difference). + let mut imp = vec![0.0f32; 2000]; + imp[100] = 1.0; + let zero = vec![0.0f32; 2000]; + let (l, r) = run(b.as_mut(), &imp, &zero); + let pk = |s: &[f32]| s.iter().enumerate().max_by(|a, b| a.1.abs().total_cmp(&b.1.abs())).unwrap().0; + let itd = pk(&r) as f64 - pk(&l) as f64; + let a = 0.0875f64; + let th = 30f64.to_radians(); + let want = a / 343.0 * (th + th.sin()) * SR as f64; + assert!((itd - want).abs() <= 1.5, "ITD {itd} samples vs {want}"); + assert!(l[pk(&l)].abs() > r[pk(&r)].abs(), "head shadow: far ear quieter"); + // Ambisonic pan 180°: the left source ends up on the right. + let mut p = fx("ambisonics_panner", &[("pan", 180.0)]); + let x = noise(13, n, 0.3); + let (l, r) = run(p.as_mut(), &x, &zero[..0].iter().copied().chain(std::iter::repeat_n(0.0, n)).collect::>()); + assert!(rms(&r) > 3.0 * rms(&l), "rotated: L {} R {}", rms(&l), rms(&r)); + let (g, _) = special::AmbisonicsPanner::source_gains(30.0, 0.0, 0.0, 0.0); + assert!((g - 1.0).abs() < 1e-6); +} + +#[test] +fn loudness_meter_passes_through_and_measures() { + let n = SR as usize * 3; + let x = sine(1000.0, 0.1, SR as f64, n, 0.0); + let mut m = special::LoudnessMeterFx::new(SR, 2); + let (mut a, mut b) = (x.clone(), x.clone()); + m.process(&mut [&mut a, &mut b]); + assert_eq!(a, x); + let mut reference = crate::LoudnessMeter::new(SR as f64, 2); + reference.process(&[&x, &x]); + assert!((m.meter().integrated() - reference.integrated()).abs() < 1e-9); + assert!(m.meter().integrated().is_finite()); + // In 5.1 the surround channel counts too. + let z = vec![0.0f32; n]; + let mut m = special::LoudnessMeterFx::new(SR, 6); + let mut io: Vec> = vec![z.clone(), z.clone(), z.clone(), z.clone(), x.clone(), z.clone()]; + m.process(&mut io.iter_mut().map(|c| &mut c[..]).collect::>()); + let mut reference = crate::LoudnessMeter::new(SR as f64, 6); + reference.process(&[&z, &z, &z, &z, &x, &z]); + assert!(reference.integrated().is_finite()); + assert!((m.meter().integrated() - reference.integrated()).abs() < 1e-9); +} + +/// The multiband compressor processes every channel of a 10-channel buffer alike. +#[test] +fn multiband_compressor_processes_every_channel() { + let x = sine(200.0, 0.8, SR as f64, 9_600, 0.0); + let mut e = multiband::MultibandCompressor::new(SR, 10); + let mut io: Vec> = vec![x.clone(); 10]; + e.process(&mut io.iter_mut().map(|c| &mut c[..]).collect::>()); + assert_ne!(io[0], x, "the first channel is unchanged"); + assert_eq!(io[9], io[0], "the tenth channel differs from the first"); +} + +/// A choice parameter with no choices, or a default past its list, does not panic. +#[test] +fn degenerate_parameter_specs() { + let p = crate::ParamSpec::choice("c", "C", &[], 3); + assert_eq!((p.min, p.max, p.default), (0.0, 0.0, 0.0)); + assert_eq!(p.sanitize(5.0), 0.0); + let p = crate::ParamSpec::new("x", "X", 10.0, -10.0, 0.0, crate::Unit::None); + assert_eq!(p.sanitize(3.0), -10.0); +} + +/// Delays and reverbs report a tail: an impulse still sounds just before it, and has fallen +/// below -50 dB after it. +#[test] +fn delays_and_reverbs_report_their_tails() { + for (id, params) in [ + ("delay", &[("feedback", 50.0), ("mix", 100.0)][..]), + ("analog_delay", &[("feedback", 50.0)][..]), + ("multitap_delay", &[("feedback2", 60.0)][..]), + ("reverb", &[("mix", 100.0)][..]), + ("convolution_reverb", &[("mix", 100.0)][..]), + ("surround_reverb", &[][..]), + ] { + let mut e = fx(id, params); + let tail = e.tail_samples(); + assert!(tail > SR as usize / 10, "{id}: tail {tail}"); + let n = e.latency() + tail + SR as usize / 2; + let mut x = vec![0.0f32; n]; + x[0] = 1.0; + let (a, b) = run(e.as_mut(), &x, &x); + let peak = |r: std::ops::Range| a[r.clone()].iter().chain(&b[r]).fold(0.0f32, |m, v| m.max(v.abs())); + let end = e.latency() + tail; + assert!(peak(end..n) < 0.003, "{id}: {} after a tail of {tail}", peak(end..n)); + assert!(peak(end / 2..end) > 1e-6, "{id}: silent well before the tail of {tail} ends"); + } +} + +/// Effects built directly, outside the registry, with a huge channel count are capped at +/// [`crate::MAX_CHANNELS`] channels instead of allocating without bound, and an unusable sample +/// rate is replaced. +#[test] +fn direct_constructors_cap_the_channel_count() { + fn check(new: fn(f32, usize) -> E, name: &str) { + let mut e = new(SR, usize::MAX); + let mut x = vec![0.1f32; 256]; + e.process(&mut [&mut x]); + assert!(x.iter().all(|v| v.is_finite()), "{name}"); + // Unusable rates are replaced as `sane_sample_rate` describes. + for rate in [f32::MAX, f32::INFINITY, f32::NAN, 0.0] { + let mut e = new(rate, 1); + let mut x = vec![0.1f32; 256]; + e.process(&mut [&mut x]); + assert!(x.iter().all(|v| v.is_finite()), "{name} at {rate}"); + } + } + macro_rules! huge { + ($($ty:ty),* $(,)?) => { + $(check(<$ty>::new, stringify!($ty));)* + }; + } + huge!( + declick::ClickRemover, + eq::ParametricEq, + essential::DeEsser, + essential::DeReverb, + essential::SpeechEnhance, + filters::FftFilter, + filters::ScientificFilter, + modulation::AnalogDelay, + modulation::ChorusFlanger, + modulation::Flanger, + modulation::MultitapDelay, + modulation::Phaser, + multiband::MultibandCompressor, + restoration::DeHum, + restoration::DeNoise, + reverbs::ConvolutionReverb, + special::Distortion, + special::GuitarSuite, + special::Mastering, + special::VocalEnhancer, + time::Delay, + time::Reverb, + reverbs::SurroundReverb, + special::StereoExpander, + special::Binauralizer, + special::LoudnessMeterFx, + multiband::DynamicsRack, + multiband::TubeCompressor, + channel::Amplify, + filters::FullParametricEq, + pitch::PitchShifter, + ); +} + +#[test] +#[ignore = "wall-clock timing: run with --ignored on an optimized build"] +fn realtime_factor_sanity() { + let secs = 2.0; + let n = (SR * secs) as usize; + let l = noise(14, n, 0.3); + let r = noise(15, n, 0.3); + let mut slowest = (f64::INFINITY, ""); + for e in effects() { + let mut f = (e.create)(SR, 2); + let (mut a, mut b) = (l.clone(), r.clone()); + let t0 = std::time::Instant::now(); + for (ca, cb) in a.chunks_mut(512).zip(b.chunks_mut(512)) { + f.process(&mut [ca, cb]); + } + let dt = t0.elapsed().as_secs_f64().max(1e-9); + let rtf = secs as f64 / dt; + if rtf < slowest.0 { + slowest = (rtf, e.id); + } + assert!(rtf > 1.0, "{}: only {rtf:.1}× realtime", e.id); + } + eprintln!("slowest effect: {} at {:.0}× realtime", slowest.1, slowest.0); +} + +fn gain_db(x: f32) -> f32 { + crate::gain_to_db(x) +} + +fn db_to_gain(x: f32) -> f32 { + crate::db_to_gain(x) +} diff --git a/crates/audio-dsp/src/effects/channel.rs b/crates/audio-dsp/src/effects/channel.rs new file mode 100644 index 000000000..af15b18ec --- /dev/null +++ b/crates/audio-dsp/src/effects/channel.rs @@ -0,0 +1,345 @@ +//! Gain and channel utilities: amplify, channel volume, balance/pan, invert, swap, fill. + +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing}; +use std::f32::consts::FRAC_PI_2; + +const RAMP_MS: f32 = 20.0; + +/// Amplify: one smoothed gain for all channels. +pub struct Amplify { + pv: ParamValues, + gain: Smoothed, +} + +impl Amplify { + pub const PARAMS: &'static [ParamSpec] = &[ParamSpec::new("gain", "Gain", -96.0, 24.0, 0.0, Unit::Decibels)]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = Amplify { pv: ParamValues::new(Self::PARAMS), gain: Smoothed::with_ms(1.0, sample_rate, RAMP_MS) }; + s.apply_params(true); + s + } + fn apply_params(&mut self, snap: bool) { + let db = self.pv.v("gain"); + self.gain.set(if db <= -96.0 { 0.0 } else { db_to_gain(db) }); + if snap { + self.gain.snap(); + } + } +} + +impl AudioEffect for Amplify { + param_plumbing!("amplify"); + fn reset(&mut self) { + self.gain.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + for i in 0..n { + let g = self.gain.tick(); + for ch in channels.iter_mut() { + ch[i] *= g; + } + } + } +} + +/// Per-channel volume (L R C LFE Ls Rs order). +pub struct ChannelVolume { + pv: ParamValues, + gains: [Smoothed; 6], +} + +const CHANNEL_IDS: [&str; 6] = ["left", "right", "center", "lfe", "left_surround", "right_surround"]; + +impl ChannelVolume { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("left", "Left", -96.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("right", "Right", -96.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("center", "Center", -96.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("lfe", "LFE", -96.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("left_surround", "Left Surround", -96.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("right_surround", "Right Surround", -96.0, 24.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = ChannelVolume { pv: ParamValues::new(Self::PARAMS), gains: [Smoothed::with_ms(1.0, sample_rate, RAMP_MS); 6] }; + s.apply_params(true); + s + } + fn apply_params(&mut self, snap: bool) { + for (g, id) in self.gains.iter_mut().zip(CHANNEL_IDS) { + let db = self.pv.v(id); + g.set(if db <= -96.0 { 0.0 } else { db_to_gain(db) }); + if snap { + g.snap(); + } + } + } +} + +impl AudioEffect for ChannelVolume { + param_plumbing!("channel_volume"); + fn reset(&mut self) { + self.gains.iter_mut().for_each(Smoothed::snap); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + for i in 0..n { + for (c, g) in self.gains.iter_mut().enumerate() { + let g = g.tick(); + if let Some(ch) = channels.get_mut(c) { + ch[i] *= g; + } + } + } + } +} + +/// Constant-power gains `(left, right)` for a pan position in −1 … +1 (center = −3 dB each). +pub fn constant_power_pan(p: f32) -> (f32, f32) { + let theta = (p.clamp(-1.0, 1.0) + 1.0) * 0.25 * std::f32::consts::PI; + (theta.cos(), theta.sin()) +} + +/// Balance gains for a stereo source: the side opposite the direction is attenuated with a +/// cosine (constant-power) law, the other side stays at unity. Center = unity both sides. +pub fn balance_gains(p: f32) -> (f32, f32) { + let p = p.clamp(-1.0, 1.0); + ((p.max(0.0) * FRAC_PI_2).cos(), ((-p).max(0.0) * FRAC_PI_2).cos()) +} + +/// Stereo balance / pan. "Balance" attenuates one side of a stereo source; "Pan" sums to mono +/// and positions it with the constant-power law (normalized so the center is unity for a +/// correlated source). +pub struct Balance { + pv: ParamValues, + gl: Smoothed, + gr: Smoothed, + pan_mode: bool, + mode_mix: Smoothed, +} + +impl Balance { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("balance", "Balance", -100.0, 100.0, 0.0, Unit::Pan), + ParamSpec::choice("mode", "Mode", &["Balance", "Pan (constant power)"], 0), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = Balance { + pv: ParamValues::new(Self::PARAMS), + gl: Smoothed::with_ms(1.0, sample_rate, RAMP_MS), + gr: Smoothed::with_ms(1.0, sample_rate, RAMP_MS), + pan_mode: false, + mode_mix: Smoothed::with_ms(0.0, sample_rate, RAMP_MS), + }; + s.apply_params(true); + s + } + fn apply_params(&mut self, snap: bool) { + let p = self.pv.v("balance") / 100.0; + self.pan_mode = self.pv.idx("mode") == 1; + let (l, r) = if self.pan_mode { + let (l, r) = constant_power_pan(p); + (l * std::f32::consts::SQRT_2, r * std::f32::consts::SQRT_2) + } else { + balance_gains(p) + }; + self.gl.set(l); + self.gr.set(r); + self.mode_mix.set(if self.pan_mode { 1.0 } else { 0.0 }); + if snap { + self.gl.snap(); + self.gr.snap(); + self.mode_mix.snap(); + } + } +} + +impl AudioEffect for Balance { + param_plumbing!("balance"); + fn reset(&mut self) { + self.gl.snap(); + self.gr.snap(); + self.mode_mix.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + if channels.len() < 2 { + return; + } + let (a, b) = channels.split_at_mut(1); + let (l, r) = (&mut a[0], &mut b[0]); + for i in 0..n { + let gl = self.gl.tick(); + let gr = self.gr.tick(); + let mm = self.mode_mix.tick(); + let mono = 0.5 * (l[i] + r[i]); + let il = l[i] + mm * (mono - l[i]); + let ir = r[i] + mm * (mono - r[i]); + l[i] = il * gl; + r[i] = ir * gr; + } + } +} + +/// Polarity inversion. +pub struct Invert { + pv: ParamValues, +} + +impl Invert { + pub const PARAMS: &'static [ParamSpec] = &[ParamSpec::choice("channels", "Channels", &["All", "Left", "Right"], 0)]; + pub fn new(_sample_rate: f32, _channels: usize) -> Self { + Invert { pv: ParamValues::new(Self::PARAMS) } + } + fn apply_params(&mut self, _snap: bool) {} +} + +impl AudioEffect for Invert { + param_plumbing!("invert"); + fn reset(&mut self) {} + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let which = self.pv.idx("channels"); + for (c, ch) in channels.iter_mut().enumerate() { + if which == 0 || which == c + 1 { + ch[..n].iter_mut().for_each(|v| *v = -*v); + } + } + } +} + +/// Parameterless channel routing utilities. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Routing { + /// Swap left and right. + Swap, + /// Fill left with right. + FillLeft, + /// Fill right with left. + FillRight, +} + +/// Swap / Fill Left with Right / Fill Right with Left. +pub struct Route { + pv: ParamValues, + kind: Routing, +} + +impl Route { + pub const PARAMS: &'static [ParamSpec] = &[]; + pub fn new(kind: Routing) -> Self { + Route { pv: ParamValues::new(Self::PARAMS), kind } + } + fn apply_params(&mut self, _snap: bool) {} +} + +impl AudioEffect for Route { + fn id(&self) -> &'static str { + match self.kind { + Routing::Swap => "swap_channels", + Routing::FillLeft => "fill_left", + Routing::FillRight => "fill_right", + } + } + fn params(&self) -> &'static [ParamSpec] { + Self::PARAMS + } + fn set_param(&mut self, id: &str, value: f32) -> bool { + let ok = self.pv.set(id, value); + self.apply_params(false); + ok + } + fn param(&self, id: &str) -> Option { + self.pv.get(id) + } + fn reset(&mut self) {} + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + if channels.len() < 2 { + return; + } + let (a, b) = channels.split_at_mut(1); + let (l, r) = (&mut a[0][..n], &mut b[0][..n]); + match self.kind { + Routing::Swap => l.swap_with_slice(r), + Routing::FillLeft => l.copy_from_slice(r), + Routing::FillRight => r.copy_from_slice(l), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn amplify_reaches_exact_gain() { + let mut a = Amplify::new(48000.0, 2); + a.set_param("gain", -6.0); + let mut l = vec![1.0f32; 2000]; + let mut r = vec![0.5f32; 2000]; + a.process(&mut [&mut l, &mut r]); + assert!((l[1999] - db_to_gain(-6.0)).abs() < 1e-6); + assert!((r[1999] - 0.5 * db_to_gain(-6.0)).abs() < 1e-6); + // Smoothed, not stepped. + assert!(l[0] > 0.99); + a.set_param("gain", -96.0); + a.process(&mut [&mut l, &mut r]); + assert_eq!(l[1999], 0.0); + } + + #[test] + fn channel_volume_per_channel() { + let mut c = ChannelVolume::new(48000.0, 2); + c.set_param("right", -20.0); + c.reset(); + let mut l = vec![1.0f32; 10]; + let mut r = vec![1.0f32; 10]; + c.process(&mut [&mut l, &mut r]); + assert_eq!(l[5], 1.0); + assert!((r[5] - 0.1).abs() < 1e-6); + } + + #[test] + fn pan_is_constant_power() { + for i in -10..=10 { + let (l, r) = constant_power_pan(i as f32 / 10.0); + assert!((l * l + r * r - 1.0).abs() < 1e-6); + } + assert_eq!(balance_gains(0.0), (1.0, 1.0)); + let (l, r) = balance_gains(1.0); + assert!(l.abs() < 1e-6 && r == 1.0); + let mut b = Balance::new(48000.0, 2); + b.set_param("mode", 1.0); + b.set_param("balance", 100.0); + b.reset(); + let mut l = vec![0.5f32; 4]; + let mut r = vec![0.5f32; 4]; + b.process(&mut [&mut l, &mut r]); + assert!(l[3].abs() < 1e-6); + assert!((r[3] - 0.5 * std::f32::consts::SQRT_2).abs() < 1e-6); + } + + #[test] + fn invert_swap_fill() { + let mut l = vec![1.0f32, 2.0]; + let mut r = vec![3.0f32, 4.0]; + Route::new(Routing::Swap).process(&mut [&mut l, &mut r]); + assert_eq!((l.clone(), r.clone()), (vec![3.0, 4.0], vec![1.0, 2.0])); + Route::new(Routing::FillLeft).process(&mut [&mut l, &mut r]); + assert_eq!(l, vec![1.0, 2.0]); + l[0] = 9.0; + Route::new(Routing::FillRight).process(&mut [&mut l, &mut r]); + assert_eq!(r, vec![9.0, 2.0]); + let mut inv = Invert::new(48000.0, 2); + inv.set_param("channels", 2.0); + inv.process(&mut [&mut l, &mut r]); + assert_eq!((l, r), (vec![9.0, 2.0], vec![-9.0, -2.0])); + } +} diff --git a/crates/audio-dsp/src/effects/declick.rs b/crates/audio-dsp/src/effects/declick.rs new file mode 100644 index 000000000..988816e7e --- /dev/null +++ b/crates/audio-dsp/src/effects/declick.rs @@ -0,0 +1,237 @@ +//! Automatic Click Remover: clicks are found as outliers of the linear-prediction residual and +//! replaced by autoregressive interpolation. +//! +//! Textbook method (Vaseghi & Rayner style): per 512-sample block an order-`p` LPC model is fitted +//! (autocorrelation + Levinson–Durbin over a Hann-windowed 1152-sample analysis span); samples +//! whose prediction error exceeds `k·σ` (σ from the median absolute residual) mark a click, +//! nearby marks are merged, and each region is re-synthesized by forward prediction from the +//! clean past and backward prediction from the future, cross-faded. Regions longer than the +//! maximum click length are left alone (they are transients, not clicks). Latency is one block +//! plus the look-ahead. + +use crate::{AudioEffect, ParamSpec, ParamValues, Unit, block_len, param_plumbing}; + +const BLOCK: usize = 512; +const CONTEXT: usize = 512; +const LOOKAHEAD: usize = 128; +const SPAN: usize = CONTEXT + BLOCK + LOOKAHEAD; +const MAX_ORDER: usize = 32; + +#[derive(Clone, Debug)] +struct Chan { + buf: Vec, + out: Vec, + pos: usize, +} + +impl Chan { + fn new() -> Chan { + Chan { buf: vec![0.0; SPAN], out: vec![0.0; BLOCK], pos: 0 } + } + fn reset(&mut self) { + self.buf.iter_mut().for_each(|v| *v = 0.0); + self.out.iter_mut().for_each(|v| *v = 0.0); + self.pos = 0; + } +} + +/// Shared analysis scratch. +#[derive(Clone, Debug)] +struct Scratch { + win: Vec, + xw: Vec, + resid: Vec, + sorted: Vec, + marks: Vec, +} + +/// LPC coefficients `a[1..=p]` (prediction x̂[n] = Σ a_k x[n−k]) by Levinson–Durbin. +/// Returns `false` for silent / degenerate input. +fn lpc(x: &[f64], p: usize, a: &mut [f64; MAX_ORDER + 1]) -> bool { + let mut r = [0.0f64; MAX_ORDER + 1]; + for (k, rk) in r.iter_mut().enumerate().take(p + 1) { + *rk = x[k..].iter().zip(x).map(|(u, v)| u * v).sum(); + } + if !r[0].is_finite() || r[0] <= 1e-12 { + return false; + } + r[0] *= 1.0 + 1e-6; // white-noise correction + let mut e = r[0]; + let mut tmp = [0.0f64; MAX_ORDER + 1]; + *a = [0.0; MAX_ORDER + 1]; + for i in 1..=p { + let mut acc = r[i]; + for j in 1..i { + acc -= a[j] * r[i - j]; + } + let k = acc / e; + tmp[..i].copy_from_slice(&a[..i]); + a[i] = k; + for j in 1..i { + a[j] = tmp[j] - k * tmp[i - j]; + } + e *= 1.0 - k * k; + if e <= 1e-15 { + return false; + } + } + true +} + +/// Automatic click remover. +pub struct ClickRemover { + pv: ParamValues, + ch: Vec, + s: Scratch, + /// Number of clicks repaired so far (for metering / tests). + pub repaired: usize, +} + +impl ClickRemover { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("threshold", "Threshold", 1.0, 100.0, 30.0, Unit::None), + ParamSpec::new("complexity", "Complexity", 1.0, 100.0, 16.0, Unit::None), + ]; + + pub fn new(_sample_rate: f32, channels: usize) -> Self { + let win = (0..SPAN).map(|i| (0.5 - 0.5 * (2.0 * std::f64::consts::PI * (i as f64 + 0.5) / SPAN as f64).cos()) as f32).collect(); + ClickRemover { + pv: ParamValues::new(Self::PARAMS), + ch: vec![Chan::new(); crate::sane_channels(channels)], + s: Scratch { win, xw: vec![0.0; SPAN], resid: vec![0.0; SPAN], sorted: vec![0.0; SPAN], marks: vec![false; SPAN] }, + repaired: 0, + } + } + fn apply_params(&mut self, _snap: bool) {} + + /// Detection factor k (residual outliers above k·σ are clicks). + fn k(&self) -> f32 { + 4.0 + 0.2 * self.pv.v("threshold") + } + fn order(&self) -> usize { + (8.0 + 24.0 * (self.pv.v("complexity") - 1.0) / 99.0).round() as usize + } + fn max_len(&self) -> usize { + (16.0 + 48.0 * (self.pv.v("complexity") - 1.0) / 99.0).round() as usize + } + + fn analyze(c: &mut Chan, s: &mut Scratch, p: usize, k: f32, max_len: usize) -> usize { + let buf = &mut c.buf; + for i in 0..SPAN { + s.xw[i] = (buf[i] * s.win[i]) as f64; + } + let mut a = [0.0f64; MAX_ORDER + 1]; + if !lpc(&s.xw, p, &mut a) { + return 0; + } + // Prediction residual over the span. + for n in 0..SPAN { + s.resid[n] = if n < p { + 0.0 + } else { + let mut pred = 0.0f64; + for j in 1..=p { + pred += a[j] * buf[n - j] as f64; + } + (buf[n] as f64 - pred) as f32 + }; + } + for n in 0..SPAN { + s.sorted[n] = s.resid[n].abs(); + } + let valid = &mut s.sorted[p..]; + let mid = valid.len() / 2; + valid.select_nth_unstable_by(mid, |x, y| x.total_cmp(y)); + let sigma = valid[mid] / 0.6745; + if sigma <= 1e-9 { + return 0; + } + let thr = k * sigma; + s.marks.iter_mut().for_each(|m| *m = false); + let mut n = CONTEXT; + let mut repaired = 0; + while n < CONTEXT + BLOCK { + if s.resid[n].abs() <= thr { + n += 1; + continue; + } + // Group outliers separated by ≤ 4 samples. + let first = n; + let mut last = n; + let mut m = n + 1; + while m < SPAN - p && m <= last + 4 { + if s.resid[m].abs() > thr { + last = m; + } + m += 1; + } + let start = first.saturating_sub(2).max(p); + let end = (last + 3).min(SPAN - p - 1); + n = last + 1; + if end <= start || end - start > max_len { + continue; + } + // Forward prediction from the (clean) past. + let len = end - start; + let mut fwd = [0.0f32; 80]; + let mut bwd = [0.0f32; 80]; + for t in 0..len { + let i = start + t; + let mut pred = 0.0f64; + for j in 1..=p { + let v = if i - j >= start { fwd[i - j - start] } else { buf[i - j] }; + pred += a[j] * v as f64; + } + fwd[t] = pred as f32; + } + // Backward prediction from the future (stationary AR: same coefficients reversed). + for t in (0..len).rev() { + let i = start + t; + let mut pred = 0.0f64; + for j in 1..=p { + let v = if i + j < end { bwd[i + j - start] } else { buf[i + j] }; + pred += a[j] * v as f64; + } + bwd[t] = pred as f32; + } + for t in 0..len { + let w = (t + 1) as f32 / (len + 1) as f32; + buf[start + t] = (1.0 - w) * fwd[t] + w * bwd[t]; + } + repaired += 1; + } + repaired + } +} + +impl AudioEffect for ClickRemover { + param_plumbing!("click_remover"); + fn latency(&self) -> usize { + BLOCK + LOOKAHEAD + } + fn reset(&mut self) { + self.ch.iter_mut().for_each(Chan::reset); + self.repaired = 0; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.ch.len()); + let (p, k, max_len) = (self.order(), self.k(), self.max_len().min(80)); + for (ci, chan) in channels.iter_mut().enumerate().take(nch) { + let c = &mut self.ch[ci]; + for v in chan[..n].iter_mut() { + let x = *v; + *v = c.out[c.pos]; + c.buf[SPAN - BLOCK + c.pos] = x; + c.pos += 1; + if c.pos == BLOCK { + c.pos = 0; + self.repaired += Self::analyze(c, &mut self.s, p, k, max_len); + // Emit the finished block, then slide the span. + c.out.copy_from_slice(&c.buf[CONTEXT..CONTEXT + BLOCK]); + c.buf.copy_within(BLOCK.., 0); + } + } + } + } +} diff --git a/crates/audio-dsp/src/effects/dither.rs b/crates/audio-dsp/src/effects/dither.rs new file mode 100644 index 000000000..5eb609bea --- /dev/null +++ b/crates/audio-dsp/src/effects/dither.rs @@ -0,0 +1,127 @@ +//! Dither: requantization to 16, 20 or 24 bits with triangular (TPDF) dither and optional +//! first-order noise shaping, for the last step before a fixed-point file or encoder. + +use crate::generator::Noise; +use crate::{AudioEffect, MAX_CHANNELS, ParamSpec, ParamValues, block_len, param_plumbing}; + +/// TPDF dither and requantization. Each output sample is a multiple of the target word length's +/// step (2^(1 - bits)) within -1 ..= 1 - step. With noise shaping, each channel's quantization +/// error is fed back into its next sample, which moves the noise toward high frequencies. +/// Digital silence stays silent, and a non-finite sample becomes 0. +pub struct Dither { + pv: ParamValues, + noise: Noise, + lsb: f32, + shape: bool, + err: Vec, +} + +impl Dither { + pub const PARAMS: &'static [ParamSpec] = + &[ParamSpec::choice("bits", "Bit Depth", &["16", "20", "24"], 0), ParamSpec::toggle("noise_shaping", "Noise Shaping", false)]; + + pub fn new(_sample_rate: f32, channels: usize) -> Self { + let mut s = Dither { + pv: ParamValues::new(Self::PARAMS), + noise: Noise::new(0xD17E), + lsb: 0.0, + shape: false, + err: vec![0.0; channels.clamp(1, MAX_CHANNELS)], + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, _snap: bool) { + let bits = [16.0f32, 20.0, 24.0].get(self.pv.idx("bits")).copied().unwrap_or(16.0); + self.lsb = 2f32.powf(1.0 - bits); + self.shape = self.pv.on("noise_shaping"); + } +} + +impl AudioEffect for Dither { + param_plumbing!("dither"); + fn reset(&mut self) { + self.err.iter_mut().for_each(|e| *e = 0.0); + self.noise = Noise::new(0xD17E); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let lsb = self.lsb; + // Frame by frame, so the noise sequence does not depend on how the stream is cut. + for i in 0..n { + for (ch, e) in channels.iter_mut().zip(self.err.iter_mut()) { + let x = &mut ch[i]; + if *x == 0.0 || !x.is_finite() { + *x = 0.0; + *e = 0.0; + continue; + } + // Full scale bounds the input, so the error fed back stays within a few steps. + let x0 = x.clamp(-1.0, 1.0); + let v = if self.shape { x0 - *e } else { x0 }; + let d = (self.noise.bipolar() + self.noise.bipolar()) * 0.5 * lsb; + let q = ((v + d) / lsb).round() * lsb; + *e = q - v; + *x = q.clamp(-1.0, 1.0 - lsb); + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::{Rng, rms}; + + #[test] + fn output_sits_on_the_16_bit_grid_with_tpdf_noise() { + let mut d = Dither::new(48_000.0, 1); + let mut r = Rng::new(3); + let src: Vec = (0..96_000).map(|_| r.uniform() * 0.5).collect(); + let mut x = src.clone(); + d.process(&mut [&mut x]); + let lsb = 2f32.powi(-15); + assert!(x.iter().all(|v| (v / lsb - (v / lsb).round()).abs() < 1e-3)); + // TPDF dither of 2 LSB peak to peak plus rounding: the error's RMS is about 0.5 LSB. + let err: Vec = x.iter().zip(&src).map(|(a, b)| a - b).collect(); + let e = rms(&err) / f64::from(lsb); + assert!((0.4..0.65).contains(&e), "error RMS {e} LSB"); + assert!(err.iter().all(|v| v.abs() <= 1.5 * lsb)); + } + + #[test] + fn silence_stays_silent_and_nan_is_zeroed() { + let mut d = Dither::new(48_000.0, 2); + let (mut a, mut b) = (vec![0.0f32; 512], vec![f32::NAN; 512]); + d.process(&mut [&mut a, &mut b]); + assert!(a.iter().chain(&b).all(|v| *v == 0.0)); + } + + #[test] + fn huge_samples_with_noise_shaping_stay_on_the_grid() { + let mut d = Dither::new(48_000.0, 1); + assert!(d.set_param("noise_shaping", 1.0)); + let mut x = vec![f32::MAX, -f32::MAX, 0.25, 0.25, 1e30, 0.1]; + d.process(&mut [&mut x]); + let lsb = 2f32.powi(-15); + assert!(x.iter().all(|v| v.is_finite() && (-1.0..=1.0 - lsb).contains(v)), "{x:?}"); + assert!((x[2] - 0.25).abs() < 4.0 * lsb && (x[5] - 0.1).abs() < 4.0 * lsb, "{x:?}"); + } + + #[test] + fn noise_shaping_moves_the_error_up_in_frequency() { + let run = |shape: bool| { + let mut d = Dither::new(48_000.0, 1); + assert!(d.set_param("noise_shaping", if shape { 1.0 } else { 0.0 })); + let src: Vec = (0..48_000).map(|i| 0.25 * (i as f32 * 0.01).sin()).collect(); + let mut x = src.clone(); + d.process(&mut [&mut x]); + let err: Vec = x.iter().zip(&src).map(|(a, b)| a - b).collect(); + // Low-frequency share of the error: a 32-sample moving average keeps below ~1.5 kHz. + let low: Vec = err.windows(32).map(|w| w.iter().sum::() / 32.0).collect(); + rms(&low) + }; + assert!(run(true) < run(false) * 0.5); + } +} diff --git a/crates/audio-dsp/src/effects/dynamics.rs b/crates/audio-dsp/src/effects/dynamics.rs new file mode 100644 index 000000000..fecada85e --- /dev/null +++ b/crates/audio-dsp/src/effects/dynamics.rs @@ -0,0 +1,904 @@ +//! Dynamics: compressor, expander/gate, look-ahead true-peak limiter and the maximizer. +//! +//! Detection is stereo-linked (the loudest channel drives one common gain) so the image does +//! not shift. Gain computers work in dB; attack/release are one-pole smoothers on the gain. +//! The compressor and the gate take a key input ([`AudioEffect::process_keyed`]): when one is +//! given, the loudest key channel drives the detector instead of the processed channels. + +use super::util::{coef, lin_db}; +use crate::oversample::{Interpolator, PolyphaseBank, true_peak_factor}; +use crate::{AudioEffect, MAX_CHANNELS, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing, sane_sample_rate, usable_key}; +use std::collections::VecDeque; + +/// Channels of key input the compressor and the gate read. +const KEY_CHANNELS: usize = 2; + +/// The detector's input for frame `i`: the loudest absolute value and the largest square over +/// the key channels when a key is given, else over the processed channels. +#[inline] +fn detect(channels: &[&mut [f32]], key: Option<&[&[f32]]>, i: usize) -> (f32, f32) { + let mut peak = 0.0f32; + let mut sq = 0.0f32; + let mut take = |x: f32| { + if x.is_finite() { + peak = peak.max(x.abs()); + sq = sq.max(x * x); + } + }; + match key { + Some(key) => key.iter().take(KEY_CHANNELS).for_each(|k| take(k[i])), + None => channels.iter().for_each(|c| take(c[i])), + } + (peak, sq) +} + +/// Static compressor curve with a quadratic soft knee (output level in dB for input level `x`). +pub fn compressor_curve(x: f32, threshold: f32, ratio: f32, knee: f32) -> f32 { + let d = x - threshold; + if knee > 0.0 && 2.0 * d.abs() <= knee { + x + (1.0 / ratio - 1.0) * (d + knee / 2.0).powi(2) / (2.0 * knee) + } else if d > 0.0 { + threshold + d / ratio + } else { + x + } +} + +/// Static downward-expander curve (output level in dB), attenuation limited to `range` dB. +pub fn expander_curve(x: f32, threshold: f32, ratio: f32, range: f32) -> f32 { + if x >= threshold { x } else { x + ((x - threshold) * (ratio - 1.0)).max(-range) } +} + +// --------------------------------------------------------------------------------------------- + +/// Feed-forward compressor (peak or RMS detector, soft knee, attack/release, make-up gain). +pub struct Compressor { + pv: ParamValues, + sr: f32, + threshold: f32, + ratio: f32, + knee: f32, + rms: bool, + att: f32, + rel: f32, + rms_coef: f32, + makeup: Smoothed, + /// Detector mean square (RMS mode). + ms: f32, + /// Smoothed gain reduction (dB, ≤ 0). + env: f32, + gr_meter: f32, +} + +impl Compressor { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("threshold", "Threshold", -60.0, 0.0, -20.0, Unit::Decibels), + ParamSpec::new("ratio", "Ratio", 1.0, 30.0, 4.0, Unit::Ratio), + ParamSpec::new("knee", "Knee", 0.0, 24.0, 6.0, Unit::Decibels), + ParamSpec::log("attack", "Attack", 0.01, 300.0, 10.0, Unit::Milliseconds), + ParamSpec::log("release", "Release", 1.0, 3000.0, 100.0, Unit::Milliseconds), + ParamSpec::new("makeup", "Make-up Gain", -40.0, 40.0, 0.0, Unit::Decibels), + ParamSpec::choice("detector", "Detector", &["Peak", "RMS"], 0), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = sane_sample_rate(sample_rate); + let mut s = Compressor { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + threshold: 0.0, + ratio: 1.0, + knee: 0.0, + rms: false, + att: 0.0, + rel: 0.0, + rms_coef: coef(10.0, sample_rate), + makeup: Smoothed::with_ms(1.0, sample_rate, 20.0), + ms: 0.0, + env: 0.0, + gr_meter: 0.0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.threshold = self.pv.v("threshold"); + self.ratio = self.pv.v("ratio"); + self.knee = self.pv.v("knee"); + self.att = coef(self.pv.v("attack"), self.sr); + self.rel = coef(self.pv.v("release"), self.sr); + self.rms = self.pv.idx("detector") == 1; + self.makeup.set(db_to_gain(self.pv.v("makeup"))); + if snap { + self.makeup.snap(); + } + } + + /// Static curve at the current settings. + pub fn curve(&self, x_db: f32) -> f32 { + compressor_curve(x_db, self.threshold, self.ratio, self.knee) + } + + fn run(&mut self, channels: &mut [&mut [f32]], key: &[&[f32]]) { + let n = block_len(channels); + let key = usable_key(key, n); + let mut deepest = 0.0f32; + for i in 0..n { + let (peak, sq) = detect(channels, key, i); + let level_db = if self.rms { + self.ms = self.rms_coef * self.ms + (1.0 - self.rms_coef) * sq; + if !(1e-30..=f32::MAX).contains(&self.ms) { + self.ms = 0.0; + } + 10.0 * self.ms.max(1e-20).log10() + } else { + lin_db(peak) + }; + let target = self.curve(level_db) - level_db; + let c = if target < self.env { self.att } else { self.rel }; + self.env = c * self.env + (1.0 - c) * target; + if !(1e-9..=f32::MAX).contains(&self.env.abs()) { + self.env = 0.0; + } + deepest = deepest.min(self.env); + let g = db_to_gain(self.env) * self.makeup.tick(); + for ch in channels.iter_mut() { + ch[i] *= g; + } + } + if n > 0 { + self.gr_meter = -deepest; + } + } +} + +impl AudioEffect for Compressor { + param_plumbing!("compressor"); + fn transfer_db(&self, band: usize, input_db: f32) -> Option { + (band == 0).then(|| self.curve(input_db) + self.pv.v("makeup")) + } + fn reset(&mut self) { + self.makeup.snap(); + self.ms = 0.0; + self.env = 0.0; + self.gr_meter = 0.0; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + self.run(channels, &[]); + } + fn key_channels(&self) -> usize { + KEY_CHANNELS + } + fn process_keyed(&mut self, channels: &mut [&mut [f32]], key: &[&[f32]]) { + self.run(channels, key); + } + /// The deepest gain reduction during the last block, in dB (≥ 0). + fn gain_reduction_db(&self) -> f32 { + self.gr_meter + } +} + +// --------------------------------------------------------------------------------------------- + +/// Downward expander / noise gate with hold (ratio ≥ 10 behaves as a gate). +pub struct Gate { + pv: ParamValues, + sr: f32, + threshold: f32, + ratio: f32, + range: f32, + att: f32, + rel: f32, + hold: u32, + hold_left: u32, + env: f32, + gr_meter: f32, +} + +impl Gate { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("threshold", "Threshold", -90.0, 0.0, -40.0, Unit::Decibels), + ParamSpec::log("ratio", "Ratio", 1.0, 100.0, 10.0, Unit::Ratio), + ParamSpec::new("range", "Range", 0.0, 90.0, 60.0, Unit::Decibels), + ParamSpec::log("attack", "Attack", 0.01, 100.0, 1.0, Unit::Milliseconds), + ParamSpec::new("hold", "Hold", 0.0, 2000.0, 50.0, Unit::Milliseconds), + ParamSpec::log("release", "Release", 1.0, 3000.0, 150.0, Unit::Milliseconds), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = sane_sample_rate(sample_rate); + let mut s = Gate { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + threshold: 0.0, + ratio: 1.0, + range: 0.0, + att: 0.0, + rel: 0.0, + hold: 0, + hold_left: 0, + env: 0.0, + gr_meter: 0.0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, _snap: bool) { + self.threshold = self.pv.v("threshold"); + self.ratio = self.pv.v("ratio"); + self.range = self.pv.v("range"); + self.att = coef(self.pv.v("attack"), self.sr); + self.rel = coef(self.pv.v("release"), self.sr); + self.hold = (self.pv.v("hold") * 0.001 * self.sr) as u32; + } + + pub fn curve(&self, x_db: f32) -> f32 { + expander_curve(x_db, self.threshold, self.ratio, self.range) + } +} + +impl AudioEffect for Gate { + param_plumbing!("gate"); + fn transfer_db(&self, band: usize, input_db: f32) -> Option { + (band == 0).then(|| self.curve(input_db)) + } + fn reset(&mut self) { + self.env = 0.0; + self.hold_left = 0; + self.gr_meter = 0.0; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + self.run(channels, &[]); + } + fn key_channels(&self) -> usize { + KEY_CHANNELS + } + fn process_keyed(&mut self, channels: &mut [&mut [f32]], key: &[&[f32]]) { + self.run(channels, key); + } + /// The deepest attenuation during the last block, in dB (≥ 0). + fn gain_reduction_db(&self) -> f32 { + self.gr_meter + } +} + +impl Gate { + fn run(&mut self, channels: &mut [&mut [f32]], key: &[&[f32]]) { + let n = block_len(channels); + let key = usable_key(key, n); + let mut deepest = 0.0f32; + for i in 0..n { + let (peak, _) = detect(channels, key, i); + let level = lin_db(peak); + let target = self.curve(level) - level; + if target >= self.env { + // Opening (or staying open): attack. + self.env = self.att * self.env + (1.0 - self.att) * target; + if target >= 0.0 { + self.hold_left = self.hold; + } + } else if self.hold_left > 0 { + self.hold_left -= 1; + } else { + self.env = self.rel * self.env + (1.0 - self.rel) * target; + if !self.env.is_finite() { + self.env = 0.0; + } + } + deepest = deepest.min(self.env); + let g = db_to_gain(self.env); + for ch in channels.iter_mut() { + ch[i] *= g; + } + } + if n > 0 { + self.gr_meter = -deepest; + } + } +} + +// --------------------------------------------------------------------------------------------- + +/// Look-ahead brick-wall limiter. +/// +/// The required gain for each (optionally true-peak) detected sample is held for the look-ahead +/// window with a sliding minimum, released with a one-pole, and then smoothed with a moving +/// average exactly as long as the look-ahead, so the gain has reached its target when the peak +/// leaves the delay line. A final clip at the ceiling guarantees the sample peak never exceeds it. +pub struct Limiter { + pv: ParamValues, + sr: f32, + in_gain: Smoothed, + ceiling: f32, + rel: f32, + true_peak: bool, + /// Look-ahead (samples) and detector alignment delay. + look: usize, + det_delay: usize, + bank: PolyphaseBank, + interp: Vec, + /// Per-channel delay line (ring), length `look + det_delay + 1`. + delay: Vec>, + wpos: usize, + /// Monotonic deque for the sliding minimum: (sample index, gain). + minq: VecDeque<(u64, f32)>, + /// Box filter ring and running sum. + box_ring: Vec, + box_pos: usize, + box_sum: f64, + rel_state: f32, + t: u64, + gr_meter: f32, +} + +impl Limiter { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("input_gain", "Input Boost", 0.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("ceiling", "Ceiling", -24.0, 0.0, -1.0, Unit::Decibels), + ParamSpec::log("release", "Release", 1.0, 1000.0, 60.0, Unit::Milliseconds), + ParamSpec::toggle("true_peak", "True Peak", true), + ]; + /// Fixed look-ahead time. + pub const LOOKAHEAD_MS: f32 = 5.0; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = sane_sample_rate(sample_rate); + let channels = channels.clamp(1, MAX_CHANNELS); + let bank = PolyphaseBank::new(true_peak_factor(sample_rate as f64).max(2)); + let look = ((Self::LOOKAHEAD_MS * 0.001 * sample_rate).round() as usize).max(1); + let det_delay = bank.delay(); + let dlen = look + det_delay + 1; + let mut s = Limiter { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + in_gain: Smoothed::with_ms(1.0, sample_rate, 20.0), + ceiling: 1.0, + rel: 0.0, + true_peak: true, + look, + det_delay, + bank, + interp: vec![Interpolator::default(); channels], + delay: vec![vec![0.0; dlen]; channels], + wpos: 0, + minq: VecDeque::with_capacity(look + 2), + box_ring: vec![1.0; look + 1], + box_pos: 0, + box_sum: (look + 1) as f64, + rel_state: 1.0, + t: 0, + gr_meter: 0.0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.in_gain.set(db_to_gain(self.pv.v("input_gain"))); + self.ceiling = db_to_gain(self.pv.v("ceiling")); + self.rel = coef(self.pv.v("release"), self.sr); + self.true_peak = self.pv.on("true_peak"); + if snap { + self.in_gain.snap(); + } + } +} + +impl AudioEffect for Limiter { + param_plumbing!("limiter"); + fn latency(&self) -> usize { + self.look + self.det_delay + } + /// The deepest gain reduction during the last block, in dB (≥ 0). + fn gain_reduction_db(&self) -> f32 { + self.gr_meter + } + fn reset(&mut self) { + self.in_gain.snap(); + self.interp.iter_mut().for_each(Interpolator::reset); + self.delay.iter_mut().for_each(|d| d.iter_mut().for_each(|v| *v = 0.0)); + self.wpos = 0; + self.minq.clear(); + self.box_ring.iter_mut().for_each(|v| *v = 1.0); + self.box_pos = 0; + self.box_sum = self.box_ring.len() as f64; + self.rel_state = 1.0; + self.t = 0; + self.gr_meter = 0.0; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.delay.len()); + let dlen = self.delay[0].len(); + let window = (self.look + 1) as u64; + let mut min_g = None::; + for i in 0..n { + let g_in = self.in_gain.tick(); + let det_pos = (self.wpos + dlen - self.det_delay) % dlen; + let out_pos = (self.wpos + 1) % dlen; // oldest = look + det_delay samples ago + let mut det = 0.0f32; + for ch in 0..nch { + // A non-finite sample would pass the final clip as NaN; it becomes silence. + let x = channels[ch][i]; + let x = if x.is_finite() { x * g_in } else { 0.0 }; + self.delay[ch][self.wpos] = x; + let aligned = self.delay[ch][det_pos].abs(); + let tp = if self.true_peak { self.interp[ch].push_peak(&self.bank, x) } else { 0.0 }; + det = det.max(aligned.max(tp)); + } + let greq = if det > self.ceiling { self.ceiling / det } else { 1.0 }; + // Sliding minimum over the last `window` values. + while let Some(&(_, v)) = self.minq.back() { + if v >= greq { + self.minq.pop_back(); + } else { + break; + } + } + self.minq.push_back((self.t, greq)); + while let Some(&(idx, _)) = self.minq.front() { + if idx + window <= self.t { + self.minq.pop_front(); + } else { + break; + } + } + let m = self.minq.front().map_or(1.0, |&(_, v)| v); + // Release. + self.rel_state = if m < self.rel_state { m } else { self.rel_state + (m - self.rel_state) * (1.0 - self.rel) }; + // Moving average over look+1 samples. + self.box_sum += self.rel_state as f64 - self.box_ring[self.box_pos] as f64; + self.box_ring[self.box_pos] = self.rel_state; + self.box_pos = (self.box_pos + 1) % self.box_ring.len(); + let g = (self.box_sum / self.box_ring.len() as f64) as f32; + for ch in 0..nch { + let y = self.delay[ch][out_pos] * g; + channels[ch][i] = y.clamp(-self.ceiling, self.ceiling); + } + self.wpos = (self.wpos + 1) % dlen; + self.t += 1; + // Periodically re-sum to cancel floating-point drift. + if self.t.is_multiple_of(65536) { + self.box_sum = self.box_ring.iter().map(|&v| v as f64).sum(); + } + min_g = Some(min_g.map_or(g, |m| m.min(g))); + } + if let Some(g) = min_g { + self.gr_meter = -lin_db(g).min(0.0); + } + } +} + +// --------------------------------------------------------------------------------------------- + +/// Look-ahead of the maximizer. +const MAXIMIZER_LOOKAHEAD_MS: f32 = 1.5; + +/// Loudness maximizer: a look-ahead brick-wall limiter driven by `-threshold` dB, so lowering +/// the threshold raises the level into the ceiling. The gain is the minimum required gain over +/// the look-ahead window, released with a one-pole and smoothed by a moving average as long as +/// the window, so it has ramped down when each peak leaves the delay line. The output never +/// exceeds the ceiling; the ceiling changes at once, the drive glides over 20 ms. +pub struct Maximizer { + pv: ParamValues, + sr: f32, + drive: Smoothed, + ceiling: f32, + rel: f32, + /// Look-ahead in samples (at least 1). + look: usize, + /// Per-channel delay rings of `look` samples, which delay by `look - 1`. + delay: Vec>, + pos: usize, + /// Monotonic ring of (sample index, required gain) for the sliding minimum. + win: Vec<(u64, f32)>, + win_head: usize, + win_len: usize, + clock: u64, + /// Moving-average ring and its running sum. + smooth: Vec, + sum: f64, + held: f32, + gr_meter: f32, +} + +impl Maximizer { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("threshold", "Threshold", -30.0, 0.0, 0.0, Unit::Decibels), + ParamSpec::new("ceiling", "Ceiling", -30.0, 0.0, -0.3, Unit::Decibels), + ParamSpec::log("release", "Release", 1.0, 1000.0, 50.0, Unit::Milliseconds), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = sane_sample_rate(sample_rate); + let channels = channels.clamp(1, MAX_CHANNELS); + let look = ((MAXIMIZER_LOOKAHEAD_MS * 0.001 * sample_rate).round() as usize).max(1); + let mut s = Maximizer { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + drive: Smoothed::with_ms(1.0, sample_rate, 20.0), + ceiling: 1.0, + rel: 0.0, + look, + delay: vec![vec![0.0; look]; channels], + pos: 0, + win: vec![(0, 1.0); look], + win_head: 0, + win_len: 0, + clock: 0, + smooth: vec![1.0; look], + sum: look as f64, + held: 1.0, + gr_meter: 0.0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.drive.set(db_to_gain(-self.pv.v("threshold"))); + self.ceiling = db_to_gain(self.pv.v("ceiling")); + self.rel = coef(self.pv.v("release"), self.sr); + if snap { + self.drive.snap(); + } + } + + /// The minimum of the requests of the last `look` samples, `req` included. + fn window_min(&mut self, req: f32) -> f32 { + let cap = self.win.len(); + let t = self.clock; + self.clock = t.saturating_add(1); + let la = self.look as u64; + while self.win_len > 0 && self.win.get(self.win_head).is_some_and(|&(at, _)| at.saturating_add(la) <= t) { + self.win_head = (self.win_head + 1) % cap; + self.win_len -= 1; + } + while self.win_len > 0 && self.win.get((self.win_head + self.win_len - 1) % cap).is_some_and(|&(_, v)| v >= req) { + self.win_len -= 1; + } + if self.win_len == cap { + self.win_head = (self.win_head + 1) % cap; + self.win_len -= 1; + } + if let Some(slot) = self.win.get_mut((self.win_head + self.win_len) % cap) { + *slot = (t, req); + self.win_len += 1; + } + self.win.get(self.win_head).map_or(1.0, |&(_, v)| v.min(1.0)) + } +} + +impl AudioEffect for Maximizer { + param_plumbing!("maximizer"); + fn latency(&self) -> usize { + self.look - 1 + } + /// The deepest gain reduction during the last block, in dB (≥ 0). + fn gain_reduction_db(&self) -> f32 { + self.gr_meter + } + fn reset(&mut self) { + self.drive.snap(); + self.delay.iter_mut().for_each(|d| d.iter_mut().for_each(|v| *v = 0.0)); + self.pos = 0; + self.win_head = 0; + self.win_len = 0; + self.clock = 0; + self.smooth.iter_mut().for_each(|v| *v = 1.0); + self.sum = self.look as f64; + self.held = 1.0; + self.gr_meter = 0.0; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.delay.len()); + let la = self.look; + let mut min_gain = 1.0f32; + for i in 0..n { + let drive = self.drive.tick(); + let ceil = self.ceiling; + let p = self.pos; + let mut peak = 0.0f32; + for ch in 0..nch { + let x = channels[ch][i]; + let x = if x.is_finite() { x * drive } else { 0.0 }; + peak = peak.max(x.abs()); + self.delay[ch][p] = x; + } + let req = if peak > ceil { ceil / peak } else { 1.0 }; + let hold = self.window_min(req); + self.held = if hold < self.held { hold } else { hold + (self.held - hold) * self.rel }; + self.sum += f64::from(self.held) - f64::from(self.smooth[p]); + self.smooth[p] = self.held; + self.pos = (p + 1) % la; + if self.pos == 0 { + // Re-sum once per window to cancel floating-point drift. + self.sum = self.smooth.iter().map(|&v| f64::from(v)).sum(); + } + let g = ((self.sum / la as f64) as f32).clamp(0.0, 1.0); + min_gain = min_gain.min(g); + // The next slot holds the sample written `la - 1` samples ago: by now the moving + // average has fully taken in the gain that sample required. + for ch in 0..nch { + channels[ch][i] = (self.delay[ch][self.pos] * g).clamp(-ceil, ceil); + } + } + if n > 0 { + self.gr_meter = -lin_db(min_gain).min(0.0); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::loudness::LoudnessMeter; + use crate::testutil::*; + + const SR: f32 = 48000.0; + + #[test] + fn compressor_static_curve() { + let c = |x| compressor_curve(x, -20.0, 4.0, 0.0); + assert_eq!(c(-30.0), -30.0); + assert_eq!(c(-20.0), -20.0); + assert_eq!(c(0.0), -15.0); + // Soft knee: continuous at both knee edges, midpoint below the hard curve. + let k = |x| compressor_curve(x, -20.0, 4.0, 10.0); + assert!((k(-25.0) + 25.0).abs() < 1e-5); + assert!((k(-15.0) - c(-15.0)).abs() < 1e-5); + assert!(k(-20.0) < -20.0); + assert!((k(-20.0) - (-20.0 + (0.25 - 1.0) * 25.0 / 20.0)).abs() < 1e-5); + // Monotonic. + let mut prev = f32::MIN; + for i in 0..800 { + let y = k(-80.0 + i as f32 * 0.1); + assert!(y >= prev); + prev = y; + } + } + + #[test] + fn compressor_steady_state_matches_curve() { + for detector in [0.0, 1.0] { + let mut c = Compressor::new(SR, 2); + c.set_param("threshold", -20.0); + c.set_param("ratio", 4.0); + c.set_param("knee", 0.0); + c.set_param("makeup", 3.0); + c.set_param("detector", detector); + // Constant (DC) level: peak and RMS detectors agree. + for level_db in [-40.0f32, -10.0, -2.0] { + c.reset(); + let v = db_to_gain(level_db); + let mut l = vec![v; 48000]; + let mut r = vec![-v; 48000]; + c.process(&mut [&mut l, &mut r]); + let out_db = lin_db(l[47999]); + let expect = compressor_curve(level_db, -20.0, 4.0, 0.0) + 3.0; + assert!((out_db - expect).abs() < 0.05, "det {detector} in {level_db}: {out_db} vs {expect}"); + assert_eq!(l[47999], -r[47999]); + } + } + } + + #[test] + fn compressor_attack_time() { + let mut c = Compressor::new(SR, 1); + c.set_param("threshold", -20.0); + c.set_param("ratio", 20.0); + c.set_param("knee", 0.0); + c.set_param("attack", 10.0); + let mut x = vec![1.0f32; 4800]; + c.process(&mut [&mut x]); + // After one time constant ~63% of the final reduction (in dB) is applied. + let final_db = compressor_curve(0.0, -20.0, 20.0, 0.0); + let at_tau = lin_db(x[480]); + assert!((at_tau / final_db - 0.632).abs() < 0.02, "{at_tau} / {final_db}"); + } + + #[test] + fn gate_attenuates_below_threshold_and_holds() { + let mut g = Gate::new(SR, 1); + g.set_param("threshold", -30.0); + g.set_param("ratio", 100.0); + g.set_param("range", 40.0); + g.set_param("hold", 100.0); + g.set_param("release", 10.0); + let loud = db_to_gain(-10.0); + let quiet = db_to_gain(-50.0); + let mut x: Vec = (0..48000).map(|i| if i < 24000 { loud } else { quiet }).collect(); + g.process(&mut [&mut x]); + assert!((lin_db(x[23999]) + 10.0).abs() < 0.01); + // During hold (100 ms) the gate stays open. + assert!((lin_db(x[24000 + 2400]) + 50.0).abs() < 0.01); + // Well after hold + release: attenuated by the full range. + assert!((lin_db(x[47999]) + 90.0).abs() < 0.1, "{}", lin_db(x[47999])); + assert!((expander_curve(-40.0, -30.0, 2.0, 60.0) + 50.0).abs() < 1e-6); + } + + #[test] + fn limiter_never_exceeds_ceiling() { + let mut rng = Rng::new(7); + for tp in [0.0, 1.0] { + let mut lim = Limiter::new(SR, 2); + lim.set_param("ceiling", -1.0); + lim.set_param("input_gain", 12.0); + lim.set_param("true_peak", tp); + let ceiling = db_to_gain(-1.0); + let mut all_l = Vec::new(); + let mut all_r = Vec::new(); + for block in 0..200 { + let len = 1 + (rng.next_u64() % 700) as usize; + let mut l: Vec = (0..len).map(|_| rng.uniform() * 0.8).collect(); + let mut r: Vec = (0..len).map(|_| rng.uniform() * 0.3).collect(); + if block % 7 == 0 { + l[len / 2] = 4.0; // impulse + r[0] = -3.0; + } + lim.process(&mut [&mut l, &mut r]); + assert!(l.iter().chain(&r).all(|v| v.abs() <= ceiling + 1e-7)); + all_l.extend_from_slice(&l); + all_r.extend_from_slice(&r); + } + if tp == 1.0 { + // With true-peak detection the reconstructed peak stays close to the ceiling. + let mut m = LoudnessMeter::new(SR as f64, 2); + m.process(&[&all_l, &all_r]); + assert!(m.true_peak_dbtp() < -1.0 + 0.6, "TP {}", m.true_peak_dbtp()); + } + } + } + + #[test] + fn limiter_is_transparent_below_ceiling_with_reported_latency() { + let mut lim = Limiter::new(SR, 1); + let lat = lim.latency(); + let x = sine(1000.0, 0.3, SR as f64, 4800, 0.0); + let mut y = x.clone(); + lim.process(&mut [&mut y]); + for i in lat..4800 { + assert!((y[i] - x[i - lat]).abs() < 1e-6); + } + } + + #[test] + fn limiter_reduces_loud_sine_to_ceiling_smoothly() { + let mut lim = Limiter::new(SR, 1); + lim.set_param("ceiling", -6.0); + let mut x = sine(200.0, 1.0, SR as f64, 48000, 0.0); + lim.process(&mut [&mut x]); + let tail = &x[24000..]; + let peak = tail.iter().fold(0.0f32, |a, v| a.max(v.abs())); + assert!((lin_db(peak) + 6.0).abs() < 0.3, "{}", lin_db(peak)); + assert!((lim.gain_reduction_db() - 6.0).abs() < 0.5, "{}", lim.gain_reduction_db()); + } + + #[test] + fn limiter_turns_non_finite_input_into_silence() { + let mut lim = Limiter::new(SR, 2); + let mut l = vec![0.1f32; 2048]; + let mut r = vec![0.1f32; 2048]; + l[10] = f32::NAN; + r[20] = f32::INFINITY; + lim.process(&mut [&mut l, &mut r]); + assert!(l.iter().chain(&r).all(|v| v.is_finite() && v.abs() <= db_to_gain(-1.0))); + } + + #[test] + fn a_key_drives_the_compressor() { + let quiet = db_to_gain(-40.0); + let loud = vec![db_to_gain(-6.0); 48_000]; + let mut c = Compressor::new(SR, 2); + assert_eq!(c.key_channels(), 2); + c.set_param("threshold", -30.0); + c.set_param("ratio", 10.0); + c.set_param("knee", 0.0); + let (mut l, mut r) = (vec![quiet; 48_000], vec![quiet; 48_000]); + c.process_keyed(&mut [&mut l, &mut r], &[&loud, &loud]); + // The key sits 24 dB over the threshold: 24 * (1 - 1/10) = 21.6 dB of reduction. + assert!((lin_db(l[47_999]) + 40.0 + 21.6).abs() < 0.1, "{}", lin_db(l[47_999])); + assert!((c.gain_reduction_db() - 21.6).abs() < 0.1); + // Without a key the quiet input is under the threshold and passes. + c.reset(); + let mut x = vec![quiet; 48_000]; + c.process(&mut [&mut x]); + assert!((lin_db(x[47_999]) + 40.0).abs() < 0.01); + assert_eq!(c.gain_reduction_db(), 0.0); + // A key shorter than the block is ignored. + c.reset(); + let mut x = vec![quiet; 1024]; + c.process_keyed(&mut [&mut x], &[&loud[..10]]); + assert!((lin_db(x[1023]) + 40.0).abs() < 0.01); + } + + #[test] + fn a_key_opens_the_gate() { + let mut g = Gate::new(SR, 1); + g.set_param("threshold", -30.0); + g.set_param("range", 60.0); + let quiet = db_to_gain(-50.0); + let open = vec![db_to_gain(-10.0); 24_000]; + let closed = vec![0.0f32; 24_000]; + let mut x = vec![quiet; 24_000]; + g.process_keyed(&mut [&mut x], &[&open]); + assert!((lin_db(x[23_999]) + 50.0).abs() < 0.01, "open: {}", lin_db(x[23_999])); + let mut x = vec![quiet; 24_000]; + g.process_keyed(&mut [&mut x], &[&closed]); + assert!(lin_db(x[23_999]) < -105.0, "closed: {}", lin_db(x[23_999])); + assert!(g.gain_reduction_db() > 55.0); + } + + #[test] + fn maximizer_holds_the_ceiling_and_reports_its_latency() { + let mut m = Maximizer::new(SR, 2); + m.set_param("threshold", -12.0); + m.set_param("ceiling", -1.0); + m.reset(); + let ceiling = db_to_gain(-1.0); + let mut rng = Rng::new(11); + for block in 0..100 { + let len = (rng.next_u64() % 900) as usize; + let mut l: Vec = (0..len).map(|_| rng.uniform() * 0.9).collect(); + let mut r: Vec = (0..len).map(|_| rng.uniform() * 0.9).collect(); + if block % 5 == 0 && len > 0 { + l[len / 3] = 1.0; + } + m.process(&mut [&mut l, &mut r]); + assert!(l.iter().chain(&r).all(|v| v.is_finite() && v.abs() <= ceiling + 1e-7)); + } + assert!(m.gain_reduction_db() > 0.0); + // Below the ceiling it is a pure delay of `latency()` samples. + let mut m = Maximizer::new(SR, 1); + m.set_param("ceiling", 0.0); + let lat = m.latency(); + assert_eq!(lat, 71, "1.5 ms at 48 kHz is 72 samples of look-ahead"); + let x = sine(1000.0, 0.5, SR as f64, 4800, 0.0); + let mut y = x.clone(); + m.process(&mut [&mut y]); + for i in lat..4800 { + assert!((y[i] - x[i - lat]).abs() < 1e-6, "sample {i}"); + } + } + + #[test] + fn maximizer_ramps_down_before_a_peak_instead_of_clipping_it() { + // One loud sample after silence: the output peak lands on the ceiling, and the gain + // has already fallen when it arrives, so samples just before it are attenuated too. + let mut m = Maximizer::new(SR, 1); + m.set_param("ceiling", -6.0); + let lat = m.latency(); + let mut x = vec![0.25f32; 2000]; + x[1000] = 1.0; + m.process(&mut [&mut x]); + let at = 1000 + lat; + assert!((x[at] - db_to_gain(-6.0)).abs() < 1e-4, "{}", x[at]); + assert!(x[at - 10] < 0.25 * 0.99, "the gain ramps down ahead of the peak"); + } + + /// The sliding minimum against a scan of the last `look` requests. + #[test] + fn maximizer_window_min_matches_a_scan() { + let mut rng = Rng::new(5); + for sr in [1_000.0f32, 2_000.0, 48_000.0] { + let mut m = Maximizer::new(sr, 1); + let la = m.look; + let mut ring = vec![1.0f32; la]; + for i in 0..6_000 { + if i == 3_000 { + m.reset(); + ring.iter_mut().for_each(|v| *v = 1.0); + } + let req = (rng.uniform() * 0.5 + 0.5).min(1.0); + ring[i % la] = req; + let scan = ring.iter().fold(1.0f32, |a, &v| a.min(v)); + // Before the window is full, the scan sees the initial 1.0 values the window + // never held, which are larger and do not change the minimum. + assert_eq!(m.window_min(req), scan, "sr {sr} step {i}"); + } + } + } +} diff --git a/crates/audio-dsp/src/effects/eq.rs b/crates/audio-dsp/src/effects/eq.rs new file mode 100644 index 000000000..9732f8444 --- /dev/null +++ b/crates/audio-dsp/src/effects/eq.rs @@ -0,0 +1,644 @@ +//! Parametric (8-band) and simple 3-band equalizers. + +use crate::biquad::{Biquad, Coeffs, FilterType}; +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, param_plumbing}; + +/// Names of [`FilterType::ALL`] for the `type` choice parameters. +pub const FILTER_TYPE_NAMES: &[&str] = &["Peaking", "Low Shelf", "High Shelf", "Low Pass", "High Pass", "Notch", "Band Pass"]; + +/// Coefficients are recomputed at most every this many samples while parameters glide. +const COEFF_INTERVAL: u32 = 16; +const SMOOTH_MS: f32 = 30.0; +/// Most bands a [`BandBank`] can hold. +pub(crate) const MAX_BANDS: usize = 40; + +#[derive(Clone, Copy)] +pub(crate) struct BandSettings { + enabled: bool, + kind: FilterType, + frequency_hz: f32, + gain_db: f32, + q: f32, + snap: bool, +} + +impl BandSettings { + pub(crate) fn new(enabled: bool, kind: FilterType, frequency_hz: f32, gain_db: f32, q: f32, snap: bool) -> Self { + Self { enabled, kind, frequency_hz, gain_db, q, snap } + } +} + +#[derive(Clone, Debug)] +struct Band { + kind: FilterType, + /// log2(Hz). + freq: Smoothed, + gain: Smoothed, + q: Smoothed, + /// Band enable cross-fade (0 = bypassed, 1 = active). + mix: Smoothed, + coeffs: Coeffs, + dirty: bool, +} + +/// A bank of biquad bands shared by both EQs. +#[derive(Clone, Debug)] +pub(crate) struct BandBank { + sample_rate: f64, + bands: Vec, + /// `state[ch][band]`. + state: Vec>, + counter: u32, +} + +impl BandBank { + pub(crate) fn new(sample_rate: f32, channels: usize, nbands: usize) -> Self { + assert!(nbands <= MAX_BANDS); + let band = Band { + kind: FilterType::Peaking, + freq: Smoothed::with_ms(1000f32.log2(), sample_rate, SMOOTH_MS), + gain: Smoothed::with_ms(0.0, sample_rate, SMOOTH_MS), + q: Smoothed::with_ms(1.0, sample_rate, SMOOTH_MS), + mix: Smoothed::with_ms(0.0, sample_rate, SMOOTH_MS), + coeffs: Coeffs::IDENTITY, + dirty: true, + }; + BandBank { + sample_rate: sample_rate as f64, + bands: vec![band; nbands], + state: vec![vec![Biquad::new(); nbands]; crate::sane_channels(channels)], + counter: 0, + } + } + + pub(crate) fn set_band(&mut self, i: usize, settings: BandSettings) { + let BandSettings { enabled, kind, frequency_hz, gain_db, q, snap } = settings; + let b = &mut self.bands[i]; + if b.kind != kind { + b.kind = kind; + b.dirty = true; + } + b.freq.set(frequency_hz.max(1.0).log2()); + b.gain.set(gain_db); + b.q.set(q); + b.mix.set(if enabled { 1.0 } else { 0.0 }); + if snap { + b.freq.snap(); + b.gain.snap(); + b.q.snap(); + b.mix.snap(); + } + b.dirty = true; + } + + pub(crate) fn update_coeffs(&mut self, force: bool) { + let sr = self.sample_rate; + for b in &mut self.bands { + if b.dirty || force { + b.coeffs = Coeffs::design(b.kind, sr, 2f64.powf(b.freq.value() as f64), b.q.value() as f64, b.gain.value() as f64); + b.dirty = b.freq.is_smoothing() || b.gain.is_smoothing() || b.q.is_smoothing(); + } + } + } + + pub(crate) fn reset(&mut self) { + for b in &mut self.bands { + b.freq.snap(); + b.gain.snap(); + b.q.snap(); + b.mix.snap(); + b.dirty = true; + } + for ch in &mut self.state { + ch.iter_mut().for_each(Biquad::reset); + } + self.counter = 0; + self.update_coeffs(true); + } + + /// Analytic magnitude (dB) of the whole bank at its current (target-reached) settings. + pub(crate) fn response_db(&self, freq: f64) -> f64 { + let mut db = 0.0; + for b in &self.bands { + if b.mix.target() >= 0.5 { + let c = Coeffs::design(b.kind, self.sample_rate, 2f64.powf(b.freq.target() as f64), b.q.target() as f64, b.gain.target() as f64); + db += c.magnitude_db(freq, self.sample_rate); + } + } + db + } + + /// Process; `out_gain` is applied per sample. + pub(crate) fn process(&mut self, channels: &mut [&mut [f32]], out_gain: &mut Smoothed) { + let n = block_len(channels); + let nch = channels.len().min(self.state.len()); + if n == 0 { + return; + } + if !out_gain.is_smoothing() + && self.bands.iter().all(|b| !b.dirty && !b.freq.is_smoothing() && !b.gain.is_smoothing() && !b.q.is_smoothing() && !b.mix.is_smoothing()) + { + // Keep the exact per-sample arithmetic and recursive state; only the settled + // parameter/smoother bookkeeping is hoisted out of the hot loop. + let g = out_gain.value() as f64; + let bands = &self.bands; + // Channels are filtered in pairs so two independent recurrences share one loop. + let mut held: Option<(&mut [f32], &mut [Biquad])> = None; + for (channel, state) in channels.iter_mut().take(nch).zip(&mut self.state) { + for (b, st) in bands.iter().zip(state.iter_mut()) { + if b.mix.value() <= 0.0 { + st.reset(); + } + } + // A settled unit transfer with zero state is exactly transparent for finite + // f32 input. Do not discard a tail or bypass a non-finite sample. Bounded + // coefficients also ensure intermediate f64 products cannot overflow. + let transparent = bands.iter().zip(state.iter()).all(|(b, st)| { + b.mix.value() <= 0.0 + || (st.is_clear() + && b.coeffs.b0 == 1.0 + && b.coeffs.b1 == b.coeffs.a1 + && b.coeffs.b2 == b.coeffs.a2 + && b.coeffs.b1.abs() <= 4.0 + && b.coeffs.b2.abs() <= 4.0) + }); + if transparent && channel.iter().take(n).all(|x| x.is_finite()) { + let active = bands.iter().any(|b| b.mix.value() > 0.0); + for sample in channel.iter_mut().take(n) { + let x = *sample as f64; + // An active identity biquad adds +0, which normalizes negative zero. + *sample = ((if active { x + 0.0 } else { x }) * g) as f32; + } + continue; + } + let (channel, state) = (&mut channel[..n], state.as_mut_slice()); + match held.take() { + Some((first, first_state)) => filter_pair(bands, first, first_state, channel, state, g), + None => held = Some((channel, state)), + } + } + if let Some((channel, state)) = held { + for sample in channel.iter_mut() { + let mut x = *sample as f64; + for (b, st) in bands.iter().zip(state.iter_mut()) { + let m = b.mix.value() as f64; + if m > 0.0 { + let y = st.tick(&b.coeffs, x); + x += m * (y - x); + } + } + *sample = (x * g) as f32; + } + } + self.counter = (self.counter + (n % COEFF_INTERVAL as usize) as u32) % COEFF_INTERVAL; + return; + } + for i in 0..n { + if self.counter == 0 { + self.update_coeffs(false); + } + self.counter = (self.counter + 1) % COEFF_INTERVAL; + for b in &mut self.bands { + b.freq.tick(); + b.gain.tick(); + b.q.tick(); + if b.freq.is_smoothing() || b.gain.is_smoothing() || b.q.is_smoothing() { + b.dirty = true; + } + } + let g = out_gain.tick(); + // Tick the band mixes once per sample (shared by all channels). + let mut mixes = [0.0f32; MAX_BANDS]; + for (m, b) in mixes.iter_mut().zip(self.bands.iter_mut()) { + *m = b.mix.tick(); + } + for ch in 0..nch { + let mut x = channels[ch][i] as f64; + for (k, b) in self.bands.iter().enumerate() { + let m = mixes[k] as f64; + let st = &mut self.state[ch][k]; + if m > 0.0 { + let y = st.tick(&b.coeffs, x); + x += m * (y - x); + } else { + st.reset(); + } + } + channels[ch][i] = (x * g as f64) as f32; + } + } + } +} + +/// The settled band cascade for two channels, with the same per-channel arithmetic as one. +fn filter_pair(bands: &[Band], l: &mut [f32], l_state: &mut [Biquad], r: &mut [f32], r_state: &mut [Biquad], g: f64) { + for (a, b) in l.iter_mut().zip(r.iter_mut()) { + let (mut x, mut y) = (*a as f64, *b as f64); + for ((band, sl), sr) in bands.iter().zip(l_state.iter_mut()).zip(r_state.iter_mut()) { + let m = band.mix.value() as f64; + if m > 0.0 { + let yl = sl.tick(&band.coeffs, x); + x += m * (yl - x); + let yr = sr.tick(&band.coeffs, y); + y += m * (yr - y); + } + } + *a = (x * g) as f32; + *b = (y * g) as f32; + } +} + +macro_rules! eq_params { + ($(($n:literal, $on:expr, $ty:expr, $f:expr, $q:expr)),* $(,)?) => { + &[ + $( + ParamSpec::toggle(concat!("b", $n, ".on"), concat!("Band ", $n, " On"), $on), + ParamSpec::choice(concat!("b", $n, ".type"), concat!("Band ", $n, " Type"), FILTER_TYPE_NAMES, $ty), + ParamSpec::log(concat!("b", $n, ".freq"), concat!("Band ", $n, " Frequency"), 20.0, 20000.0, $f, Unit::Hertz), + ParamSpec::new(concat!("b", $n, ".gain"), concat!("Band ", $n, " Gain"), -30.0, 30.0, 0.0, Unit::Decibels), + ParamSpec::log(concat!("b", $n, ".q"), concat!("Band ", $n, " Q"), 0.1, 30.0, $q, Unit::Q), + )* + ParamSpec::new("output", "Output Gain", -30.0, 30.0, 0.0, Unit::Decibels), + ] + }; +} + +const BAND_IDS: [[&str; 5]; 8] = [ + ["b1.on", "b1.type", "b1.freq", "b1.gain", "b1.q"], + ["b2.on", "b2.type", "b2.freq", "b2.gain", "b2.q"], + ["b3.on", "b3.type", "b3.freq", "b3.gain", "b3.q"], + ["b4.on", "b4.type", "b4.freq", "b4.gain", "b4.q"], + ["b5.on", "b5.type", "b5.freq", "b5.gain", "b5.q"], + ["b6.on", "b6.type", "b6.freq", "b6.gain", "b6.q"], + ["b7.on", "b7.type", "b7.freq", "b7.gain", "b7.q"], + ["b8.on", "b8.type", "b8.freq", "b8.gain", "b8.q"], +]; + +/// 8-band parametric EQ. Every band can be any [`FilterType`]; defaults are +/// HP · low shelf · 4 × peaking · high shelf · LP with the pass filters disabled. +pub struct ParametricEq { + pv: ParamValues, + bank: BandBank, + out: Smoothed, +} + +impl ParametricEq { + pub const PARAMS: &'static [ParamSpec] = eq_params![ + ("1", false, 4, 30.0, 0.707), + ("2", true, 1, 100.0, 0.707), + ("3", true, 0, 250.0, 1.0), + ("4", true, 0, 700.0, 1.0), + ("5", true, 0, 2000.0, 1.0), + ("6", true, 0, 5000.0, 1.0), + ("7", true, 2, 10000.0, 0.707), + ("8", false, 3, 18000.0, 0.707), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = ParametricEq { + pv: ParamValues::new(Self::PARAMS), + bank: BandBank::new(sample_rate, channels, 8), + out: Smoothed::with_ms(1.0, sample_rate, SMOOTH_MS), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + for (i, ids) in BAND_IDS.iter().enumerate() { + self.bank.set_band( + i, + BandSettings::new( + self.pv.on(ids[0]), + FilterType::from_index(self.pv.idx(ids[1])), + self.pv.v(ids[2]), + self.pv.v(ids[3]), + self.pv.v(ids[4]), + snap, + ), + ); + } + self.out.set(crate::db_to_gain(self.pv.v("output"))); + if snap { + self.out.snap(); + self.bank.update_coeffs(true); + } + } + + /// Analytic magnitude response (dB) at the target settings, including output gain, for + /// drawing the EQ curve. + pub fn response_db(&self, freq: f64) -> f64 { + self.bank.response_db(freq) + self.pv.v("output") as f64 + } +} + +impl AudioEffect for ParametricEq { + param_plumbing!("parametric_eq"); + fn response_db(&self, freq: f64) -> Option { + Some(ParametricEq::response_db(self, freq)) + } + fn reset(&mut self) { + self.out.snap(); + self.bank.reset(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + self.bank.process(channels, &mut self.out); + } +} + +/// Simple 3-band EQ: low shelf, mid peak, high shelf. +pub struct SimpleEq { + pv: ParamValues, + bank: BandBank, + out: Smoothed, +} + +impl SimpleEq { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("low", "Low", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::log("low_freq", "Low Frequency", 20.0, 1000.0, 200.0, Unit::Hertz), + ParamSpec::new("mid", "Mid", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::log("mid_freq", "Mid Frequency", 100.0, 10000.0, 1000.0, Unit::Hertz), + ParamSpec::log("mid_q", "Mid Q", 0.1, 10.0, 0.7, Unit::Q), + ParamSpec::new("high", "High", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::log("high_freq", "High Frequency", 1000.0, 20000.0, 5000.0, Unit::Hertz), + ParamSpec::new("output", "Output Gain", -24.0, 24.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = SimpleEq { + pv: ParamValues::new(Self::PARAMS), + bank: BandBank::new(sample_rate, channels, 3), + out: Smoothed::with_ms(1.0, sample_rate, SMOOTH_MS), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let sq = std::f32::consts::FRAC_1_SQRT_2; + let p = &self.pv; + let (lg, lf, mg, mf, mq, hg, hf) = (p.v("low"), p.v("low_freq"), p.v("mid"), p.v("mid_freq"), p.v("mid_q"), p.v("high"), p.v("high_freq")); + self.bank.set_band(0, BandSettings::new(true, FilterType::LowShelf, lf, lg, sq, snap)); + self.bank.set_band(1, BandSettings::new(true, FilterType::Peaking, mf, mg, mq, snap)); + self.bank.set_band(2, BandSettings::new(true, FilterType::HighShelf, hf, hg, sq, snap)); + self.out.set(crate::db_to_gain(self.pv.v("output"))); + if snap { + self.out.snap(); + self.bank.update_coeffs(true); + } + } + + pub fn response_db(&self, freq: f64) -> f64 { + self.bank.response_db(freq) + self.pv.v("output") as f64 + } +} + +impl AudioEffect for SimpleEq { + param_plumbing!("simple_eq"); + fn response_db(&self, freq: f64) -> Option { + Some(SimpleEq::response_db(self, freq)) + } + fn reset(&mut self) { + self.out.snap(); + self.bank.reset(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + self.bank.process(channels, &mut self.out); + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::*; + + const SR: f32 = 48000.0; + + fn measure(fx: &mut dyn AudioEffect, freq: f64) -> f64 { + fx.reset(); + let n = SR as usize; + let mut l = sine(freq, 0.25, SR as f64, n, 0.0); + let mut r = l.clone(); + fx.process(&mut [&mut l, &mut r]); + let a = tone_amplitude(&l[n / 2..], freq, SR as f64); + let b = tone_amplitude(&r[n / 2..], freq, SR as f64); + assert!((a - b).abs() < 1e-6); + db(a / 0.25) + } + + #[test] + fn default_parametric_is_flat() { + let mut eq = ParametricEq::new(SR, 2); + for f in [30.0, 250.0, 1000.0, 8000.0, 16000.0] { + assert!(eq.response_db(f).abs() < 1e-9); + assert!(measure(&mut eq, f).abs() < 0.01); + } + } + + #[test] + fn parametric_bands_match_analytic_response() { + let mut eq = ParametricEq::new(SR, 2); + eq.set_param("b4.gain", 9.0); + eq.set_param("b4.freq", 1000.0); + eq.set_param("b4.q", 2.0); + eq.set_param("b2.gain", -6.0); + eq.set_param("b1.on", 1.0); + eq.set_param("b1.freq", 40.0); + eq.set_param("b8.on", 1.0); + eq.set_param("b8.type", 5.0); // notch + eq.set_param("b8.freq", 12000.0); + eq.set_param("b8.q", 5.0); + eq.set_param("output", 1.5); + assert!((eq.response_db(1000.0) - (9.0 + 1.5 + eq.bank.response_db(1000.0) - 9.0)).abs() < 1e-9); + for f in [30.0, 80.0, 400.0, 1000.0, 3000.0, 12000.0 * 1.2] { + let m = measure(&mut eq, f); + assert!((m - eq.response_db(f)).abs() < 0.05, "f {f}: measured {m} analytic {}", eq.response_db(f)); + } + assert!(measure(&mut eq, 12000.0) < -30.0); + } + + #[test] + fn simple_eq_gains() { + let mut eq = SimpleEq::new(SR, 2); + eq.set_param("low", 6.0); + eq.set_param("high", -6.0); + eq.set_param("mid", 3.0); + assert!((measure(&mut eq, 30.0) - eq.response_db(30.0)).abs() < 0.05); + assert!((eq.response_db(20.0) - 6.0).abs() < 0.3); + assert!((eq.response_db(20000.0) + 6.0).abs() < 0.5); + assert!((measure(&mut eq, 1000.0) - eq.response_db(1000.0)).abs() < 0.05); + } + + #[test] + fn gain_change_glides_without_jump() { + let mut eq = ParametricEq::new(SR, 1); + let mut x = vec![0.5f32; 4800]; + eq.process(&mut [&mut x[..2400]]); + eq.set_param("output", 12.0); + eq.process(&mut [&mut x[2400..]]); + let max_step = x.windows(2).map(|w| (w[1] - w[0]).abs()).fold(0.0, f32::max); + assert!(max_step < 0.01, "step {max_step}"); + assert!((x[4799] - 0.5 * crate::db_to_gain(12.0)).abs() < 1e-4); + } +} + +#[cfg(test)] +impl BandBank { + fn process_reference(&mut self, channels: &mut [&mut [f32]], out_gain: &mut Smoothed) { + let n = block_len(channels); + let nch = channels.len().min(self.state.len()); + for i in 0..n { + if self.counter == 0 { + self.update_coeffs(false); + } + self.counter = (self.counter + 1) % COEFF_INTERVAL; + for b in &mut self.bands { + b.freq.tick(); + b.gain.tick(); + b.q.tick(); + if b.freq.is_smoothing() || b.gain.is_smoothing() || b.q.is_smoothing() { + b.dirty = true; + } + } + let g = out_gain.tick(); + // Tick the band mixes once per sample (shared by all channels). + let mut mixes = [0.0f32; MAX_BANDS]; + for (m, b) in mixes.iter_mut().zip(self.bands.iter_mut()) { + *m = b.mix.tick(); + } + for ch in 0..nch { + let mut x = channels[ch][i] as f64; + for (k, b) in self.bands.iter().enumerate() { + let m = mixes[k] as f64; + let st = &mut self.state[ch][k]; + if m > 0.0 { + let y = st.tick(&b.coeffs, x); + x += m * (y - x); + } else { + st.reset(); + } + } + channels[ch][i] = (x * g as f64) as f32; + } + } + } +} + +#[cfg(test)] +mod throughput_tests { + use super::*; + #[test] + fn flat_eq_fast_path_preserves_samples_and_filter_tails() { + let mut fast = BandBank::new(48000.0, 2, 1); + fast.set_band(0, BandSettings::new(true, FilterType::Peaking, 1000.0, 0.0, 0.7, true)); + fast.reset(); + let mut reference = fast.clone(); + let mut gain = Smoothed::new(1.0, 0); + let mut ref_gain = gain; + for input in [ + vec![-0.0, 0.0, f32::MIN_POSITIVE, f32::from_bits(1), f32::MAX, -f32::MAX, 0.7], + vec![0.0; 100], + vec![f32::INFINITY, f32::NEG_INFINITY, f32::NAN], + ] { + let mut a = [input.clone(), input]; + let mut b = a.clone(); + let [al, ar] = &mut a; + let [bl, br] = &mut b; + fast.process(&mut [al, ar], &mut gain); + reference.process_reference(&mut [bl, br], &mut ref_gain); + for (a, b) in a.iter().flatten().zip(b.iter().flatten()) { + assert_eq!(a.to_bits(), b.to_bits()); + } + } + // A newly flat filter must drain its old state, not drop the tail. + fast.reset(); + fast.set_band(0, BandSettings::new(true, FilterType::Peaking, 1000.0, 12.0, 0.7, true)); + fast.update_coeffs(true); + fast.process(&mut [&mut [0.5], &mut [0.5]], &mut gain); + fast.set_band(0, BandSettings::new(true, FilterType::Peaking, 1000.0, 0.0, 0.7, true)); + fast.update_coeffs(true); + reference = fast.clone(); + let mut a = [vec![0.0; 4096], vec![0.0; 4096]]; + let mut b = a.clone(); + let [al, ar] = &mut a; + let [bl, br] = &mut b; + fast.process(&mut [al, ar], &mut gain); + reference.process_reference(&mut [bl, br], &mut ref_gain); + assert_eq!(a, b); + assert!(a[0].iter().any(|x| *x != 0.0)); + } + #[test] + fn settled_and_automated_eq_matches_original_loop() { + let mut fast = BandBank::new(48000.0, 2, 3); + fast.reset(); + let mut reference = fast.clone(); + let mut gain = Smoothed::with_ms(1.0, 48000.0, 20.0); + let mut ref_gain = gain; + for block in 0..500 { + if matches!(block, 2 | 90 | 180 | 270 | 360) { + let on = block != 180; + let db = if block == 270 { 0.0 } else { 9.0 }; + for bank in [&mut fast, &mut reference] { + bank.set_band(0, BandSettings::new(on, FilterType::Peaking, 1733.0, db, 0.7, false)); + } + gain.set(if block == 360 { 1.0 } else { 0.8 }); + ref_gain.set(gain.target()); + } + let n = [0, 1, 17, 64, 513][block % 5]; + let input: Vec = (0..n).map(|i| if block > 400 { 0.0 } else { ((i + block * 13) as f32 * 0.17).sin() * 0.3 }).collect(); + let right: Vec = + input.iter().enumerate().map(|(i, x)| if block > 450 { 0.0 } else { 0.5 * x + (i as f32 * 0.031).cos() * 0.2 }).collect(); + let mut a = [input, right]; + let mut b = a.clone(); + let [al, ar] = &mut a; + let [bl, br] = &mut b; + fast.process(&mut [al, ar], &mut gain); + reference.process_reference(&mut [bl, br], &mut ref_gain); + for (a, b) in a.iter().flatten().zip(b.iter().flatten()) { + assert_eq!(a.to_bits(), b.to_bits(), "block {block}"); + } + assert_eq!(fast.counter, reference.counter); + } + } + #[test] + fn settled_eq_pairs_channels_like_original_loop() { + let kinds = [FilterType::HighPass, FilterType::LowShelf, FilterType::Peaking, FilterType::Notch, FilterType::HighShelf, FilterType::LowPass]; + for (flat, nch) in [(false, 1), (false, 2), (false, 3), (false, 5), (true, 3)] { + let mut fast = BandBank::new(48000.0, nch, kinds.len()); + for (i, kind) in kinds.iter().enumerate() { + let gain = if flat { 0.0 } else { 3.0 * i as f32 - 7.0 }; + let kind = if flat { FilterType::Peaking } else { *kind }; + fast.set_band(i, BandSettings::new(i != 2, kind, 40.0 * 3.1f32.powi(i as i32), gain, 0.5 + 0.4 * i as f32, true)); + } + fast.reset(); + let mut reference = fast.clone(); + let mut gain = Smoothed::new(0.9, 0); + let mut ref_gain = gain; + for block in 0..40 { + let n = [512, 1, 17, 0, 64][block % 5]; + let mut a: Vec> = (0..nch) + .map(|ch| { + (0..n) + .map(|i| match (ch, block) { + (1, 10..=12) if flat => f32::NAN, + (2, 20..) => 0.0, + _ => ((i + block * 31) as f32 * (0.05 + 0.07 * ch as f32)).sin() * 0.4, + }) + .collect() + }) + .collect(); + let mut b = a.clone(); + let mut ar: Vec<&mut [f32]> = a.iter_mut().map(|c| c.as_mut_slice()).collect(); + let mut br: Vec<&mut [f32]> = b.iter_mut().map(|c| c.as_mut_slice()).collect(); + fast.process(&mut ar, &mut gain); + reference.process_reference(&mut br, &mut ref_gain); + for (x, y) in a.iter().flatten().zip(b.iter().flatten()) { + assert_eq!(x.to_bits(), y.to_bits(), "nch {nch} flat {flat} block {block}"); + } + } + } + } +} diff --git a/crates/audio-dsp/src/effects/essential.rs b/crates/audio-dsp/src/effects/essential.rs new file mode 100644 index 000000000..57e25049b --- /dev/null +++ b/crates/audio-dsp/src/effects/essential.rs @@ -0,0 +1,823 @@ +//! Speech and cleanup processors: DeEsser (split-band), DeReverb (spectral late-reverberation +//! suppression), Enhance Speech (a DSP voice-enhancement chain) and Stereo Width (mid/side). +//! +//! All written from textbook descriptions: +//! * de-esser: complementary split (band = 2nd-order high-pass, rest = x − band) with a relative +//! band-vs-broadband detector driving the band gain; +//! * de-reverb: the statistical late-reverberation model (exponentially decaying diffuse tail, +//! Polack): the late-reverb PSD at frame t is predicted from the reverberant PSD T_d earlier, +//! λ_r(t) = e^{−2Δ·T_d}·λ_x(t − T_d), Δ = 3·ln10 / RT60, and removed by spectral subtraction +//! with over-subtraction and a gain floor (Lebart et al. 2001; Habets 2007); +//! * enhance speech: high-pass, de-mud cut, presence and air boosts (RBJ biquads), then one gain +//! computer combining a downward expander (noise between words) and a soft-knee compressor. + +use super::stft::{Pairing, Plan, Spectral, StftChannel, fft_size, stream}; +use crate::biquad::{Biquad, Coeffs, FilterType}; +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, flush, param_plumbing}; + +/// One-pole smoothing coefficient for a time constant in ms. +fn coef(ms: f64, sr: f64) -> f64 { + if ms <= 0.0 { 0.0 } else { (-1.0 / (ms * 0.001 * sr)).exp() } +} + +#[inline] +fn pow_db(p: f64) -> f64 { + 10.0 * (p + 1e-20).log10() +} + +// --------------------------------------------------------------------------------------------- + +/// De-esser: a 2nd-order high-pass sidechain at `frequency` detects sibilance (the band level +/// exceeds the broadband level by more than `threshold`); the band above `frequency` is then cut +/// by a dynamic RBJ high shelf whose gain follows the gain reduction (attack ~1 ms, release +/// ~60 ms, stereo-linked). At 0 dB reduction the shelf is an exact identity, so non-sibilant +/// passages pass unchanged. (A subtractive split `x − HP(x)` is not used: the high-pass phase +/// shift around the crossover makes `x − (1 − g)·HP(x)` boost there instead of cutting.) +pub struct DeEsser { + pv: ParamValues, + sr: f64, + freq: Smoothed, + coeffs: Coeffs, + hp: Vec, + shelf: Vec, + shelf_coeffs: Coeffs, + shelf_gr: f64, + env_band: f64, + env_full: f64, + /// Smoothed gain reduction (dB, ≤ 0). + gr: f64, + det: f64, + att: f64, + rel: f64, + threshold: f64, + reduction: f64, + gr_meter: f32, +} + +impl DeEsser { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::log("frequency", "Frequency", 2000.0, 12000.0, 6000.0, Unit::Hertz), + ParamSpec::new("threshold", "Threshold", -40.0, 0.0, -12.0, Unit::Decibels), + ParamSpec::new("reduction", "Max Reduction", 0.0, 24.0, 8.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let channels = crate::sane_channels(channels); + let sr = sample_rate as f64; + let mut s = DeEsser { + pv: ParamValues::new(Self::PARAMS), + sr, + freq: Smoothed::with_ms(6000.0, sample_rate, 20.0), + coeffs: Coeffs::IDENTITY, + hp: vec![Biquad::new(); crate::sane_channels(channels)], + shelf: vec![Biquad::new(); crate::sane_channels(channels)], + shelf_coeffs: Coeffs::IDENTITY, + shelf_gr: 0.0, + env_band: 0.0, + env_full: 0.0, + gr: 0.0, + det: coef(2.0, sr), + att: coef(1.0, sr), + rel: coef(60.0, sr), + threshold: -12.0, + reduction: 8.0, + gr_meter: 0.0, + }; + s.apply_params(true); + s + } + + fn design(&mut self) { + self.coeffs = Coeffs::design(FilterType::HighPass, self.sr, self.freq.value() as f64, std::f64::consts::FRAC_1_SQRT_2, 0.0); + self.design_shelf(); + } + + fn design_shelf(&mut self) { + self.shelf_coeffs = if self.gr == 0.0 { + Coeffs::IDENTITY + } else { + Coeffs::design(FilterType::HighShelf, self.sr, self.freq.value() as f64, std::f64::consts::FRAC_1_SQRT_2, self.gr) + }; + self.shelf_gr = self.gr; + } + + fn apply_params(&mut self, snap: bool) { + self.freq.set(self.pv.v("frequency")); + self.threshold = self.pv.v("threshold") as f64; + self.reduction = self.pv.v("reduction") as f64; + if snap { + self.freq.snap(); + self.design(); + } + } +} + +impl AudioEffect for DeEsser { + param_plumbing!("deesser"); + /// The band's gain reduction at the end of the last block, in dB (≥ 0). + fn gain_reduction_db(&self) -> f32 { + -self.gr_meter + } + fn reset(&mut self) { + self.freq.snap(); + self.design(); + self.hp.iter_mut().for_each(Biquad::reset); + self.shelf.iter_mut().for_each(Biquad::reset); + self.env_band = 0.0; + self.env_full = 0.0; + self.gr = 0.0; + self.gr_meter = 0.0; + self.design_shelf(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.hp.len()); + for i in 0..n { + if self.freq.is_smoothing() { + self.freq.tick(); + self.design(); + } + let (mut pb, mut pf) = (0.0f64, 0.0f64); + for ch in 0..nch { + let x = channels[ch][i] as f64; + let b = self.hp[ch].tick(&self.coeffs, x); + pb += b * b; + pf += x * x; + } + self.env_band = flush(self.det * self.env_band + (1.0 - self.det) * pb); + self.env_full = flush(self.det * self.env_full + (1.0 - self.det) * pf); + let bdb = pow_db(self.env_band); + let excess = bdb - pow_db(self.env_full) - self.threshold; + let target = if bdb > -70.0 && excess > 0.0 { -(excess * 2.0).min(self.reduction) } else { 0.0 }; + let c = if target < self.gr { self.att } else { self.rel }; + self.gr = flush(c * self.gr + (1.0 - c) * target); + if target == 0.0 && self.gr > -1e-4 { + self.gr = 0.0; + } + if (self.gr - self.shelf_gr).abs() > 0.05 || (self.gr == 0.0) != (self.shelf_gr == 0.0) { + self.design_shelf(); + } + for ch in 0..nch { + let x = channels[ch][i] as f64; + channels[ch][i] = self.shelf[ch].tick(&self.shelf_coeffs, x) as f32; + } + } + self.gr_meter = self.gr as f32; + } +} + +// --------------------------------------------------------------------------------------------- + +/// Late-reverberation delay T_d (s): reflections later than this count as reverb. +const DEREVERB_TD: f64 = 0.05; +/// Time constant (s) of the PSD smoothing. +const DEREVERB_PSD_TAU: f64 = 0.02; + +#[derive(Clone, Debug)] +struct ReverbState { + psd: Vec, + /// Ring of past smoothed PSDs, `delay_frames` deep. + hist: Vec, + pos: usize, + gains: Vec, + frames: usize, +} + +impl ReverbState { + fn new(bins: usize, delay: usize) -> Self { + ReverbState { psd: vec![0.0; bins], hist: vec![0.0; bins * delay], pos: 0, gains: vec![1.0; bins], frames: 0 } + } + fn reset(&mut self) { + self.psd.iter_mut().for_each(|v| *v = 0.0); + self.hist.iter_mut().for_each(|v| *v = 0.0); + self.gains.iter_mut().for_each(|v| *v = 1.0); + self.pos = 0; + self.frames = 0; + } +} + +/// Spectral de-reverberation: suppresses the late reverberant tail predicted by the exponential +/// decay model for the assumed `rt60`. `amount` sets the over-subtraction and the gain floor +/// (0 % = identity apart from the STFT delay, 100 % ≈ −18 dB floor). +pub struct DeReverb { + pv: ParamValues, + sr: f32, + n: usize, + hop: usize, + delay: usize, + spec: Spectral, + stft: Vec, + state: Vec, + smoothed_gains: Vec, + /// e^{−2Δ·T_d} (power decay over the delay). + decay: f32, + beta: f32, + floor: f32, + alpha: f32, +} + +impl DeReverb { + pub const PARAMS: &'static [ParamSpec] = + &[ParamSpec::new("amount", "Amount", 0.0, 100.0, 50.0, Unit::Percent), ParamSpec::log("rt60", "Decay (RT60)", 0.1, 5.0, 0.8, Unit::Seconds)]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let n = fft_size(sample_rate); + let hop = n / 4; + let bins = n / 2 + 1; + let delay = ((DEREVERB_TD * sample_rate as f64 / hop as f64).round() as usize).max(1); + let ch = crate::sane_channels(channels); + let mut s = DeReverb { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + n, + hop, + delay, + spec: Spectral::new(n, true), + stft: vec![StftChannel::new(n); ch], + state: vec![ReverbState::new(bins, delay); ch], + smoothed_gains: vec![1.0; bins], + decay: 1.0, + beta: 1.0, + floor: 1.0, + alpha: (-(hop as f64) / (sample_rate as f64 * DEREVERB_PSD_TAU)).exp() as f32, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, _snap: bool) { + let amount = self.pv.v("amount") / 100.0; + let rt60 = self.pv.v("rt60") as f64; + let delta = 3.0 * std::f64::consts::LN_10 / rt60; + let td = self.delay as f64 * self.hop as f64 / self.sr as f64; + self.decay = (-2.0 * delta * td).exp() as f32; + self.beta = 1.0 + amount; + self.floor = db_to_gain(-18.0 * amount); + } +} + +impl AudioEffect for DeReverb { + param_plumbing!("dereverb"); + fn latency(&self) -> usize { + self.n + } + fn reset(&mut self) { + self.stft.iter_mut().for_each(StftChannel::reset); + self.state.iter_mut().for_each(ReverbState::reset); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let len = block_len(channels); + let (n, hop, delay) = (self.n, self.hop, self.delay); + let (decay, beta, floor, alpha) = (self.decay, self.beta, self.floor, self.alpha); + let scale = 1.0 / (n as f32 * 2.0); + let bins = n / 2 + 1; + let (states, sg) = (&mut self.state, &mut self.smoothed_gains); + stream(&mut self.stft, &mut self.spec, channels, len, Plan { hop, scale, pairing: Pairing::Full }, &mut |ch, _, re, im| { + let st = &mut states[ch]; + let warm = st.frames >= delay; + let base = st.pos * bins; + for k in 0..bins { + let p = re[k] * re[k] + im[k] * im[k]; + let psd = alpha * st.psd[k] + (1.0 - alpha) * p; + // Range test: tiny values and NaN/inf (one bad input sample) clear the state + // instead of poisoning the recursion and its history ring. + st.psd[k] = if (1e-30..=f32::MAX).contains(&psd) { psd } else { 0.0 }; + // Late reverb predicted from the PSD `delay` frames ago (the ring slot we are + // about to overwrite holds exactly that frame). + let late = if warm { decay * st.hist[base + k] } else { 0.0 }; + st.hist[base + k] = st.psd[k]; + let target = if st.psd[k] > 0.0 { (1.0 - beta * late / st.psd[k]).max(floor) } else { 1.0 }; + let g = &mut st.gains[k]; + // fast recovery on onsets, slower suppression (less musical noise) + let c = if target > *g { 0.8 } else { 0.5 }; + *g += (target - *g) * c; + } + st.pos = (st.pos + 1) % delay; + st.frames = st.frames.saturating_add(1); + for k in 0..bins { + let a = st.gains[k.saturating_sub(1)]; + let c = st.gains[(k + 1).min(bins - 1)]; + sg[k] = 0.25 * a + 0.5 * st.gains[k] + 0.25 * c; + } + for k in 0..bins { + re[k] *= sg[k]; + im[k] *= sg[k]; + } + }); + } +} + +// --------------------------------------------------------------------------------------------- + +const ENH_STAGES: usize = 4; +/// Expander: below this level (dBFS) the signal is pushed down (noise between words). +const ENH_EXP_THRESHOLD: f64 = -50.0; +const ENH_EXP_RATIO: f64 = 3.0; +const ENH_EXP_RANGE: f64 = 18.0; +/// Compressor above this level (dBFS). +const ENH_COMP_THRESHOLD: f64 = -24.0; +const ENH_COMP_RATIO: f64 = 3.0; +const ENH_COMP_KNEE: f64 = 6.0; +/// Make-up gain: puts conversational speech (≈ −20 dBFS RMS) back near its input loudness. +const ENH_MAKEUP: f64 = 3.0; + +/// Enhance Speech: a DSP voice-enhancement chain (no machine learning): 80 Hz high-pass, +/// de-mud cut, presence and air boosts, then a combined downward expander + soft-knee +/// compressor with make-up gain. `tone` picks the cut/boost frequencies for lower or higher +/// voices; `mix` blends with the dry signal. +pub struct SpeechEnhance { + pv: ParamValues, + sr: f64, + coeffs: [Coeffs; ENH_STAGES], + filters: Vec<[Biquad; ENH_STAGES]>, + mix: Smoothed, + /// Detector mean square. + ms: f64, + /// Smoothed expander gain (dB, ≤ 0): opens fast, closes slowly. + env_exp: f64, + /// Smoothed compressor gain (dB, ≤ 0): fast attack, slow release. + env_comp: f64, + det: f64, + fast: f64, + exp_close: f64, + comp_rel: f64, +} + +impl SpeechEnhance { + pub const PARAMS: &'static [ParamSpec] = + &[ParamSpec::new("mix", "Mix", 0.0, 100.0, 100.0, Unit::Percent), ParamSpec::choice("tone", "Tone", &["Low Tone", "High Tone"], 0)]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let sr = sample_rate as f64; + let mut s = SpeechEnhance { + pv: ParamValues::new(Self::PARAMS), + sr, + coeffs: [Coeffs::IDENTITY; ENH_STAGES], + filters: vec![[Biquad::new(); ENH_STAGES]; crate::sane_channels(channels)], + mix: Smoothed::with_ms(1.0, sample_rate, 20.0), + ms: 0.0, + env_exp: 0.0, + env_comp: 0.0, + det: coef(5.0, sr), + fast: coef(3.0, sr), + exp_close: coef(30.0, sr), + comp_rel: coef(120.0, sr), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let high = self.pv.idx("tone") == 1; + let (mud, presence) = if high { (350.0, 4000.0) } else { (250.0, 2500.0) }; + let sr = self.sr; + self.coeffs = [ + Coeffs::design(FilterType::HighPass, sr, 80.0, std::f64::consts::FRAC_1_SQRT_2, 0.0), + Coeffs::design(FilterType::Peaking, sr, mud, 1.0, -3.0), + Coeffs::design(FilterType::Peaking, sr, presence, 1.0, 4.0), + Coeffs::design(FilterType::HighShelf, sr, 10000.0, std::f64::consts::FRAC_1_SQRT_2, 2.0), + ]; + self.mix.set(self.pv.v("mix") / 100.0); + if snap { + self.mix.snap(); + } + } + + /// Static downward-expander gain (dB) for a detector level (dBFS). + fn expander_db(level: f64) -> f64 { + if level < ENH_EXP_THRESHOLD { ((level - ENH_EXP_THRESHOLD) * (ENH_EXP_RATIO - 1.0)).max(-ENH_EXP_RANGE) } else { 0.0 } + } + + /// Static soft-knee compressor gain (dB) for a detector level (dBFS). + fn compressor_db(level: f64) -> f64 { + let d = level - ENH_COMP_THRESHOLD; + if 2.0 * d.abs() <= ENH_COMP_KNEE { + (1.0 / ENH_COMP_RATIO - 1.0) * (d + ENH_COMP_KNEE / 2.0).powi(2) / (2.0 * ENH_COMP_KNEE) + } else if d > 0.0 { + d / ENH_COMP_RATIO - d + } else { + 0.0 + } + } +} + +impl AudioEffect for SpeechEnhance { + param_plumbing!("speech_enhance"); + fn reset(&mut self) { + self.filters.iter_mut().for_each(|f| f.iter_mut().for_each(Biquad::reset)); + self.mix.snap(); + self.ms = 0.0; + self.env_exp = 0.0; + self.env_comp = 0.0; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.filters.len()).min(crate::MAX_CHANNELS); + let mut wet = [0.0f64; crate::MAX_CHANNELS]; + for i in 0..n { + let mut sq = 0.0f64; + for ch in 0..nch { + let mut x = channels[ch][i] as f64; + for (st, c) in self.filters[ch].iter_mut().zip(self.coeffs.iter()) { + x = st.tick(c, x); + } + wet[ch] = x; + sq = sq.max(x * x); + } + self.ms = flush(self.det * self.ms + (1.0 - self.det) * sq); + let level = pow_db(self.ms); + let te = Self::expander_db(level); + let c = if te > self.env_exp { self.fast } else { self.exp_close }; + self.env_exp = c * self.env_exp + (1.0 - c) * te; + let tc = Self::compressor_db(level); + let c = if tc < self.env_comp { self.fast } else { self.comp_rel }; + self.env_comp = c * self.env_comp + (1.0 - c) * tc; + if self.env_exp.abs() < 1e-9 { + self.env_exp = 0.0; + } + if self.env_comp.abs() < 1e-9 { + self.env_comp = 0.0; + } + let g = 10f64.powf((self.env_exp + self.env_comp + ENH_MAKEUP) / 20.0); + let m = self.mix.tick() as f64; + for (ch, w) in wet.iter().enumerate().take(nch) { + let dry = channels[ch][i] as f64; + channels[ch][i] = (dry + m * (w * g - dry)) as f32; + } + } + } +} + +// --------------------------------------------------------------------------------------------- + +/// Stereo width by mid/side scaling: 0 % = mono, 100 % = unchanged, 200 % = side doubled. +/// Only the first two channels are processed; mono input passes through. +pub struct StereoWidth { + pv: ParamValues, + width: Smoothed, +} + +impl StereoWidth { + pub const PARAMS: &'static [ParamSpec] = &[ParamSpec::new("width", "Width", 0.0, 200.0, 100.0, Unit::Percent)]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = StereoWidth { pv: ParamValues::new(Self::PARAMS), width: Smoothed::with_ms(1.0, sample_rate, 20.0) }; + s.apply_params(true); + s + } + fn apply_params(&mut self, snap: bool) { + self.width.set(self.pv.v("width") / 100.0); + if snap { + self.width.snap(); + } + } +} + +impl AudioEffect for StereoWidth { + param_plumbing!("stereo_width"); + fn reset(&mut self) { + self.width.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + if channels.len() < 2 { + // keep the smoother in step with time + for _ in 0..n { + self.width.tick(); + } + return; + } + let (l, rest) = channels.split_at_mut(1); + let (l, r) = (&mut l[0], &mut rest[0]); + for i in 0..n { + let w = self.width.tick(); + let m = 0.5 * (l[i] + r[i]); + let s = 0.5 * (l[i] - r[i]) * w; + l[i] = m + s; + r[i] = m - s; + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::*; + + const SR: f32 = 48000.0; + + fn energy(x: &[f32]) -> f64 { + x.iter().map(|&v| (v as f64) * (v as f64)).sum::() + } + + #[test] + fn speech_enhance_processes_every_channel_it_was_built_for() { + let mut fx = SpeechEnhance::new(SR, 12); + fx.set_param("mix", 100.0); + let x = sine(300.0, 0.3, SR as f64, 4_800, 0.0); + let mut bufs = vec![x.clone(); 12]; + let mut chans: Vec<&mut [f32]> = bufs.iter_mut().map(|b| &mut b[..]).collect(); + fx.process(&mut chans); + assert!(bufs[0] != x, "the first channel is unchanged"); + assert!(bufs.iter().all(|b| *b == bufs[0]), "the channels differ"); + } + + /// Band-limited energy via a 4th-order band-pass (two cascaded RBJ band-passes at the + /// geometric center), for relative before/after comparisons. + fn band_energy(x: &[f32], lo: f64, hi: f64) -> f64 { + let fc = (lo * hi).sqrt(); + let q = fc / (hi - lo); + let c = Coeffs::design(FilterType::BandPass, SR as f64, fc, q, 0.0); + let (mut a, mut b) = (Biquad::new(), Biquad::new()); + x.iter().map(|&v| b.tick(&c, a.tick(&c, v as f64))).map(|v| v * v).sum::() + } + + fn harmonic_voice(n: usize, f0: f64, amp: f64) -> Vec { + let mut v = vec![0.0f32; n]; + let mut k = 1; + while f0 * k as f64 <= 1500.0 { + let s = sine(f0 * k as f64, amp / k as f64, SR as f64, n, k as f64 * 0.7); + for (o, x) in v.iter_mut().zip(&s) { + *o += x; + } + k += 1; + } + v + } + + fn bandpassed_noise(seed: u64, n: usize, lo: f64, hi: f64, amp: f32) -> Vec { + let mut r = Rng::new(seed); + let fc = (lo * hi).sqrt(); + let c = Coeffs::design(FilterType::BandPass, SR as f64, fc, fc / (hi - lo), 0.0); + let (mut a, mut b) = (Biquad::new(), Biquad::new()); + (0..n).map(|_| (b.tick(&c, a.tick(&c, (r.uniform() * amp) as f64)) * 2.0) as f32).collect() + } + + #[test] + fn deesser_zero_reduction_is_identity() { + let mut d = DeEsser::new(SR, 1); + d.set_param("reduction", 0.0); + d.reset(); + let mut r = Rng::new(3); + let x: Vec = (0..20000).map(|_| r.uniform() * 0.5).collect(); + let mut y = x.clone(); + d.process(&mut [&mut y]); + for (a, b) in x.iter().zip(&y) { + assert!((a - b).abs() < 1e-6); + } + } + + #[test] + fn deesser_reduces_sibilance_keeps_voice() { + let n = SR as usize * 4; + let voice = harmonic_voice(n, 150.0, 0.15); + let sib = bandpassed_noise(11, n, 5000.0, 10000.0, 0.6); + // sibilant bursts: 150 ms every 500 ms (from 250 ms) + let burst = |i: usize| { + let p = i % (SR as usize / 2); + p >= SR as usize / 4 && p < SR as usize / 4 + (0.15 * SR) as usize + }; + let x: Vec = (0..n).map(|i| voice[i] + if burst(i) { sib[i] } else { 0.0 }).collect(); + for (reduction, need) in [(8.0f32, 5.0f64), (16.0, 6.0)] { + let mut d = DeEsser::new(SR, 1); + d.set_param("reduction", reduction); + d.reset(); + let mut y = x.clone(); + d.process(&mut [&mut y]); + let pick = |v: &[f32], on: bool| -> Vec { + v.iter().enumerate().skip(SR as usize).filter(|(i, _)| burst(*i) == on).map(|(_, s)| *s).collect() + }; + let (xb, yb) = (pick(&x, true), pick(&y, true)); + let sib_drop = 10.0 * (band_energy(&yb, 5000.0, 10000.0) / band_energy(&xb, 5000.0, 10000.0)).log10(); + let low_change = 10.0 * (band_energy(&y, 150.0, 1500.0) / band_energy(&x, 150.0, 1500.0)).log10(); + let (xq, yq) = (pick(&x, false), pick(&y, false)); + let quiet_change = 10.0 * (energy(&yq) / energy(&xq)).log10(); + println!( + "deesser reduction {reduction} dB: sibilance {sib_drop:.2} dB, voice band {low_change:.3} dB, non-sibilant passages {quiet_change:.3} dB" + ); + assert!(sib_drop < -need, "sibilance only {sib_drop} dB"); + assert!(low_change.abs() < 1.0, "voice band changed {low_change} dB"); + assert!(quiet_change.abs() < 0.5, "non-sibilant passages changed {quiet_change} dB"); + } + } + + /// Voice bursts (0.1 s every 0.5 s) with a statistical late-reverb tail (DRR about 0 dB). + fn reverberant_bursts(n: usize) -> (Vec, usize, usize) { + let sr = SR as f64; + let period = (0.5 * sr) as usize; + let on = (0.1 * sr) as usize; + let dry_src = harmonic_voice(n, 180.0, 0.25); + let dry: Vec = (0..n).map(|i| if i % period < on { dry_src[i] } else { 0.0 }).collect(); + // Statistical late reverb (Polack): white noise shaped by the energy envelope of the dry + // signal convolved with an exponential decay (a one-pole filter on the energy). + let rt60 = 0.8; + let a = (-6.0 * std::f64::consts::LN_10 / (rt60 * sr)).exp(); // power decay per sample + let mut e = 0.0f64; + let mut rng = Rng::new(77); + let wet_gain = 1.0 - a; // tail energy ≈ direct energy (DRR ≈ 0 dB) + let x: Vec = dry + .iter() + .map(|&d| { + e = a * e + wet_gain * (d as f64) * (d as f64); + d + (rng.uniform() as f64 * 3f64.sqrt() * e.sqrt()) as f32 + }) + .collect(); + (x, period, on) + } + + /// After one NaN or infinite input sample DeReverb's gain reduction comes back: the tail + /// suppression matches a run without the bad sample (not just finite output). + #[test] + fn dereverb_gain_reduction_recovers_after_non_finite_sample() { + let n = SR as usize * 6; + let (x, period, on) = reverberant_bursts(n); + let run = |bad: Option| { + let mut fx = DeReverb::new(SR, 1); + fx.set_param("amount", 100.0); + fx.reset(); + let mut y = x.clone(); + if let Some(b) = bad { + y[SR as usize * 2 + 777] = b; + } + for blk in y.chunks_mut(512) { + fx.process(&mut [blk]); + } + y.split_off(DeReverb::new(SR, 1).latency()) + }; + // Tail-to-burst energy ratio (dB) over the last two seconds (latency already removed). + let tail_ratio = |v: &[f32]| { + let (mut b, mut g) = (0.0f64, 0.0f64); + for (i, s) in v.iter().enumerate().skip(SR as usize * 4) { + let p = (*s as f64) * (*s as f64); + if i % period < on { b += p } else { g += p } + } + 10.0 * (g / b).log10() + }; + let clean = run(None); + let x = &x[..clean.len()]; + let reduction = tail_ratio(x) - tail_ratio(&clean); + assert!(reduction >= 4.0, "clean run reduces the tail by only {reduction} dB"); + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let y = run(Some(bad)); + assert!(y[SR as usize * 4..].iter().all(|v| v.is_finite()), "{bad}: output not finite"); + let got = tail_ratio(x) - tail_ratio(&y); + assert!((got - reduction).abs() < 0.5, "{bad}: tail reduction {got} dB after the bad sample, {reduction} dB without"); + } + } + + #[test] + fn dereverb_suppresses_tail() { + let n = SR as usize * 6; + let (x, period, on) = reverberant_bursts(n); + let mut fx = DeReverb::new(SR, 1); + fx.set_param("amount", 100.0); + fx.reset(); + let lat = fx.latency(); + let mut y = x.clone(); + fx.process(&mut [&mut y]); + let y = &y[lat..]; + let start = SR as usize; // after warm-up + let split = |v: &[f32]| { + let (mut b, mut g) = (0.0, 0.0); + for (i, s) in v.iter().enumerate().take(n - lat).skip(start) { + let p = (*s as f64) * (*s as f64); + if i % period < on { b += p } else { g += p } + } + (b, g) + }; + let (xb, xg) = split(&x); + let (yb, yg) = split(y); + let before = 10.0 * (xg / xb).log10(); + let after = 10.0 * (yg / yb).log10(); + let burst_loss = 10.0 * (yb / xb).log10(); + println!("dereverb: tail/burst {before:.2} dB → {after:.2} dB (improvement {:.2} dB), burst energy {burst_loss:.2} dB", before - after); + assert!(before - after >= 4.0, "tail improvement only {} dB", before - after); + assert!(burst_loss > -3.0, "burst energy lost {burst_loss} dB"); + } + + #[test] + fn dereverb_zero_amount_is_delayed_identity() { + let mut d = DeReverb::new(SR, 1); + d.set_param("amount", 0.0); + let lat = d.latency(); + let mut rng = Rng::new(9); + let x: Vec = (0..20000).map(|_| rng.uniform() * 0.5).collect(); + let mut y = x.clone(); + d.process(&mut [&mut y]); + for i in lat..x.len() { + assert!((y[i] - x[i - lat]).abs() < 1e-4); + } + } + + #[test] + fn speech_enhance_presence_noise_and_level() { + let sr = SR as usize; + let n = sr * 4; + let voice = harmonic_voice(n, 140.0, 0.08); + let fric = bandpassed_noise(5, n, 1500.0, 6000.0, 0.05); + let mut rng = Rng::new(42); + // syllables: 200 ms on, 200 ms off; −60 dBFS-ish background noise throughout + let syl = |i: usize| (i / (sr / 5)).is_multiple_of(2); + let x: Vec = (0..n).map(|i| rng.uniform() * 0.0017 + if syl(i) { voice[i] + fric[i] } else { 0.0 }).collect(); + let mut fx = SpeechEnhance::new(SR, 1); + let mut y = x.clone(); + fx.process(&mut [&mut y]); + let pick = |v: &[f32], on: bool| -> Vec { + v.iter() + .enumerate() + .skip(sr) + .filter(|(i, _)| { + let p = i % (2 * sr / 5); + // skip 50 ms after each edge + syl(*i) == on && p % (sr / 5) > sr / 20 + }) + .map(|(_, s)| *s) + .collect() + }; + let (xs, ys) = (pick(&x, true), pick(&y, true)); + let tilt_in = 10.0 * (band_energy(&xs, 2000.0, 5000.0) / band_energy(&xs, 200.0, 400.0)).log10(); + let tilt_out = 10.0 * (band_energy(&ys, 2000.0, 5000.0) / band_energy(&ys, 200.0, 400.0)).log10(); + let noise = 10.0 * (energy(&pick(&y, false)) / energy(&pick(&x, false))).log10(); + let level = 10.0 * (energy(&y[sr..]) / energy(&x[sr..])).log10(); + println!( + "enhance speech: presence/mud tilt {tilt_in:.2} → {tilt_out:.2} dB (+{:.2}), noise between syllables {noise:.2} dB, level {level:.2} dB", + tilt_out - tilt_in + ); + assert!(tilt_out - tilt_in > 3.0); + assert!(noise <= -3.0, "noise floor only {noise} dB"); + assert!(level.abs() <= 3.0, "level changed {level} dB"); + // mix 0 is identity + let mut fx = SpeechEnhance::new(SR, 1); + fx.set_param("mix", 0.0); + fx.reset(); + let mut z = x.clone(); + fx.process(&mut [&mut z]); + assert!(z.iter().zip(&x).all(|(a, b)| (a - b).abs() < 1e-6)); + } + + #[test] + fn stereo_width_laws() { + let mut rng = Rng::new(1); + let l0: Vec = (0..4000).map(|_| rng.uniform() * 0.5).collect(); + let r0: Vec = (0..4000).map(|_| rng.uniform() * 0.5).collect(); + let run = |w: f32| { + let mut fx = StereoWidth::new(SR, 2); + fx.set_param("width", w); + fx.reset(); + let (mut l, mut r) = (l0.clone(), r0.clone()); + fx.process(&mut [&mut l, &mut r]); + (l, r) + }; + let (l, r) = run(0.0); + assert!(l.iter().zip(&r).all(|(a, b)| (a - b).abs() < 1e-7)); + let (l, r) = run(100.0); + assert!(l.iter().zip(&l0).chain(r.iter().zip(&r0)).all(|(a, b)| (a - b).abs() < 1e-6)); + let (l, r) = run(200.0); + for i in 0..l.len() { + let (m, s) = (0.5 * (l0[i] + r0[i]), 0.5 * (l0[i] - r0[i])); + assert!((0.5 * (l[i] + r[i]) - m).abs() < 1e-6); + assert!((0.5 * (l[i] - r[i]) - 2.0 * s).abs() < 1e-6); + } + // mono passes through + let mut fx = StereoWidth::new(SR, 2); + fx.set_param("width", 0.0); + let mut m = l0.clone(); + fx.process(&mut [&mut m]); + assert_eq!(m, l0); + } + + /// A dialogue cleanup chain on 60 s of stereo 48 kHz. + /// `cargo test --release -p craft-audio-dsp dialogue_chain_realtime -- --ignored --nocapture` + #[test] + #[ignore] + fn dialogue_chain_realtime() { + let sr = SR as usize; + let n = sr * 60; + let mut rng = Rng::new(3); + let voice = harmonic_voice(n, 140.0, 0.1); + let mut l: Vec = (0..n).map(|i| voice[i] + rng.uniform() * 0.01).collect(); + let mut r: Vec = l.iter().map(|v| v * 0.9 + rng.uniform() * 0.01).collect(); + let mut chain: Vec> = + ["denoise", "parametric_eq", "dehum", "deesser", "dereverb", "compressor", "simple_eq", "speech_enhance", "reverb"] + .iter() + .map(|id| crate::create_effect(id, SR, 2).unwrap()) + .collect(); + chain[1].set_param("b1.on", 1.0); + chain[1].set_param("b2.on", 1.0); + chain[1].set_param("b2.type", 4.0); + chain[1].set_param("b2.freq", 80.0); + let t0 = std::time::Instant::now(); + for (lb, rb) in l.chunks_mut(1024).zip(r.chunks_mut(1024)) { + for fx in chain.iter_mut() { + fx.process(&mut [&mut *lb, &mut *rb]); + } + } + let secs = t0.elapsed().as_secs_f64(); + println!("dialogue chain: 60 s stereo in {secs:.3} s = {:.1}× realtime (one core)", 60.0 / secs); + assert!(l.iter().chain(&r).all(|v| v.is_finite())); + } +} diff --git a/crates/audio-dsp/src/effects/filters.rs b/crates/audio-dsp/src/effects/filters.rs new file mode 100644 index 000000000..444ec5120 --- /dev/null +++ b/crates/audio-dsp/src/effects/filters.rs @@ -0,0 +1,698 @@ +//! Filter and EQ effects: graphic equalizers (10/20/30 bands), the full parametric equalizer +//! (pass filters, shelves, five peaking bands), the six-notch filter, the Scientific Filter +//! (Bessel / Butterworth / Chebyshev / elliptic designs) and the FFT Filter (frequency-sampled +//! gain curve applied by STFT overlap-add). + +use super::eq::{BandBank, BandSettings, MAX_BANDS}; +use super::stft::{Pairing, Plan, Spectral, StftChannel, fft_size, stream}; +use crate::biquad::{Biquad, FilterType}; +use crate::design::{self, Band, Family, MAX_SECTIONS, Prototype, Sections}; +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing}; + +const SMOOTH_MS: f32 = 30.0; + +/// Q of a peaking band `octaves` wide (between the −3 dB points of the analog prototype). +pub fn q_for_octaves(octaves: f64) -> f64 { + let p = 2f64.powf(octaves); + p.sqrt() / (p - 1.0) +} + +/// Copy `N` parameter-spec arrays into one flat array (const-evaluable). +const fn flatten(groups: [[ParamSpec; K]; N]) -> [ParamSpec; M] { + let mut out = [ParamSpec::new("", "", 0.0, 0.0, 0.0, Unit::None); M]; + let mut g = 0; + while g < N { + let mut k = 0; + while k < K { + out[g * K + k] = groups[g][k]; + k += 1; + } + g += 1; + } + out +} + +/// `a` followed by `b` (const-evaluable). +const fn join(a: [ParamSpec; A], b: [ParamSpec; B]) -> [ParamSpec; M] { + let mut out = [ParamSpec::new("", "", 0.0, 0.0, 0.0, Unit::None); M]; + let mut i = 0; + while i < A { + out[i] = a[i]; + i += 1; + } + let mut j = 0; + while j < B { + out[A + j] = b[j]; + j += 1; + } + out +} + +// ------------------------------------------------------------------------------ graphic EQ + +/// Center frequencies of the 10-band graphic equalizer. +pub const GEQ10_FREQS: [f32; 10] = [31.5, 63.0, 125.0, 250.0, 500.0, 1000.0, 2000.0, 4000.0, 8000.0, 16000.0]; +const GEQ10_PARAMS: &[ParamSpec] = &[ + ParamSpec::new("b1", "31.5 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b2", "63 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b3", "125 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b4", "250 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b5", "500 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b6", "1 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b7", "2 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b8", "4 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b9", "8 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b10", "16 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("gain", "Master Gain", -24.0, 24.0, 0.0, Unit::Decibels), +]; +/// Center frequencies of the 20-band graphic equalizer. +pub const GEQ20_FREQS: [f32; 20] = [ + 31.5, 44.0, 63.0, 88.0, 125.0, 177.0, 250.0, 355.0, 500.0, 710.0, 1000.0, 1400.0, 2000.0, 2800.0, 4000.0, 5600.0, 8000.0, 11200.0, 16000.0, + 22400.0, +]; +const GEQ20_PARAMS: &[ParamSpec] = &[ + ParamSpec::new("b1", "31.5 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b2", "44 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b3", "63 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b4", "88 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b5", "125 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b6", "177 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b7", "250 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b8", "355 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b9", "500 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b10", "710 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b11", "1 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b12", "1.4 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b13", "2 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b14", "2.8 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b15", "4 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b16", "5.6 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b17", "8 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b18", "11.2 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b19", "16 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b20", "22.4 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("gain", "Master Gain", -24.0, 24.0, 0.0, Unit::Decibels), +]; +/// Center frequencies of the 30-band graphic equalizer. +pub const GEQ30_FREQS: [f32; 30] = [ + 25.0, 31.5, 40.0, 50.0, 63.0, 80.0, 100.0, 125.0, 160.0, 200.0, 250.0, 315.0, 400.0, 500.0, 630.0, 800.0, 1000.0, 1250.0, 1600.0, 2000.0, 2500.0, + 3150.0, 4000.0, 5000.0, 6300.0, 8000.0, 10000.0, 12500.0, 16000.0, 20000.0, +]; +const GEQ30_PARAMS: &[ParamSpec] = &[ + ParamSpec::new("b1", "25 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b2", "31.5 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b3", "40 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b4", "50 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b5", "63 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b6", "80 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b7", "100 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b8", "125 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b9", "160 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b10", "200 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b11", "250 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b12", "315 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b13", "400 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b14", "500 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b15", "630 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b16", "800 Hz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b17", "1 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b18", "1.25 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b19", "1.6 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b20", "2 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b21", "2.5 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b22", "3.15 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b23", "4 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b24", "5 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b25", "6.3 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b26", "8 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b27", "10 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b28", "12.5 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b29", "16 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("b30", "20 kHz", -24.0, 24.0, 0.0, Unit::Decibels), + ParamSpec::new("gain", "Master Gain", -24.0, 24.0, 0.0, Unit::Decibels), +]; + +/// Constant-Q graphic equalizer with 10 (octave), 20 (half-octave) or 30 (third-octave) bands. +pub struct GraphicEq { + pv: ParamValues, + bank: BandBank, + out: Smoothed, +} + +impl GraphicEq { + pub const PARAMS: &'static [ParamSpec] = match N { + 10 => GEQ10_PARAMS, + 20 => GEQ20_PARAMS, + _ => GEQ30_PARAMS, + }; + const ID: &'static str = match N { + 10 => "graphic_eq_10", + 20 => "graphic_eq_20", + _ => "graphic_eq_30", + }; + + /// Band center frequencies. + pub fn freqs() -> &'static [f32] { + match N { + 10 => &GEQ10_FREQS, + 20 => &GEQ20_FREQS, + _ => &GEQ30_FREQS, + } + } + + /// Band Q (octave, half-octave or third-octave bandwidth). + pub fn q() -> f32 { + q_for_octaves(match N { + 10 => 1.0, + 20 => 0.5, + _ => 1.0 / 3.0, + }) as f32 + } + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + assert!(N <= MAX_BANDS); + let mut s = GraphicEq { + pv: ParamValues::new(Self::PARAMS), + bank: BandBank::new(sample_rate, channels, N), + out: Smoothed::with_ms(1.0, sample_rate, SMOOTH_MS), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let q = Self::q(); + for (i, &f) in Self::freqs().iter().enumerate() { + let g = self.pv.v(Self::PARAMS[i].id); + self.bank.set_band(i, BandSettings::new(true, FilterType::Peaking, f, g, q, snap)); + } + self.out.set(db_to_gain(self.pv.v("gain"))); + if snap { + self.out.snap(); + self.bank.update_coeffs(true); + } + } +} + +impl AudioEffect for GraphicEq { + param_plumbing!(Self::ID); + fn response_db(&self, freq: f64) -> Option { + Some(self.bank.response_db(freq) + self.pv.v("gain") as f64) + } + fn reset(&mut self) { + self.out.snap(); + self.bank.reset(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + self.bank.process(channels, &mut self.out); + } +} + +// ----------------------------------------------------------------------- parametric EQ + +/// Pass-filter slopes. +pub const SLOPES: &[&str] = &["12 dB/oct", "24 dB/oct", "36 dB/oct", "48 dB/oct"]; + +macro_rules! peq_band { + ($p:literal, $name:literal, $f:expr, $q:expr) => { + [ + ParamSpec::toggle(concat!($p, "_on"), concat!($name, " On"), true), + ParamSpec::log(concat!($p, "_freq"), concat!($name, " Frequency"), 20.0, 20000.0, $f, Unit::Hertz), + ParamSpec::new(concat!($p, "_gain"), concat!($name, " Gain"), -30.0, 30.0, 0.0, Unit::Decibels), + ParamSpec::log(concat!($p, "_q"), concat!($name, " Q"), 0.1, 30.0, $q, Unit::Q), + ] + }; +} + +/// The bands of the full parametric equalizer between its pass filters, in signal order: +/// (parameter prefix, filter type). +pub const PEQ_BANDS: [(&str, FilterType); 7] = [ + ("low", FilterType::LowShelf), + ("b1", FilterType::Peaking), + ("b2", FilterType::Peaking), + ("mid", FilterType::Peaking), + ("b4", FilterType::Peaking), + ("b5", FilterType::Peaking), + ("high", FilterType::HighShelf), +]; + +const PEQ_BAND_IDS: [[&str; 4]; 7] = [ + ["low_on", "low_freq", "low_gain", "low_q"], + ["b1_on", "b1_freq", "b1_gain", "b1_q"], + ["b2_on", "b2_freq", "b2_gain", "b2_q"], + ["mid_on", "mid_freq", "mid_gain", "mid_q"], + ["b4_on", "b4_freq", "b4_gain", "b4_q"], + ["b5_on", "b5_freq", "b5_gain", "b5_q"], + ["high_on", "high_freq", "high_gain", "high_q"], +]; + +const PEQ_HEAD: [ParamSpec; 4] = [ + ParamSpec::new("master_gain", "Master Gain", -30.0, 30.0, 0.0, Unit::Decibels), + ParamSpec::toggle("hp_on", "High Pass On", false), + ParamSpec::log("hp_freq", "High Pass Frequency", 10.0, 20000.0, 30.0, Unit::Hertz), + ParamSpec::choice("hp_slope", "High Pass Slope", SLOPES, 0), +]; +const PEQ_TAIL: [ParamSpec; 3] = [ + ParamSpec::toggle("lp_on", "Low Pass On", false), + ParamSpec::log("lp_freq", "Low Pass Frequency", 20.0, 22000.0, 18000.0, Unit::Hertz), + ParamSpec::choice("lp_slope", "Low Pass Slope", SLOPES, 0), +]; +const PEQ_MID: [ParamSpec; 28] = flatten([ + peq_band!("low", "Low Shelf", 100.0, 0.707), + peq_band!("b1", "Band 1", 200.0, 1.0), + peq_band!("b2", "Band 2", 500.0, 1.0), + peq_band!("mid", "Band 3", 1000.0, 1.0), + peq_band!("b4", "Band 4", 2000.0, 1.0), + peq_band!("b5", "Band 5", 5000.0, 1.0), + peq_band!("high", "High Shelf", 8000.0, 0.707), +]); +const PEQ_HEAD_MID: [ParamSpec; 32] = join(PEQ_HEAD, PEQ_MID); +const PEQ_PARAMS: [ParamSpec; 35] = join(PEQ_HEAD_MID, PEQ_TAIL); + +/// Butterworth Q of section `k` (0-based) of an order-`2m` cascade. +pub fn butterworth_q(m: usize, k: usize) -> f32 { + let n = 2 * m; + (1.0 / (2.0 * (std::f64::consts::PI * (2 * k + 1) as f64 / (2 * n) as f64).cos())) as f32 +} + +/// Full parametric equalizer: master gain, high-pass (12–48 dB/oct), low shelf, +/// five peaking bands, high shelf and low-pass (12–48 dB/oct), all RBJ biquads. +pub struct FullParametricEq { + pv: ParamValues, + bank: BandBank, + out: Smoothed, +} + +impl FullParametricEq { + pub const PARAMS: &'static [ParamSpec] = &PEQ_PARAMS; + /// Bank layout: 4 high-pass slots, 7 bands, 4 low-pass slots. + const SLOTS: usize = 4 + 7 + 4; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = FullParametricEq { + pv: ParamValues::new(Self::PARAMS), + bank: BandBank::new(sample_rate, channels, Self::SLOTS), + out: Smoothed::with_ms(1.0, sample_rate, SMOOTH_MS), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let p = &self.pv; + let pass = |on: bool, slope: usize, slot: usize| -> (bool, f32) { + let m = slope + 1; + if on && slot < m { (true, butterworth_q(m, slot)) } else { (false, std::f32::consts::FRAC_1_SQRT_2) } + }; + let (hp_on, hp_f, hp_s) = (p.on("hp_on"), p.v("hp_freq"), p.idx("hp_slope")); + let (lp_on, lp_f, lp_s) = (p.on("lp_on"), p.v("lp_freq"), p.idx("lp_slope")); + let mut bands = [(false, FilterType::Peaking, 1000.0, 0.0, 1.0); 7]; + for (i, ids) in PEQ_BAND_IDS.iter().enumerate() { + bands[i] = (p.on(ids[0]), PEQ_BANDS[i].1, p.v(ids[1]), p.v(ids[2]), p.v(ids[3])); + } + for slot in 0..4 { + let (on, q) = pass(hp_on, hp_s, slot); + self.bank.set_band(slot, BandSettings::new(on, FilterType::HighPass, hp_f, 0.0, q, snap)); + let (on, q) = pass(lp_on, lp_s, slot); + self.bank.set_band(11 + slot, BandSettings::new(on, FilterType::LowPass, lp_f, 0.0, q, snap)); + } + for (i, (on, kind, f, g, q)) in bands.into_iter().enumerate() { + self.bank.set_band(4 + i, BandSettings::new(on, kind, f, g, q, snap)); + } + self.out.set(db_to_gain(self.pv.v("master_gain"))); + if snap { + self.out.snap(); + self.bank.update_coeffs(true); + } + } +} + +impl AudioEffect for FullParametricEq { + param_plumbing!("parametric_eq_full"); + fn response_db(&self, freq: f64) -> Option { + Some(self.bank.response_db(freq) + self.pv.v("master_gain") as f64) + } + fn reset(&mut self) { + self.out.snap(); + self.bank.reset(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + self.bank.process(channels, &mut self.out); + } +} + +// ---------------------------------------------------------------------------- notch filter + +/// Notch widths. +pub const NOTCH_WIDTHS: &[&str] = &["Narrow", "Very Narrow", "Super Narrow"]; +const NOTCH_Q: [f32; 3] = [8.0, 20.0, 50.0]; + +macro_rules! notch { + ($n:literal, $f:expr) => { + [ + ParamSpec::toggle(concat!("n", $n, "_on"), concat!("Notch ", $n, " On"), false), + ParamSpec::log(concat!("n", $n, "_freq"), concat!("Notch ", $n, " Frequency"), 20.0, 20000.0, $f, Unit::Hertz), + ParamSpec::new(concat!("n", $n, "_gain"), concat!("Notch ", $n, " Gain"), -90.0, 0.0, -30.0, Unit::Decibels), + ] + }; +} + +const NOTCH_BANDS: [ParamSpec; 18] = + flatten([notch!("1", 60.0), notch!("2", 120.0), notch!("3", 180.0), notch!("4", 240.0), notch!("5", 300.0), notch!("6", 360.0)]); +const NOTCH_PARAMS: [ParamSpec; 19] = join(NOTCH_BANDS, [ParamSpec::choice("width", "Notch Width", NOTCH_WIDTHS, 0)]); + +const NOTCH_IDS: [[&str; 3]; 6] = [ + ["n1_on", "n1_freq", "n1_gain"], + ["n2_on", "n2_freq", "n2_gain"], + ["n3_on", "n3_freq", "n3_gain"], + ["n4_on", "n4_freq", "n4_gain"], + ["n5_on", "n5_freq", "n5_gain"], + ["n6_on", "n6_freq", "n6_gain"], +]; + +/// Up to six narrow cuts (constant-bandwidth [`FilterType::Cut`] biquads) of selectable width. +pub struct NotchFilter { + pv: ParamValues, + bank: BandBank, + out: Smoothed, +} + +impl NotchFilter { + pub const PARAMS: &'static [ParamSpec] = &NOTCH_PARAMS; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = NotchFilter { pv: ParamValues::new(Self::PARAMS), bank: BandBank::new(sample_rate, channels, 6), out: Smoothed::new(1.0, 0) }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let q = NOTCH_Q[self.pv.idx("width").min(2)]; + for (i, ids) in NOTCH_IDS.iter().enumerate() { + self.bank.set_band(i, BandSettings::new(self.pv.on(ids[0]), FilterType::Cut, self.pv.v(ids[1]), self.pv.v(ids[2]), q, snap)); + } + if snap { + self.bank.update_coeffs(true); + } + } +} + +impl AudioEffect for NotchFilter { + param_plumbing!("notch_filter"); + fn response_db(&self, freq: f64) -> Option { + Some(self.bank.response_db(freq)) + } + fn reset(&mut self) { + self.bank.reset(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + self.bank.process(channels, &mut self.out); + } +} + +// ----------------------------------------------------------------------- scientific filter + +pub const SCI_TYPES: &[&str] = &["Bessel", "Butterworth", "Chebyshev", "Elliptical"]; +pub const SCI_MODES: &[&str] = &["Low Pass", "High Pass", "Band Pass", "Band Stop"]; + +/// Classical IIR designs (see [`crate::design`]) as a cascade of biquads. Cutoff changes glide +/// (redesigned every 32 samples while moving); type/order/ripple changes switch immediately. +pub struct ScientificFilter { + pv: ParamValues, + sr: f32, + proto_key: (usize, usize, f32, f32), + proto: Prototype, + band: Band, + /// log2 cutoffs (smoothed so automation glides). + f1: Smoothed, + f2: Smoothed, + sections: Sections, + state: Vec<[Biquad; MAX_SECTIONS]>, + gain: Smoothed, + counter: u32, + dirty: bool, +} + +impl ScientificFilter { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::choice("type", "Type", SCI_TYPES, 1), + ParamSpec::choice("mode", "Mode", SCI_MODES, 0), + ParamSpec::new("order", "Order", 1.0, design::MAX_ORDER as f32, 6.0, Unit::None), + ParamSpec::log("cutoff", "Cutoff", 20.0, 20000.0, 1000.0, Unit::Hertz), + ParamSpec::log("high_cutoff", "High Cutoff", 20.0, 20000.0, 4000.0, Unit::Hertz), + ParamSpec::new("ripple", "Passband Ripple", 0.01, 6.0, 1.0, Unit::Decibels), + ParamSpec::new("stop_atten", "Stopband Attenuation", 20.0, 120.0, 60.0, Unit::Decibels), + ParamSpec::new("gain", "Master Gain", -30.0, 30.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let proto = design::prototype(Family::Butterworth, 1, 1.0, 60.0); + let mut s = ScientificFilter { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + proto_key: (usize::MAX, 0, 0.0, 0.0), + proto, + band: Band::LowPass, + f1: Smoothed::with_ms(10.0, sample_rate, SMOOTH_MS), + f2: Smoothed::with_ms(12.0, sample_rate, SMOOTH_MS), + sections: design::realize(&proto, Band::LowPass, 1000.0, 2000.0, sample_rate as f64), + state: vec![[Biquad::new(); MAX_SECTIONS]; crate::sane_channels(channels)], + gain: Smoothed::with_ms(1.0, sample_rate, SMOOTH_MS), + counter: 0, + dirty: true, + }; + s.apply_params(true); + s + } + + fn family(&self) -> Family { + [Family::Bessel, Family::Butterworth, Family::Chebyshev, Family::Elliptic][self.pv.idx("type").min(3)] + } + + fn apply_params(&mut self, snap: bool) { + let key = (self.pv.idx("type"), self.pv.v("order").round() as usize, self.pv.v("ripple"), self.pv.v("stop_atten")); + if key != self.proto_key { + self.proto_key = key; + self.proto = design::prototype(self.family(), key.1, key.2 as f64, key.3 as f64); + } + self.band = [Band::LowPass, Band::HighPass, Band::BandPass, Band::BandStop][self.pv.idx("mode").min(3)]; + self.f1.set(self.pv.v("cutoff").log2()); + self.f2.set(self.pv.v("high_cutoff").log2()); + self.gain.set(db_to_gain(self.pv.v("gain"))); + self.dirty = true; + if snap { + self.f1.snap(); + self.f2.snap(); + self.gain.snap(); + self.redesign(); + } + } + + fn redesign(&mut self) { + let (f1, f2) = (2f64.powf(self.f1.value() as f64), 2f64.powf(self.f2.value() as f64)); + self.sections = design::realize(&self.proto, self.band, f1, f2, self.sr as f64); + self.dirty = self.f1.is_smoothing() || self.f2.is_smoothing(); + } + + /// The designed cascade at the target settings. + pub fn target_sections(&self) -> Sections { + design::realize(&self.proto, self.band, self.pv.v("cutoff") as f64, self.pv.v("high_cutoff") as f64, self.sr as f64) + } +} + +impl AudioEffect for ScientificFilter { + param_plumbing!("scientific_filter"); + fn response_db(&self, freq: f64) -> Option { + Some(self.target_sections().magnitude_db(freq, self.sr as f64) + self.pv.v("gain") as f64) + } + fn reset(&mut self) { + self.f1.snap(); + self.f2.snap(); + self.gain.snap(); + self.state.iter_mut().for_each(|s| s.iter_mut().for_each(Biquad::reset)); + self.counter = 0; + self.redesign(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.state.len()); + for i in 0..n { + if self.counter == 0 && self.dirty { + self.redesign(); + } + self.counter = (self.counter + 1) % 32; + self.f1.tick(); + self.f2.tick(); + if self.f1.is_smoothing() || self.f2.is_smoothing() { + self.dirty = true; + } + let g = self.gain.tick() as f64; + let secs = self.sections.as_slice(); + for ch in 0..nch { + let mut x = channels[ch][i] as f64; + for (c, st) in secs.iter().zip(self.state[ch].iter_mut()) { + x = st.tick(c, x); + } + channels[ch][i] = (x * g) as f32; + } + } + } +} + +// ------------------------------------------------------------------------------ FFT filter + +/// Number of FFT Filter curve points. +pub const FFT_POINTS: usize = 8; +const FFT_POINT_IDS: [[&str; 2]; FFT_POINTS] = [ + ["p1_freq", "p1_gain"], + ["p2_freq", "p2_gain"], + ["p3_freq", "p3_gain"], + ["p4_freq", "p4_gain"], + ["p5_freq", "p5_gain"], + ["p6_freq", "p6_gain"], + ["p7_freq", "p7_gain"], + ["p8_freq", "p8_gain"], +]; + +macro_rules! fft_point { + ($n:literal, $f:expr) => { + [ + ParamSpec::log(concat!("p", $n, "_freq"), concat!("Point ", $n, " Frequency"), 20.0, 20000.0, $f, Unit::Hertz), + ParamSpec::new(concat!("p", $n, "_gain"), concat!("Point ", $n, " Gain"), -60.0, 20.0, 0.0, Unit::Decibels), + ] + }; +} + +const FFT_POINT_PARAMS: [ParamSpec; 16] = flatten([ + fft_point!("1", 40.0), + fft_point!("2", 100.0), + fft_point!("3", 250.0), + fft_point!("4", 600.0), + fft_point!("5", 1500.0), + fft_point!("6", 4000.0), + fft_point!("7", 9000.0), + fft_point!("8", 16000.0), +]); +const FFT_PARAMS: [ParamSpec; 17] = join(FFT_POINT_PARAMS, [ParamSpec::choice("interp", "Interpolation", &["Linear", "Smooth"], 1)]); + +/// Gain (dB) of the FFT Filter curve at `freq` for points `(freq, gain_db)` (any order): +/// constant beyond the end points, interpolated in log-frequency between them (linearly or with +/// a smoothstep). +pub fn fft_curve_db(points: &[(f32, f32)], freq: f32, smooth: bool) -> f32 { + let mut pts = [(0.0f32, 0.0f32); FFT_POINTS]; + let n = points.len().min(FFT_POINTS); + pts[..n].copy_from_slice(&points[..n]); + pts[..n].sort_by(|a, b| a.0.total_cmp(&b.0)); + let pts = &pts[..n]; + if pts.is_empty() { + return 0.0; + } + if freq <= pts[0].0 { + return pts[0].1; + } + for w in pts.windows(2) { + if freq <= w[1].0 { + let span = (w[1].0 / w[0].0).log2(); + let mut t = if span > 0.0 { (freq / w[0].0).log2() / span } else { 1.0 }; + if smooth { + t = t * t * (3.0 - 2.0 * t); + } + return w[0].1 + (w[1].1 - w[0].1) * t; + } + } + pts[n - 1].1 +} + +/// Zero-phase frequency-domain gain curve (8 points), applied with a √Hann STFT at 75 % +/// overlap (latency = FFT size). Curve changes glide over a few frames. +pub struct FftFilter { + pv: ParamValues, + sr: f32, + n: usize, + hop: usize, + spec: Spectral, + stft: Vec, + /// Target and current per-bin linear gains. + target: Vec, + gains: Vec, +} + +impl FftFilter { + pub const PARAMS: &'static [ParamSpec] = &FFT_PARAMS; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let n = fft_size(sample_rate); + let bins = n / 2 + 1; + let mut s = FftFilter { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + n, + hop: n / 4, + spec: Spectral::new(n, true), + stft: vec![StftChannel::new(n); crate::sane_channels(channels)], + target: vec![1.0; bins], + gains: vec![1.0; bins], + }; + s.apply_params(true); + s + } + + fn points(&self) -> [(f32, f32); FFT_POINTS] { + let mut p = [(0.0, 0.0); FFT_POINTS]; + for (i, ids) in FFT_POINT_IDS.iter().enumerate() { + p[i] = (self.pv.v(ids[0]), self.pv.v(ids[1])); + } + p + } + + fn apply_params(&mut self, snap: bool) { + let pts = self.points(); + let smooth = self.pv.idx("interp") == 1; + let bins = self.n / 2 + 1; + for k in 0..bins { + let f = (k as f32 * self.sr / self.n as f32).max(1.0); + self.target[k] = db_to_gain(fft_curve_db(&pts, f, smooth)); + } + if snap { + self.gains.copy_from_slice(&self.target); + } + } +} + +impl AudioEffect for FftFilter { + param_plumbing!("fft_filter"); + fn latency(&self) -> usize { + self.n + } + fn response_db(&self, freq: f64) -> Option { + Some(fft_curve_db(&self.points(), freq as f32, self.pv.idx("interp") == 1) as f64) + } + fn reset(&mut self) { + self.stft.iter_mut().for_each(StftChannel::reset); + self.gains.copy_from_slice(&self.target); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let len = block_len(channels); + let (n, hop) = (self.n, self.hop); + let scale = 1.0 / (n as f32 * 2.0); + let bins = n / 2 + 1; + let (gains, target) = (&mut self.gains, &self.target); + stream(&mut self.stft, &mut self.spec, channels, len, Plan { hop, scale, pairing: Pairing::Full }, &mut |ch, _, re, im| { + // Every channel frames at the same samples; the gains glide once per frame. + if ch == 0 { + for k in 0..bins { + gains[k] += (target[k] - gains[k]) * 0.5; + } + } + for k in 0..bins { + re[k] *= gains[k]; + im[k] *= gains[k]; + } + }); + } +} diff --git a/crates/audio-dsp/src/effects/generator.rs b/crates/audio-dsp/src/effects/generator.rs new file mode 100644 index 000000000..f3fb684f7 --- /dev/null +++ b/crates/audio-dsp/src/effects/generator.rs @@ -0,0 +1,98 @@ +//! Signal generator: replaces its input with a test tone or noise (line-up tones, sync checks). + +use crate::generator::{Oscillator, Waveform}; +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing}; + +/// Level at and below which the generator is silent. +const OFF_DB: f32 = -96.0; + +/// Test-tone and noise generator. Every channel gets the same signal; the level and frequency +/// glide over 20 ms when changed. +pub struct SignalGenerator { + pv: ParamValues, + sr: f32, + osc: Oscillator, + wave: Waveform, + level: Smoothed, + freq: Smoothed, +} + +impl SignalGenerator { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::choice("waveform", "Waveform", &["Sine", "Square", "Saw", "Triangle", "White Noise", "Pink Noise"], 0), + ParamSpec::log("freq", "Frequency", 20.0, 20_000.0, 1_000.0, Unit::Hertz), + ParamSpec::new("level", "Level", OFF_DB, 0.0, -20.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = SignalGenerator { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + osc: Oscillator::new(0x00C0_FFEE), + wave: Waveform::Sine, + level: Smoothed::with_ms(0.0, sample_rate, 20.0), + freq: Smoothed::with_ms(1_000.0, sample_rate, 20.0), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.wave = Waveform::from_index(self.pv.idx("waveform")); + let db = self.pv.v("level"); + self.level.set(if db <= OFF_DB { 0.0 } else { db_to_gain(db) }); + self.freq.set(self.pv.v("freq")); + if snap { + self.level.snap(); + self.freq.snap(); + } + } +} + +impl AudioEffect for SignalGenerator { + param_plumbing!("signal_generator"); + fn reset(&mut self) { + self.osc.reset(); + self.level.snap(); + self.freq.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + for i in 0..n { + let g = self.level.tick(); + let f = self.freq.tick(); + let y = self.osc.next(self.wave, f / self.sr) * g; + for ch in channels.iter_mut() { + ch[i] = y; + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::{db, tone_amplitude}; + + #[test] + fn the_tone_replaces_the_input_at_the_set_level() { + let mut g = SignalGenerator::new(48_000.0, 2); + assert!(g.set_param("level", -12.0)); + g.reset(); + let (mut l, mut r) = (vec![0.7f32; 48_000], vec![-0.7f32; 48_000]); + g.process(&mut [&mut l, &mut r]); + assert_eq!(l, r); + assert!((db(tone_amplitude(&l, 1_000.0, 48_000.0)) + 12.0).abs() < 0.05); + } + + #[test] + fn the_lowest_level_is_silence() { + let mut g = SignalGenerator::new(48_000.0, 1); + assert!(g.set_param("level", -200.0)); + g.reset(); + let mut x = vec![0.5f32; 1024]; + g.process(&mut [&mut x]); + assert!(x.iter().all(|v| *v == 0.0)); + } +} diff --git a/crates/audio-dsp/src/effects/modulation.rs b/crates/audio-dsp/src/effects/modulation.rs new file mode 100644 index 000000000..57fa6f49c --- /dev/null +++ b/crates/audio-dsp/src/effects/modulation.rs @@ -0,0 +1,587 @@ +//! Modulation and echo effects: Chorus/Flanger, Flanger, Phaser, Analog Delay and Multitap +//! Delay. All modulated delays read with linear interpolation; feedback loops are bounded +//! (|g| < 1, or saturating for the Analog Delay). + +use super::util::{AllPass1, DelayLine, Envelope, Lfo, OnePole, coef, uni_sine, uni_tri, wrap_phase}; +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing}; + +const SM: f32 = 20.0; + +// ---------------------------------------------------------------------------- chorus / flanger + +/// Chorus (three modulated voices, 15–35 ms) or flanger (one voice, 0.3–5 ms, feedback). +pub struct ChorusFlanger { + pv: ParamValues, + sr: f32, + lines: Vec, + lfo: Lfo, + fb: Vec, + fast: Vec, + slow: Vec, + mix: Smoothed, + width: Smoothed, + intensity: Smoothed, + speed: f32, +} + +impl ChorusFlanger { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::choice("mode", "Mode", &["Chorus", "Flanger"], 0), + ParamSpec::log("speed", "Speed", 0.05, 10.0, 0.8, Unit::Hertz), + ParamSpec::new("width", "Width", 0.0, 100.0, 50.0, Unit::Percent), + ParamSpec::new("intensity", "Intensity", 0.0, 100.0, 30.0, Unit::Percent), + ParamSpec::new("transience", "Transience", 0.0, 100.0, 0.0, Unit::Percent), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 50.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let ch = crate::sane_channels(channels); + let max = (0.05 * sample_rate) as usize; + let mut s = ChorusFlanger { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + lines: vec![DelayLine::new(max); ch], + lfo: Lfo::default(), + fb: vec![0.0; ch], + fast: vec![Envelope::default(); ch], + slow: vec![Envelope::default(); ch], + mix: Smoothed::with_ms(0.0, sample_rate, SM), + width: Smoothed::with_ms(0.0, sample_rate, SM), + intensity: Smoothed::with_ms(0.0, sample_rate, SM), + speed: 1.0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.mix.set(self.pv.v("mix") / 100.0); + self.width.set(self.pv.v("width") / 100.0); + self.intensity.set(self.pv.v("intensity") / 100.0); + self.speed = self.pv.v("speed"); + if snap { + self.mix.snap(); + self.width.snap(); + self.intensity.snap(); + } + } +} + +impl AudioEffect for ChorusFlanger { + param_plumbing!("chorus_flanger"); + fn reset(&mut self) { + self.lines.iter_mut().for_each(DelayLine::reset); + self.lfo.reset(); + self.fb.iter_mut().for_each(|v| *v = 0.0); + self.fast.iter_mut().for_each(|e| e.env = 0.0); + self.slow.iter_mut().for_each(|e| e.env = 0.0); + self.mix.snap(); + self.width.snap(); + self.intensity.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.lines.len()); + let flanger = self.pv.idx("mode") == 1; + let trans = self.pv.v("transience") / 100.0; + let ms = self.sr * 0.001; + let (fa, fr, sa, sr_) = (coef(0.5, self.sr), coef(20.0, self.sr), coef(30.0, self.sr), coef(200.0, self.sr)); + for i in 0..n { + let mix = self.mix.tick(); + let width = self.width.tick(); + let inten = self.intensity.tick(); + for ch in 0..nch { + let x = channels[ch][i]; + let off = ch as f64 * 0.25; + let line = &mut self.lines[ch]; + let wet = if flanger { + let d = (0.3 + 4.7 * width * uni_tri(self.lfo.phase(off))) * ms; + let y = line.read(d); + self.fb[ch] = y; + y + } else { + let mut acc = 0.0; + for v in 0..3 { + let d = (15.0 + 20.0 * width * uni_sine(self.lfo.phase(off + v as f64 / 3.0))) * ms; + acc += line.read(d); + } + let y = acc / 3.0; + self.fb[ch] = y; + y + }; + let g = if flanger { 0.95 * inten } else { 0.6 * inten }; + line.push(x + g * self.fb[ch]); + let mut w = wet; + if trans > 0.0 { + let a = x.abs(); + let f = self.fast[ch].tick(fa, fr, a); + let s = self.slow[ch].tick(sa, sr_, a); + let boost = if s > 1e-9 { ((f - s) / s).clamp(0.0, 2.0) } else { 0.0 }; + w *= 1.0 + trans * boost; + } + channels[ch][i] = x + mix * (w - x); + } + self.lfo.advance(self.speed, self.sr); + } + } +} + +// ------------------------------------------------------------------------------------ flanger + +/// Classic flanger: the delay sweeps between the initial and final delay; stereo phasing +/// offsets the right channel's LFO; feedback, inverted and "special effects" (normal minus +/// inverted sweep) modes. +pub struct Flanger { + pv: ParamValues, + sr: f32, + lines: Vec, + lfo: Lfo, + d0: Smoothed, + d1: Smoothed, + fb: Smoothed, + mix: Smoothed, +} + +impl Flanger { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::log("initial_delay", "Initial Delay", 0.1, 20.0, 1.0, Unit::Milliseconds), + ParamSpec::log("final_delay", "Final Delay", 0.1, 20.0, 5.0, Unit::Milliseconds), + ParamSpec::new("stereo_phasing", "Stereo Phasing", 0.0, 180.0, 90.0, Unit::None), + ParamSpec::new("feedback", "Feedback", -100.0, 100.0, 50.0, Unit::Percent), + ParamSpec::log("rate", "Modulation Rate", 0.01, 10.0, 0.5, Unit::Hertz), + ParamSpec::toggle("inverted", "Inverted", false), + ParamSpec::toggle("special", "Special Effects", false), + ParamSpec::toggle("sinusoidal", "Sinusoidal", true), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 50.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let ch = crate::sane_channels(channels); + let sm = |v| Smoothed::with_ms(v, sample_rate, SM); + let mut s = Flanger { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + lines: vec![DelayLine::new((0.025 * sample_rate) as usize); ch], + lfo: Lfo::default(), + d0: sm(0.0), + d1: sm(0.0), + fb: sm(0.0), + mix: sm(0.0), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let ms = self.sr * 0.001; + self.d0.set(self.pv.v("initial_delay") * ms); + self.d1.set(self.pv.v("final_delay") * ms); + self.fb.set(0.95 * self.pv.v("feedback") / 100.0); + self.mix.set(self.pv.v("mix") / 100.0); + if snap { + for s in [&mut self.d0, &mut self.d1, &mut self.fb, &mut self.mix] { + s.snap(); + } + } + } +} + +impl AudioEffect for Flanger { + param_plumbing!("flanger"); + fn reset(&mut self) { + self.lines.iter_mut().for_each(DelayLine::reset); + self.lfo.reset(); + for s in [&mut self.d0, &mut self.d1, &mut self.fb, &mut self.mix] { + s.snap(); + } + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.lines.len()); + let sine = self.pv.on("sinusoidal"); + let inv = if self.pv.on("inverted") { -1.0 } else { 1.0 }; + let special = self.pv.on("special"); + let phasing = self.pv.v("stereo_phasing") as f64 / 360.0; + let rate = self.pv.v("rate"); + let shape = |p: f64| if sine { uni_sine(p) } else { uni_tri(p) }; + for i in 0..n { + let (d0, d1, fb, mix) = (self.d0.tick(), self.d1.tick(), self.fb.tick(), self.mix.tick()); + for ch in 0..nch { + let x = channels[ch][i]; + let p = self.lfo.phase(if ch == 1 { phasing } else { 0.0 }); + let line = &mut self.lines[ch]; + let y = line.read(d0 + (d1 - d0) * shape(p)); + let wet = if special { + let y2 = line.read(d0 + (d1 - d0) * shape(wrap_phase(p + 0.5))); + 0.5 * (y - y2) + 0.5 * y + } else { + y + }; + line.push(x + fb * y); + channels[ch][i] = x + mix * (inv * wet - x); + } + self.lfo.advance(rate, self.sr); + } + } +} + +// -------------------------------------------------------------------------------------- phaser + +const MAX_STAGES: usize = 12; + +/// Swept cascade of first-order all-pass stages with feedback. +pub struct Phaser { + pv: ParamValues, + sr: f32, + ap: Vec<[AllPass1; MAX_STAGES]>, + coefs: Vec, + fbs: Vec, + lfo: Lfo, + counter: u32, + intensity: Smoothed, + mix: Smoothed, + fb: Smoothed, + out: Smoothed, +} + +impl Phaser { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("stages", "Stages", 2.0, MAX_STAGES as f32, 4.0, Unit::None), + ParamSpec::new("intensity", "Intensity", 0.0, 100.0, 100.0, Unit::Percent), + ParamSpec::new("depth", "Depth", 0.0, 100.0, 70.0, Unit::Percent), + ParamSpec::log("rate", "Modulation Rate", 0.01, 10.0, 0.5, Unit::Hertz), + ParamSpec::new("phase_diff", "Phase Difference", 0.0, 180.0, 90.0, Unit::None), + ParamSpec::log("upper_freq", "Upper Frequency", 100.0, 20000.0, 2500.0, Unit::Hertz), + ParamSpec::new("feedback", "Feedback", -100.0, 100.0, 0.0, Unit::Percent), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 50.0, Unit::Percent), + ParamSpec::new("output", "Output Gain", -24.0, 24.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let ch = crate::sane_channels(channels); + let sm = |v| Smoothed::with_ms(v, sample_rate, SM); + let mut s = Phaser { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + ap: vec![[AllPass1::default(); MAX_STAGES]; ch], + coefs: vec![0.0; ch], + fbs: vec![0.0; ch], + lfo: Lfo::default(), + counter: 0, + intensity: sm(0.0), + mix: sm(0.0), + fb: sm(0.0), + out: sm(1.0), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.intensity.set(self.pv.v("intensity") / 100.0); + self.mix.set(self.pv.v("mix") / 100.0); + self.fb.set(0.9 * self.pv.v("feedback") / 100.0); + self.out.set(db_to_gain(self.pv.v("output"))); + if snap { + for s in [&mut self.intensity, &mut self.mix, &mut self.fb, &mut self.out] { + s.snap(); + } + } + } +} + +impl AudioEffect for Phaser { + param_plumbing!("phaser"); + fn reset(&mut self) { + self.ap.iter_mut().for_each(|a| a.iter_mut().for_each(AllPass1::reset)); + self.fbs.iter_mut().for_each(|v| *v = 0.0); + self.lfo.reset(); + self.counter = 0; + for s in [&mut self.intensity, &mut self.mix, &mut self.fb, &mut self.out] { + s.snap(); + } + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.ap.len()); + let stages = ((self.pv.v("stages").round() as usize / 2) * 2).clamp(2, MAX_STAGES); + let depth = self.pv.v("depth") / 100.0; + let upper = self.pv.v("upper_freq"); + let diff = self.pv.v("phase_diff") as f64 / 360.0; + let rate = self.pv.v("rate"); + for i in 0..n { + if self.counter == 0 { + for ch in 0..nch { + let p = self.lfo.phase(if ch == 1 { diff } else { 0.0 }); + // Sweep down from the upper frequency by up to 6 octaves. + let f = upper * 2f32.powf(-6.0 * depth * uni_sine(p)); + self.coefs[ch] = AllPass1::coef(f, self.sr); + } + } + self.counter = (self.counter + 1) % 8; + let (inten, mix, fb, out) = (self.intensity.tick(), self.mix.tick(), self.fb.tick() as f64, self.out.tick()); + for ch in 0..nch { + let x = channels[ch][i]; + let a = self.coefs[ch]; + let mut y = x as f64 + fb * self.fbs[ch]; + for st in self.ap[ch].iter_mut().take(stages) { + y = st.tick(a, y); + } + self.fbs[ch] = if y.is_finite() { y } else { 0.0 }; + let wet = x + inten * (y as f32 - x); + channels[ch][i] = (x + mix * (wet - x)) * out; + } + self.lfo.advance(rate, self.sr); + } + } +} + +// -------------------------------------------------------------------------------- analog delay + +pub const ANALOG_MODES: &[&str] = &["Tape", "Tape/Tube", "Analog"]; + +/// Delay with a colored, saturating feedback path (tape / tape+tube / bucket-brigade style +/// low-pass and soft clipping) and stereo spread. +pub struct AnalogDelay { + pv: ParamValues, + sr: f32, + lines: Vec, + lp: Vec, + time: Smoothed, + dry: Smoothed, + wet: Smoothed, + fb: Smoothed, + drive: Smoothed, + spread: Smoothed, +} + +impl AnalogDelay { + pub const MAX_MS: f32 = 8000.0; + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::choice("mode", "Mode", ANALOG_MODES, 0), + ParamSpec::new("dry", "Dry Out", 0.0, 100.0, 100.0, Unit::Percent), + ParamSpec::new("wet", "Wet Out", 0.0, 100.0, 40.0, Unit::Percent), + ParamSpec::log("delay", "Delay", 5.0, 8000.0, 250.0, Unit::Milliseconds), + ParamSpec::new("feedback", "Feedback", 0.0, 200.0, 40.0, Unit::Percent), + ParamSpec::new("trash", "Trash", 0.0, 200.0, 0.0, Unit::Percent), + ParamSpec::new("spread", "Spread", 0.0, 200.0, 0.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let ch = crate::sane_channels(channels); + let max = super::util::delay_line_len(Self::MAX_MS * 1.5, sample_rate, ch); + let sm = |v| Smoothed::with_ms(v, sample_rate, SM); + let mut s = AnalogDelay { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + lines: vec![DelayLine::new(max); ch], + lp: vec![OnePole::default(); ch], + time: Smoothed::with_ms(1.0, sample_rate, 100.0), + dry: sm(1.0), + wet: sm(0.0), + fb: sm(0.0), + drive: sm(1.0), + spread: sm(0.0), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.time.set(self.pv.v("delay") * 0.001 * self.sr); + self.dry.set(self.pv.v("dry") / 100.0); + self.wet.set(self.pv.v("wet") / 100.0); + self.fb.set(self.pv.v("feedback") / 100.0); + self.drive.set(1.0 + 4.0 * self.pv.v("trash") / 100.0); + self.spread.set(self.pv.v("spread") / 100.0); + if snap { + for s in [&mut self.time, &mut self.dry, &mut self.wet, &mut self.fb, &mut self.drive, &mut self.spread] { + s.snap(); + } + } + } +} + +impl AudioEffect for AnalogDelay { + param_plumbing!("analog_delay"); + fn tail_samples(&self) -> usize { + super::util::echo_tail(self.pv.v("delay"), self.pv.v("feedback") / 100.0, self.sr) + } + fn reset(&mut self) { + self.lines.iter_mut().for_each(DelayLine::reset); + self.lp.iter_mut().for_each(OnePole::reset); + for s in [&mut self.time, &mut self.dry, &mut self.wet, &mut self.fb, &mut self.drive, &mut self.spread] { + s.snap(); + } + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.lines.len()); + let mode = self.pv.idx("mode"); + let cutoff = [6500.0, 5000.0, 3200.0][mode.min(2)]; + let a = OnePole::alpha(cutoff, self.sr); + for i in 0..n { + let (t, dry, wet, fb, drive, spread) = + (self.time.tick(), self.dry.tick(), self.wet.tick(), self.fb.tick(), self.drive.tick(), self.spread.tick()); + for ch in 0..nch { + let x = channels[ch][i]; + let side = match (nch, ch) { + (1, _) => 0.0, + (_, 0) => -0.25, + _ => 0.25, + }; + let d = t * (1.0 + side * spread); + let line = &mut self.lines[ch]; + let y = line.read(d - 1.0); + let c = self.lp[ch].lp(a, y) * drive; + let sat = match mode { + 0 => c.tanh(), + 1 => (c + 0.2).tanh() - 0.2f32.tanh(), + _ => c / (1.0 + c.abs()), + } / drive; + line.push(x + fb * sat); + channels[ch][i] = dry * x + wet * y; + } + } + } +} + +// ------------------------------------------------------------------------------- multitap delay + +const TAPS: usize = 4; +const TAP_IDS: [[&str; 3]; TAPS] = + [["delay1", "feedback1", "level1"], ["delay2", "feedback2", "level2"], ["delay3", "feedback3", "level3"], ["delay4", "feedback4", "level4"]]; + +/// Four independent feedback delay taps mixed into one wet signal. +pub struct MultitapDelay { + pv: ParamValues, + sr: f32, + /// `[channel * TAPS + tap]`. + lines: Vec, + time: [Smoothed; TAPS], + fb: [Smoothed; TAPS], + level: [Smoothed; TAPS], + mix: Smoothed, +} + +impl MultitapDelay { + pub const MAX_MS: f32 = 4000.0; + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::log("delay1", "Delay 1", 1.0, 4000.0, 250.0, Unit::Milliseconds), + ParamSpec::new("feedback1", "Feedback 1", 0.0, 95.0, 0.0, Unit::Percent), + ParamSpec::new("level1", "Level 1", -96.0, 0.0, -6.0, Unit::Decibels), + ParamSpec::log("delay2", "Delay 2", 1.0, 4000.0, 500.0, Unit::Milliseconds), + ParamSpec::new("feedback2", "Feedback 2", 0.0, 95.0, 0.0, Unit::Percent), + ParamSpec::new("level2", "Level 2", -96.0, 0.0, -9.0, Unit::Decibels), + ParamSpec::log("delay3", "Delay 3", 1.0, 4000.0, 750.0, Unit::Milliseconds), + ParamSpec::new("feedback3", "Feedback 3", 0.0, 95.0, 0.0, Unit::Percent), + ParamSpec::new("level3", "Level 3", -96.0, 0.0, -12.0, Unit::Decibels), + ParamSpec::log("delay4", "Delay 4", 1.0, 4000.0, 1000.0, Unit::Milliseconds), + ParamSpec::new("feedback4", "Feedback 4", 0.0, 95.0, 0.0, Unit::Percent), + ParamSpec::new("level4", "Level 4", -96.0, 0.0, -15.0, Unit::Decibels), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 50.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let ch = crate::sane_channels(channels); + let max = super::util::delay_line_len(Self::MAX_MS, sample_rate, ch * TAPS); + let sm = |v| Smoothed::with_ms(v, sample_rate, SM); + let tm = || Smoothed::with_ms(1.0, sample_rate, 100.0); + let mut s = MultitapDelay { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + lines: vec![DelayLine::new(max); ch * TAPS], + time: [tm(), tm(), tm(), tm()], + fb: [sm(0.0), sm(0.0), sm(0.0), sm(0.0)], + level: [sm(0.0), sm(0.0), sm(0.0), sm(0.0)], + mix: sm(0.0), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + for (k, ids) in TAP_IDS.iter().enumerate() { + self.time[k].set(self.pv.v(ids[0]) * 0.001 * self.sr); + self.fb[k].set(self.pv.v(ids[1]) / 100.0); + let l = self.pv.v(ids[2]); + self.level[k].set(if l <= -96.0 { 0.0 } else { db_to_gain(l) }); + } + self.mix.set(self.pv.v("mix") / 100.0); + if snap { + self.snap(); + } + } + + fn snap(&mut self) { + for k in 0..TAPS { + self.time[k].snap(); + self.fb[k].snap(); + self.level[k].snap(); + } + self.mix.snap(); + } +} + +impl AudioEffect for MultitapDelay { + param_plumbing!("multitap_delay"); + /// The longest tail of the four taps. + fn tail_samples(&self) -> usize { + [("delay1", "feedback1"), ("delay2", "feedback2"), ("delay3", "feedback3"), ("delay4", "feedback4")] + .iter() + .map(|&(d, f)| super::util::echo_tail(self.pv.v(d), self.pv.v(f) / 100.0, self.sr)) + .max() + .unwrap_or(0) + } + fn reset(&mut self) { + self.lines.iter_mut().for_each(DelayLine::reset); + self.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.lines.len() / TAPS); + for i in 0..n { + let mut t = [0.0f32; TAPS]; + let mut fb = [0.0f32; TAPS]; + let mut lv = [0.0f32; TAPS]; + for k in 0..TAPS { + t[k] = self.time[k].tick(); + fb[k] = self.fb[k].tick(); + lv[k] = self.level[k].tick(); + } + let mix = self.mix.tick(); + for ch in 0..nch { + let x = channels[ch][i]; + let mut wet = 0.0; + for k in 0..TAPS { + let line = &mut self.lines[ch * TAPS + k]; + let y = line.read(t[k] - 1.0); + line.push(x + fb[k] * y); + wet += lv[k] * y; + } + channels[ch][i] = x + mix * (wet - x); + } + } + } +} + +#[cfg(test)] +impl AnalogDelay { + /// Samples the delay lines can hold, over all channels. + pub(crate) fn held_samples(&self) -> usize { + self.lines.iter().map(|l| l.max_delay() as usize).sum() + } +} + +#[cfg(test)] +impl MultitapDelay { + /// Samples the delay lines can hold, over all channels and taps. + pub(crate) fn held_samples(&self) -> usize { + self.lines.iter().map(|l| l.max_delay() as usize).sum() + } +} diff --git a/crates/audio-dsp/src/effects/multiband.rs b/crates/audio-dsp/src/effects/multiband.rs new file mode 100644 index 000000000..a27de3c3d --- /dev/null +++ b/crates/audio-dsp/src/effects/multiband.rs @@ -0,0 +1,626 @@ +//! Dynamics rack ("Dynamics": auto gate → expander → compressor → limiter), the four-band +//! Multiband Compressor (Linkwitz–Riley crossovers with all-pass phase compensation, so the +//! bands sum to an all-pass) and the Tube-modeled Compressor. + +use super::dynamics::{compressor_curve, expander_curve}; +use super::util::{coef, lin_db}; +use crate::biquad::{Biquad, Coeffs, FilterType}; +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing}; + +/// Attenuation of a closed gate (dB). +const GATE_RANGE: f32 = 80.0; +/// Most expander attenuation (dB). +const EXP_RANGE: f32 = 60.0; + +#[inline] +fn smooth(env: &mut f32, target: f32, att: f32, rel: f32) { + // Gains in dB (≤ 0): falling = attack, rising = release. + let c = if target < *env { att } else { rel }; + *env = c * *env + (1.0 - c) * target; + if !(1e-7..=f32::MAX).contains(&env.abs()) { + *env = 0.0; + } +} + +/// Cubic soft clipper with ceiling `t` (linear): identity below t/2, smooth to exactly ±t. +#[inline] +pub fn soft_clip(x: f32, t: f32) -> f32 { + let k = 0.5 * t; + let a = x.abs(); + if a <= k { + x + } else { + // Quadratic blend from slope 1 at k to slope 0 at 2t − k… normalized to reach t. + let u = ((a - k) / (2.0 * (t - k))).min(1.0); + let y = k + (t - k) * (2.0 * u - u * u); + y.copysign(x) + } +} + +// --------------------------------------------------------------------------------- dynamics + +/// Dynamics rack: Auto Gate, Compressor, Expander and Limiter sections in series +/// (stereo-linked peak detection), plus output gain. +pub struct DynamicsRack { + pv: ParamValues, + sr: f32, + gate_env: f32, + gate_hold: u32, + exp_env: f32, + comp_env: f32, + lim_env: f32, + out: Smoothed, + /// Cached coefficients. + c: [f32; 8], + hold: u32, +} + +impl DynamicsRack { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::toggle("gate_on", "Auto Gate", false), + ParamSpec::new("gate_threshold", "Gate Threshold", -80.0, 0.0, -50.0, Unit::Decibels), + ParamSpec::log("gate_attack", "Gate Attack", 0.1, 100.0, 2.0, Unit::Milliseconds), + ParamSpec::log("gate_release", "Gate Release", 1.0, 3000.0, 100.0, Unit::Milliseconds), + ParamSpec::new("gate_hold", "Gate Hold", 0.0, 1000.0, 50.0, Unit::Milliseconds), + ParamSpec::toggle("comp_on", "Compressor", true), + ParamSpec::new("comp_threshold", "Compressor Threshold", -60.0, 0.0, -20.0, Unit::Decibels), + ParamSpec::new("comp_ratio", "Compressor Ratio", 1.0, 30.0, 2.0, Unit::Ratio), + ParamSpec::log("comp_attack", "Compressor Attack", 0.1, 300.0, 10.0, Unit::Milliseconds), + ParamSpec::log("comp_release", "Compressor Release", 1.0, 3000.0, 100.0, Unit::Milliseconds), + ParamSpec::toggle("comp_auto", "Auto Makeup", false), + ParamSpec::new("comp_makeup", "Compressor Makeup", 0.0, 30.0, 0.0, Unit::Decibels), + ParamSpec::toggle("exp_on", "Expander", false), + ParamSpec::new("exp_threshold", "Expander Threshold", -80.0, 0.0, -60.0, Unit::Decibels), + ParamSpec::new("exp_ratio", "Expander Ratio", 1.0, 30.0, 2.0, Unit::Ratio), + ParamSpec::toggle("lim_on", "Limiter", false), + ParamSpec::new("lim_threshold", "Limiter Threshold", -30.0, 0.0, -1.0, Unit::Decibels), + ParamSpec::log("lim_release", "Limiter Release", 1.0, 1000.0, 50.0, Unit::Milliseconds), + ParamSpec::toggle("soft_clip", "Soft Clip", false), + ParamSpec::new("output", "Output Gain", -30.0, 30.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = DynamicsRack { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + gate_env: 0.0, + gate_hold: 0, + exp_env: 0.0, + comp_env: 0.0, + lim_env: 0.0, + out: Smoothed::with_ms(1.0, sample_rate, 20.0), + c: [0.0; 8], + hold: 0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let p = &self.pv; + let sr = self.sr; + self.c = [ + coef(p.v("gate_attack"), sr), + coef(p.v("gate_release"), sr), + coef(1.0, sr), + coef(80.0, sr), + coef(p.v("comp_attack"), sr), + coef(p.v("comp_release"), sr), + 0.0, + coef(p.v("lim_release"), sr), + ]; + self.hold = (p.v("gate_hold") * 0.001 * sr) as u32; + self.out.set(db_to_gain(p.v("output") + self.makeup_db())); + if snap { + self.out.snap(); + } + } + + fn makeup_db(&self) -> f32 { + let p = &self.pv; + if !p.on("comp_on") { + return 0.0; + } + let auto = if p.on("comp_auto") { + let (t, r) = (p.v("comp_threshold"), p.v("comp_ratio")); + -0.5 * t * (1.0 - 1.0 / r) + } else { + 0.0 + }; + p.v("comp_makeup") + auto + } + + /// Static gain (dB) of the enabled sections for a detector level, before make-up/output. + fn static_gain(&self, level: f32) -> f32 { + let p = &self.pv; + let mut l = level; + if p.on("gate_on") && l < p.v("gate_threshold") { + l -= GATE_RANGE; + } + if p.on("exp_on") { + l = expander_curve(l, p.v("exp_threshold"), p.v("exp_ratio"), EXP_RANGE); + } + if p.on("comp_on") { + l = compressor_curve(l, p.v("comp_threshold"), p.v("comp_ratio"), 0.0); + } + if p.on("lim_on") { + l = l.min(p.v("lim_threshold")); + } + l - level + } +} + +impl AudioEffect for DynamicsRack { + param_plumbing!("dynamics_rack"); + fn transfer_db(&self, band: usize, input_db: f32) -> Option { + (band == 0).then(|| input_db + self.static_gain(input_db) + self.pv.v("output") + self.makeup_db()) + } + fn reset(&mut self) { + self.gate_env = 0.0; + self.gate_hold = 0; + self.exp_env = 0.0; + self.comp_env = 0.0; + self.lim_env = 0.0; + self.out.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let p = &self.pv; + let (gate_on, gt) = (p.on("gate_on"), p.v("gate_threshold")); + let (exp_on, et, er) = (p.on("exp_on"), p.v("exp_threshold"), p.v("exp_ratio")); + let (comp_on, ct, cr) = (p.on("comp_on"), p.v("comp_threshold"), p.v("comp_ratio")); + let (lim_on, lt) = (p.on("lim_on"), p.v("lim_threshold")); + let clip = p.on("soft_clip"); + let ceiling = db_to_gain(lt); + let c = self.c; + for i in 0..n { + let peak = channels.iter().fold(0.0f32, |a, ch| a.max(ch[i].abs())); + let mut l = lin_db(peak); + let mut g = 0.0f32; + if gate_on { + let target = if l < gt { -GATE_RANGE } else { 0.0 }; + if target >= 0.0 { + self.gate_hold = self.hold; + smooth(&mut self.gate_env, 0.0, c[1], c[0]); + } else if self.gate_hold > 0 { + self.gate_hold -= 1; + } else { + smooth(&mut self.gate_env, target, c[1], c[1]); + } + g += self.gate_env; + l += self.gate_env; + } + if exp_on { + let target = expander_curve(l, et, er, EXP_RANGE) - l; + smooth(&mut self.exp_env, target, c[2], c[3]); + g += self.exp_env; + l += self.exp_env; + } + if comp_on { + let target = compressor_curve(l, ct, cr, 0.0) - l; + smooth(&mut self.comp_env, target, c[4], c[5]); + g += self.comp_env; + l += self.comp_env; + } + if lim_on { + let target = (lt - l).min(0.0); + if target < self.lim_env { + self.lim_env = target; + } else { + smooth(&mut self.lim_env, target, 0.0, c[7]); + } + g += self.lim_env; + } + let gain = db_to_gain(g); + let o = self.out.tick(); + for ch in channels.iter_mut() { + let mut y = ch[i] * gain; + if lim_on { + y = if clip { soft_clip(y, ceiling) } else { y.clamp(-ceiling, ceiling) }; + } + ch[i] = y * o; + } + } + } +} + +// ----------------------------------------------------------------------- multiband compressor + +/// Number of bands. +pub const MB_BANDS: usize = 4; +/// Channels the multiband compressor processes: every channel the crate supports. +const MB_MAX_CH: usize = crate::MAX_CHANNELS; + +macro_rules! mb_band { + ($n:literal) => { + [ + ParamSpec::new(concat!("b", $n, "_threshold"), concat!("Band ", $n, " Threshold"), -60.0, 0.0, -18.0, Unit::Decibels), + ParamSpec::new(concat!("b", $n, "_ratio"), concat!("Band ", $n, " Ratio"), 1.0, 30.0, 3.0, Unit::Ratio), + ParamSpec::log(concat!("b", $n, "_attack"), concat!("Band ", $n, " Attack"), 0.1, 500.0, 10.0, Unit::Milliseconds), + ParamSpec::log(concat!("b", $n, "_release"), concat!("Band ", $n, " Release"), 1.0, 5000.0, 100.0, Unit::Milliseconds), + ParamSpec::new(concat!("b", $n, "_gain"), concat!("Band ", $n, " Gain"), -18.0, 18.0, 0.0, Unit::Decibels), + ParamSpec::toggle(concat!("b", $n, "_solo"), concat!("Band ", $n, " Solo"), false), + ParamSpec::toggle(concat!("b", $n, "_bypass"), concat!("Band ", $n, " Bypass"), false), + ] + }; +} + +const fn mb_params() -> [ParamSpec; 3 + 4 * 7 + 5] { + let head = [ + ParamSpec::log("xo1", "Low Crossover", 20.0, 1000.0, 120.0, Unit::Hertz), + ParamSpec::log("xo2", "Mid Crossover", 100.0, 8000.0, 2000.0, Unit::Hertz), + ParamSpec::log("xo3", "High Crossover", 1000.0, 20000.0, 10000.0, Unit::Hertz), + ]; + let bands = [mb_band!("1"), mb_band!("2"), mb_band!("3"), mb_band!("4")]; + let tail = [ + ParamSpec::new("output", "Output Gain", -18.0, 18.0, 0.0, Unit::Decibels), + ParamSpec::toggle("lim_on", "Limiter", false), + ParamSpec::new("lim_threshold", "Limiter Threshold", -30.0, 0.0, -0.1, Unit::Decibels), + ParamSpec::log("lim_release", "Limiter Release", 1.0, 1000.0, 50.0, Unit::Milliseconds), + ParamSpec::toggle("link", "Link Channels", true), + ]; + let mut out = [ParamSpec::new("", "", 0.0, 0.0, 0.0, Unit::None); 3 + 4 * 7 + 5]; + let mut i = 0; + while i < 3 { + out[i] = head[i]; + i += 1; + } + let mut b = 0; + while b < 4 { + let mut k = 0; + while k < 7 { + out[3 + b * 7 + k] = bands[b][k]; + k += 1; + } + b += 1; + } + let mut t = 0; + while t < 5 { + out[31 + t] = tail[t]; + t += 1; + } + out +} + +const MB_PARAMS: [ParamSpec; 36] = mb_params(); + +/// Parameter ids of band `b` (0-based): threshold, ratio, attack, release, gain, solo, bypass. +pub const MB_IDS: [[&str; 7]; MB_BANDS] = [ + ["b1_threshold", "b1_ratio", "b1_attack", "b1_release", "b1_gain", "b1_solo", "b1_bypass"], + ["b2_threshold", "b2_ratio", "b2_attack", "b2_release", "b2_gain", "b2_solo", "b2_bypass"], + ["b3_threshold", "b3_ratio", "b3_attack", "b3_release", "b3_gain", "b3_solo", "b3_bypass"], + ["b4_threshold", "b4_ratio", "b4_attack", "b4_release", "b4_gain", "b4_solo", "b4_bypass"], +]; + +/// Per-channel crossover filter state. +#[derive(Clone, Copy, Debug, Default)] +struct XoState { + lp1: [Biquad; 2], + hp1: [Biquad; 2], + lp2: [Biquad; 2], + hp2: [Biquad; 2], + lp3: [Biquad; 2], + hp3: [Biquad; 2], + /// Phase compensation: band 1 through AP(f2), AP(f3); band 2 through AP(f3). + ap1_2: Biquad, + ap1_3: Biquad, + ap2_3: Biquad, +} + +#[derive(Clone, Copy, Debug)] +struct XoCoeffs { + lp: [Coeffs; 3], + hp: [Coeffs; 3], + ap: [Coeffs; 3], +} + +/// Four-band compressor with LR4 crossovers. +pub struct MultibandCompressor { + pv: ParamValues, + sr: f32, + xo: [Smoothed; 3], + xc: XoCoeffs, + state: Vec, + /// Gain-reduction envelopes (dB), `[channel][band]` (channel 0 is used when linked). + env: Vec<[f32; MB_BANDS]>, + lim_env: f32, + band_gain: [Smoothed; MB_BANDS], + out: Smoothed, + att: [f32; MB_BANDS], + rel: [f32; MB_BANDS], + lim_rel: f32, + counter: u32, +} + +const Q_BW: f64 = std::f64::consts::FRAC_1_SQRT_2; + +impl MultibandCompressor { + pub const PARAMS: &'static [ParamSpec] = &MB_PARAMS; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let sm = |v: f32| Smoothed::with_ms(v, sample_rate, 30.0); + let mut s = MultibandCompressor { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + xo: [sm(1.0), sm(1.0), sm(1.0)], + xc: XoCoeffs { lp: [Coeffs::IDENTITY; 3], hp: [Coeffs::IDENTITY; 3], ap: [Coeffs::IDENTITY; 3] }, + state: vec![XoState::default(); crate::sane_channels(channels)], + env: vec![[0.0; MB_BANDS]; crate::sane_channels(channels)], + lim_env: 0.0, + band_gain: [sm(1.0), sm(1.0), sm(1.0), sm(1.0)], + out: sm(1.0), + att: [0.0; MB_BANDS], + rel: [0.0; MB_BANDS], + lim_rel: 0.0, + counter: 0, + }; + s.apply_params(true); + s + } + + /// Crossover frequencies (Hz) at the current settings, kept strictly increasing. + pub fn crossovers(&self) -> [f32; 3] { + let a = self.pv.v("xo1"); + let b = self.pv.v("xo2").max(a * 1.25); + let c = self.pv.v("xo3").max(b * 1.25).min(self.sr * 0.45); + [a, b.min(c / 1.25), c] + } + + fn update_xo(&mut self) { + let sr = self.sr as f64; + for k in 0..3 { + let f = 2f64.powf(self.xo[k].value() as f64); + self.xc.lp[k] = Coeffs::design(FilterType::LowPass, sr, f, Q_BW, 0.0); + self.xc.hp[k] = Coeffs::design(FilterType::HighPass, sr, f, Q_BW, 0.0); + self.xc.ap[k] = Coeffs::design(FilterType::AllPass, sr, f, Q_BW, 0.0); + } + } + + fn apply_params(&mut self, snap: bool) { + let xo = self.crossovers(); + for k in 0..3 { + self.xo[k].set(xo[k].log2()); + } + for b in 0..MB_BANDS { + let ids = MB_IDS[b]; + self.att[b] = coef(self.pv.v(ids[2]), self.sr); + self.rel[b] = coef(self.pv.v(ids[3]), self.sr); + self.band_gain[b].set(self.band_level(b)); + } + self.lim_rel = coef(self.pv.v("lim_release"), self.sr); + self.out.set(db_to_gain(self.pv.v("output"))); + if snap { + self.xo.iter_mut().for_each(Smoothed::snap); + self.band_gain.iter_mut().for_each(Smoothed::snap); + self.out.snap(); + self.update_xo(); + } + } + + /// Linear output level of band `b` from its gain, solo and bypass switches. + fn band_level(&self, b: usize) -> f32 { + let any_solo = MB_IDS.iter().any(|ids| self.pv.on(ids[5])); + let ids = MB_IDS[b]; + if any_solo && !self.pv.on(ids[5]) { + return 0.0; + } + if self.pv.on(ids[6]) { 1.0 } else { db_to_gain(self.pv.v(ids[4])) } + } + + #[inline] + fn split(st: &mut XoState, c: &XoCoeffs, x: f64) -> [f64; MB_BANDS] { + let lr = |f: &mut [Biquad; 2], co: &Coeffs, v: f64| { + let u = f[0].tick(co, v); + f[1].tick(co, u) + }; + let b1 = lr(&mut st.lp1, &c.lp[0], x); + let r1 = lr(&mut st.hp1, &c.hp[0], x); + let b1 = st.ap1_3.tick(&c.ap[2], st.ap1_2.tick(&c.ap[1], b1)); + let b2 = lr(&mut st.lp2, &c.lp[1], r1); + let r2 = lr(&mut st.hp2, &c.hp[1], r1); + let b2 = st.ap2_3.tick(&c.ap[2], b2); + let b3 = lr(&mut st.lp3, &c.lp[2], r2); + let b4 = lr(&mut st.hp3, &c.hp[2], r2); + [b1, b2, b3, b4] + } +} + +impl AudioEffect for MultibandCompressor { + param_plumbing!("multiband_compressor"); + fn transfer_db(&self, band: usize, input_db: f32) -> Option { + let ids = MB_IDS.get(band)?; + if self.pv.on(ids[6]) { + return Some(input_db); + } + Some(compressor_curve(input_db, self.pv.v(ids[0]), self.pv.v(ids[1]), 0.0) + self.pv.v(ids[4])) + } + fn reset(&mut self) { + self.xo.iter_mut().for_each(Smoothed::snap); + self.band_gain.iter_mut().for_each(Smoothed::snap); + self.out.snap(); + self.update_xo(); + self.state.iter_mut().for_each(|s| *s = XoState::default()); + self.env.iter_mut().for_each(|e| *e = [0.0; MB_BANDS]); + self.lim_env = 0.0; + self.counter = 0; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.state.len()); + let link = self.pv.on("link"); + let lim_on = self.pv.on("lim_on"); + let lt = self.pv.v("lim_threshold"); + let ceiling = db_to_gain(lt); + let mut thr = [0.0f32; MB_BANDS]; + let mut ratio = [1.0f32; MB_BANDS]; + let mut byp = [false; MB_BANDS]; + for b in 0..MB_BANDS { + thr[b] = self.pv.v(MB_IDS[b][0]); + ratio[b] = self.pv.v(MB_IDS[b][1]); + byp[b] = self.pv.on(MB_IDS[b][6]); + } + let mut bands = [[0.0f64; MB_BANDS]; MB_MAX_CH]; + for i in 0..n { + if self.counter == 0 && self.xo.iter().any(Smoothed::is_smoothing) { + self.update_xo(); + } + self.counter = (self.counter + 1) % 16; + for x in &mut self.xo { + x.tick(); + } + let mut bg = [0.0f32; MB_BANDS]; + for b in 0..MB_BANDS { + bg[b] = self.band_gain[b].tick(); + } + let o = self.out.tick(); + for ch in 0..nch.min(MB_MAX_CH) { + bands[ch] = Self::split(&mut self.state[ch], &self.xc, channels[ch][i] as f64); + } + // Detection (per band; linked = loudest channel drives all). + let mut gains = [[1.0f32; MB_BANDS]; MB_MAX_CH]; + for b in 0..MB_BANDS { + if byp[b] { + continue; + } + if link { + let peak = (0..nch.min(MB_MAX_CH)).fold(0.0f32, |a, ch| a.max(bands[ch][b].abs() as f32)); + let l = lin_db(peak); + let target = compressor_curve(l, thr[b], ratio[b], 0.0) - l; + smooth(&mut self.env[0][b], target, self.att[b], self.rel[b]); + let g = db_to_gain(self.env[0][b]); + for gc in gains.iter_mut().take(nch.min(MB_MAX_CH)) { + gc[b] = g; + } + } else { + for ch in 0..nch.min(MB_MAX_CH) { + let l = lin_db(bands[ch][b].abs() as f32); + let target = compressor_curve(l, thr[b], ratio[b], 0.0) - l; + smooth(&mut self.env[ch][b], target, self.att[b], self.rel[b]); + gains[ch][b] = db_to_gain(self.env[ch][b]); + } + } + } + let mut ys = [0.0f32; MB_MAX_CH]; + for ch in 0..nch.min(MB_MAX_CH) { + let mut y = 0.0f64; + for b in 0..MB_BANDS { + y += bands[ch][b] * (gains[ch][b] * bg[b]) as f64; + } + ys[ch] = y as f32 * o; + } + if lim_on { + let peak = ys[..nch.min(MB_MAX_CH)].iter().fold(0.0f32, |a, v| a.max(v.abs())); + let target = (lt - lin_db(peak)).min(0.0); + if target < self.lim_env { + self.lim_env = target; + } else { + smooth(&mut self.lim_env, target, 0.0, self.lim_rel); + } + let g = db_to_gain(self.lim_env); + for y in ys.iter_mut().take(nch.min(MB_MAX_CH)) { + *y = (*y * g).clamp(-ceiling, ceiling); + } + } + for ch in 0..nch.min(MB_MAX_CH) { + channels[ch][i] = ys[ch]; + } + } + } +} + +// --------------------------------------------------------------------- tube-modeled compressor + +/// Compressor with an RMS detector, wide soft knee, program-dependent release and a gentle +/// symmetric tube-style saturation stage (`tanh(kx)/k`, k = ½: −0.2 dB at −6 dBFS). +pub struct TubeCompressor { + pv: ParamValues, + sr: f32, + ms: f32, + env: f32, + slow: f32, + att: f32, + rel: f32, + rms_c: f32, + out: Smoothed, +} + +const TUBE_K: f32 = 0.5; +const TUBE_KNEE: f32 = 10.0; + +impl TubeCompressor { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("threshold", "Threshold", -60.0, 0.0, -20.0, Unit::Decibels), + ParamSpec::new("ratio", "Ratio", 1.0, 30.0, 4.0, Unit::Ratio), + ParamSpec::log("attack", "Attack", 0.1, 500.0, 10.0, Unit::Milliseconds), + ParamSpec::log("release", "Release", 1.0, 5000.0, 100.0, Unit::Milliseconds), + ParamSpec::new("output", "Output Gain", -30.0, 30.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = TubeCompressor { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + ms: 0.0, + env: 0.0, + slow: 0.0, + att: 0.0, + rel: 0.0, + rms_c: coef(5.0, sample_rate), + out: Smoothed::with_ms(1.0, sample_rate, 20.0), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.att = coef(self.pv.v("attack"), self.sr); + self.rel = coef(self.pv.v("release"), self.sr); + self.out.set(db_to_gain(self.pv.v("output"))); + if snap { + self.out.snap(); + } + } +} + +impl AudioEffect for TubeCompressor { + param_plumbing!("tube_compressor"); + fn transfer_db(&self, band: usize, input_db: f32) -> Option { + (band == 0).then(|| compressor_curve(input_db, self.pv.v("threshold"), self.pv.v("ratio"), TUBE_KNEE) + self.pv.v("output")) + } + fn reset(&mut self) { + self.ms = 0.0; + self.env = 0.0; + self.slow = 0.0; + self.out.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let (t, r) = (self.pv.v("threshold"), self.pv.v("ratio")); + let slow_c = coef(1500.0, self.sr); + for i in 0..n { + let sq = channels.iter().fold(0.0f32, |a, ch| a.max(ch[i] * ch[i])); + self.ms = self.rms_c * self.ms + (1.0 - self.rms_c) * sq; + if !(1e-30..=f32::MAX).contains(&self.ms) { + self.ms = 0.0; + } + let l = 10.0 * self.ms.max(1e-20).log10(); + let target = compressor_curve(l, t, r, TUBE_KNEE) - l; + // Program-dependent release: long, sustained reduction releases more slowly. + self.slow = slow_c * self.slow + (1.0 - slow_c) * self.env; + if !(1e-7..=f32::MAX).contains(&self.slow.abs()) { + self.slow = 0.0; + } + let rel = self.rel + (self.slow / -20.0).clamp(0.0, 1.0) * (1.0 - self.rel) * 0.5; + smooth(&mut self.env, target, self.att, rel.min(0.999_999)); + let g = db_to_gain(self.env); + let o = self.out.tick(); + for buf in channels.iter_mut() { + let y = buf[i] * g; + buf[i] = (TUBE_K * y).tanh() / TUBE_K * o; + } + } + } +} diff --git a/crates/audio-dsp/src/effects/pitch.rs b/crates/audio-dsp/src/effects/pitch.rs new file mode 100644 index 000000000..6d4a87665 --- /dev/null +++ b/crates/audio-dsp/src/effects/pitch.rs @@ -0,0 +1,330 @@ +//! Pitch shifter: phase vocoder with peak-region shifting and identity phase locking. +//! +//! Every STFT frame (8× overlap) is analyzed for spectral peaks; each peak's region of influence +//! (down to the magnitude minima between peaks) is moved as a block so that the peak lands on +//! `k·ratio`, preserving the window's main-lobe shape. All bins of a region receive the same phase +//! rotation, accumulated per frame from the peak's instantaneous frequency so the partial's +//! frequency is scaled exactly by `ratio` while the within-lobe phase relations stay coherent +//! (low phasiness). Duration is unchanged. At ratio 1 the output is the input delayed by the +//! frame size. + +use super::stft::{Pairing, Plan, Spectral, StftChannel, fft_size, stream}; +use crate::{AudioEffect, ParamSpec, ParamValues, Unit, block_len, param_plumbing}; +use std::f32::consts::PI; + +const OVERLAP: usize = 8; + +#[derive(Clone, Debug)] +struct PvState { + /// Previous frame's analysis spectrum (bins 0..=n/2); its phase is only needed at peaks. + last_re: Vec, + last_im: Vec, + /// Accumulated phase rotation per output bin (from the previous frame). + rot: Vec, + new_rot: Vec, +} + +/// Frame scratch shared by all channels. +#[derive(Clone, Debug)] +struct Scratch { + mag: Vec, + out_re: Vec, + out_im: Vec, + peaks: Vec, +} + +/// Semitone pitch shifter (±12 st, fractional allowed). +pub struct PitchShifter { + pv: ParamValues, + n: usize, + hop: usize, + spec: Spectral, + stft: Vec, + state: Vec, + scratch: Scratch, + target_ratio: f32, + /// Ratio used by the current frame (glides per frame towards the target). + ratio: f32, +} + +/// Wrap a phase to (−π, π]. +#[inline] +fn wrap(p: f32) -> f32 { + p - 2.0 * PI * ((p + PI) / (2.0 * PI)).floor() +} + +impl PitchShifter { + pub const PARAMS: &'static [ParamSpec] = &[ParamSpec::new("semitones", "Pitch", -12.0, 12.0, 0.0, Unit::Semitones)]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let n = fft_size(sample_rate); + let bins = n / 2 + 1; + let ch = channels.clamp(1, crate::MAX_CHANNELS); + let mut s = PitchShifter { + pv: ParamValues::new(Self::PARAMS), + n, + hop: n / OVERLAP, + spec: Spectral::new(n, false), + stft: vec![StftChannel::new(n); ch], + state: vec![PvState { last_re: vec![0.0; bins], last_im: vec![0.0; bins], rot: vec![0.0; bins], new_rot: vec![0.0; bins] }; ch], + scratch: Scratch { mag: vec![0.0; bins], out_re: vec![0.0; bins], out_im: vec![0.0; bins], peaks: Vec::with_capacity(bins) }, + target_ratio: 1.0, + ratio: 1.0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.target_ratio = 2f32.powf(self.pv.v("semitones") / 12.0); + if snap { + self.ratio = self.target_ratio; + } + } +} + +/// Shift one analyzed half spectrum (bins 0..=n/2) in place. +fn shift_frame(spec_re: &mut [f32], spec_im: &mut [f32], st: &mut PvState, sc: &mut Scratch, ratio: f32, expect: f32) { + let bins = sc.mag.len(); + let mut max_mag = 0.0f32; + for k in 0..bins { + let (re, im) = (spec_re[k], spec_im[k]); + sc.mag[k] = (re * re + im * im).sqrt(); + max_mag = max_mag.max(sc.mag[k]); + sc.out_re[k] = 0.0; + sc.out_im[k] = 0.0; + st.new_rot[k] = 0.0; + } + // Peaks: local maxima over ±2 bins, above −100 dB of the frame maximum. + sc.peaks.clear(); + let floor = max_mag * 1e-5; + for k in 0..bins { + let m = sc.mag[k]; + if m <= floor { + continue; + } + let lo = k.saturating_sub(2); + let hi = (k + 2).min(bins - 1); + if (lo..k).all(|j| sc.mag[j] < m) && (k + 1..=hi).all(|j| sc.mag[j] <= m) { + sc.peaks.push(k); + } + } + let np = sc.peaks.len(); + let mut start = 0usize; + for i in 0..np { + let p = sc.peaks[i]; + // Region end: magnitude minimum between this peak and the next. + let end = if i + 1 < np { + let q = sc.peaks[i + 1]; + let mut mi = p + 1; + for j in p + 1..q { + if sc.mag[j] < sc.mag[mi] { + mi = j; + } + } + mi + } else { + bins + }; + // Instantaneous frequency of the peak (bins). + let phase = spec_im[p].atan2(spec_re[p]); + let last_phase = st.last_im[p].atan2(st.last_re[p]); + let d = wrap(phase - last_phase - p as f32 * expect); + let f = p as f32 + d / expect; + let target = (p as f32 * ratio).round() as isize; + let delta = target - p as isize; + let prev_rot = if (0..bins as isize).contains(&target) { st.rot[target as usize] } else { 0.0 }; + let rot = wrap(prev_rot + (ratio - 1.0) * f * expect); + // A NaN or inf input sample leaves a non-finite previous spectrum; `rot` is accumulated + // across frames, so it must not keep the NaN. + let rot = if rot.is_finite() { rot } else { 0.0 }; + // mag·e^{i(φ+rot)} = X·e^{i·rot}: one sin_cos per region instead of one per bin. + let (s, c) = rot.sin_cos(); + for k in start..end { + let t = k as isize + delta; + if t < 0 || t >= bins as isize { + continue; + } + let t = t as usize; + let (re, im) = (spec_re[k], spec_im[k]); + sc.out_re[t] += re * c - im * s; + sc.out_im[t] += re * s + im * c; + st.new_rot[t] = rot; + } + start = end; + } + st.last_re.copy_from_slice(spec_re); + st.last_im.copy_from_slice(spec_im); + spec_re.copy_from_slice(&sc.out_re); + spec_im.copy_from_slice(&sc.out_im); + std::mem::swap(&mut st.rot, &mut st.new_rot); +} + +impl AudioEffect for PitchShifter { + param_plumbing!("pitch_shifter"); + fn latency(&self) -> usize { + self.n + } + fn reset(&mut self) { + self.stft.iter_mut().for_each(StftChannel::reset); + for s in &mut self.state { + s.last_re.iter_mut().for_each(|v| *v = 0.0); + s.last_im.iter_mut().for_each(|v| *v = 0.0); + s.rot.iter_mut().for_each(|v| *v = 0.0); + } + self.ratio = self.target_ratio; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let len = block_len(channels); + let (n, hop) = (self.n, self.hop); + // Hann² summed over 8× overlap = 3/8 · 8 = 3. + let scale = 1.0 / (n as f32 * 3.0 / 8.0 * OVERLAP as f32); + let expect = 2.0 * PI * hop as f32 / n as f32; + // Sample-major so every channel hits its frame boundary on the same sample and the ratio + // glides identically for all channels (once per frame). + let (state, sc, target_ratio) = (&mut self.state, &mut self.scratch, self.target_ratio); + let mut ratio = self.ratio; + let mut frame_ratio = ratio; + stream(&mut self.stft, &mut self.spec, channels, len, Plan { hop, scale, pairing: Pairing::SynthesisOnly }, &mut |ch, first, re, im| { + if first { + frame_ratio = ratio; + ratio += (target_ratio - ratio) * 0.5; + if (ratio - target_ratio).abs() < 1e-5 { + ratio = target_ratio; + } + } + shift_frame(re, im, &mut state[ch], sc, frame_ratio, expect); + }); + self.ratio = ratio; + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::*; + + const SR: f32 = 48000.0; + + fn shifted(semis: f32, f_in: f64) -> (Vec, usize) { + let mut p = PitchShifter::new(SR, 2); + p.set_param("semitones", semis); + p.reset(); + let n = SR as usize * 2; + let mut l = sine(f_in, 0.5, SR as f64, n, 0.0); + let mut r = l.clone(); + p.process(&mut [&mut l, &mut r]); + // Both channels share one complex FFT, so they agree to rounding, not bit for bit. + assert!(l.iter().zip(&r).all(|(a, b)| (a - b).abs() < 1e-5)); + (l, p.latency()) + } + + #[test] + fn octave_up_and_down() { + for (semis, f_in, f_out) in [(12.0, 440.0, 880.0), (-12.0, 440.0, 220.0), (7.0, 300.0, 300.0 * 1.498_307)] { + let (y, lat) = shifted(semis, f_in); + let tail = &y[lat + 4096..]; + let a_out = tone_amplitude(tail, f_out, SR as f64); + let a_in = tone_amplitude(tail, f_in, SR as f64); + assert!(db(a_out / 0.5).abs() < 3.0, "{semis}: level {} dB", db(a_out / 0.5)); + assert!(db(a_in / a_out) < -30.0, "{semis}: residual {} dB", db(a_in / a_out)); + // Output is a clean tone: almost all energy at the target frequency. + let r = rms(tail); + assert!((db(a_out / std::f64::consts::SQRT_2 / r)).abs() < 1.0); + } + } + + /// The previous per-bin version of `shift_frame` (atan2 and sin_cos for every bin). + fn shift_frame_reference(re: &mut [f32], im: &mut [f32], last_phase: &mut [f32], rot: &mut [f32], ratio: f32, expect: f32) { + let bins = last_phase.len(); + let mag: Vec = (0..bins).map(|k| (re[k] * re[k] + im[k] * im[k]).sqrt()).collect(); + let phase: Vec = (0..bins).map(|k| im[k].atan2(re[k])).collect(); + let max_mag = mag.iter().fold(0.0f32, |a, &m| a.max(m)); + let (mut out_re, mut out_im, mut new_rot) = (vec![0.0f32; bins], vec![0.0f32; bins], vec![0.0f32; bins]); + let floor = max_mag * 1e-5; + let peaks: Vec = (0..bins) + .filter(|&k| { + let m = mag[k]; + m > floor && (k.saturating_sub(2)..k).all(|j| mag[j] < m) && (k + 1..=(k + 2).min(bins - 1)).all(|j| mag[j] <= m) + }) + .collect(); + let mut start = 0usize; + for (i, &p) in peaks.iter().enumerate() { + let end = match peaks.get(i + 1) { + Some(&q) => (p + 1..q).fold(p + 1, |mi, j| if mag[j] < mag[mi] { j } else { mi }), + None => bins, + }; + let d = wrap(phase[p] - last_phase[p] - p as f32 * expect); + let f = p as f32 + d / expect; + let target = (p as f32 * ratio).round() as isize; + let delta = target - p as isize; + let prev_rot = if (0..bins as isize).contains(&target) { rot[target as usize] } else { 0.0 }; + let r = wrap(prev_rot + (ratio - 1.0) * f * expect); + for k in start..end { + let t = k as isize + delta; + if t < 0 || t >= bins as isize { + continue; + } + let t = t as usize; + let (s, c) = (phase[k] + r).sin_cos(); + out_re[t] += mag[k] * c; + out_im[t] += mag[k] * s; + new_rot[t] = r; + } + start = end; + } + last_phase.copy_from_slice(&phase); + re[..bins].copy_from_slice(&out_re); + im[..bins].copy_from_slice(&out_im); + rot.copy_from_slice(&new_rot); + } + + #[test] + fn matches_per_bin_reference_to_rounding() { + let n = fft_size(SR); + let (bins, hop) = (n / 2 + 1, n / OVERLAP); + let expect = 2.0 * PI * hop as f32 / n as f32; + let mut rng = Rng::new(3); + let tones = [sine(220.0, 0.3, SR as f64, 40 * hop + n, 0.0), sine(1234.5, 0.2, SR as f64, 40 * hop + n, 1.0)]; + let x: Vec = (0..40 * hop + n).map(|i| tones[0][i] + tones[1][i] + 0.05 * rng.uniform()).collect(); + let mut spec = Spectral::new(n, false); + let mut st = PvState { last_re: vec![0.0; bins], last_im: vec![0.0; bins], rot: vec![0.0; bins], new_rot: vec![0.0; bins] }; + let mut sc = Scratch { mag: vec![0.0; bins], out_re: vec![0.0; bins], out_im: vec![0.0; bins], peaks: Vec::new() }; + let (mut last_phase, mut rot) = (vec![0.0f32; bins], vec![0.0f32; bins]); + let (mut ratio, mut worst) = (1.0f32, 0.0f32); + for f in 0..40 { + let target = if f < 20 { 2f32.powf(7.0 / 12.0) } else { 2f32.powf(-5.0 / 12.0) }; + ratio += (target - ratio) * 0.5; + spec.analyze(&x[f * hop..f * hop + n]); + let (mut re, mut im) = (spec.re.clone(), spec.im.clone()); + shift_frame(&mut spec.re[..bins], &mut spec.im[..bins], &mut st, &mut sc, ratio, expect); + shift_frame_reference(&mut re, &mut im, &mut last_phase, &mut rot, ratio, expect); + assert!(st.rot.iter().zip(&rot).all(|(a, b)| a.to_bits() == b.to_bits()), "frame {f}: rotations differ"); + let peak = (0..bins).map(|k| re[k].hypot(im[k])).fold(0.0f32, f32::max); + for k in 0..bins { + worst = worst.max((spec.re[k] - re[k]).hypot(spec.im[k] - im[k]) / peak); + } + } + assert!(worst < 1e-5, "relative deviation {worst}"); + } + + #[test] + fn zero_shift_is_delayed_identity() { + let (y, lat) = shifted(0.0, 440.0); + let x = sine(440.0, 0.5, SR as f64, y.len(), 0.0); + for i in lat + 2048..y.len() { + assert!((y[i] - x[i - lat]).abs() < 2e-3, "i {i}"); + } + } + + /// A huge channel count builds the most channels the crate handles instead of allocating + /// without bound. + #[test] + fn a_huge_channel_count_is_capped() { + let mut p = PitchShifter::new(SR, usize::MAX); + let mut x = vec![0.25f32; 512]; + p.process(&mut [&mut x]); + assert!(x.iter().all(|v| v.is_finite())); + } +} diff --git a/crates/audio-dsp/src/effects/restoration.rs b/crates/audio-dsp/src/effects/restoration.rs new file mode 100644 index 000000000..0e9d7e8c8 --- /dev/null +++ b/crates/audio-dsp/src/effects/restoration.rs @@ -0,0 +1,355 @@ +//! Restoration: DeHum (harmonic notch comb) and DeNoise (STFT spectral gating). + +use super::stft::{Pairing, Plan, Spectral, StftChannel, fft_size, stream}; +use crate::biquad::{Biquad, Coeffs, FilterType}; +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing}; + +const MAX_HARMONICS: usize = 10; + +/// Removes mains hum: a cascade of notches at the fundamental (50/60 Hz) and its harmonics. +pub struct DeHum { + pv: ParamValues, + sr: f32, + coeffs: [Coeffs; MAX_HARMONICS], + /// Per-stage enable cross-fade (so changing the harmonic count is click-free). + stage_mix: [Smoothed; MAX_HARMONICS], + state: Vec<[Biquad; MAX_HARMONICS]>, + amount: Smoothed, +} + +impl DeHum { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::choice("frequency", "Frequency", &["50 Hz", "60 Hz"], 0), + ParamSpec::new("harmonics", "Harmonics", 1.0, MAX_HARMONICS as f32, 5.0, Unit::None), + ParamSpec::log("q", "Notch Q", 1.0, 100.0, 30.0, Unit::Q), + ParamSpec::new("amount", "Amount", 0.0, 100.0, 100.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = DeHum { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + coeffs: [Coeffs::IDENTITY; MAX_HARMONICS], + stage_mix: [Smoothed::with_ms(0.0, sample_rate, 20.0); MAX_HARMONICS], + state: vec![[Biquad::new(); MAX_HARMONICS]; crate::sane_channels(channels)], + amount: Smoothed::with_ms(1.0, sample_rate, 20.0), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let f0 = if self.pv.idx("frequency") == 1 { 60.0 } else { 50.0 }; + let h = self.pv.v("harmonics").round() as usize; + let q = self.pv.v("q") as f64; + for k in 0..MAX_HARMONICS { + let f = f0 * (k + 1) as f64; + let active = k < h && f < self.sr as f64 * 0.45; + self.coeffs[k] = Coeffs::design(FilterType::Notch, self.sr as f64, f, q, 0.0); + self.stage_mix[k].set(if active { 1.0 } else { 0.0 }); + if snap { + self.stage_mix[k].snap(); + } + } + self.amount.set(self.pv.v("amount") / 100.0); + if snap { + self.amount.snap(); + } + } +} + +impl AudioEffect for DeHum { + param_plumbing!("dehum"); + fn reset(&mut self) { + self.state.iter_mut().for_each(|s| s.iter_mut().for_each(Biquad::reset)); + self.stage_mix.iter_mut().for_each(Smoothed::snap); + self.amount.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.state.len()); + for i in 0..n { + let mut mix = [0.0f64; MAX_HARMONICS]; + for (m, s) in mix.iter_mut().zip(self.stage_mix.iter_mut()) { + *m = s.tick() as f64; + } + let amt = self.amount.tick() as f64; + for ch in 0..nch { + let dry = channels[ch][i] as f64; + let mut x = dry; + for k in 0..MAX_HARMONICS { + let st = &mut self.state[ch][k]; + if mix[k] > 0.0 { + let y = st.tick(&self.coeffs[k], x); + x += mix[k] * (y - x); + } else { + st.reset(); + } + } + channels[ch][i] = (dry + amt * (x - dry)) as f32; + } + } + } +} + +// --------------------------------------------------------------------------------------------- + +/// Minimum-statistics sub-windows. +const MS_SUBWINDOWS: usize = 8; +/// Length of the minimum-statistics search window (seconds). +const MS_WINDOW_S: f32 = 1.5; +/// Bias compensation of the minimum of smoothed periodograms (≈ +4 dB). +const MS_BIAS: f32 = 2.5; +const PSD_SMOOTH: f32 = 0.8; + +#[derive(Clone, Debug)] +struct NoiseState { + psd: Vec, + cur_min: Vec, + ring: Vec, + ring_pos: usize, + frames_in_sub: usize, + gains: Vec, + started: bool, +} + +impl NoiseState { + fn new(bins: usize) -> Self { + NoiseState { + psd: vec![0.0; bins], + cur_min: vec![f32::INFINITY; bins], + ring: vec![f32::INFINITY; bins * MS_SUBWINDOWS], + ring_pos: 0, + frames_in_sub: 0, + gains: vec![1.0; bins], + started: false, + } + } + fn reset(&mut self) { + self.psd.iter_mut().for_each(|v| *v = 0.0); + self.cur_min.iter_mut().for_each(|v| *v = f32::INFINITY); + self.ring.iter_mut().for_each(|v| *v = f32::INFINITY); + self.gains.iter_mut().for_each(|v| *v = 1.0); + self.ring_pos = 0; + self.frames_in_sub = 0; + self.started = false; + } +} + +/// Broadband noise reduction by spectral gating: the noise floor of every STFT bin is tracked +/// continuously with minimum statistics (so no "learn" step is needed), and bins that do not +/// rise above `floor × threshold` are attenuated by `reduction`, with per-bin attack/release +/// and light frequency smoothing to avoid musical noise. +pub struct DeNoise { + pv: ParamValues, + n: usize, + hop: usize, + sub_frames: usize, + spec: Spectral, + stft: Vec, + noise: Vec, + smoothed_gains: Vec, + floor: f32, + thr: f32, + release: f32, +} + +impl DeNoise { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("reduction", "Reduction", 0.0, 40.0, 12.0, Unit::Decibels), + ParamSpec::new("threshold", "Threshold", 0.0, 20.0, 6.0, Unit::Decibels), + ParamSpec::new("smoothing", "Smoothing", 0.0, 100.0, 50.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let n = fft_size(sample_rate); + let hop = n / 4; + let bins = n / 2 + 1; + let sub_frames = ((MS_WINDOW_S * sample_rate / hop as f32 / MS_SUBWINDOWS as f32).round() as usize).max(1); + let ch = crate::sane_channels(channels); + let mut s = DeNoise { + pv: ParamValues::new(Self::PARAMS), + n, + hop, + sub_frames, + spec: Spectral::new(n, true), + stft: vec![StftChannel::new(n); ch], + noise: vec![NoiseState::new(bins); ch], + smoothed_gains: vec![1.0; bins], + floor: 1.0, + thr: 1.0, + release: 0.5, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, _snap: bool) { + self.floor = db_to_gain(-self.pv.v("reduction")); + self.thr = 10f32.powf(self.pv.v("threshold") / 10.0); + // 0 % → fast (0.6 per frame), 100 % → slow (0.03 per frame). + self.release = 0.6 - 0.57 * self.pv.v("smoothing") / 100.0; + } +} + +impl AudioEffect for DeNoise { + param_plumbing!("denoise"); + fn latency(&self) -> usize { + self.n + } + fn reset(&mut self) { + self.stft.iter_mut().for_each(StftChannel::reset); + self.noise.iter_mut().for_each(NoiseState::reset); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let len = block_len(channels); + let (n, hop, sub_frames) = (self.n, self.hop, self.sub_frames); + let (floor, thr, release) = (self.floor, self.thr, self.release); + let scale = 1.0 / (n as f32 * 2.0); + let (states, sg) = (&mut self.noise, &mut self.smoothed_gains); + stream(&mut self.stft, &mut self.spec, channels, len, Plan { hop, scale, pairing: Pairing::SynthesisOnly }, &mut |ch, _, re, im| { + let st = &mut states[ch]; + let bins = n / 2 + 1; + let mut accepted = true; + for k in 0..bins { + let p = re[k] * re[k] + im[k] * im[k]; + let psd = if st.started { PSD_SMOOTH * st.psd[k] + (1.0 - PSD_SMOOTH) * p } else { p }; + // A frame with a NaN or inf input sample would leave the recursion non-finite + // for good; skip it instead, also for the minimum statistics (a rejected bin + // would otherwise record its stale zero as the noise floor). + if psd.is_finite() { + st.psd[k] = psd; + st.cur_min[k] = st.cur_min[k].min(psd); + } else { + accepted = false; + } + } + // the recursion starts with the first frame that was accepted + st.started |= accepted; + st.frames_in_sub += 1; + let rotate = st.frames_in_sub == sub_frames; + for k in 0..bins { + let mut m = st.cur_min[k]; + for u in 0..MS_SUBWINDOWS { + m = m.min(st.ring[u * bins + k]); + } + let noise = m * MS_BIAS; + let target = if st.psd[k] > noise * thr { 1.0 } else { floor }; + let g = &mut st.gains[k]; + let c = if target > *g { 0.7 } else { release }; + *g += (target - *g) * c; + if rotate { + st.ring[st.ring_pos * bins + k] = st.cur_min[k]; + st.cur_min[k] = f32::INFINITY; + } + } + if rotate { + st.ring_pos = (st.ring_pos + 1) % MS_SUBWINDOWS; + st.frames_in_sub = 0; + } + // Frequency smoothing (3-tap) to reduce musical noise. + for k in 0..bins { + let a = st.gains[k.saturating_sub(1)]; + let b = st.gains[k]; + let c = st.gains[(k + 1).min(bins - 1)]; + sg[k] = 0.25 * a + 0.5 * b + 0.25 * c; + } + for k in 0..bins { + re[k] *= sg[k]; + im[k] *= sg[k]; + } + }); + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::*; + + const SR: f32 = 48000.0; + + #[test] + fn dehum_removes_hum_keeps_program() { + let mut d = DeHum::new(SR, 1); + d.set_param("frequency", 0.0); + d.set_param("harmonics", 4.0); + let n = SR as usize * 2; + let hum = |f: f64| sine(f, 0.2, SR as f64, n, 0.1); + let (h1, h3, p) = (hum(50.0), hum(150.0), sine(1000.0, 0.2, SR as f64, n, 0.0)); + let mut x: Vec = (0..n).map(|i| h1[i] + h3[i] + p[i]).collect(); + d.process(&mut [&mut x]); + let tail = &x[n / 2..]; + assert!(db(tone_amplitude(tail, 50.0, SR as f64) / 0.2) < -30.0); + assert!(db(tone_amplitude(tail, 150.0, SR as f64) / 0.2) < -30.0); + assert!(db(tone_amplitude(tail, 1000.0, SR as f64) / 0.2).abs() < 0.2); + // 60 Hz mode leaves 50 Hz mostly alone. + let mut d60 = DeHum::new(SR, 1); + d60.set_param("frequency", 1.0); + d60.reset(); + let mut y = hum(50.0); + d60.process(&mut [&mut y]); + assert!(db(tone_amplitude(&y[n / 2..], 50.0, SR as f64) / 0.2) > -3.0); + } + + #[test] + fn denoise_zero_reduction_is_delayed_identity() { + let mut d = DeNoise::new(SR, 1); + d.set_param("reduction", 0.0); + let lat = d.latency(); + let mut rng = Rng::new(9); + let x: Vec = (0..20000).map(|_| rng.uniform() * 0.5).collect(); + let mut y = x.clone(); + d.process(&mut [&mut y]); + for i in lat..x.len() { + assert!((y[i] - x[i - lat]).abs() < 1e-4, "i {i}: {} vs {}", y[i], x[i - lat]); + } + } + + #[test] + fn denoise_reduces_noise_and_keeps_bursts() { + let mut d = DeNoise::new(SR, 1); + d.set_param("reduction", 20.0); + let lat = d.latency(); + let n = SR as usize * 8; + let mut rng = Rng::new(21); + let noise: Vec = (0..n).map(|_| rng.uniform() * 0.02).collect(); + let tone = sine(1000.0, 0.3, SR as f64, n, 0.0); + // Tone bursts: on for 0.5 s, off for 0.5 s. + let on = |i: usize| (i / (SR as usize / 2)) % 2 == 1; + let x: Vec = (0..n).map(|i| noise[i] + if on(i) { tone[i] } else { 0.0 }).collect(); + let mut y = x.clone(); + d.process(&mut [&mut y]); + let half = SR as usize / 2; + // Evaluate the last seconds (after warm-up), aligned for latency, away from edges. + let seg = |k: usize| { + let s = k * half + lat + half / 4; + s..s + half / 2 + }; + let (off, onn) = (seg(14), seg(15)); + let red = db(rms(&y[off.clone()]) / rms(&x[off.start - lat..off.end - lat])); + assert!(red < -10.0, "noise reduction only {red} dB"); + let kept = db(tone_amplitude(&y[onn.clone()], 1000.0, SR as f64) / 0.3); + assert!(kept.abs() < 1.0, "tone changed by {kept} dB"); + } + + #[test] + fn denoise_recovers_from_a_non_finite_first_frame() { + let mut d = DeNoise::new(SR, 1); + d.set_param("reduction", 20.0); + let n = SR as usize * 4; + let mut rng = Rng::new(21); + let mut y: Vec = (0..n).map(|_| rng.uniform() * 0.02).collect(); + let x = y.clone(); + y[10] = f32::NAN; + d.process(&mut [&mut y]); + // the stale zero of the rejected first frame must not become the noise floor: the steady + // noise is still reduced once the estimate has settled + let tail = n - SR as usize / 2..n; + assert!(y[tail.clone()].iter().all(|v| v.is_finite())); + let red = db(rms(&y[tail.clone()]) / rms(&x[tail])); + assert!(red < -10.0, "noise reduction only {red} dB"); + } +} diff --git a/crates/audio-dsp/src/effects/reverbs.rs b/crates/audio-dsp/src/effects/reverbs.rs new file mode 100644 index 000000000..c4e805c89 --- /dev/null +++ b/crates/audio-dsp/src/effects/reverbs.rs @@ -0,0 +1,752 @@ +//! Convolution Reverb (uniformly partitioned overlap-save convolution with impulse responses +//! we generate ourselves) and Surround Reverb (early reflections + the FDN late field). + +use super::time::Reverb; +use super::util::{DelayLine, OnePole, Prng}; +use crate::fft::Fft; +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing}; + +/// Partition (block) size; the effect's latency. +const PART: usize = 256; + +/// Built-in impulse responses (generated, see [`generate_ir`]). +pub const IMPULSES: &[&str] = &["Small Room", "Medium Room", "Large Hall", "Cathedral", "Plate", "Ambience", "Vocal Booth"]; + +/// Character of a generated impulse. +#[derive(Clone, Copy, Debug)] +struct IrSpec { + rt60: f32, + /// Early-reflection span (ms) and count. + er_ms: f32, + er_count: usize, + /// How fast the high frequencies die relative to the low ones (1/s). + hf_decay: f32, + /// Late-field onset (ms). + onset_ms: f32, + seed: u64, +} + +const IR_SPECS: [IrSpec; 7] = [ + IrSpec { rt60: 0.45, er_ms: 25.0, er_count: 10, hf_decay: 6.0, onset_ms: 8.0, seed: 11 }, + IrSpec { rt60: 0.8, er_ms: 45.0, er_count: 14, hf_decay: 4.0, onset_ms: 15.0, seed: 12 }, + IrSpec { rt60: 1.9, er_ms: 80.0, er_count: 18, hf_decay: 2.2, onset_ms: 30.0, seed: 13 }, + IrSpec { rt60: 3.2, er_ms: 120.0, er_count: 22, hf_decay: 1.4, onset_ms: 45.0, seed: 14 }, + IrSpec { rt60: 1.6, er_ms: 0.0, er_count: 0, hf_decay: 1.0, onset_ms: 1.0, seed: 15 }, + IrSpec { rt60: 0.3, er_ms: 15.0, er_count: 8, hf_decay: 8.0, onset_ms: 4.0, seed: 16 }, + IrSpec { rt60: 0.2, er_ms: 8.0, er_count: 6, hf_decay: 12.0, onset_ms: 2.0, seed: 17 }, +]; + +/// Longest impulse kept, in samples (about 5.4 s at 192 kHz). At higher rates the longest +/// impulses are cut to it, which bounds the reverb's buffers to about 60 MB. +const MAX_IR_SAMPLES: usize = 1 << 20; + +fn ir_len(spec: &IrSpec, sr: f32) -> usize { + (((spec.rt60 * 1.1 + spec.er_ms * 0.001) * sr) as usize + 1).min(MAX_IR_SAMPLES) +} + +/// Fill `out` (stereo, equal lengths) with a synthetic impulse response: sparse early +/// reflections plus exponentially decaying noise whose bandwidth narrows over time (high +/// frequencies decay faster), fading in over the onset, each channel normalized to unit energy. +/// Deterministic for a given index and sample rate. +fn generate_ir(index: usize, sr: f32, out: [&mut [f32]; 2]) { + let spec = IR_SPECS[index.min(IR_SPECS.len() - 1)]; + for (c, buf) in out.into_iter().enumerate() { + let len = buf.len(); + let mut rng = Prng::new(spec.seed * 2 + c as u64); + let mut lp = OnePole::default(); + let onset = (spec.onset_ms * 0.001 * sr).max(1.0); + for (i, v) in buf.iter_mut().enumerate() { + let t = i as f32 / sr; + let env = (-6.907_755 * t / spec.rt60).exp(); + let fade = (i as f32 / onset).min(1.0); + let fc = (16000.0 * (-t * spec.hf_decay).exp()).max(800.0); + let a = OnePole::alpha(fc, sr); + *v = lp.lp(a, rng.uniform()) * env * fade; + } + for _ in 0..spec.er_count { + let t = 0.002 + (rng.uniform() * 0.5 + 0.5) * spec.er_ms * 0.001; + let i = ((t * sr) as usize).min(len - 1); + let amp = 0.6 * (-3.0 * t / (spec.er_ms * 0.001 + 1e-3)).exp() * if rng.uniform() < 0.0 { -1.0 } else { 1.0 }; + buf[i] += amp; + } + let e: f64 = buf.iter().map(|&v| (v as f64) * (v as f64)).sum(); + let g = if e > 0.0 { (1.0 / e.sqrt()) as f32 } else { 0.0 }; + buf.iter_mut().for_each(|v| *v *= g); + } +} + +/// Convolution reverb with generated impulses (mono-summed input, decorrelated stereo IR). +/// +/// A change to the impulse, room size or damping rebuilds the impulse's partitions in the next +/// `process` call, which then takes much longer than a block (up to about 1,400 FFTs of 512 +/// points at 48 kHz, four times that at 192 kHz). A live host changes these settings while the +/// effect is bypassed, or accepts a dropout; the other settings are smoothed per sample. +pub struct ConvolutionReverb { + pv: ParamValues, + sr: f32, + fft: Fft, + /// Base impulse (current preset) and the processed one (size, damping) per output channel. + base: [Vec; 2], + base_len: usize, + /// Partition spectra (B+1 bins, re/im interleaved per partition): `h[ch][p * 2(B+1) ..]`. + h: [Vec; 2], + parts: usize, + /// The previous partition set, still audible until the next block crossfades from it to `h`. + h_prev: [Vec; 2], + parts_prev: usize, + xfade: bool, + /// A block has been convolved since construction or reset, so an impulse change can click. + primed: bool, + /// Frequency-domain delay line of input spectra (same layout), ring of `max_parts`. + fdl: Vec, + head: usize, + max_parts: usize, + /// Time-domain input history (2B) and block in/out buffers. + hist: Vec, + inbuf: Vec, + out: [Vec; 2], + pos: usize, + re: Vec, + im: Vec, + pre: DelayLine, + dry_delay: Vec, + key: (usize, f32, f32, f32), + /// Impulse, size or damping changed since the last rebuild; rebuilt at the next `process`. + dirty: bool, + mix: Smoothed, + gain: Smoothed, + width: Smoothed, + predelay: Smoothed, +} + +impl ConvolutionReverb { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::choice("impulse", "Impulse", IMPULSES, 1), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 30.0, Unit::Percent), + ParamSpec::new("room_size", "Room Size", 10.0, 100.0, 100.0, Unit::Percent), + ParamSpec::log("damping_lf", "Damping LF", 10.0, 1000.0, 10.0, Unit::Hertz), + ParamSpec::log("damping_hf", "Damping HF", 1000.0, 20000.0, 20000.0, Unit::Hertz), + ParamSpec::new("predelay", "Pre-Delay", 0.0, 500.0, 0.0, Unit::Milliseconds), + ParamSpec::new("width", "Width", 0.0, 100.0, 100.0, Unit::Percent), + ParamSpec::new("gain", "Gain", -24.0, 12.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let max_len = IR_SPECS.iter().map(|s| ir_len(s, sample_rate)).max().unwrap_or(1); + let max_parts = max_len.div_ceil(PART); + let bins2 = 2 * (PART + 1); + let mut s = ConvolutionReverb { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + fft: Fft::new(2 * PART), + base: [vec![0.0; max_len], vec![0.0; max_len]], + base_len: 0, + h: [vec![0.0; max_parts * bins2], vec![0.0; max_parts * bins2]], + parts: 0, + h_prev: [vec![0.0; max_parts * bins2], vec![0.0; max_parts * bins2]], + parts_prev: 0, + xfade: false, + primed: false, + fdl: vec![0.0; max_parts * bins2], + head: 0, + max_parts, + hist: vec![0.0; 2 * PART], + inbuf: vec![0.0; PART], + out: [vec![0.0; PART], vec![0.0; PART]], + pos: 0, + re: vec![0.0; 2 * PART], + im: vec![0.0; 2 * PART], + pre: DelayLine::new((0.5 * sample_rate) as usize + 2), + dry_delay: vec![DelayLine::new(PART + 2); crate::sane_channels(channels)], + key: (usize::MAX, 0.0, 0.0, 0.0), + dirty: false, + mix: Smoothed::with_ms(0.0, sample_rate, 20.0), + gain: Smoothed::with_ms(1.0, sample_rate, 20.0), + width: Smoothed::with_ms(1.0, sample_rate, 20.0), + predelay: Smoothed::with_ms(0.0, sample_rate, 50.0), + }; + s.apply_params(true); + s + } + + /// Rebuild the partition spectra (only when the impulse, size or damping changed). Once audio + /// has run, the audible set is kept in `h_prev` and the next block crossfades to the new one. + fn rebuild(&mut self) { + let key = (self.pv.idx("impulse"), self.pv.v("room_size"), self.pv.v("damping_lf"), self.pv.v("damping_hf")); + if key == self.key { + return; + } + if self.primed && !self.xfade { + std::mem::swap(&mut self.h, &mut self.h_prev); + self.parts_prev = self.parts; + self.xfade = true; + } + if key.0 != self.key.0 { + let len = ir_len(&IR_SPECS[key.0.min(IR_SPECS.len() - 1)], self.sr).min(self.base[0].len()); + let [a, b] = &mut self.base; + generate_ir(key.0, self.sr, [&mut a[..len], &mut b[..len]]); + self.base_len = len; + } + self.key = key; + // Room size shortens the impulse by resampling it (linear interpolation). + let scale = (key.1 / 100.0).clamp(0.1, 1.0); + let len = ((self.base_len as f32 * scale) as usize).max(1); + self.parts = len.div_ceil(PART).min(self.max_parts); + let (alf, ahf) = (OnePole::alpha(key.2, self.sr), OnePole::alpha(key.3, self.sr)); + let bins2 = 2 * (PART + 1); + for c in 0..2 { + let mut hp = OnePole::default(); + let mut lp = OnePole::default(); + for p in 0..self.parts { + for k in 0..2 * PART { + self.re[k] = 0.0; + self.im[k] = 0.0; + } + for k in 0..PART { + let i = p * PART + k; + if i >= len { + break; + } + let src = i as f32 / scale; + let i0 = src as usize; + let fr = src - i0 as f32; + let b = &self.base[c]; + let v0 = b.get(i0).copied().unwrap_or(0.0); + let v1 = b.get(i0 + 1).copied().unwrap_or(0.0); + let mut v = (v0 + (v1 - v0) * fr) * scale.sqrt().recip(); + if key.2 > 10.5 { + v = hp.hp(alf, v); + } + if key.3 < 19999.0 { + v = lp.lp(ahf, v); + } + self.re[k] = v; + } + self.fft.forward(&mut self.re, &mut self.im); + let dst = &mut self.h[c][p * bins2..(p + 1) * bins2]; + for k in 0..=PART { + dst[2 * k] = self.re[k]; + dst[2 * k + 1] = self.im[k]; + } + } + } + } + + /// Partitions the impulse for the current settings has, built or not. + fn pending_parts(&self) -> usize { + let base = ir_len(&IR_SPECS[self.pv.idx("impulse").min(IR_SPECS.len() - 1)], self.sr).min(self.base[0].len()); + let scale = (self.pv.v("room_size") / 100.0).clamp(0.1, 1.0); + ((base as f32 * scale) as usize).max(1).div_ceil(PART).min(self.max_parts) + } + + fn apply_params(&mut self, snap: bool) { + if snap { + self.rebuild(); + } else { + self.dirty = true; + } + self.mix.set(self.pv.v("mix") / 100.0); + self.gain.set(db_to_gain(self.pv.v("gain"))); + self.width.set(self.pv.v("width") / 100.0); + self.predelay.set(self.pv.v("predelay") * 0.001 * self.sr); + if snap { + self.mix.snap(); + self.gain.snap(); + self.width.snap(); + self.predelay.snap(); + } + } + + /// Convolve the collected block (`inbuf`) and fill `out`, crossfading linearly over the block + /// from the previous partition set when the impulse changed. + fn block(&mut self) { + let bins2 = 2 * (PART + 1); + self.primed = true; + self.hist.copy_within(PART.., 0); + self.hist[PART..].copy_from_slice(&self.inbuf); + self.re.copy_from_slice(&self.hist); + self.im.iter_mut().for_each(|v| *v = 0.0); + self.fft.forward(&mut self.re, &mut self.im); + self.head = (self.head + self.max_parts - 1) % self.max_parts; + { + let slot = &mut self.fdl[self.head * bins2..(self.head + 1) * bins2]; + for k in 0..=PART { + slot[2 * k] = self.re[k]; + slot[2 * k + 1] = self.im[k]; + } + } + if std::mem::take(&mut self.xfade) { + let mut prev = [[0.0f32; PART]; 2]; + convolve(&self.fft, &self.fdl, self.head, self.max_parts, &self.h_prev, self.parts_prev, &mut self.re, &mut self.im); + for k in 0..PART { + prev[0][k] = self.re[PART + k]; + prev[1][k] = self.im[PART + k]; + } + convolve(&self.fft, &self.fdl, self.head, self.max_parts, &self.h, self.parts, &mut self.re, &mut self.im); + for k in 0..PART { + let g = (k + 1) as f32 / PART as f32; + self.re[PART + k] = prev[0][k] + g * (self.re[PART + k] - prev[0][k]); + self.im[PART + k] = prev[1][k] + g * (self.im[PART + k] - prev[1][k]); + } + } else { + convolve(&self.fft, &self.fdl, self.head, self.max_parts, &self.h, self.parts, &mut self.re, &mut self.im); + } + let s = 1.0 / (2 * PART) as f32; + for k in 0..PART { + self.out[0][k] = self.re[PART + k] * s; + self.out[1][k] = self.im[PART + k] * s; + } + } +} + +/// Multiply the input spectra in the delay line with the first `parts` partitions of `h`; the +/// unscaled left and right outputs land in `re[PART..]` and `im[PART..]`. +#[allow(clippy::too_many_arguments)] +fn convolve(fft: &Fft, fdl: &[f32], head: usize, max_parts: usize, h: &[Vec; 2], parts: usize, re: &mut [f32], im: &mut [f32]) { + let bins2 = 2 * (PART + 1); + // Accumulate Y_L and Y_R (half spectra) then pack Z = Y_L + j·Y_R for one inverse FFT. + let mut yl = [0.0f32; 2 * (PART + 1)]; + let mut yr = [0.0f32; 2 * (PART + 1)]; + for p in 0..parts { + let xi = ((head + p) % max_parts) * bins2; + let x = &fdl[xi..xi + bins2]; + let hl = &h[0][p * bins2..(p + 1) * bins2]; + let hr = &h[1][p * bins2..(p + 1) * bins2]; + for k in 0..=PART { + let (xr, xim) = (x[2 * k], x[2 * k + 1]); + yl[2 * k] += xr * hl[2 * k] - xim * hl[2 * k + 1]; + yl[2 * k + 1] += xr * hl[2 * k + 1] + xim * hl[2 * k]; + yr[2 * k] += xr * hr[2 * k] - xim * hr[2 * k + 1]; + yr[2 * k + 1] += xr * hr[2 * k + 1] + xim * hr[2 * k]; + } + } + let n = 2 * PART; + for k in 0..n { + let (lr, li, rr, ri) = if k <= PART { + (yl[2 * k], yl[2 * k + 1], yr[2 * k], yr[2 * k + 1]) + } else { + let m = n - k; + (yl[2 * m], -yl[2 * m + 1], yr[2 * m], -yr[2 * m + 1]) + }; + // Z = Y_L + j·Y_R + re[k] = lr - ri; + im[k] = li + rr; + } + fft.inverse(re, im); +} + +impl AudioEffect for ConvolutionReverb { + param_plumbing!("convolution_reverb"); + fn latency(&self) -> usize { + PART + } + /// The pre-delay plus the longest of the impulse in use, the one it is fading from and the one + /// the current settings will build at the next block. + fn tail_samples(&self) -> usize { + let fading = if self.xfade { self.parts_prev } else { 0 }; + let parts = self.parts.max(fading).max(self.pending_parts()); + super::util::tail_samples(self.pv.v("predelay") * 0.001, self.sr) + parts * PART + } + fn reset(&mut self) { + self.fdl.iter_mut().for_each(|v| *v = 0.0); + self.hist.iter_mut().for_each(|v| *v = 0.0); + self.inbuf.iter_mut().for_each(|v| *v = 0.0); + self.out.iter_mut().for_each(|o| o.iter_mut().for_each(|v| *v = 0.0)); + self.head = 0; + self.pos = 0; + self.primed = false; + self.xfade = false; + self.pre.reset(); + self.dry_delay.iter_mut().for_each(DelayLine::reset); + self.mix.snap(); + self.gain.snap(); + self.width.snap(); + self.predelay.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.dry_delay.len()); + if nch == 0 { + return; + } + if self.dirty { + self.dirty = false; + self.rebuild(); + } + for i in 0..n { + let (mix, gain, width, pd) = (self.mix.tick(), self.gain.tick(), self.width.tick(), self.predelay.tick()); + let mono = channels[..nch].iter().map(|c| c[i]).sum::() / nch as f32; + self.pre.push(mono); + self.inbuf[self.pos] = self.pre.read(pd); + let (wl, wr) = (self.out[0][self.pos], self.out[1][self.pos]); + self.pos += 1; + if self.pos == PART { + self.pos = 0; + self.block(); + } + // Width: 0 = mono wet, 1 = full decorrelated stereo. + let m = 0.5 * (wl + wr); + let (wl, wr) = (m + width * (wl - m), m + width * (wr - m)); + for ch in 0..nch { + self.dry_delay[ch].push(channels[ch][i]); + let dry = self.dry_delay[ch].tap(PART); + let wet = if nch == 1 { + m + } else if ch == 0 { + wl + } else { + wr + }; + channels[ch][i] = dry + mix * (wet * gain - dry); + } + } + } +} + +// ------------------------------------------------------------------------- surround reverb + +const ER_TAPS: usize = 8; +const ER_MS: [f32; ER_TAPS] = [7.1, 11.3, 15.7, 19.9, 24.2, 31.7, 38.3, 47.9]; +const ER_GAIN: [f32; ER_TAPS] = [0.8, -0.7, 0.62, -0.55, 0.47, -0.4, 0.33, -0.27]; +const CHUNK: usize = 256; + +/// Early reflections (8 taps, alternating sides) plus the 8-line FDN late field, with +/// low/high cut on the wet signal, wet width, and separate dry/wet levels. The center input +/// level controls how much of the mid (L+R) signal feeds the reverb. +pub struct SurroundReverb { + pv: ParamValues, + sr: f32, + late: Reverb, + er: DelayLine, + lc: [OnePole; 2], + hc: [OnePole; 2], + scratch: [[f32; CHUNK]; 2], + dry: Smoothed, + wet: Smoothed, + early: Smoothed, + width: Smoothed, + center: Smoothed, + size: Smoothed, +} + +impl SurroundReverb { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("center_input", "Center Input", 0.0, 100.0, 100.0, Unit::Percent), + ParamSpec::new("room_size", "Room Size", 0.0, 100.0, 50.0, Unit::Percent), + ParamSpec::log("decay", "Decay", 0.1, 20.0, 1.5, Unit::Seconds), + ParamSpec::new("predelay", "Pre-Delay", 0.0, 200.0, 20.0, Unit::Milliseconds), + ParamSpec::new("damping", "Damping", 0.0, 100.0, 40.0, Unit::Percent), + ParamSpec::new("early", "Early Reflections", 0.0, 100.0, 40.0, Unit::Percent), + ParamSpec::log("low_cut", "Low Frequency Cut", 20.0, 1000.0, 20.0, Unit::Hertz), + ParamSpec::log("high_cut", "High Frequency Cut", 1000.0, 20000.0, 12000.0, Unit::Hertz), + ParamSpec::new("width", "Width", 0.0, 100.0, 100.0, Unit::Percent), + ParamSpec::new("dry", "Dry", 0.0, 100.0, 80.0, Unit::Percent), + ParamSpec::new("wet", "Wet", 0.0, 100.0, 30.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut late = Reverb::new(sample_rate, channels); + late.set_param("mix", 100.0); + let sm = |v| Smoothed::with_ms(v, sample_rate, 20.0); + let mut s = SurroundReverb { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + late, + er: DelayLine::new((0.1 * sample_rate) as usize), + lc: [OnePole::default(); 2], + hc: [OnePole::default(); 2], + scratch: [[0.0; CHUNK]; 2], + dry: sm(1.0), + wet: sm(0.0), + early: sm(0.0), + width: sm(1.0), + center: sm(1.0), + size: sm(1.0), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.late.set_param("size", self.pv.v("room_size")); + self.late.set_param("decay", self.pv.v("decay")); + self.late.set_param("predelay", self.pv.v("predelay")); + self.late.set_param("damping", self.pv.v("damping")); + self.dry.set(self.pv.v("dry") / 100.0); + self.wet.set(self.pv.v("wet") / 100.0); + self.early.set(self.pv.v("early") / 100.0); + self.width.set(self.pv.v("width") / 100.0); + self.center.set(self.pv.v("center_input") / 100.0); + self.size.set(0.5 + self.pv.v("room_size") / 100.0); + if snap { + self.late.reset(); + for s in [&mut self.dry, &mut self.wet, &mut self.early, &mut self.width, &mut self.center, &mut self.size] { + s.snap(); + } + } + } +} + +impl AudioEffect for SurroundReverb { + param_plumbing!("surround_reverb"); + /// Pre-delay plus the decay time (RT60, the time to fall 60 dB). + fn tail_samples(&self) -> usize { + super::util::tail_samples(self.pv.v("predelay") * 0.001 + self.pv.v("decay"), self.sr) + } + fn reset(&mut self) { + self.late.reset(); + self.er.reset(); + self.lc = [OnePole::default(); 2]; + self.hc = [OnePole::default(); 2]; + for s in [&mut self.dry, &mut self.wet, &mut self.early, &mut self.width, &mut self.center, &mut self.size] { + s.snap(); + } + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(2); + if nch == 0 { + return; + } + let (alc, ahc) = (OnePole::alpha(self.pv.v("low_cut"), self.sr), OnePole::alpha(self.pv.v("high_cut"), self.sr)); + let ms = self.sr * 0.001; + let mut start = 0; + while start < n { + let len = (n - start).min(CHUNK); + // Reverb input: side signal plus the center-weighted mid. + for i in 0..len { + let (l, r) = + if nch == 2 { (channels[0][start + i], channels[1][start + i]) } else { (channels[0][start + i], channels[0][start + i]) }; + let c = self.center.tick(); + let (mid, side) = (0.5 * (l + r), 0.5 * (l - r)); + self.scratch[0][i] = c * mid + side; + self.scratch[1][i] = c * mid - side; + } + { + let [a, b] = &mut self.scratch; + self.late.process(&mut [&mut a[..len], &mut b[..len]]); + } + for i in 0..len { + let x = if nch == 2 { 0.5 * (channels[0][start + i] + channels[1][start + i]) } else { channels[0][start + i] }; + let size = self.size.tick(); + self.er.push(x); + let (mut el, mut er) = (0.0, 0.0); + for k in 0..ER_TAPS { + let v = ER_GAIN[k] * self.er.read(ER_MS[k] * size * ms); + if k % 2 == 0 { el += v } else { er += v } + } + let early = self.early.tick(); + let (dry, wet, width) = (self.dry.tick(), self.wet.tick(), self.width.tick()); + let mut w = [self.scratch[0][i] + early * el, self.scratch[1][i] + early * er]; + for c in 0..2 { + w[c] = self.hc[c].lp(ahc, self.lc[c].hp(alc, w[c])); + } + let m = 0.5 * (w[0] + w[1]); + let (wl, wr) = (m + width * (w[0] - m), m + width * (w[1] - m)); + if nch == 2 { + channels[0][start + i] = dry * channels[0][start + i] + wet * wl; + channels[1][start + i] = dry * channels[1][start + i] + wet * wr; + } else { + channels[0][start + i] = dry * channels[0][start + i] + wet * m; + } + } + start += len; + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::Rng; + + #[test] + fn set_param_defers_the_impulse_rebuild_to_process() { + let mut fx = ConvolutionReverb::new(48_000.0, 2); + let key = fx.key; + fx.set_param("damping_hf", 8000.0); + fx.set_param("room_size", 60.0); + assert_eq!(fx.key, key, "set_param rebuilt the impulse"); + fx.process(&mut [&mut [0.0; 16][..], &mut [0.0; 16][..]]); + assert_eq!(fx.key, (key.0, 60.0, key.2, 8000.0)); + assert!(!fx.dirty); + } + + #[test] + fn the_impulse_is_bounded_at_the_highest_rate() { + let mut fx = ConvolutionReverb::new(crate::MAX_SAMPLE_RATE, 2); + assert!(fx.base[0].len() <= MAX_IR_SAMPLES && fx.max_parts * PART <= MAX_IR_SAMPLES + PART); + let mut x = vec![0.0f32; 1024]; + x[0] = 1.0; + let mut y = x.clone(); + fx.set_param("mix", 100.0); + fx.process(&mut [&mut x[..], &mut y[..]]); + assert!(x.iter().chain(&y).all(|v| v.is_finite())); + } + + #[test] + fn the_tail_covers_an_impulse_not_built_yet() { + let mut fx = ConvolutionReverb::new(48_000.0, 2); + fx.set_param("room_size", 10.0); + fx.process(&mut [&mut [0.0; 16][..], &mut [0.0; 16][..]]); + let short = fx.tail_samples(); + fx.set_param("room_size", 100.0); + fx.set_param("impulse", 3.0); + let before = fx.tail_samples(); + fx.process(&mut [&mut [0.0; 16][..], &mut [0.0; 16][..]]); + assert!(before > short, "{before} <= {short}"); + assert!(before >= fx.tail_samples(), "{before} < {}", fx.tail_samples()); + } + + #[test] + fn deferred_rebuild_output_is_identical() { + let changes: &[&[(&str, f32)]] = &[ + &[("room_size", 70.0)], + &[], + &[("damping_lf", 200.0), ("damping_hf", 6000.0)], + &[("impulse", 2.0), ("mix", 80.0)], + &[("room_size", 30.0), ("room_size", 90.0)], + &[("impulse", 4.0), ("damping_hf", 20_000.0), ("damping_lf", 10.0)], + ]; + let mut eager = ConvolutionReverb::new(48_000.0, 2); + let mut deferred = ConvolutionReverb::new(48_000.0, 2); + let mut rng = Rng::new(5); + for (block, set) in changes.iter().cycle().take(24).enumerate() { + for &(id, v) in *set { + eager.set_param(id, v); + eager.rebuild(); + deferred.set_param(id, v); + } + let n = 300 + 37 * block; + let l: Vec = (0..n).map(|_| rng.uniform()).collect(); + let r: Vec = (0..n).map(|_| rng.uniform()).collect(); + let (mut l1, mut r1, mut l2, mut r2) = (l.clone(), r.clone(), l, r); + eager.process(&mut [&mut l1, &mut r1]); + deferred.process(&mut [&mut l2, &mut r2]); + for (a, b) in l1.iter().chain(&r1).zip(l2.iter().chain(&r2)) { + assert_eq!(a.to_bits(), b.to_bits(), "block {block}"); + } + } + } + + /// Run `fx` over `l`/`r` in calls of `step` samples, applying `set` before the call that + /// starts at sample `at`; returns the left output. + fn run(fx: &mut ConvolutionReverb, l: &[f32], r: &[f32], step: usize, set: &mut dyn FnMut(&mut ConvolutionReverb, usize)) -> Vec { + let (mut l, mut r) = (l.to_vec(), r.to_vec()); + let mut at = 0; + for (a, b) in l.chunks_mut(step).zip(r.chunks_mut(step)) { + set(fx, at); + at += a.len(); + fx.process(&mut [a, b]); + } + l + } + + fn sine(n: usize) -> Vec { + (0..n).map(|i| 0.5 * (std::f32::consts::TAU * 200.0 * i as f32 / 48_000.0).sin()).collect() + } + + fn wet() -> ConvolutionReverb { + let mut fx = ConvolutionReverb::new(48_000.0, 2); + fx.set_param("mix", 100.0); + fx + } + + /// Apply `changes` at once without a crossfade (the old instant swap). + fn snap(fx: &mut ConvolutionReverb, changes: &[(&str, f32)]) { + for &(id, v) in changes { + fx.set_param(id, v); + } + fx.primed = false; + fx.rebuild(); + fx.primed = true; + } + + fn max_jump(y: &[f32]) -> f32 { + y.windows(2).map(|w| (w[1] - w[0]).abs()).fold(0.0, f32::max) + } + + #[test] + fn impulse_change_crossfades_within_one_partition() { + let n = 48_000 * 5 / 2; + let at = 188 * 512; + let x = sine(n); + for change in [("impulse", 3.0), ("damping_lf", 800.0), ("room_size", 40.0)] { + let faded = run(&mut wet(), &x, &x, 512, &mut |fx, i| { + if i == at { + fx.set_param(change.0, change.1); + } + }); + let instant = run(&mut wet(), &x, &x, 512, &mut |fx, i| { + if i == at { + snap(fx, &[change]); + } + }); + // The latency is unchanged and the new impulse is fully in after one partition. + let (fade_from, fade_to) = (at + PART, at + 2 * PART); + for (i, (a, b)) in faded.iter().zip(&instant).enumerate() { + if !(fade_from..fade_to).contains(&i) { + assert_eq!(a.to_bits(), b.to_bits(), "{change:?}: sample {i}"); + } + } + assert!(faded[fade_from..fade_to].iter().zip(&instant[fade_from..fade_to]).any(|(a, b)| a != b)); + let steady = max_jump(&faded[at - 4096..at]); + let around = at - PART..at + 4 * PART; + let (jf, ji) = (max_jump(&faded[around.clone()]), max_jump(&instant[around])); + assert!(jf < 1.5 * steady, "{change:?}: jump {jf} vs steady {steady}"); + assert!(ji > 4.0 * jf, "{change:?}: instant jump {ji} vs faded {jf}"); + } + } + + #[test] + fn repeated_changes_before_the_crossfade_fade_from_the_audible_impulse() { + let n = 48_000 * 2; + let at = 256 * 300; + let x = sine(n); + let mut fx = wet(); + let faded = run(&mut fx, &x, &x, 64, &mut |fx, i| { + if i == at { + fx.set_param("impulse", 3.0); + } + if i == at + 64 { + assert!(fx.xfade); + fx.set_param("damping_lf", 800.0); + } + if i == at + 128 { + fx.set_param("room_size", 50.0); + } + }); + assert_eq!(fx.key, (3, 50.0, 800.0, 20_000.0)); + assert!(!fx.xfade); + let instant = run(&mut wet(), &x, &x, 64, &mut |fx, i| { + if i == at { + snap(fx, &[("impulse", 3.0), ("damping_lf", 800.0), ("room_size", 50.0)]); + } + }); + let (fade_from, fade_to) = (at + PART, at + 2 * PART); + for (i, (a, b)) in faded.iter().zip(&instant).enumerate() { + if !(fade_from..fade_to).contains(&i) { + assert_eq!(a.to_bits(), b.to_bits(), "sample {i}"); + } + } + let steady = max_jump(&faded[at - 4096..at]); + let jf = max_jump(&faded[at - PART..at + 4 * PART]); + assert!(jf < 1.5 * steady, "jump {jf} vs steady {steady}"); + } + + #[test] + fn unchanged_impulse_does_not_crossfade() { + let mut rng = Rng::new(9); + let x: Vec = (0..48_000).map(|_| rng.uniform()).collect(); + let plain = run(&mut ConvolutionReverb::new(48_000.0, 2), &x, &x, 512, &mut |_, _| {}); + let touched = run(&mut ConvolutionReverb::new(48_000.0, 2), &x, &x, 512, &mut |fx, i| { + fx.set_param("room_size", 100.0); + fx.set_param("damping_hf", 20_000.0); + fx.set_param("mix", 30.0); + assert!(!fx.xfade, "sample {i}"); + }); + assert!(plain.iter().zip(&touched).all(|(a, b)| a.to_bits() == b.to_bits())); + } +} diff --git a/crates/audio-dsp/src/effects/special.rs b/crates/audio-dsp/src/effects/special.rs new file mode 100644 index 000000000..5ae18c762 --- /dev/null +++ b/crates/audio-dsp/src/effects/special.rs @@ -0,0 +1,971 @@ +//! Special and stereo effects: Channel Mixer, Distortion, GuitarSuite, Mastering, Vocal +//! Enhancer, Stereo Expander, Binauralizer, Ambisonics Panner, Loudness Meter and Mute. + +use super::multiband::soft_clip; +use super::time::Reverb; +use super::util::{DcBlock, DelayLine, OnePole, coef, lin_db}; +use crate::biquad::{Biquad, Coeffs, FilterType}; +use crate::loudness::LoudnessMeter; +use crate::{AudioEffect, MAX_CHANNELS, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, flush32, param_plumbing}; +use std::f32::consts::{FRAC_PI_2, PI}; + +const SM: f32 = 20.0; +const CHUNK: usize = 256; + +fn sm(v: f32, sr: f32) -> Smoothed { + Smoothed::with_ms(v, sr, SM) +} + +// ------------------------------------------------------------------------------ channel mixer + +/// 2×2 channel matrix with per-output polarity inversion. +pub struct ChannelMixer { + pv: ParamValues, + g: [Smoothed; 4], +} + +impl ChannelMixer { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("l_from_l", "Left - Left", -100.0, 100.0, 100.0, Unit::Percent), + ParamSpec::new("l_from_r", "Left - Right", -100.0, 100.0, 0.0, Unit::Percent), + ParamSpec::new("r_from_l", "Right - Left", -100.0, 100.0, 0.0, Unit::Percent), + ParamSpec::new("r_from_r", "Right - Right", -100.0, 100.0, 100.0, Unit::Percent), + ParamSpec::toggle("invert_l", "Invert Left", false), + ParamSpec::toggle("invert_r", "Invert Right", false), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = ChannelMixer { + pv: ParamValues::new(Self::PARAMS), + g: [sm(1.0, sample_rate), sm(0.0, sample_rate), sm(0.0, sample_rate), sm(1.0, sample_rate)], + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let il = if self.pv.on("invert_l") { -1.0 } else { 1.0 }; + let ir = if self.pv.on("invert_r") { -1.0 } else { 1.0 }; + let v = [ + il * self.pv.v("l_from_l") / 100.0, + il * self.pv.v("l_from_r") / 100.0, + ir * self.pv.v("r_from_l") / 100.0, + ir * self.pv.v("r_from_r") / 100.0, + ]; + for (s, v) in self.g.iter_mut().zip(v) { + s.set(v); + if snap { + s.snap(); + } + } + } +} + +impl AudioEffect for ChannelMixer { + param_plumbing!("channel_mixer"); + fn reset(&mut self) { + self.g.iter_mut().for_each(Smoothed::snap); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + if channels.len() < 2 { + for i in 0..n { + let g: Vec4 = self.tick(); + channels[0][i] *= g[0] + g[1]; + } + return; + } + let (a, b) = channels.split_at_mut(1); + let (l, r) = (&mut a[0], &mut b[0]); + for i in 0..n { + let g = self.tick(); + let (x, y) = (l[i], r[i]); + l[i] = g[0] * x + g[1] * y; + r[i] = g[2] * x + g[3] * y; + } + } +} + +type Vec4 = [f32; 4]; + +impl ChannelMixer { + #[inline] + fn tick(&mut self) -> Vec4 { + [self.g[0].tick(), self.g[1].tick(), self.g[2].tick(), self.g[3].tick()] + } +} + +// --------------------------------------------------------------------------------- distortion + +pub const DIST_CURVES: &[&str] = &["Soft Clip", "Hard Clip", "Tube", "Foldback"]; + +/// Memoryless transfer curves (unity small-signal slope). +#[inline] +pub fn shape(kind: usize, v: f32) -> f32 { + match kind { + 0 => v.tanh(), + 1 => v.clamp(-1.0, 1.0), + 2 => { + if v >= 0.0 { + v.tanh() + } else { + (1.6 * v).tanh() / 1.6 + } + } + _ => v.sin(), + } +} + +/// Waveshaping distortion: drive, curve, asymmetry (bias, DC-blocked), tone low-pass, output, +/// dry/wet mix. +pub struct Distortion { + pv: ParamValues, + sr: f32, + dc: Vec, + lp: Vec, + drive: Smoothed, + bias: Smoothed, + out: Smoothed, + mix: Smoothed, +} + +impl Distortion { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("drive", "Drive", 0.0, 48.0, 12.0, Unit::Decibels), + ParamSpec::choice("curve", "Curve", DIST_CURVES, 0), + ParamSpec::new("symmetry", "Asymmetry", -100.0, 100.0, 0.0, Unit::Percent), + ParamSpec::log("tone", "Tone", 500.0, 20000.0, 20000.0, Unit::Hertz), + ParamSpec::new("output", "Output Gain", -48.0, 12.0, 0.0, Unit::Decibels), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 100.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let ch = crate::sane_channels(channels); + let mut s = Distortion { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + dc: vec![DcBlock::default(); ch], + lp: vec![OnePole::default(); ch], + drive: sm(1.0, sample_rate), + bias: sm(0.0, sample_rate), + out: sm(1.0, sample_rate), + mix: sm(1.0, sample_rate), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + self.drive.set(db_to_gain(self.pv.v("drive"))); + self.bias.set(0.5 * self.pv.v("symmetry") / 100.0); + self.out.set(db_to_gain(self.pv.v("output"))); + self.mix.set(self.pv.v("mix") / 100.0); + if snap { + for s in [&mut self.drive, &mut self.bias, &mut self.out, &mut self.mix] { + s.snap(); + } + } + } +} + +impl AudioEffect for Distortion { + param_plumbing!("distortion"); + fn reset(&mut self) { + self.dc.iter_mut().for_each(DcBlock::reset); + self.lp.iter_mut().for_each(OnePole::reset); + for s in [&mut self.drive, &mut self.bias, &mut self.out, &mut self.mix] { + s.snap(); + } + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.dc.len()); + let kind = self.pv.idx("curve"); + let tone = self.pv.v("tone"); + let a = OnePole::alpha(tone, self.sr); + let r = DcBlock::r(self.sr); + for i in 0..n { + let (d, b, o, m) = (self.drive.tick(), self.bias.tick(), self.out.tick(), self.mix.tick()); + for ch in 0..nch { + let x = channels[ch][i]; + let mut y = shape(kind, d * x + b) - shape(kind, b); + y = self.dc[ch].tick(r, y); + if tone < 19999.0 { + y = self.lp[ch].lp(a, y); + } + channels[ch][i] = x + m * (y * o - x); + } + } + } +} + +// -------------------------------------------------------------------------------- GuitarSuite + +pub const GS_AMPS: &[&str] = &["None", "Clean Combo", "British Stack", "Tweed", "Modern High Gain"]; +pub const GS_FILTERS: &[&str] = &["None", "Low Pass", "High Pass", "Band Pass"]; +pub const GS_DIST: &[&str] = &["Soft", "Hard", "Fuzz"]; + +/// Guitar chain: compressor → distortion → amplifier/cabinet voicing → filter, with mix and +/// output gain. +pub struct GuitarSuite { + pv: ParamValues, + sr: f32, + env: f32, + cab: [Coeffs; 4], + filt: Coeffs, + st: Vec<[Biquad; 5]>, + dc: Vec, + mix: Smoothed, + out: Smoothed, + drive: Smoothed, +} + +impl GuitarSuite { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("compressor", "Compressor", 0.0, 100.0, 30.0, Unit::Percent), + ParamSpec::new("distortion", "Distortion", 0.0, 100.0, 40.0, Unit::Percent), + ParamSpec::choice("dist_type", "Distortion Type", GS_DIST, 0), + ParamSpec::choice("amp", "Amplifier", GS_AMPS, 1), + ParamSpec::choice("filter", "Filter", GS_FILTERS, 0), + ParamSpec::log("filter_freq", "Filter Frequency", 100.0, 10000.0, 2000.0, Unit::Hertz), + ParamSpec::new("filter_res", "Filter Resonance", 0.0, 100.0, 20.0, Unit::Percent), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 100.0, Unit::Percent), + ParamSpec::new("output", "Output Gain", -24.0, 12.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let ch = crate::sane_channels(channels); + let mut s = GuitarSuite { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + env: 0.0, + cab: [Coeffs::IDENTITY; 4], + filt: Coeffs::IDENTITY, + st: vec![[Biquad::new(); 5]; ch], + dc: vec![DcBlock::default(); ch], + mix: sm(1.0, sample_rate), + out: sm(1.0, sample_rate), + drive: sm(1.0, sample_rate), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let sr = self.sr as f64; + let d = |k, f, q, g| Coeffs::design(k, sr, f, q, g); + use FilterType::*; + self.cab = match self.pv.idx("amp") { + 0 => [Coeffs::IDENTITY; 4], + 1 => [d(HighPass, 70.0, 0.7, 0.0), d(Peaking, 400.0, 0.8, -2.0), d(Peaking, 2500.0, 1.0, 3.0), d(LowPass, 6000.0, 0.8, 0.0)], + 2 => [d(HighPass, 90.0, 0.7, 0.0), d(Peaking, 800.0, 0.7, 4.0), d(Peaking, 3000.0, 1.2, 2.0), d(LowPass, 4500.0, 0.9, 0.0)], + 3 => [d(HighPass, 60.0, 0.7, 0.0), d(LowShelf, 200.0, 0.7, 3.0), d(Peaking, 1200.0, 0.8, 2.0), d(LowPass, 4000.0, 0.7, 0.0)], + _ => [d(HighPass, 100.0, 0.8, 0.0), d(Peaking, 500.0, 1.0, -5.0), d(Peaking, 2000.0, 0.8, 5.0), d(LowPass, 5000.0, 1.0, 0.0)], + }; + let q = 0.5 + 7.5 * self.pv.v("filter_res") / 100.0; + let f = self.pv.v("filter_freq") as f64; + self.filt = match self.pv.idx("filter") { + 1 => d(LowPass, f, q as f64, 0.0), + 2 => d(HighPass, f, q as f64, 0.0), + 3 => d(BandPass, f, q as f64, 0.0), + _ => Coeffs::IDENTITY, + }; + self.mix.set(self.pv.v("mix") / 100.0); + self.out.set(db_to_gain(self.pv.v("output"))); + self.drive.set(db_to_gain(36.0 * self.pv.v("distortion") / 100.0)); + if snap { + self.mix.snap(); + self.out.snap(); + self.drive.snap(); + } + } +} + +impl AudioEffect for GuitarSuite { + param_plumbing!("guitar_suite"); + fn reset(&mut self) { + self.env = 0.0; + self.st.iter_mut().for_each(|s| s.iter_mut().for_each(Biquad::reset)); + self.dc.iter_mut().for_each(DcBlock::reset); + self.mix.snap(); + self.out.snap(); + self.drive.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.st.len()); + let comp = self.pv.v("compressor") / 100.0; + let (thr, ratio) = (-6.0 - 30.0 * comp, 1.0 + 7.0 * comp); + let (att, rel) = (coef(5.0, self.sr), coef(120.0, self.sr)); + let kind = match self.pv.idx("dist_type") { + 0 => 0, + 1 => 1, + _ => 2, + }; + let r = DcBlock::r(self.sr); + for i in 0..n { + let (mix, out, drive) = (self.mix.tick(), self.out.tick(), self.drive.tick()); + let peak = channels[..nch].iter().fold(0.0f32, |a, c| a.max(c[i].abs())); + let l = lin_db(peak); + let target = if comp > 0.0 && l > thr { (thr + (l - thr) / ratio) - l } else { 0.0 }; + let c = if target < self.env { att } else { rel }; + self.env = c * self.env + (1.0 - c) * target; + if !(1e-7..=f32::MAX).contains(&self.env.abs()) { + self.env = 0.0; + } + let g = db_to_gain(self.env); + // Distortion level compensation keeps the output near the input level. + let comp_out = 1.0 / drive.sqrt(); + for ch in 0..nch { + let x = channels[ch][i]; + let v = x * g * drive; + let mut y = match kind { + 0 => v.tanh(), + 1 => v.clamp(-1.0, 1.0), + _ => (v + 0.3).tanh() - 0.3f32.tanh() + 0.5 * (2.0 * v).tanh(), + } * comp_out; + y = self.dc[ch].tick(r, y); + let st = &mut self.st[ch]; + let mut yd = y as f64; + for (k, c) in self.cab.iter().enumerate() { + yd = st[k].tick(c, yd); + } + yd = st[4].tick(&self.filt, yd); + channels[ch][i] = x + mix * (yd as f32 * out - x); + } + } + } +} + +// --------------------------------------------------------------------------------- mastering + +pub const EXCITER_MODES: &[&str] = &["Retro", "Tape", "Tube"]; + +/// Mastering chain: three-band EQ → reverb → exciter → widener → loudness maximiser → output. +/// At its defaults it is transparent. +pub struct Mastering { + pv: ParamValues, + sr: f32, + eq: [Coeffs; 3], + st: Vec<[Biquad; 3]>, + rev: Reverb, + scratch: [[f32; CHUNK]; 2], + hp: Vec, + lim_env: f32, + rev_amt: Smoothed, + exc: Smoothed, + width: Smoothed, + boost: Smoothed, + out: Smoothed, +} + +impl Mastering { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("eq_low", "Low Shelf Gain", -12.0, 12.0, 0.0, Unit::Decibels), + ParamSpec::log("eq_mid_freq", "Peak Frequency", 100.0, 10000.0, 1000.0, Unit::Hertz), + ParamSpec::new("eq_mid", "Peak Gain", -12.0, 12.0, 0.0, Unit::Decibels), + ParamSpec::new("eq_high", "High Shelf Gain", -12.0, 12.0, 0.0, Unit::Decibels), + ParamSpec::new("reverb", "Reverb Amount", 0.0, 100.0, 0.0, Unit::Percent), + ParamSpec::new("exciter", "Exciter Amount", 0.0, 100.0, 0.0, Unit::Percent), + ParamSpec::choice("exciter_mode", "Exciter Mode", EXCITER_MODES, 1), + ParamSpec::new("widener", "Widener", 0.0, 200.0, 100.0, Unit::Percent), + ParamSpec::new("loudness", "Loudness Maximizer", 0.0, 100.0, 0.0, Unit::Percent), + ParamSpec::new("output", "Output Gain", -24.0, 12.0, 0.0, Unit::Decibels), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let ch = crate::sane_channels(channels); + let mut rev = Reverb::new(sample_rate, 2); + rev.set_param("mix", 100.0); + rev.set_param("decay", 1.4); + rev.set_param("size", 40.0); + rev.reset(); + let mut s = Mastering { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + eq: [Coeffs::IDENTITY; 3], + st: vec![[Biquad::new(); 3]; ch], + rev, + scratch: [[0.0; CHUNK]; 2], + hp: vec![OnePole::default(); ch], + lim_env: 0.0, + rev_amt: sm(0.0, sample_rate), + exc: sm(0.0, sample_rate), + width: sm(1.0, sample_rate), + boost: sm(1.0, sample_rate), + out: sm(1.0, sample_rate), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let sr = self.sr as f64; + let q = std::f64::consts::FRAC_1_SQRT_2; + self.eq = [ + Coeffs::design(FilterType::LowShelf, sr, 100.0, q, self.pv.v("eq_low") as f64), + Coeffs::design(FilterType::Peaking, sr, self.pv.v("eq_mid_freq") as f64, 1.0, self.pv.v("eq_mid") as f64), + Coeffs::design(FilterType::HighShelf, sr, 8000.0, q, self.pv.v("eq_high") as f64), + ]; + self.rev_amt.set(0.4 * self.pv.v("reverb") / 100.0); + self.exc.set(0.6 * self.pv.v("exciter") / 100.0); + self.width.set(self.pv.v("widener") / 100.0); + self.boost.set(db_to_gain(12.0 * self.pv.v("loudness") / 100.0)); + self.out.set(db_to_gain(self.pv.v("output"))); + if snap { + for s in [&mut self.rev_amt, &mut self.exc, &mut self.width, &mut self.boost, &mut self.out] { + s.snap(); + } + } + } +} + +impl AudioEffect for Mastering { + param_plumbing!("mastering"); + fn response_db(&self, freq: f64) -> Option { + Some(self.eq.iter().map(|c| c.magnitude_db(freq, self.sr as f64)).sum::() + self.pv.v("output") as f64) + } + fn reset(&mut self) { + self.st.iter_mut().for_each(|s| s.iter_mut().for_each(Biquad::reset)); + self.rev.reset(); + self.hp.iter_mut().for_each(OnePole::reset); + self.lim_env = 0.0; + for s in [&mut self.rev_amt, &mut self.exc, &mut self.width, &mut self.boost, &mut self.out] { + s.snap(); + } + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.st.len()); + if nch == 0 { + return; + } + let loud = self.pv.v("loudness") > 0.0; + let use_rev = self.pv.v("reverb") > 0.0; + let mode = self.pv.idx("exciter_mode"); + let ahp = OnePole::alpha(3000.0, self.sr); + let ceiling = db_to_gain(-0.3); + let rel = coef(60.0, self.sr); + let mut start = 0; + while start < n { + let len = (n - start).min(CHUNK); + // EQ in place. + for ch in 0..nch { + for v in channels[ch][start..start + len].iter_mut() { + let mut y = *v as f64; + for (k, c) in self.eq.iter().enumerate() { + y = self.st[ch][k].tick(c, y); + } + *v = y as f32; + } + } + if use_rev { + for i in 0..len { + self.scratch[0][i] = channels[0][start + i]; + self.scratch[1][i] = channels[nch.min(2) - 1][start + i]; + } + let [a, b] = &mut self.scratch; + self.rev.process(&mut [&mut a[..len], &mut b[..len]]); + } + for i in 0..len { + let (ra, ex, w, boost, out) = (self.rev_amt.tick(), self.exc.tick(), self.width.tick(), self.boost.tick(), self.out.tick()); + let mut y = [0.0f32; 2]; + for ch in 0..nch.min(2) { + let mut v = channels[ch][start + i]; + if use_rev { + v += ra * self.scratch[ch][i]; + } + if ex > 0.0 { + let h = self.hp[ch].hp(ahp, v); + let s = match mode { + 0 => (3.0 * h).clamp(-1.0, 1.0) / 3.0, + 1 => (3.0 * h).tanh() / 3.0, + _ => ((3.0 * h + 0.2).tanh() - 0.2f32.tanh()) / 3.0, + }; + v += ex * (s - h * 0.5) * 2.0; + } + y[ch] = v; + } + if nch >= 2 { + let (m, s) = (0.5 * (y[0] + y[1]), 0.5 * (y[0] - y[1]) * w); + y = [m + s, m - s]; + } + if loud { + for v in y.iter_mut().take(nch.min(2)) { + *v *= boost; + } + let peak = y[..nch.min(2)].iter().fold(0.0f32, |a, v| a.max(v.abs())); + let target = (lin_db(ceiling) - lin_db(peak)).min(0.0); + if target < self.lim_env { + // An inf input sample gives -inf, which the release would never leave. + self.lim_env = if target.is_finite() { target } else { 0.0 }; + } else { + self.lim_env = rel * self.lim_env + (1.0 - rel) * target; + } + let g = db_to_gain(self.lim_env); + for v in y.iter_mut().take(nch.min(2)) { + *v = soft_clip(*v * g, ceiling); + } + } + for ch in 0..nch.min(2) { + channels[ch][start + i] = y[ch] * out; + } + } + start += len; + } + } +} + +// ---------------------------------------------------------------------------- vocal enhancer + +pub const VOCAL_MODES: &[&str] = &["Male", "Female", "Music"]; + +/// Fixed voicings: Male / Female (rumble cut, de-mud, presence and air, gentle 2:1 +/// compression) or Music (carves the vocal presence range so a voice sits on top). +pub struct VocalEnhancer { + pv: ParamValues, + sr: f32, + eq: [Coeffs; 4], + st: Vec<[Biquad; 4]>, + env: f32, +} + +impl VocalEnhancer { + pub const PARAMS: &'static [ParamSpec] = &[ParamSpec::choice("mode", "Mode", VOCAL_MODES, 0)]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = VocalEnhancer { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + eq: [Coeffs::IDENTITY; 4], + st: vec![[Biquad::new(); 4]; crate::sane_channels(channels)], + env: 0.0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, _snap: bool) { + let sr = self.sr as f64; + let d = |k, f, q, g| Coeffs::design(k, sr, f, q, g); + use FilterType::*; + self.eq = match self.pv.idx("mode") { + 0 => [d(HighPass, 80.0, 0.707, 0.0), d(Peaking, 250.0, 1.0, -3.0), d(Peaking, 3000.0, 1.0, 3.0), d(HighShelf, 10000.0, 0.707, 1.5)], + 1 => [d(HighPass, 120.0, 0.707, 0.0), d(Peaking, 400.0, 1.0, -2.0), d(Peaking, 5000.0, 1.0, 3.0), d(HighShelf, 10000.0, 0.707, 2.0)], + _ => [d(HighPass, 40.0, 0.707, 0.0), d(Peaking, 1500.0, 0.7, -4.0), d(Peaking, 3500.0, 1.0, -2.0), Coeffs::IDENTITY], + }; + } +} + +impl AudioEffect for VocalEnhancer { + param_plumbing!("vocal_enhancer"); + fn response_db(&self, freq: f64) -> Option { + Some(self.eq.iter().map(|c| c.magnitude_db(freq, self.sr as f64)).sum()) + } + fn reset(&mut self) { + self.st.iter_mut().for_each(|s| s.iter_mut().for_each(Biquad::reset)); + self.env = 0.0; + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.st.len()); + let voice = self.pv.idx("mode") < 2; + let (att, rel) = (coef(5.0, self.sr), coef(150.0, self.sr)); + for i in 0..n { + for ch in 0..nch { + let mut y = channels[ch][i] as f64; + for (k, c) in self.eq.iter().enumerate() { + y = self.st[ch][k].tick(c, y); + } + channels[ch][i] = y as f32; + } + if voice { + let peak = channels[..nch].iter().fold(0.0f32, |a, c| a.max(c[i].abs())); + let l = lin_db(peak); + let target = if l > -18.0 { (-18.0 + (l + 18.0) / 2.0) - l } else { 0.0 }; + let c = if target < self.env { att } else { rel }; + self.env = c * self.env + (1.0 - c) * target; + if !(1e-7..=f32::MAX).contains(&self.env.abs()) { + self.env = 0.0; + } + let g = db_to_gain(self.env); + for ch in channels[..nch].iter_mut() { + ch[i] *= g; + } + } + } + } +} + +// --------------------------------------------------------------------------- stereo expander + +/// Mid/side: the side signal is scaled by Stereo Expand and the center (mid) signal is panned. +pub struct StereoExpander { + pv: ParamValues, + gl: Smoothed, + gr: Smoothed, + side: Smoothed, +} + +impl StereoExpander { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("center_pan", "Center Channel Pan", -100.0, 100.0, 0.0, Unit::Pan), + ParamSpec::new("expand", "Stereo Expand", 0.0, 300.0, 100.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = + StereoExpander { pv: ParamValues::new(Self::PARAMS), gl: sm(1.0, sample_rate), gr: sm(1.0, sample_rate), side: sm(1.0, sample_rate) }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let p = self.pv.v("center_pan") / 100.0; + self.gl.set((1.0 - p).min(1.0)); + self.gr.set((1.0 + p).min(1.0)); + self.side.set(self.pv.v("expand") / 100.0); + if snap { + for s in [&mut self.gl, &mut self.gr, &mut self.side] { + s.snap(); + } + } + } +} + +impl AudioEffect for StereoExpander { + param_plumbing!("stereo_expander"); + fn reset(&mut self) { + for s in [&mut self.gl, &mut self.gr, &mut self.side] { + s.snap(); + } + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + if channels.len() < 2 { + return; + } + let (a, b) = channels.split_at_mut(1); + let (l, r) = (&mut a[0], &mut b[0]); + for i in 0..n { + let (gl, gr, w) = (self.gl.tick(), self.gr.tick(), self.side.tick()); + let (m, s) = (0.5 * (l[i] + r[i]), 0.5 * (l[i] - r[i]) * w); + l[i] = m * gl + s; + r[i] = m * gr - s; + } + } +} + +// ------------------------------------------------------------------------------ binauralizer + +const SPEED_OF_SOUND: f32 = 343.0; + +/// Head-shadow filter (one-pole/one-zero spherical-head model, Brown & Duda 1998): +/// H(s) = (1 + α s / 2ω₀) / (1 + s / 2ω₀), ω₀ = c / a, α from the angle of incidence. +#[derive(Clone, Copy, Debug, Default)] +struct Shadow { + b0: f32, + b1: f32, + a1: f32, + x1: f32, + y1: f32, +} + +impl Shadow { + fn design(incidence_deg: f32, radius: f32, sr: f32) -> Shadow { + let alpha = 1.05 + 0.95 * (incidence_deg / 150.0 * PI).cos(); + let w0 = SPEED_OF_SOUND / radius; + let k = 2.0 * sr; + let t = k / (2.0 * w0); + let a0 = 1.0 + t; + Shadow { b0: (1.0 + alpha * t) / a0, b1: (1.0 - alpha * t) / a0, a1: (1.0 - t) / a0, x1: 0.0, y1: 0.0 } + } + #[inline] + fn tick(&mut self, x: f32) -> f32 { + let y = self.b0 * x + self.b1 * self.x1 - self.a1 * self.y1; + self.x1 = x; + self.y1 = flush32(y); + y + } + fn set_coeffs(&mut self, o: &Shadow) { + self.b0 = o.b0; + self.b1 = o.b1; + self.a1 = o.a1; + } +} + +/// Renders the stereo input as two virtual loudspeakers at ±`angle` heard through a spherical +/// head model (Woodworth interaural time difference + head-shadow filtering), for headphones. +pub struct Binauralizer { + pv: ParamValues, + sr: f32, + lines: [DelayLine; 2], + /// near-L, far-L→R, near-R, far-R→L + sh: [Shadow; 4], + itd: Smoothed, + mix: Smoothed, +} + +impl Binauralizer { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("angle", "Speaker Angle", 0.0, 90.0, 30.0, Unit::None), + ParamSpec::new("head_size", "Head Size", 12.0, 24.0, 17.5, Unit::None), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 100.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let max = (0.002 * sample_rate) as usize + 4; + let mut s = Binauralizer { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + lines: [DelayLine::new(max), DelayLine::new(max)], + sh: [Shadow::default(); 4], + itd: sm(0.0, sample_rate), + mix: sm(1.0, sample_rate), + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let theta = self.pv.v("angle"); + let a = self.pv.v("head_size") * 0.01 / 2.0; + // Ears at ±90°: near ear sees the source at 90° − θ off its axis, the far ear 90° + θ. + let near = Shadow::design(90.0 - theta, a, self.sr); + let far = Shadow::design(90.0 + theta, a, self.sr); + for (k, s) in self.sh.iter_mut().enumerate() { + s.set_coeffs(if k % 2 == 0 { &near } else { &far }); + } + let th = theta.to_radians(); + self.itd.set(a / SPEED_OF_SOUND * (th + th.sin()) * self.sr); + self.mix.set(self.pv.v("mix") / 100.0); + if snap { + self.itd.snap(); + self.mix.snap(); + } + } +} + +impl AudioEffect for Binauralizer { + param_plumbing!("binauralizer"); + fn reset(&mut self) { + self.lines.iter_mut().for_each(DelayLine::reset); + for s in &mut self.sh { + s.x1 = 0.0; + s.y1 = 0.0; + } + self.itd.snap(); + self.mix.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + if channels.len() < 2 { + return; + } + let (a, b) = channels.split_at_mut(1); + let (l, r) = (&mut a[0], &mut b[0]); + for i in 0..n { + let (itd, mix) = (self.itd.tick(), self.mix.tick()); + let (xl, xr) = (l[i], r[i]); + self.lines[0].push(xl); + self.lines[1].push(xr); + let near_l = self.sh[0].tick(xl); + let far_l = self.sh[1].tick(self.lines[0].read(itd)); + let near_r = self.sh[2].tick(xr); + let far_r = self.sh[3].tick(self.lines[1].read(itd)); + let (bl, br) = (0.5 * (near_l + far_r), 0.5 * (near_r + far_l)); + l[i] = xl + mix * (bl - xl); + r[i] = xr + mix * (br - xr); + } + } +} + +// ------------------------------------------------------------------------- ambisonics panner + +/// Rotates the sound field (pan / tilt / roll) of a stereo source pair placed at ±30° and +/// re-renders it to stereo with constant-power panning; sources turned behind the listener +/// are attenuated, raised/lowered sources slightly softened. Identity at 0/0/0. +pub struct AmbisonicsPanner { + pv: ParamValues, + /// out L ← in L, out L ← in R, out R ← in L, out R ← in R + m: [Smoothed; 4], +} + +impl AmbisonicsPanner { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("pan", "Pan", -180.0, 180.0, 0.0, Unit::None), + ParamSpec::new("tilt", "Tilt", -90.0, 90.0, 0.0, Unit::None), + ParamSpec::new("roll", "Roll", -180.0, 180.0, 0.0, Unit::None), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = AmbisonicsPanner { + pv: ParamValues::new(Self::PARAMS), + m: [sm(1.0, sample_rate), sm(0.0, sample_rate), sm(0.0, sample_rate), sm(1.0, sample_rate)], + }; + s.apply_params(true); + s + } + + /// (left gain, right gain) for a source at azimuth `az` (degrees, + = left) after rotation. + pub fn source_gains(az: f32, pan: f32, tilt: f32, roll: f32) -> (f32, f32) { + let (az, el) = (az.to_radians(), 0.0f32); + // x forward, y left, z up + let mut v = [el.cos() * az.cos(), el.cos() * az.sin(), el.sin()]; + let rot = |v: [f32; 3], axis: usize, ang: f32| -> [f32; 3] { + let (s, c) = ang.to_radians().sin_cos(); + let [x, y, z] = v; + match axis { + 0 => [x, c * y - s * z, s * y + c * z], + 1 => [c * x + s * z, y, -s * x + c * z], + _ => [c * x - s * y, s * x + c * y, z], + } + }; + v = rot(v, 0, roll); + v = rot(v, 1, tilt); + v = rot(v, 2, pan); + let p = (v[1] / 30f32.to_radians().sin()).clamp(-1.0, 1.0); + // constant power: p = 1 → all left, −1 → all right + let a = (1.0 - p) * 0.5 * FRAC_PI_2; + let (mut gl, mut gr) = (a.cos(), a.sin()); + let att = (1.0 - 0.3 * (-v[0]).max(0.0)) * (1.0 - 0.2 * v[2].abs()); + gl *= att; + gr *= att; + (gl, gr) + } + + fn apply_params(&mut self, snap: bool) { + let (pan, tilt, roll) = (self.pv.v("pan"), self.pv.v("tilt"), self.pv.v("roll")); + let (ll, rl) = Self::source_gains(30.0, pan, tilt, roll); + let (lr, rr) = Self::source_gains(-30.0, pan, tilt, roll); + let clean = |v: f32| { + if v.abs() < 1e-6 { + 0.0 + } else if (v - 1.0).abs() < 1e-6 { + 1.0 + } else { + v + } + }; + for (s, v) in self.m.iter_mut().zip([ll, lr, rl, rr]) { + s.set(clean(v)); + if snap { + s.snap(); + } + } + } +} + +impl AudioEffect for AmbisonicsPanner { + param_plumbing!("ambisonics_panner"); + fn reset(&mut self) { + self.m.iter_mut().for_each(Smoothed::snap); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + if channels.len() < 2 { + return; + } + let (a, b) = channels.split_at_mut(1); + let (l, r) = (&mut a[0], &mut b[0]); + for i in 0..n { + let g = [self.m[0].tick(), self.m[1].tick(), self.m[2].tick(), self.m[3].tick()]; + let (x, y) = (l[i], r[i]); + l[i] = g[0] * x + g[1] * y; + r[i] = g[2] * x + g[3] * y; + } + } +} + +// ------------------------------------------------------------------------------- loudness meter + +/// Pass-through effect that measures BS.1770 loudness (momentary, short-term, integrated, +/// range, true peak) of the signal at its insert point. +pub struct LoudnessMeterFx { + pv: ParamValues, + meter: LoudnessMeter, +} + +impl LoudnessMeterFx { + pub const PARAMS: &'static [ParamSpec] = &[ParamSpec::new("target", "Target Loudness", -36.0, -5.0, -23.0, Unit::None)]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + LoudnessMeterFx { pv: ParamValues::new(Self::PARAMS), meter: LoudnessMeter::new(sample_rate as f64, channels) } + } + fn apply_params(&mut self, _snap: bool) {} + + /// The running meter. + pub fn meter(&self) -> &LoudnessMeter { + &self.meter + } +} + +impl AudioEffect for LoudnessMeterFx { + param_plumbing!("loudness_meter"); + fn reset(&mut self) { + self.meter.reset(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = self.meter.channels().min(channels.len()); + if nch == 0 || n == 0 { + return; + } + // A fixed array of slices, so measuring does not allocate. + let mut io: [&[f32]; MAX_CHANNELS] = [&[]; MAX_CHANNELS]; + for (slot, ch) in io.iter_mut().zip(channels.iter()).take(nch) { + *slot = &ch[..n]; + } + self.meter.process(&io[..nch]); + } +} + +// ----------------------------------------------------------------------------------- mute + +/// Mute with a 5 ms ramp (keyframe it to silence passages without clicks). +pub struct Mute { + pv: ParamValues, + g: Smoothed, +} + +impl Mute { + pub const PARAMS: &'static [ParamSpec] = &[ParamSpec::toggle("mute", "Mute", false)]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let mut s = Mute { pv: ParamValues::new(Self::PARAMS), g: Smoothed::with_ms(1.0, sample_rate, 5.0) }; + s.apply_params(true); + s + } + fn apply_params(&mut self, snap: bool) { + self.g.set(if self.pv.on("mute") { 0.0 } else { 1.0 }); + if snap { + self.g.snap(); + } + } +} + +impl AudioEffect for Mute { + param_plumbing!("mute"); + fn reset(&mut self) { + self.g.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + for i in 0..n { + let g = self.g.tick(); + for ch in channels.iter_mut() { + ch[i] *= g; + } + } + } +} diff --git a/crates/audio-dsp/src/effects/stft.rs b/crates/audio-dsp/src/effects/stft.rs new file mode 100644 index 000000000..160362fc9 --- /dev/null +++ b/crates/audio-dsp/src/effects/stft.rs @@ -0,0 +1,564 @@ +//! Streaming STFT overlap-add framework shared by the spectral effects. + +use crate::fft::Fft; +use std::f64::consts::PI; + +/// Per-channel streaming buffers. Latency is exactly `n` samples. +#[derive(Clone, Debug)] +pub(crate) struct StftChannel { + input: Vec, + output: Vec, + pos: usize, +} + +impl StftChannel { + pub(crate) fn new(n: usize) -> Self { + StftChannel { input: vec![0.0; n], output: vec![0.0; n], pos: 0 } + } + pub(crate) fn reset(&mut self) { + self.input.iter_mut().for_each(|v| *v = 0.0); + self.output.iter_mut().for_each(|v| *v = 0.0); + self.pos = 0; + } + /// Push one sample and pop one output sample. Every `hop` samples `frame` is called with the + /// last `n` input samples and must write an `n`-sample (windowed) frame that is overlap-added. + #[inline] + pub(crate) fn tick(&mut self, x: f32, hop: usize, frame: &mut impl FnMut(&[f32], &mut [f32])) -> f32 { + let n = self.input.len(); + self.input[n - hop + self.pos] = x; + let y = self.output[self.pos]; + self.pos += 1; + if self.pos == hop { + self.pos = 0; + self.output.copy_within(hop.., 0); + self.output[n - hop..].iter_mut().for_each(|v| *v = 0.0); + frame(&self.input, &mut self.output); + self.input.copy_within(hop.., 0); + } + y + } + + /// `tick` for two channels that frame on the same samples: `frame` gets both inputs and both + /// outputs. + #[inline] + fn tick_pair( + a: &mut StftChannel, + b: &mut StftChannel, + x: (f32, f32), + hop: usize, + frame: &mut impl FnMut(&[f32], &[f32], &mut [f32], &mut [f32]), + ) -> (f32, f32) { + debug_assert_eq!(a.pos, b.pos); + let n = a.input.len(); + a.input[n - hop + a.pos] = x.0; + b.input[n - hop + a.pos] = x.1; + let y = (a.output[a.pos], b.output[a.pos]); + a.pos += 1; + b.pos = a.pos; + if a.pos == hop { + a.pos = 0; + b.pos = 0; + for c in [&mut *a, &mut *b] { + c.output.copy_within(hop.., 0); + c.output[n - hop..].iter_mut().for_each(|v| *v = 0.0); + } + frame(&a.input, &b.input, &mut a.output, &mut b.output); + a.input.copy_within(hop.., 0); + b.input.copy_within(hop.., 0); + } + y + } +} + +/// Hop, gain and FFT pairing shared by every frame of one STFT effect run. +#[derive(Clone, Copy)] +pub(crate) struct Plan { + pub hop: usize, + pub scale: f32, + pub pairing: Pairing, +} + +/// Stream `len` samples of every channel through its `StftChannel`, sample-major. At a frame +/// boundary `bins(ch, first, re, im)` edits that channel's half spectrum (bins 0..=n/2); +/// `first` is set for the first channel that frames on this sample. Neighbouring channels that +/// frame on the same samples share one complex FFT (`a + i·b`), except for frames with a +/// non-finite sample, which run per channel so the bad channel cannot contaminate its neighbor. +/// `pairing` says whether the forward FFT is shared too or only the inverse one. +pub(crate) fn stream( + stft: &mut [StftChannel], + spec: &mut Spectral, + channels: &mut [&mut [f32]], + len: usize, + plan: Plan, + bins: &mut impl FnMut(usize, bool, &mut [f32], &mut [f32]), +) { + let Plan { hop, scale, pairing } = plan; + let nch = channels.len().min(stft.len()); + let half = spec.re2.len(); + for i in 0..len { + let mut first = true; + let mut ch = 0; + while ch < nch { + if ch + 1 < nch && stft[ch].pos == stft[ch + 1].pos { + let (lo, hi) = stft.split_at_mut(ch + 1); + let x = (channels[ch][i], channels[ch + 1][i]); + let (ya, yb) = StftChannel::tick_pair(&mut lo[ch], &mut hi[0], x, hop, &mut |a, b, out_a, out_b| { + // Finite samples can still overflow the unscaled FFT: for `Full` the packed + // analysis itself is checked before either callback sees it. + let mut shared = all_finite(a) && all_finite(b); + if shared && pairing == Pairing::Full { + spec.analyze_pair(a, b); + shared = spec.pair_finite(half); + } + if shared { + match pairing { + Pairing::Full => { + bins(ch, first, &mut spec.re[..half], &mut spec.im[..half]); + bins(ch + 1, false, &mut spec.re2, &mut spec.im2); + } + Pairing::SynthesisOnly => { + // Each channel's spectrum is bit-identical to its mono analysis; + // the edited half spectra then share one inverse FFT. + spec.analyze(a); + bins(ch, first, &mut spec.re[..half], &mut spec.im[..half]); + spec.re2.copy_from_slice(&spec.re[..half]); + spec.im2.copy_from_slice(&spec.im[..half]); + spec.analyze(b); + bins(ch + 1, false, &mut spec.re[..half], &mut spec.im[..half]); + spec.re[..half].swap_with_slice(&mut spec.re2); + spec.im[..half].swap_with_slice(&mut spec.im2); + } + } + if spec.pair_finite(half) { + spec.synthesize_add_pair(out_a, out_b, scale); + } else { + // Poisoned per-channel state can leave one edited spectrum + // non-finite: synthesize separately so it cannot leak either. + spec.synthesize_add_split(out_a, out_b, scale); + } + } else { + // A non-finite sample (or a non-finite packed spectrum) would leak into + // the other channel: keep the channels isolated for this frame. Each + // callback still runs exactly once per channel. + spec.analyze(a); + bins(ch, first, &mut spec.re[..half], &mut spec.im[..half]); + spec.synthesize_add(out_a, scale); + spec.analyze(b); + bins(ch + 1, false, &mut spec.re[..half], &mut spec.im[..half]); + spec.synthesize_add(out_b, scale); + } + first = false; + }); + channels[ch][i] = ya; + channels[ch + 1][i] = yb; + ch += 2; + } else { + channels[ch][i] = stft[ch].tick(channels[ch][i], hop, &mut |input, out| { + spec.analyze(input); + bins(ch, first, &mut spec.re[..half], &mut spec.im[..half]); + spec.synthesize_add(out, scale); + first = false; + }); + ch += 1; + } + } + } +} + +/// How much of the STFT two paired channels share. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum Pairing { + /// Forward and inverse FFT (`a + i·b`). The analyzed spectra differ from the mono ones at + /// rounding level, so only for effects whose bin edit is continuous in the spectrum. + Full, + /// Only the inverse FFT. For effects whose bin edit makes discrete decisions on the spectrum + /// (peak picking, thresholds): a rounding-level change could flip one, so they get the exact + /// mono analysis. + SynthesisOnly, +} + +/// Branch-free scan (vectorizes, unlike a short-circuiting `all`). +#[inline] +fn all_finite(x: &[f32]) -> bool { + x.iter().fold(true, |ok, v| ok & v.is_finite()) +} + +/// Periodic Hann window. +pub(crate) fn hann(n: usize) -> Vec { + (0..n).map(|i| (0.5 - 0.5 * (2.0 * PI * i as f64 / n as f64).cos()) as f32).collect() +} + +/// FFT size for spectral effects at a sample rate (~43 ms at 48 kHz). +pub(crate) fn fft_size(sample_rate: f32) -> usize { + if sample_rate <= 50_000.0 { + 2048 + } else if sample_rate <= 100_000.0 { + 4096 + } else { + 8192 + } +} + +/// Shared spectral scratch. +#[derive(Clone, Debug)] +pub(crate) struct Spectral { + pub fft: Fft, + pub window: Vec, + pub re: Vec, + pub im: Vec, + /// Second channel's half spectrum (bins 0..=n/2) after `analyze_pair`. + pub re2: Vec, + pub im2: Vec, +} + +impl Spectral { + /// `sqrt_window`: use √Hann for analysis and synthesis (sums to a constant at 75 % overlap); + /// otherwise Hann for both. + pub(crate) fn new(n: usize, sqrt_window: bool) -> Self { + let mut window = hann(n); + if sqrt_window { + window.iter_mut().for_each(|w| *w = w.sqrt()); + } + Spectral { fft: Fft::new(n), window, re: vec![0.0; n], im: vec![0.0; n], re2: vec![0.0; n / 2 + 1], im2: vec![0.0; n / 2 + 1] } + } + /// Window `input` into re/im and run the forward FFT. + pub(crate) fn analyze(&mut self, input: &[f32]) { + for i in 0..input.len() { + self.re[i] = input[i] * self.window[i]; + self.im[i] = 0.0; + } + self.fft.forward(&mut self.re, &mut self.im); + } + /// Enforce Hermitian symmetry from bins 0..=n/2, inverse FFT, window, scale and add to `out`. + pub(crate) fn synthesize_add(&mut self, out: &mut [f32], scale: f32) { + let n = self.re.len(); + self.im[0] = 0.0; + self.im[n / 2] = 0.0; + for k in 1..n / 2 { + self.re[n - k] = self.re[k]; + self.im[n - k] = -self.im[k]; + } + self.fft.inverse(&mut self.re, &mut self.im); + for i in 0..n { + out[i] += self.re[i] * self.window[i] * scale; + } + } + /// Window `a` and `b` into one complex FFT (`a + i·b`), then split it: bins 0..=n/2 of + /// re/im hold the spectrum of `a`, re2/im2 that of `b`. + pub(crate) fn analyze_pair(&mut self, a: &[f32], b: &[f32]) { + let n = self.re.len(); + for i in 0..n { + self.re[i] = a[i] * self.window[i]; + self.im[i] = b[i] * self.window[i]; + } + self.fft.forward(&mut self.re, &mut self.im); + // A[k] = (Z[k] + conj Z[n−k]) / 2, B[k] = (Z[k] − conj Z[n−k]) / 2i. Bins above n/2 are + // only read, so the lower half can be overwritten in place. + for k in 0..=n / 2 { + let m = (n - k) % n; + let (zr, zi, wr, wi) = (self.re[k], self.im[k], self.re[m], self.im[m]); + self.re[k] = 0.5 * (zr + wr); + self.im[k] = 0.5 * (zi - wi); + self.re2[k] = 0.5 * (zi + wi); + self.im2[k] = 0.5 * (wr - zr); + } + } + /// Whether both half spectra of `analyze_pair` (bins 0..half) are finite and small enough that + /// the shared unscaled FFT cannot overflow. Every FFT value sums at most 4 * half unit-twiddle + /// terms (two mirrored bins, two channels), so for FFT sizes up to 16384 a per-bin limit of + /// `f32::MAX / 65536` is safe. NaN fails the comparison. Branch-free so it vectorizes. + pub(crate) fn pair_finite(&self, half: usize) -> bool { + const LIMIT: f32 = f32::MAX / 65536.0; + [&self.re[..half], &self.im[..half], &self.re2[..half], &self.im2[..half]] + .iter() + .all(|s| s.iter().fold(true, |ok, v| ok & (v.abs() <= LIMIT))) + } + /// `synthesize_add_pair` without sharing the inverse FFT: the two spectra stay isolated. + pub(crate) fn synthesize_add_split(&mut self, out_a: &mut [f32], out_b: &mut [f32], scale: f32) { + self.synthesize_add(out_a, scale); + let half = self.re2.len(); + self.re[..half].copy_from_slice(&self.re2); + self.im[..half].copy_from_slice(&self.im2); + self.synthesize_add(out_b, scale); + } + /// `synthesize_add` for both spectra of `analyze_pair`: one inverse FFT of + /// Z = Y_a + i·Y_b, whose real part goes to `out_a` and imaginary part to `out_b`. + pub(crate) fn synthesize_add_pair(&mut self, out_a: &mut [f32], out_b: &mut [f32], scale: f32) { + let n = self.re.len(); + let h = n / 2; + self.im[0] = 0.0; + self.im[h] = 0.0; + self.im2[0] = 0.0; + self.im2[h] = 0.0; + for k in 1..h { + // Z[n−k] = conj A[k] + i·conj B[k] + self.re[n - k] = self.re[k] + self.im2[k]; + self.im[n - k] = self.re2[k] - self.im[k]; + } + for k in 0..=h { + self.re[k] -= self.im2[k]; + self.im[k] += self.re2[k]; + } + self.fft.inverse(&mut self.re, &mut self.im); + for i in 0..n { + out_a[i] += self.re[i] * self.window[i] * scale; + out_b[i] += self.im[i] * self.window[i] * scale; + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::Rng; + + /// Finite samples near `f32::MAX` overflow the unscaled FFT, forward or inverse. The packed + /// analysis is checked before any callback sees it (and the spectra again before the shared + /// inverse), so the clean partner stays as it is mono and every channel's callback still runs + /// once per frame. + #[test] + fn finite_overflow_in_one_channel_stays_in_its_channel() { + let (n, len) = (1024, 4096); + let hop = n / 4; + let scale = 1.0 / (n as f32 * 2.0); + let run = |src: &[Vec]| -> (Vec>, Vec) { + let mut stft = vec![StftChannel::new(n); src.len()]; + let mut spec = Spectral::new(n, true); + let mut y = src.to_vec(); + let mut calls = vec![0usize; src.len()]; + let mut firsts = 0; + { + let mut chans: Vec<&mut [f32]> = y.iter_mut().map(|c| c.as_mut_slice()).collect(); + stream(&mut stft, &mut spec, &mut chans, len, Plan { hop, scale, pairing: Pairing::Full }, &mut |ch, first, _, _| { + calls[ch] += 1; + firsts += usize::from(first); + }); + } + assert_eq!(firsts, calls[0], "`first` must fire once per frame"); + (y, calls) + }; + let mut bad = vec![0.0f32; len]; + bad[1000..1008].iter_mut().for_each(|v| *v = f32::MAX / 4.0); + let clean = vec![0.0f32; len]; + let mut mono_calls = 0; + for bad_left in [true, false] { + let src = if bad_left { vec![bad.clone(), clean.clone()] } else { vec![clean.clone(), bad.clone()] }; + let (y, calls) = run(&src); + let good = &y[usize::from(bad_left)]; + assert!( + good.iter().all(|v| v.is_finite()), + "bad_left={bad_left}: clean channel has non-finite samples at {:?}", + good.iter().position(|v| !v.is_finite()) + ); + let (want, mono) = run(std::slice::from_ref(&clean)); + mono_calls = mono[0]; + assert!(good.iter().zip(&want[0]).all(|(p, q)| p.to_bits() == q.to_bits())); + assert_eq!(calls, vec![mono_calls; 2]); + } + assert!(mono_calls > 0); + } + + #[test] + fn paired_channels_match_separate_ones_to_rounding() { + let (n, len) = (1024, 20000); + let hop = n / 4; + let mut rng = Rng::new(11); + let src: Vec> = (0..3).map(|_| (0..len).map(|_| rng.uniform()).collect()).collect(); + let mut gain = |ch: usize, _: bool, re: &mut [f32], im: &mut [f32]| { + for k in 0..re.len() { + let g = 1.0 / (1.0 + (k * (ch + 1)) as f32 / 64.0); + re[k] *= g; + im[k] *= g; + } + }; + let scale = 1.0 / (n as f32 * 2.0); + // Three channels: 0 and 1 share an FFT, 2 runs alone. + let mut stft = vec![StftChannel::new(n); 3]; + let mut spec = Spectral::new(n, true); + let mut joint = src.clone(); + { + let mut chans: Vec<&mut [f32]> = joint.iter_mut().map(|c| c.as_mut_slice()).collect(); + stream(&mut stft, &mut spec, &mut chans, len, Plan { hop, scale, pairing: Pairing::Full }, &mut gain); + } + for ch in 0..3 { + let mut single = vec![StftChannel::new(n)]; + let mut y = src[ch].clone(); + stream(&mut single, &mut spec, &mut [&mut y], len, Plan { hop, scale, pairing: Pairing::Full }, &mut |_, first, re, im| { + gain(ch, first, re, im) + }); + let peak = y.iter().fold(0.0f32, |a, v| a.max(v.abs())); + let dev = y.iter().zip(&joint[ch]).fold(0.0f32, |a, (p, q)| a.max((p - q).abs())); + assert!(peak > 0.1 && dev < 1e-5 * peak, "channel {ch}: deviation {dev}"); + if ch == 2 { + assert!(y.iter().zip(&joint[ch]).all(|(p, q)| p.to_bits() == q.to_bits())); + } + } + } + + /// Every STFT effect gives each channel of a paired (shared complex FFT) run the output it + /// would have as a mono signal, to rounding, on finite tone + transient material. Covers + /// identical channels (the pitch-shifter repro: three channels, +3 semitones, 256-sample + /// blocks) and channels with different content and level. + #[test] + fn paired_effects_match_mono_on_transients() { + use crate::AudioEffect; + use crate::effects::{DeNoise, DeReverb, FftFilter, PitchShifter}; + const SR: f32 = 48_000.0; + let len = 48_000; + let material = |f: f64, amp: f32, phase: f64, click_every: usize, click_at: usize, noise: f32, seed: u64| -> Vec { + let mut rng = Rng::new(seed); + let mut x: Vec = crate::testutil::sine(f, amp as f64, SR as f64, len, phase).iter().map(|v| v + noise * rng.uniform()).collect(); + for (i, v) in x.iter_mut().enumerate() { + if i % click_every == click_at { + *v += 0.8 * amp / 0.3; + } + } + x + }; + let tone = material(440.0, 0.3, 0.0, 6000, 1500, 0.0, 1); + let identical = vec![tone.clone(), tone.clone(), tone]; + let different = vec![ + material(440.0, 0.3, 0.0, 6000, 1500, 0.0, 1), + material(1250.0, 0.05, 0.7, 4410, 333, 0.01, 2), + material(97.0, 0.2, 1.3, 9000, 7000, 0.0, 3), + ]; + let make = |name: &str, ch: usize| -> Box { + let mut fx: Box = match name { + "DeReverb" => Box::new(DeReverb::new(SR, ch)), + "FftFilter" => Box::new(FftFilter::new(SR, ch)), + "DeNoise" => Box::new(DeNoise::new(SR, ch)), + _ => Box::new(PitchShifter::new(SR, ch)), + }; + if name == "PitchShifter" { + fx.set_param("semitones", 3.0); + } + fx + }; + let run = |name: &str, src: &[Vec]| -> Vec> { + let mut fx = make(name, src.len()); + let mut y = src.to_vec(); + for start in (0..len).step_by(256) { + let end = (start + 256).min(len); + let mut blk: Vec<&mut [f32]> = y.iter_mut().map(|c| &mut c[start..end]).collect(); + fx.process(&mut blk); + } + y + }; + let mut failures = Vec::new(); + for name in ["PitchShifter", "DeNoise", "DeReverb", "FftFilter"] { + for (label, src) in [("identical", &identical), ("different", &different)] { + let joint = run(name, src); + for (ch, chan) in src.iter().enumerate() { + let want = run(name, std::slice::from_ref(chan)).remove(0); + let peak = want.iter().fold(0.0f32, |a, v| a.max(v.abs())); + let dev = want.iter().zip(&joint[ch]).fold(0.0f32, |a, (p, q)| a.max((p - q).abs())); + assert!(joint[ch].iter().all(|v| v.is_finite()) && peak > 0.01, "{name} {label} ch{ch}: peak {peak}"); + if dev > 1e-5 * peak { + failures.push(format!("{name} {label} ch{ch}: max diff {dev} at peak {peak}")); + } + } + } + } + assert!(failures.is_empty(), "{failures:#?}"); + } + + /// DeNoise's noise gate is a hard threshold on the smoothed PSD: on stationary noise many bins + /// sit near it. With a shared forward FFT a rounding-level change flipped some, and the output + /// moved by up to ~4e-4 of the peak here. Paired channels must match mono to rounding. + #[test] + fn paired_denoise_matches_mono_near_its_threshold() { + use crate::AudioEffect; + use crate::effects::DeNoise; + const SR: f32 = 48_000.0; + let len = 512 * 940; + let mut rng = Rng::new(9); + let a: Vec = (0..len).map(|_| 0.1 * rng.uniform()).collect(); + let t = crate::testutil::sine(700.0, 0.2, SR as f64, len, 0.0); + let b: Vec = (0..len).map(|i| t[i] + 0.03 * rng.uniform()).collect(); + for (thr, red) in [(0.5, 20.0), (2.0, 30.0)] { + let run = |src: &[&Vec]| -> Vec> { + let mut fx = DeNoise::new(SR, src.len()); + fx.set_param("threshold", thr); + fx.set_param("reduction", red); + let mut y: Vec> = src.iter().map(|c| c.to_vec()).collect(); + for s in (0..len).step_by(512) { + let mut blk: Vec<&mut [f32]> = y.iter_mut().map(|c| &mut c[s..s + 512]).collect(); + fx.process(&mut blk); + } + y + }; + let joint = run(&[&a, &b]); + for (ch, c) in [&a, &b].into_iter().enumerate() { + let want = run(&[c]).remove(0); + let peak = want.iter().fold(0.0f32, |m, v| m.max(v.abs())); + let dev = want.iter().zip(&joint[ch]).fold(0.0f32, |m, (p, q)| m.max((p - q).abs())); + assert!(peak > 0.05 && dev <= 1e-5 * peak, "threshold {thr} ch{ch}: deviation {dev} (peak {peak})"); + } + } + } + + /// A non-finite sample in one channel must not reach its partner through the packed FFT: the + /// clean channel stays finite and equals what it would be as a mono signal. + #[test] + fn non_finite_sample_stays_in_its_channel() { + use crate::AudioEffect; + use crate::effects::{DeNoise, DeReverb, FftFilter, PitchShifter}; + const SR: f32 = 48_000.0; + let len = 24_000; + let mut rng = Rng::new(5); + let clean_a: Vec = crate::testutil::sine(440.0, 0.4, SR as f64, len, 0.0).iter().map(|v| v + 0.05 * rng.uniform()).collect(); + let clean_b: Vec = crate::testutil::sine(1250.0, 0.4, SR as f64, len, 0.3).iter().map(|v| v + 0.05 * rng.uniform()).collect(); + type Make = fn() -> Box; + let make: [(&str, Make, usize); 4] = [ + ("DeReverb", || Box::new(DeReverb::new(SR, 2)), 1), + ("FftFilter", || Box::new(FftFilter::new(SR, 2)), 1), + ("DeNoise", || Box::new(DeNoise::new(SR, 2)), 1), + ("PitchShifter", || Box::new(PitchShifter::new(SR, 2)), 1), + ]; + let mono = |name: &str, src: &[f32]| -> Vec { + let mut fx: Box = match name { + "DeReverb" => Box::new(DeReverb::new(SR, 1)), + "FftFilter" => Box::new(FftFilter::new(SR, 1)), + "DeNoise" => Box::new(DeNoise::new(SR, 1)), + _ => Box::new(PitchShifter::new(SR, 1)), + }; + if name == "PitchShifter" { + fx.set_param("semitones", 3.0); + } + let mut y = src.to_vec(); + for blk in y.chunks_mut(512) { + fx.process(&mut [blk]); + } + y + }; + for (name, ctor, _) in make { + for bad_left in [true, false] { + let (mut l, mut r) = (clean_a.clone(), clean_b.clone()); + for (k, bad) in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY].into_iter().enumerate() { + if bad_left { + l[4000 + 977 * k] = bad; + } else { + r[4000 + 977 * k] = bad; + } + } + let mut fx = ctor(); + if name == "PitchShifter" { + fx.set_param("semitones", 3.0); + } + for (bl, br) in l.chunks_mut(512).zip(r.chunks_mut(512)) { + fx.process(&mut [bl, br]); + } + let (good, src) = if bad_left { (&r, &clean_b) } else { (&l, &clean_a) }; + let want = mono(name, src); + let peak = want.iter().fold(0.0f32, |a, v| a.max(v.abs())); + assert!( + good.iter().all(|v| v.is_finite()), + "{name} bad_left={bad_left}: clean channel not finite at {:?}", + good.iter().position(|v| !v.is_finite()) + ); + let dev = good.iter().zip(&want).fold(0.0f32, |a, (p, q)| a.max((p - q).abs())); + assert!(peak > 0.05 && dev < 1e-5 * peak, "{name} bad_left={bad_left}: deviation {dev} (peak {peak})"); + } + } + } +} diff --git a/crates/audio-dsp/src/effects/time.rs b/crates/audio-dsp/src/effects/time.rs new file mode 100644 index 000000000..7710d0188 --- /dev/null +++ b/crates/audio-dsp/src/effects/time.rs @@ -0,0 +1,558 @@ +//! Time-based effects: feedback delay and an algorithmic (FDN) reverb. + +use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, flush32, param_plumbing}; + +/// Fractional read from a circular buffer: `delay` samples behind write position `w`. +#[inline] +fn read_frac(buf: &[f32], w: usize, delay: f32) -> f32 { + read_prepared(buf, w, prepare_delay(buf.len(), delay)) +} + +#[inline] +fn prepare_delay(len: usize, delay: f32) -> (usize, f32) { + let d = delay.clamp(1.0, (len - 2) as f32); + let di = d.floor(); + let frac = d - di; + // The delay is bounded by this ring's length, so wrapping needs no integer division. + // Keep the fallback for very large rings whose f32 length rounds upward. + let distance = di as usize; + let distance = if distance <= len { distance } else { distance % len }; + (distance, frac) +} + +#[inline] +fn read_prepared(buf: &[f32], w: usize, (distance, frac): (usize, f32)) -> f32 { + let len = buf.len(); + let i0 = if w >= distance { w - distance } else { len - (distance - w) }; + let i1 = if i0 == 0 { len - 1 } else { i0 - 1 }; + buf[i0] + (buf[i1] - buf[i0]) * frac +} + +/// Note divisions for tempo-synced delay, in quarter notes. +const DIVISIONS: &[&str] = &["1/1", "1/2", "1/4", "1/8", "1/16", "1/4 dotted", "1/8 dotted", "1/4 triplet", "1/8 triplet"]; +const DIVISION_QUARTERS: [f32; 9] = [4.0, 2.0, 1.0, 0.5, 0.25, 1.5, 0.75, 2.0 / 3.0, 1.0 / 3.0]; + +/// Delay time in ms for a tempo and division index. +pub fn tempo_delay_ms(bpm: f32, division: usize) -> f32 { + 60_000.0 / bpm.max(1.0) * DIVISION_QUARTERS[division.min(DIVISION_QUARTERS.len() - 1)] +} + +/// Feedback delay (per-channel), time in ms or tempo-synced. +pub struct Delay { + pv: ParamValues, + sr: f32, + bufs: Vec>, + w: usize, + /// Delay in samples (smoothed: glides like a tape delay instead of clicking). + time: Smoothed, + feedback: Smoothed, + mix: Smoothed, +} + +impl Delay { + pub const MAX_MS: f32 = 4000.0; + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::choice("mode", "Mode", &["Time", "Tempo"], 0), + ParamSpec::log("time", "Delay Time", 1.0, 2000.0, 250.0, Unit::Milliseconds), + ParamSpec::new("bpm", "Tempo", 20.0, 300.0, 120.0, Unit::Bpm), + ParamSpec::choice("division", "Division", DIVISIONS, 3), + ParamSpec::new("feedback", "Feedback", 0.0, 95.0, 30.0, Unit::Percent), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 30.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let channels = crate::sane_channels(channels); + let len = super::util::delay_line_len(Self::MAX_MS, sample_rate, channels); + let mut s = Delay { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + bufs: vec![vec![0.0; len]; channels], + w: 0, + time: Smoothed::with_ms(1.0, sample_rate, 100.0), + feedback: Smoothed::with_ms(0.0, sample_rate, 20.0), + mix: Smoothed::with_ms(0.0, sample_rate, 20.0), + }; + s.apply_params(true); + s + } + + /// Effective delay time (ms) at the current settings. + pub fn delay_ms(&self) -> f32 { + let ms = if self.pv.idx("mode") == 1 { tempo_delay_ms(self.pv.v("bpm"), self.pv.idx("division")) } else { self.pv.v("time") }; + let held = self.bufs.first().map_or(0, Vec::len).saturating_sub(2) as f32 * 1000.0 / self.sr; + ms.min(Self::MAX_MS).min(held) + } + + fn apply_params(&mut self, snap: bool) { + self.time.set(self.delay_ms() * 0.001 * self.sr); + self.feedback.set(self.pv.v("feedback") / 100.0); + self.mix.set(self.pv.v("mix") / 100.0); + if snap { + self.time.snap(); + self.feedback.snap(); + self.mix.snap(); + } + } +} + +impl AudioEffect for Delay { + param_plumbing!("delay"); + fn tail_samples(&self) -> usize { + super::util::echo_tail(self.delay_ms(), self.pv.v("feedback") / 100.0, self.sr) + } + fn reset(&mut self) { + self.bufs.iter_mut().for_each(|b| b.iter_mut().for_each(|v| *v = 0.0)); + self.w = 0; + self.time.snap(); + self.feedback.snap(); + self.mix.snap(); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len().min(self.bufs.len()); + let len = self.bufs[0].len(); + for i in 0..n { + let d = self.time.tick(); + let fb = self.feedback.tick(); + let mix = self.mix.tick(); + for ch in 0..nch { + let x = channels[ch][i]; + let buf = &mut self.bufs[ch]; + let yd = read_frac(buf, self.w, d); + buf[self.w] = flush32(x + fb * yd); + channels[ch][i] = x + mix * (yd - x); + } + self.w = if self.w + 1 == len { 0 } else { self.w + 1 }; + } + } +} + +// --------------------------------------------------------------------------------------------- + +const FDN: usize = 8; +/// Base loop delays (ms) at size = 50 %; mutually prime-ish so modes don't pile up. +const BASE_MS: [f32; FDN] = [29.7, 37.1, 41.1, 43.7, 53.9, 59.3, 67.1, 73.3]; +const MAX_SIZE_SCALE: f32 = 2.0; +/// Output tap signs (left, right) for decorrelated stereo. +const SIGN_L: [f32; FDN] = [1.0, -1.0, 1.0, -1.0, 1.0, 1.0, -1.0, -1.0]; +const SIGN_R: [f32; FDN] = [1.0, 1.0, -1.0, -1.0, 1.0, -1.0, 1.0, -1.0]; + +fn size_scale(size_pct: f32) -> f32 { + 0.35 + (MAX_SIZE_SCALE - 0.35) * size_pct / 100.0 +} + +/// 8×8 feedback-delay-network reverb with a Householder feedback matrix, per-line RT60 gains, +/// one-pole HF damping in each loop, pre-delay, size and dry/wet mix. +pub struct Reverb { + pv: ParamValues, + sr: f32, + lines: Vec>, + w: usize, + len: [Smoothed; FDN], + lp: [f32; FDN], + gains: [f32; FDN], + gain_key: ([f32; FDN], f32), + damp: Smoothed, + rt60: Smoothed, + mix: Smoothed, + pre: Vec, + pre_w: usize, + pre_len: Smoothed, + counter: u32, +} + +impl Reverb { + pub const PARAMS: &'static [ParamSpec] = &[ + ParamSpec::new("predelay", "Pre-delay", 0.0, 200.0, 20.0, Unit::Milliseconds), + ParamSpec::log("decay", "Decay (RT60)", 0.1, 20.0, 2.0, Unit::Seconds), + ParamSpec::new("damping", "HF Damping", 0.0, 100.0, 40.0, Unit::Percent), + ParamSpec::new("size", "Room Size", 0.0, 100.0, 50.0, Unit::Percent), + ParamSpec::new("mix", "Mix", 0.0, 100.0, 25.0, Unit::Percent), + ]; + + pub fn new(sample_rate: f32, _channels: usize) -> Self { + let sample_rate = crate::sane_sample_rate(sample_rate); + let max_line = (BASE_MS[FDN - 1] * MAX_SIZE_SCALE * 0.001 * sample_rate) as usize + 4; + let pre_len = (0.2 * sample_rate) as usize + 4; + let sm = |v| Smoothed::with_ms(v, sample_rate, 50.0); + let mut s = Reverb { + pv: ParamValues::new(Self::PARAMS), + sr: sample_rate, + lines: vec![vec![0.0; max_line]; FDN], + w: 0, + len: [sm(1.0); FDN], + lp: [0.0; FDN], + gains: [0.0; FDN], + gain_key: ([0.0; FDN], 0.0), + damp: sm(0.0), + rt60: sm(1.0), + mix: sm(0.0), + pre: vec![0.0; pre_len], + pre_w: 0, + pre_len: Smoothed::with_ms(1.0, sample_rate, 100.0), + counter: 0, + }; + s.apply_params(true); + s + } + + fn apply_params(&mut self, snap: bool) { + let scale = size_scale(self.pv.v("size")); + for (k, l) in self.len.iter_mut().enumerate() { + l.set(BASE_MS[k] * scale * 0.001 * self.sr); + } + self.pre_len.set((self.pv.v("predelay") * 0.001 * self.sr).max(1.0)); + self.damp.set(self.pv.v("damping") / 100.0 * 0.85); + self.rt60.set(self.pv.v("decay")); + self.mix.set(self.pv.v("mix") / 100.0); + if snap { + self.len.iter_mut().for_each(Smoothed::snap); + self.pre_len.snap(); + self.damp.snap(); + self.rt60.snap(); + self.mix.snap(); + self.update_gains(); + } + } + + fn update_gains(&mut self) { + let rt = self.rt60.value().max(0.01); + let lengths = self.len.map(|l| l.value()); + if self.gain_key == (lengths, rt) { + return; + } + self.gain_key = (lengths, rt); + for k in 0..FDN { + // Attenuation per pass so the loop decays 60 dB in rt seconds. + self.gains[k] = 10f32.powf(-3.0 * self.len[k].value() / (rt * self.sr)); + } + } +} + +impl AudioEffect for Reverb { + param_plumbing!("reverb"); + /// Pre-delay plus the decay time (RT60, the time to fall 60 dB). + fn tail_samples(&self) -> usize { + super::util::tail_samples(self.pv.v("predelay") * 0.001 + self.pv.v("decay"), self.sr) + } + fn reset(&mut self) { + self.lines.iter_mut().for_each(|l| l.iter_mut().for_each(|v| *v = 0.0)); + self.pre.iter_mut().for_each(|v| *v = 0.0); + self.lp = [0.0; FDN]; + self.w = 0; + self.pre_w = 0; + self.counter = 0; + self.apply_params(true); + } + fn process(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len(); + if nch == 0 { + return; + } + let line_len = self.lines[0].len(); + let pre_len = self.pre.len(); + let hh = 2.0 / FDN as f32; + // During a settled block these positions cannot change. Preserve the original path + // while smoothing, and preserve the 32-sample gain update grid in both cases. + let fixed = self.len.iter().all(|l| !l.is_smoothing()); + let delays = self.len.map(|l| prepare_delay(line_len, l.value())); + let predelay = (!self.pre_len.is_smoothing()).then(|| prepare_delay(pre_len, self.pre_len.value())); + for i in 0..n { + if self.counter == 0 { + self.update_gains(); + } + self.counter = (self.counter + 1) % 32; + if !fixed { + for l in &mut self.len { + l.tick(); + } + } + self.rt60.tick(); + let damp = self.damp.tick(); + let mix = self.mix.tick(); + let pd = self.pre_len.tick(); + + let mut mono = 0.0; + for ch in channels.iter() { + mono += ch[i]; + } + mono /= nch as f32; + self.pre[self.pre_w] = mono; + let input = match predelay { + Some(delay) => read_prepared(&self.pre, self.pre_w, delay), + None => read_frac(&self.pre, self.pre_w, pd), + }; + self.pre_w = if self.pre_w + 1 == pre_len { 0 } else { self.pre_w + 1 }; + + let mut v = [0.0f32; FDN]; + let mut sum = 0.0; + for k in 0..FDN { + let d = if fixed { read_prepared(&self.lines[k], self.w, delays[k]) } else { read_frac(&self.lines[k], self.w, self.len[k].value()) }; + self.lp[k] = flush32(d + (self.lp[k] - d) * damp); + v[k] = self.lp[k] * self.gains[k]; + sum += v[k]; + } + let (mut wl, mut wr) = (0.0, 0.0); + for k in 0..FDN { + let fbk = v[k] - hh * sum; + self.lines[k][self.w] = flush32(fbk + input * 0.5); + wl += SIGN_L[k] * v[k]; + wr += SIGN_R[k] * v[k]; + } + self.w = if self.w + 1 == line_len { 0 } else { self.w + 1 }; + let (wl, wr) = (wl * 0.35, wr * 0.35); + for (c, ch) in channels.iter_mut().enumerate() { + let x = ch[i]; + let wet = if nch == 1 { + 0.5 * (wl + wr) + } else if c % 2 == 0 { + wl + } else { + wr + }; + ch[i] = x + mix * (wet - x); + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::*; + + const SR: f32 = 48000.0; + + #[test] + fn delay_impulse_and_feedback() { + let mut d = Delay::new(SR, 1); + d.set_param("time", 100.0); + d.set_param("feedback", 50.0); + d.set_param("mix", 100.0); + d.reset(); + let mut x = vec![0.0f32; 24000]; + x[0] = 1.0; + d.process(&mut [&mut x]); + assert!((x[4800] - 1.0).abs() < 1e-6); + assert!((x[9600] - 0.5).abs() < 1e-6); + assert!((x[14400] - 0.25).abs() < 1e-6); + assert_eq!(x[0], 0.0); + } + + #[test] + fn tempo_sync() { + assert_eq!(tempo_delay_ms(120.0, 2), 500.0); + assert_eq!(tempo_delay_ms(120.0, 3), 250.0); + assert!((tempo_delay_ms(120.0, 5) - 750.0).abs() < 1e-3); + let mut d = Delay::new(SR, 1); + d.set_param("mode", 1.0); + d.set_param("bpm", 90.0); + d.set_param("division", 2.0); + assert!((d.delay_ms() - 666.666).abs() < 0.01); + d.set_param("bpm", 20.0); + d.set_param("division", 0.0); + assert_eq!(d.delay_ms(), Delay::MAX_MS); + } + + #[test] + fn delay_lines_at_the_highest_rate_and_channel_count_stay_within_the_budget() { + use super::super::util::MAX_DELAY_SAMPLES; + let mut d = Delay::new(crate::MAX_SAMPLE_RATE, crate::MAX_CHANNELS); + let held: usize = d.bufs.iter().map(Vec::len).sum(); + assert!(held <= MAX_DELAY_SAMPLES, "{held}"); + d.set_param("time", 2000.0); + assert!(d.delay_ms() < 2000.0, "the delay is shortened to the line: {}", d.delay_ms()); + let mut a = vec![0.5f32; 64]; + let mut chans: Vec<&mut [f32]> = vec![&mut a[..]]; + d.process(&mut chans); + assert!(a.iter().all(|v| v.is_finite())); + let analog = crate::effects::AnalogDelay::new(crate::MAX_SAMPLE_RATE, crate::MAX_CHANNELS); + let multitap = crate::effects::MultitapDelay::new(crate::MAX_SAMPLE_RATE, crate::MAX_CHANNELS); + assert!(analog.held_samples() <= MAX_DELAY_SAMPLES, "{}", analog.held_samples()); + assert!(multitap.held_samples() <= MAX_DELAY_SAMPLES, "{}", multitap.held_samples()); + } + + #[test] + fn reverb_decays_and_is_bounded() { + let mut r = Reverb::new(SR, 2); + r.set_param("mix", 100.0); + r.set_param("decay", 1.0); + r.set_param("damping", 0.0); + r.reset(); + let n = (SR * 3.0) as usize; + let mut l = vec![0.0f32; n]; + let mut rr = vec![0.0f32; n]; + l[0] = 1.0; + rr[0] = 1.0; + r.process(&mut [&mut l, &mut rr]); + assert!(l.iter().chain(&rr).all(|v| v.is_finite() && v.abs() < 1.0)); + let win = (SR * 0.1) as usize; + let e = |s: usize| rms(&l[s..s + win]); + let e1 = e((SR * 0.2) as usize); + let e2 = e((SR * 1.2) as usize); + // RT60 = 1 s → ~60 dB drop per second (allow generous tolerance). + let drop = db(e1 / e2); + assert!((45.0..75.0).contains(&drop), "decay over 1 s = {drop} dB"); + // Stereo outputs are decorrelated but both carry energy. + assert!(rms(&rr[..win * 5]) > 0.0); + assert!(l.iter().zip(&rr).any(|(a, b)| (a - b).abs() > 1e-4)); + } + + #[test] + fn reverb_stable_with_longest_decay_and_noise() { + let mut r = Reverb::new(SR, 2); + r.set_param("decay", 20.0); + r.set_param("size", 100.0); + r.set_param("damping", 0.0); + r.set_param("mix", 100.0); + let mut rng = Rng::new(3); + let mut peak = 0.0f32; + for _ in 0..100 { + let mut l: Vec = (0..4800).map(|_| rng.uniform()).collect(); + let mut rr = l.clone(); + r.process(&mut [&mut l, &mut rr]); + peak = l.iter().chain(&rr).fold(peak, |a, v| a.max(v.abs())); + } + assert!(peak.is_finite() && peak < 20.0, "peak {peak}"); + // Then silence: energy decays. + let mut last = 0.0; + for k in 0..30 { + let mut l = vec![0.0f32; 48000]; + let mut rr = vec![0.0f32; 48000]; + r.process(&mut [&mut l, &mut rr]); + let e = rms(&l); + if k > 0 { + assert!(e < last, "energy must decay"); + } + last = e; + } + } +} + +#[cfg(test)] +fn read_frac_reference(buf: &[f32], w: usize, delay: f32) -> f32 { + let len = buf.len(); + let d = delay.clamp(1.0, (len - 2) as f32); + let di = d.floor(); + let frac = d - di; + let i0 = (w + len - di as usize) % len; + let i1 = (i0 + len - 1) % len; + buf[i0] + (buf[i1] - buf[i0]) * frac +} +#[cfg(test)] +impl Reverb { + fn update_gains_reference(&mut self) { + let rt = self.rt60.value().max(0.01); + for k in 0..FDN { + // Attenuation per pass so the loop decays 60 dB in rt seconds. + self.gains[k] = 10f32.powf(-3.0 * self.len[k].value() / (rt * self.sr)); + } + } + fn process_reference(&mut self, channels: &mut [&mut [f32]]) { + let n = block_len(channels); + let nch = channels.len(); + if nch == 0 { + return; + } + let line_len = self.lines[0].len(); + let pre_len = self.pre.len(); + let hh = 2.0 / FDN as f32; + for i in 0..n { + if self.counter == 0 { + self.update_gains_reference(); + } + self.counter = (self.counter + 1) % 32; + for l in &mut self.len { + l.tick(); + } + self.rt60.tick(); + let damp = self.damp.tick(); + let mix = self.mix.tick(); + let pd = self.pre_len.tick(); + + let mut mono = 0.0; + for ch in channels.iter() { + mono += ch[i]; + } + mono /= nch as f32; + self.pre[self.pre_w] = mono; + let input = read_frac_reference(&self.pre, self.pre_w, pd); + self.pre_w = (self.pre_w + 1) % pre_len; + + let mut v = [0.0f32; FDN]; + let mut sum = 0.0; + for k in 0..FDN { + let d = read_frac_reference(&self.lines[k], self.w, self.len[k].value()); + self.lp[k] = flush32(d + (self.lp[k] - d) * damp); + v[k] = self.lp[k] * self.gains[k]; + sum += v[k]; + } + let (mut wl, mut wr) = (0.0, 0.0); + for k in 0..FDN { + let fbk = v[k] - hh * sum; + self.lines[k][self.w] = flush32(fbk + input * 0.5); + wl += SIGN_L[k] * v[k]; + wr += SIGN_R[k] * v[k]; + } + self.w = (self.w + 1) % line_len; + let (wl, wr) = (wl * 0.35, wr * 0.35); + for (c, ch) in channels.iter_mut().enumerate() { + let x = ch[i]; + let wet = if nch == 1 { + 0.5 * (wl + wr) + } else if c % 2 == 0 { + wl + } else { + wr + }; + ch[i] = x + mix * (wet - x); + } + } + } +} +#[cfg(test)] +mod throughput_tests { + use super::*; + #[test] + fn circular_reads_match_modulo_reference() { + for len in [3, 4, 17, 257, 14078] { + let buf: Vec = (0..len).map(|i| (i as f32 * 0.17).sin()).collect(); + for w in 0..len { + for delay in [-10.0, 0.0, 1.0, 1.25, 2.75, len as f32 - 2.0, len as f32, f32::INFINITY] { + assert_eq!(read_frac(&buf, w, delay).to_bits(), read_frac_reference(&buf, w, delay).to_bits()); + } + } + } + } + #[test] + fn reverb_automation_and_tail_match_original_loop() { + let mut fast = Reverb::new(48000.0, 2); + let mut reference = Reverb::new(48000.0, 2); + for block in 0..800 { + if matches!(block, 1 | 80 | 200 | 320 | 440) { + for fx in [&mut fast, &mut reference] { + fx.set_param("size", (block % 101) as f32); + fx.set_param("decay", 0.1 + (block % 20) as f32); + fx.set_param("predelay", (block % 200) as f32); + } + } + if block == 600 { + fast.reset(); + reference.reset(); + } + let n = [0, 1, 17, 64, 513][block % 5]; + let input: Vec = (0..n).map(|i| if block > 450 { 0.0 } else { ((i + block * 13) as f32 * 0.17).sin() * 0.3 }).collect(); + let mut a = [input.clone(), input]; + let mut b = a.clone(); + let [al, ar] = &mut a; + let [bl, br] = &mut b; + fast.process(&mut [al, ar]); + reference.process_reference(&mut [bl, br]); + for (a, b) in a.iter().flatten().zip(b.iter().flatten()) { + assert_eq!(a.to_bits(), b.to_bits(), "block {block}"); + } + } + } +} diff --git a/crates/audio-dsp/src/effects/util.rs b/crates/audio-dsp/src/effects/util.rs new file mode 100644 index 000000000..a9e352402 --- /dev/null +++ b/crates/audio-dsp/src/effects/util.rs @@ -0,0 +1,330 @@ +//! Small building blocks shared by the effect implementations: delay lines with fractional +//! reads, LFOs, one-pole filters, envelope followers. + +use crate::{flush, flush32}; +use std::f64::consts::PI; + +/// One-pole smoothing coefficient for a time constant in ms (0 → instant). +#[inline] +pub(crate) fn coef(ms: f32, sr: f32) -> f32 { + if ms <= 0.0 { 0.0 } else { (-1.0 / (ms * 0.001 * sr)).exp() } +} + +/// Most samples one effect keeps in its delay lines, over all its lines (128 MiB of `f32`). +pub(crate) const MAX_DELAY_SAMPLES: usize = 1 << 25; + +/// Length of each of `lines` delay lines that hold `max_ms` at `sample_rate`. The lines together +/// hold at most [`MAX_DELAY_SAMPLES`], so at high rates and channel counts the longest delay is +/// shorter than `max_ms`; reads clamp to the line. +pub(crate) fn delay_line_len(max_ms: f32, sample_rate: f32, lines: usize) -> usize { + let want = (max_ms * 0.001 * sample_rate) as usize + 4; + want.min(MAX_DELAY_SAMPLES / lines.max(1)).max(8) +} + +/// Linear → dB with a −200 dB floor. +#[inline] +pub(crate) fn lin_db(x: f32) -> f32 { + 20.0 * x.max(1e-10).log10() +} + +/// Longest tail an effect reports, in seconds. +pub(crate) const MAX_TAIL_S: f32 = 60.0; + +/// Samples until the echoes of a delay of `delay_ms` with `feedback` (gain per repeat) fall +/// 60 dB below the first one, capped at [`MAX_TAIL_S`]. A feedback of 1 or more reports the cap. +pub(crate) fn echo_tail(delay_ms: f32, feedback: f32, sr: f32) -> usize { + let repeats = if feedback.is_nan() || feedback <= 0.0 { + 1.0 + } else if feedback >= 1.0 { + f32::INFINITY + } else { + (0.001f32.ln() / feedback.ln()).ceil() + 1.0 + }; + tail_samples((delay_ms.max(0.0) * 0.001 * repeats).min(MAX_TAIL_S), sr) +} + +/// `seconds` (capped at [`MAX_TAIL_S`]) in whole samples at `sr`. +pub(crate) fn tail_samples(seconds: f32, sr: f32) -> usize { + let s = if seconds.is_finite() { seconds.clamp(0.0, MAX_TAIL_S) } else { MAX_TAIL_S }; + (s * sr).ceil() as usize +} + +/// Circular delay line with linear-interpolated fractional reads. +#[derive(Clone, Debug)] +pub(crate) struct DelayLine { + buf: Vec, + w: usize, +} + +impl DelayLine { + /// A line that can delay by up to `max` samples. + pub(crate) fn new(max: usize) -> Self { + DelayLine { buf: vec![0.0; max + 3], w: 0 } + } + pub(crate) fn reset(&mut self) { + self.buf.iter_mut().for_each(|v| *v = 0.0); + self.w = 0; + } + /// Longest usable delay in samples. + pub(crate) fn max_delay(&self) -> f32 { + (self.buf.len() - 3) as f32 + } + /// Sample written `d` samples ago (`d` ≥ 0; 0 = the sample written by the last `push`). + #[inline] + pub(crate) fn read(&self, d: f32) -> f32 { + let len = self.buf.len(); + let d = d.clamp(0.0, self.max_delay()); + let di = d.floor(); + let frac = d - di; + // `w < len` and `di <= len - 3`, so one conditional subtract wraps the index. + let i0 = self.w + len - 1 - di as usize; + let i0 = if i0 >= len { i0 - len } else { i0 }; + let i1 = if i0 == 0 { len - 1 } else { i0 - 1 }; + self.buf[i0] + (self.buf[i1] - self.buf[i0]) * frac + } + /// Integer read (`d` samples ago, 0 = newest). + #[inline] + pub(crate) fn tap(&self, d: usize) -> f32 { + let len = self.buf.len(); + self.buf[(self.w + len - 1 - d.min(len - 1)) % len] + } + #[inline] + pub(crate) fn push(&mut self, x: f32) { + self.buf[self.w] = flush32(x); + self.w += 1; + if self.w == self.buf.len() { + self.w = 0; + } + } +} + +/// Phase accumulator LFO (phase in cycles, 0..1). +#[derive(Clone, Copy, Debug, Default)] +pub(crate) struct Lfo { + phase: f64, +} + +impl Lfo { + pub(crate) fn reset(&mut self) { + self.phase = 0.0; + } + /// Current phase plus `offset` (cycles), wrapped to 0..1. + #[inline] + pub(crate) fn phase(&self, offset: f64) -> f64 { + wrap_phase(self.phase + offset) + } + #[inline] + pub(crate) fn advance(&mut self, hz: f32, sr: f32) { + self.phase += hz as f64 / sr as f64; + if self.phase >= 1.0 { + self.phase -= self.phase.floor(); + } + } +} + +/// `p.rem_euclid(1.0)`, without the `fmod` for phase sums in 0..2 (`p - 1.0` is exact there). +#[inline] +pub(crate) fn wrap_phase(p: f64) -> f64 { + if (0.0..1.0).contains(&p) { + p + } else if (1.0..2.0).contains(&p) { + p - 1.0 + } else { + p.rem_euclid(1.0) + } +} + +/// Sine of a phase in cycles, mapped to 0..1. +#[inline] +pub(crate) fn uni_sine(phase: f64) -> f32 { + (0.5 - 0.5 * (2.0 * PI * phase).cos()) as f32 +} + +/// Triangle of a phase in cycles, 0..1. +#[inline] +pub(crate) fn uni_tri(phase: f64) -> f32 { + (if phase < 0.5 { 2.0 * phase } else { 2.0 - 2.0 * phase }) as f32 +} + +/// One-pole low-pass (`y += a (x − y)`), coefficient from a cutoff frequency. +#[derive(Clone, Copy, Debug, Default)] +pub(crate) struct OnePole { + y: f64, +} + +impl OnePole { + /// Coefficient for a −3 dB cutoff at `hz` (matched-z). + pub(crate) fn alpha(hz: f32, sr: f32) -> f64 { + 1.0 - (-2.0 * PI * (hz.clamp(1.0, sr * 0.49) as f64) / sr as f64).exp() + } + #[inline] + pub(crate) fn lp(&mut self, a: f64, x: f32) -> f32 { + self.y = flush(self.y + a * (x as f64 - self.y)); + self.y as f32 + } + /// High-pass as the complement of the low-pass. + #[inline] + pub(crate) fn hp(&mut self, a: f64, x: f32) -> f32 { + x - self.lp(a, x) + } + pub(crate) fn reset(&mut self) { + self.y = 0.0; + } +} + +/// DC blocker (`y = x − x₁ + R·y₁`, R ≈ 0.995 at 48 kHz → ~20 Hz). +#[derive(Clone, Copy, Debug, Default)] +pub(crate) struct DcBlock { + x1: f64, + y1: f64, +} + +impl DcBlock { + pub(crate) fn r(sr: f32) -> f64 { + 1.0 - 2.0 * PI * 20.0 / sr as f64 + } + #[inline] + pub(crate) fn tick(&mut self, r: f64, x: f32) -> f32 { + let y = x as f64 - self.x1 + r * self.y1; + self.x1 = x as f64; + self.y1 = flush(y); + y as f32 + } + pub(crate) fn reset(&mut self) { + *self = DcBlock::default(); + } +} + +/// First-order all-pass section `H(z) = (a + z⁻¹) / (1 + a z⁻¹)`. +#[derive(Clone, Copy, Debug, Default)] +pub(crate) struct AllPass1 { + x1: f64, + y1: f64, +} + +impl AllPass1 { + /// Coefficient placing the 90° phase point at `hz`. + pub(crate) fn coef(hz: f32, sr: f32) -> f64 { + let t = (PI * (hz.clamp(1.0, sr * 0.49) as f64) / sr as f64).tan(); + (t - 1.0) / (t + 1.0) + } + #[inline] + pub(crate) fn tick(&mut self, a: f64, x: f64) -> f64 { + let y = a * x + self.x1 - a * self.y1; + self.x1 = x; + self.y1 = flush(y); + y + } + pub(crate) fn reset(&mut self) { + *self = AllPass1::default(); + } +} + +/// Peak envelope follower with separate attack / release coefficients (linear domain). +#[derive(Clone, Copy, Debug, Default)] +pub(crate) struct Envelope { + pub(crate) env: f32, +} + +impl Envelope { + #[inline] + pub(crate) fn tick(&mut self, att: f32, rel: f32, x: f32) -> f32 { + let c = if x > self.env { att } else { rel }; + self.env = c * self.env + (1.0 - c) * x; + if !(1e-20..=f32::MAX).contains(&self.env) { + self.env = 0.0; + } + self.env + } +} + +/// Tiny deterministic PRNG (xorshift64*) for generated impulse responses. +#[derive(Clone, Debug)] +pub(crate) struct Prng(u64); + +impl Prng { + pub(crate) fn new(seed: u64) -> Self { + Prng(seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) | 1) + } + pub(crate) fn next_u64(&mut self) -> u64 { + let mut x = self.0; + x ^= x >> 12; + x ^= x << 25; + x ^= x >> 27; + self.0 = x; + x.wrapping_mul(0x2545_F491_4F6C_DD1D) + } + /// Uniform in [-1, 1). + pub(crate) fn uniform(&mut self) -> f32 { + ((self.next_u64() >> 40) as f32 / (1u64 << 24) as f32) * 2.0 - 1.0 + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn delay_line_reads_integer_and_fractional() { + let mut d = DelayLine::new(8); + for i in 0..5 { + d.push(i as f32); + } + assert_eq!(d.read(0.0), 4.0); + assert_eq!(d.tap(2), 2.0); + assert!((d.read(1.5) - 2.5).abs() < 1e-6); + } + + #[test] + fn delay_read_matches_modulo_indexing() { + let reference = |line: &DelayLine, d: f32| { + let len = line.buf.len(); + let d = d.clamp(0.0, line.max_delay()); + let di = d.floor(); + let frac = d - di; + let i0 = (line.w + len - 1 - di as usize) % len; + let i1 = (i0 + len - 1) % len; + line.buf[i0] + (line.buf[i1] - line.buf[i0]) * frac + }; + for max in [0, 1, 2, 7] { + let mut line = DelayLine::new(max); + for k in 0..3 * (max + 3) { + line.push(k as f32 * 0.37 - 1.0); + for d in (-8..=4 * max as i32 + 12).map(|i| i as f32 * 0.25).chain([f32::NAN, f32::INFINITY, -f32::INFINITY, 1e30]) { + assert_eq!(line.read(d).to_bits(), reference(&line, d).to_bits(), "max {max} w {} d {d}", line.w); + } + } + } + } + + #[test] + fn wrap_phase_matches_rem_euclid() { + let edges = [0.0, -0.0, 1.0, 2.0, 3.0, -1.0, 0.5, 1.5, 1e300, f64::MIN_POSITIVE, f64::INFINITY, f64::NEG_INFINITY, f64::NAN]; + let near = edges.iter().flat_map(|&p: &f64| [p, f64::from_bits(p.to_bits().wrapping_add(1)), f64::from_bits(p.to_bits().wrapping_sub(1))]); + let mut r = Prng::new(7); + let sums = (0..100_000).map(|_| { + let mut lfo = Lfo::default(); + lfo.advance((r.uniform() + 1.0) * 24000.0, 48000.0); + lfo.phase + (r.uniform() as f64 + 1.0) * 1.5 + }); + for p in near.chain(sums) { + assert_eq!(wrap_phase(p).to_bits(), p.rem_euclid(1.0).to_bits(), "{p:e}"); + } + } + + #[test] + fn allpass_is_unit_magnitude() { + let a = AllPass1::coef(1000.0, 48000.0); + let mut ap = AllPass1::default(); + let mut e_in = 0.0; + let mut e_out = 0.0; + let mut r = Prng::new(3); + for _ in 0..48000 { + let x = r.uniform() as f64; + let y = ap.tick(a, x); + e_in += x * x; + e_out += y * y; + } + assert!((e_out / e_in - 1.0).abs() < 0.01); + } +} diff --git a/crates/audio-dsp/src/fft.rs b/crates/audio-dsp/src/fft.rs new file mode 100644 index 000000000..c530bc01b --- /dev/null +++ b/crates/audio-dsp/src/fft.rs @@ -0,0 +1,204 @@ +//! Minimal in-place radix-2 complex FFT (power-of-two sizes), allocation-free after planning. +//! +//! Kept in-crate (rather than depending on an FFT library) so the crate stays dependency-free; +//! the STFT effects only need a few fixed power-of-two sizes. + +use std::f64::consts::PI; + +/// A planned FFT of fixed power-of-two size. +#[derive(Clone, Debug)] +pub struct Fft { + n: usize, + /// Per-stage twiddles, contiguous: the stage with half-length `h` reads e^{-2πik/(2h)} for + /// k in 0..h at offset `h - 1` (values taken from the n-point table, so they match it exactly). + tw_re: Vec, + tw_im: Vec, + /// `tw_im` negated, for the inverse transform. + tw_im_inv: Vec, + rev: Vec, +} + +impl Fft { + /// Plan an FFT of size `n` (must be a power of two ≥ 2). + pub fn new(n: usize) -> Fft { + assert!(n >= 2 && n.is_power_of_two(), "FFT size must be a power of two"); + let bits = n.trailing_zeros(); + let rev = (0..n as u32).map(|i| i.reverse_bits() >> (32 - bits)).collect(); + let (mut tw_re, mut tw_im) = (Vec::with_capacity(n - 1), Vec::with_capacity(n - 1)); + let mut half = 1; + while half < n { + let stride = n / (2 * half); + for k in 0..half { + let a = -2.0 * PI * (k * stride) as f64 / n as f64; + tw_re.push(a.cos() as f32); + tw_im.push(a.sin() as f32); + } + half <<= 1; + } + let tw_im_inv = tw_im.iter().map(|w| -w).collect(); + Fft { n, tw_re, tw_im, tw_im_inv, rev } + } + + /// Forward transform (e^{-iωt}), unscaled. + pub fn forward(&self, re: &mut [f32], im: &mut [f32]) { + self.run(re, im, false); + } + + /// Inverse transform (e^{+iωt}), unscaled (divide by `n` yourself). + pub fn inverse(&self, re: &mut [f32], im: &mut [f32]) { + self.run(re, im, true); + } + + fn run(&self, re: &mut [f32], im: &mut [f32], inverse: bool) { + let n = self.n; + assert!(re.len() >= n && im.len() >= n); + let (re, im) = (&mut re[..n], &mut im[..n]); + for i in 0..n { + let j = self.rev[i] as usize; + if j > i { + re.swap(i, j); + im.swap(i, j); + } + } + let tw_im = if inverse { &self.tw_im_inv } else { &self.tw_im }; + // First stage: the twiddle is 1 + i·(∓0). The multiplications by 1 are exact and dropped; + // the ones by ∓0 stay so signed zeros come out exactly as in the general butterfly. + let wi = tw_im[0]; + for (r, i) in re.as_chunks_mut::<2>().0.iter_mut().zip(im.as_chunks_mut::<2>().0) { + let xr = r[1] - i[1] * wi; + let xi = r[1] * wi + i[1]; + r[1] = r[0] - xr; + i[1] = i[0] - xi; + r[0] += xr; + i[0] += xi; + } + let mut half = 2; + while half < n { + let wr = &self.tw_re[half - 1..2 * half - 1]; + let wi = &tw_im[half - 1..2 * half - 1]; + for (r, i) in re.chunks_exact_mut(2 * half).zip(im.chunks_exact_mut(2 * half)) { + let (ra, rb) = r.split_at_mut(half); + let (ia, ib) = i.split_at_mut(half); + for k in 0..half { + let xr = rb[k] * wr[k] - ib[k] * wi[k]; + let xi = rb[k] * wi[k] + ib[k] * wr[k]; + rb[k] = ra[k] - xr; + ib[k] = ia[k] - xi; + ra[k] += xr; + ia[k] += xi; + } + } + half <<= 1; + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn matches_naive_dft_and_round_trips() { + let n = 64; + let fft = Fft::new(n); + let x: Vec = (0..n).map(|i| ((i * 7 % 13) as f32 - 6.0) / 6.0).collect(); + let mut re = x.clone(); + let mut im = vec![0.0; n]; + fft.forward(&mut re, &mut im); + for k in 0..n { + let (mut r, mut i) = (0.0f64, 0.0f64); + for (t, &v) in x.iter().enumerate() { + let a = -2.0 * PI * (k * t) as f64 / n as f64; + r += v as f64 * a.cos(); + i += v as f64 * a.sin(); + } + assert!((re[k] as f64 - r).abs() < 1e-4, "re {k}"); + assert!((im[k] as f64 - i).abs() < 1e-4, "im {k}"); + } + fft.inverse(&mut re, &mut im); + for t in 0..n { + assert!((re[t] / n as f32 - x[t]).abs() < 1e-5); + assert!((im[t] / n as f32).abs() < 1e-5); + } + } + + /// The previous kernel (strided reads from one n/2-entry twiddle table), kept as reference. + fn run_reference(n: usize, re: &mut [f32], im: &mut [f32], inverse: bool) { + let rev: Vec = (0..n as u32).map(|i| i.reverse_bits() >> (32 - n.trailing_zeros())).collect(); + let (tw_re, tw_im): (Vec, Vec) = (0..n / 2) + .map(|k| { + let a = -2.0 * PI * k as f64 / n as f64; + (a.cos() as f32, a.sin() as f32) + }) + .unzip(); + for i in 0..n { + let j = rev[i] as usize; + if j > i { + re.swap(i, j); + im.swap(i, j); + } + } + let sign = if inverse { -1.0 } else { 1.0 }; + let mut len = 2; + while len <= n { + let half = len / 2; + let stride = n / len; + let mut start = 0; + while start < n { + for k in 0..half { + let wr = tw_re[k * stride]; + let wi = sign * tw_im[k * stride]; + let a = start + k; + let b = a + half; + let xr = re[b] * wr - im[b] * wi; + let xi = re[b] * wi + im[b] * wr; + re[b] = re[a] - xr; + im[b] = im[a] - xi; + re[a] += xr; + im[a] += xi; + } + start += len; + } + len <<= 1; + } + } + + #[test] + fn bit_identical_to_reference_kernel() { + let mut rng = crate::testutil::Rng::new(17); + for bits in 1..=13 { + let n = 1usize << bits; + let fft = Fft::new(n); + for case in 0..4 { + let mut re: Vec = (0..n).map(|_| rng.uniform()).collect(); + let mut im: Vec = match case { + 0 => vec![0.0; n], + 1 => vec![-0.0; n], + _ => (0..n).map(|_| rng.uniform() * 1e3).collect(), + }; + if case == 3 { + // Exact and signed zeros, subnormals and large values. + for (i, (r, m)) in re.iter_mut().zip(im.iter_mut()).enumerate() { + match i % 5 { + 0 => (*r, *m) = (0.0, -0.0), + 1 => (*r, *m) = (-0.0, 0.0), + 2 => *r = 1e-40, + 3 => *m = -3e30, + _ => {} + } + } + } + for inverse in [false, true] { + let (mut r1, mut i1) = (re.clone(), im.clone()); + let (mut r2, mut i2) = (re.clone(), im.clone()); + fft.run(&mut r1, &mut i1, inverse); + run_reference(n, &mut r2, &mut i2, inverse); + for k in 0..n { + assert_eq!(r1[k].to_bits(), r2[k].to_bits(), "n {n} case {case} inverse {inverse} re {k}"); + assert_eq!(i1[k].to_bits(), i2[k].to_bits(), "n {n} case {case} inverse {inverse} im {k}"); + } + } + } + } + } +} diff --git a/crates/audio-dsp/src/generator.rs b/crates/audio-dsp/src/generator.rs new file mode 100644 index 000000000..8003e02c5 --- /dev/null +++ b/crates/audio-dsp/src/generator.rs @@ -0,0 +1,246 @@ +//! Test signals: band-limited (PolyBLEP) sine, square, saw and triangle oscillators, and white +//! and pink noise. +//! +//! [`Oscillator`] produces one sample per call and never allocates, for real-time use (the +//! `signal_generator` effect). [`signal`] renders a whole buffer offline. + +use std::f32::consts::TAU; + +use crate::{MAX_CHANNELS, db_to_gain, sane_sample_rate}; + +/// Most samples [`signal`] renders over all channels (256 MiB of `f32`; about 11 minutes of +/// stereo at 48 kHz). +pub const MAX_SIGNAL_SAMPLES: usize = 1 << 26; + +/// Test-signal waveforms. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum Waveform { + Sine, + Square, + Saw, + Triangle, + WhiteNoise, + PinkNoise, +} + +impl Waveform { + pub const ALL: [Waveform; 6] = [Waveform::Sine, Waveform::Square, Waveform::Saw, Waveform::Triangle, Waveform::WhiteNoise, Waveform::PinkNoise]; + + /// The waveform for a choice index; an index out of range gives [`Waveform::Sine`]. + pub fn from_index(i: usize) -> Waveform { + Self::ALL.get(i).copied().unwrap_or(Waveform::Sine) + } +} + +#[inline] +fn poly_blep(t: f32, dt: f32) -> f32 { + if dt <= 0.0 { + 0.0 + } else if t < dt { + let t = t / dt; + 2.0 * t - t * t - 1.0 + } else if t > 1.0 - dt { + let t = (t - 1.0) / dt; + t * t + 2.0 * t + 1.0 + } else { + 0.0 + } +} + +/// Xorshift32 noise source: deterministic for a seed, and it does not allocate. +#[derive(Clone, Copy, Debug)] +pub(crate) struct Noise(u32); + +impl Noise { + pub(crate) fn new(seed: u32) -> Self { + Noise(if seed == 0 { 0x9E37_79B9 } else { seed }) + } + + #[inline] + fn next_u32(&mut self) -> u32 { + let mut x = self.0; + x ^= x << 13; + x ^= x >> 17; + x ^= x << 5; + self.0 = x; + x + } + + /// Uniform white noise in -1..1. + #[inline] + pub(crate) fn bipolar(&mut self) -> f32 { + (self.next_u32() >> 8) as f32 * (2.0 / 16_777_216.0) - 1.0 + } +} + +/// Pink noise: white noise through a sum of first-order low-passes (the "economy" pinking +/// filter), within about 0.5 dB of a -3 dB per octave slope from 10 Hz to 20 kHz at 48 kHz. +#[derive(Clone, Copy, Debug, Default)] +struct Pinking { + b: [f32; 7], +} + +impl Pinking { + #[inline] + fn next(&mut self, white: f32) -> f32 { + let b = &mut self.b; + b[0] = 0.99886 * b[0] + white * 0.055_517_9; + b[1] = 0.99332 * b[1] + white * 0.075_075_9; + b[2] = 0.96900 * b[2] + white * 0.153_852; + b[3] = 0.86650 * b[3] + white * 0.310_485_6; + b[4] = 0.55000 * b[4] + white * 0.532_952_2; + b[5] = -0.7616 * b[5] - white * 0.016_898; + let out = b[0] + b[1] + b[2] + b[3] + b[4] + b[5] + b[6] + white * 0.5362; + b[6] = white * 0.115_926; + out * 0.11 + } +} + +/// Phase-accumulator oscillator. Periodic waveforms peak at 1; white noise is uniform in -1..1 +/// and pink noise stays within -1..1. +#[derive(Clone, Copy, Debug)] +pub struct Oscillator { + phase: f32, + seed: u32, + noise: Noise, + pink: Pinking, +} + +impl Oscillator { + /// An oscillator at phase 0. `seed` picks the noise sequence. + pub fn new(seed: u32) -> Self { + Oscillator { phase: 0.0, seed, noise: Noise::new(seed), pink: Pinking::default() } + } + + /// Back to phase 0 and the start of the noise sequence. + pub fn reset(&mut self) { + *self = Oscillator::new(self.seed); + } + + /// One sample of `wave`; `step` is frequency divided by sample rate, clamped to 0..0.49 + /// (a non-finite step holds the phase). + #[inline] + pub fn next(&mut self, wave: Waveform, step: f32) -> f32 { + let dt = if step.is_finite() { step.clamp(0.0, 0.49) } else { 0.0 }; + let t = self.phase; + let out = match wave { + Waveform::Sine => (t * TAU).sin(), + Waveform::Saw => 2.0 * t - 1.0 - poly_blep(t, dt), + Waveform::Square => { + let naive = if t < 0.5 { 1.0 } else { -1.0 }; + let t2 = if t + 0.5 >= 1.0 { t - 0.5 } else { t + 0.5 }; + naive + poly_blep(t, dt) - poly_blep(t2, dt) + } + Waveform::Triangle => { + // Starts at 0 and rises, like the sine. + let u = t + 0.25; + let u = if u >= 1.0 { u - 1.0 } else { u }; + 1.0 - 4.0 * (u - 0.5).abs() + } + Waveform::WhiteNoise => self.noise.bipolar(), + Waveform::PinkNoise => { + let w = self.noise.bipolar(); + self.pink.next(w).clamp(-1.0, 1.0) + } + }; + self.phase += dt; + if self.phase >= 1.0 { + self.phase -= 1.0; + } + out + } +} + +/// Renders `frames` frames of a test signal on `channels` identical channels. Periodic +/// waveforms peak at `level_db` dBFS (capped at 0); noise stays at or below it. `channels` is +/// capped at [`crate::MAX_CHANNELS`] and `frames` so that all channels together hold at most +/// [`MAX_SIGNAL_SAMPLES`]; an unusable rate is +/// replaced as [`crate::sane_sample_rate`] describes, a non-finite frequency gives 1 kHz and a +/// NaN level gives -20 dBFS. +pub fn signal(wave: Waveform, freq: f32, level_db: f32, sample_rate: f32, frames: usize, channels: usize) -> Vec> { + let sr = sane_sample_rate(sample_rate); + let channels = channels.min(MAX_CHANNELS); + if channels == 0 { + return Vec::new(); + } + let frames = frames.min(MAX_SIGNAL_SAMPLES / channels); + let f = if freq.is_finite() { freq.clamp(0.0, sr * 0.49) } else { 1000.0 }; + let g = db_to_gain(if level_db.is_nan() { -20.0 } else { level_db.min(0.0) }); + let mut osc = Oscillator::new(0x1234_5678); + let mono: Vec = (0..frames).map(|_| osc.next(wave, f / sr) * g).collect(); + let mut out: Vec> = (1..channels).map(|_| mono.clone()).collect(); + out.push(mono); + out +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::{db, rms, tone_amplitude}; + + #[test] + fn periodic_waves_peak_at_the_level_and_sit_on_the_frequency() { + for wave in [Waveform::Sine, Waveform::Square, Waveform::Saw, Waveform::Triangle] { + let out = signal(wave, 1000.0, -6.0, 48_000.0, 48_000, 2); + assert_eq!(out.len(), 2); + assert_eq!(out[0], out[1]); + let peak = out[0].iter().fold(0.0f32, |m, v| m.max(v.abs())); + // PolyBLEP corrections overshoot the edges of the square and saw slightly. + assert!((db(f64::from(peak)) + 6.0).abs() < 0.6, "{wave:?}: peak {peak}"); + let fundamental = tone_amplitude(&out[0], 1000.0, 48_000.0); + assert!(fundamental > 0.3, "{wave:?}: fundamental {fundamental}"); + } + } + + #[test] + fn the_square_is_band_limited() { + // A 5 kHz square's 9th harmonic (45 kHz) folds to 3 kHz. PolyBLEP keeps that alias well + // below the one a naive square has. + let blep = signal(Waveform::Square, 5_000.0, 0.0, 48_000.0, 48_000, 1).remove(0); + let mut phase = 0.0f32; + let naive: Vec = (0..48_000) + .map(|_| { + let v = if phase < 0.5 { 1.0 } else { -1.0 }; + phase += 5_000.0 / 48_000.0; + if phase >= 1.0 { + phase -= 1.0; + } + v + }) + .collect(); + let alias = |x: &[f32]| tone_amplitude(x, 3_000.0, 48_000.0) / tone_amplitude(x, 5_000.0, 48_000.0); + assert!(alias(&blep) < alias(&naive) / 4.0, "alias {} dB, naive {} dB", db(alias(&blep)), db(alias(&naive))); + } + + #[test] + fn pink_noise_falls_3_db_per_octave() { + let x = signal(Waveform::PinkNoise, 0.0, 0.0, 48_000.0, 1 << 17, 1).remove(0); + // Power in two bands an octave apart, each the sum of 128 equally spaced single-bin probes. + let band = |lo: f64| (0..128).map(|k| tone_amplitude(&x, lo * (1.0 + k as f64 / 128.0), 48_000.0).powi(2)).sum::(); + let low = band(500.0); + let high = band(1000.0); + // Equal-width probes: a -3 dB/octave density gives 3 dB less per probe an octave up. + let slope = 10.0 * (high / low).log10(); + assert!((slope + 3.0).abs() < 1.5, "slope {slope} dB per octave"); + assert!(x.iter().all(|v| v.abs() <= 1.0)); + assert!(rms(&x) > 0.01); + } + + #[test] + fn hostile_arguments_give_bounded_output() { + assert!(signal(Waveform::Sine, f32::NAN, f32::NAN, f32::NAN, 100, 1)[0].iter().all(|v| v.is_finite() && v.abs() <= 0.11)); + assert_eq!(signal(Waveform::Sine, 1000.0, 0.0, 48_000.0, 10, 1000).len(), MAX_CHANNELS); + assert!(signal(Waveform::Saw, 1e9, 40.0, 0.0, 64, 1)[0].iter().all(|v| v.abs() <= 1.5)); + assert!(signal(Waveform::Sine, 1000.0, 0.0, 48_000.0, 0, 2).iter().all(Vec::is_empty)); + assert!(signal(Waveform::Sine, 1000.0, 0.0, 48_000.0, usize::MAX, 0).is_empty()); + } + + #[test] + fn reset_restarts_the_sequence() { + let mut o = Oscillator::new(7); + let a: Vec = (0..64).map(|_| o.next(Waveform::WhiteNoise, 0.0)).collect(); + o.reset(); + let b: Vec = (0..64).map(|_| o.next(Waveform::WhiteNoise, 0.0)).collect(); + assert_eq!(a, b); + } +} diff --git a/crates/audio-dsp/src/lib.rs b/crates/audio-dsp/src/lib.rs new file mode 100644 index 000000000..2e3a74327 --- /dev/null +++ b/crates/audio-dsp/src/lib.rs @@ -0,0 +1,465 @@ +//! Real-time audio DSP for the Craft apps: dependency-free and `wasm32` clean. +//! +//! * [`loudness`]: ITU-R BS.1770-4 / EBU R128 loudness meter (momentary, short-term, +//! integrated, loudness range, sample peak, true peak) and the loudness-normalization helper. +//! * [`effects`]: audio effects behind the common [`AudioEffect`] trait, with a registry +//! ([`effects()`]) describing every effect's parameters (range, unit, default) so a host and +//! its interface can build controls generically. +//! * [`biquad`]: RBJ-cookbook biquads (TDF-II) with analytic magnitude response. +//! * [`sync`]: offset between two recordings of one event (GCC-PHAT, sample-accurate). +//! * [`resample`]: streaming, block-invariant rate conversion for playback on a device at another +//! rate. [`offline`] converts whole buffers with a polyphase windowed-sinc filter. +//! * [`stretch`]: WSOLA time stretch that keeps the pitch. +//! * [`channels`]: channel layouts, ITU-R BS.775 up/downmix, 5.1 mixdown types, the 5.1 panner. +//! * [`pan`]: stereo pan laws, a surround panner over any speaker layout, and first-order +//! ambisonic encoding and decoding. +//! * [`generator`]: band-limited test tones and white and pink noise. +//! +//! Conventions: audio is **planar f32** (`&mut [&mut [f32]]`, one slice per channel, all the same +//! length). `process` never allocates; all buffers are sized at construction. Parameters may be +//! changed between blocks. Some are smoothed per sample when they change (gains, mix amounts and +//! equalizer bands among them); others, such as a compressor's threshold, ratio, knee and times or +//! a limiter's ceiling and release, take effect from the next sample. With the parameters held +//! still, the output does not depend on how the stream is cut into blocks. Recursive state is flushed to zero when it decays below ~1e-30 so +//! denormals never appear (no FTZ/DAZ CPU flags needed, which keeps the crate `unsafe`-free and +//! portable to wasm). +//! +//! **Stability.** The items exported here are the crate's API. A change that removes or changes +//! one is a breaking change and bumps the crate's major version (its minor version while it is +//! below 1.0). Effect ids and parameter ids are part of the API too: hosts save them in their +//! files. + +#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))] +// Per-sample loops index several channel slices with one frame index. +#![allow(clippy::needless_range_loop)] + +pub mod biquad; +pub mod channels; +pub mod design; +pub mod ducking; +pub mod effects; +pub(crate) mod fft; +pub mod generator; +pub mod loudness; +pub mod offline; +pub(crate) mod oversample; +pub mod pan; +pub mod resample; +mod smooth; +pub mod stretch; +pub mod sync; + +pub use effects::{Category, EffectInfo, create_effect, effect_info, effects}; +pub use loudness::{LoudnessMeter, normalize_gain_db}; +pub(crate) use smooth::Smoothed; + +/// Lowest sample rate the crate builds state for; a lower, zero or non-finite rate becomes +/// [`FALLBACK_SAMPLE_RATE`]. +pub const MIN_SAMPLE_RATE: f32 = 1_000.0; +/// Highest sample rate the crate builds state for; a higher rate is clamped to it. +pub const MAX_SAMPLE_RATE: f32 = 1_536_000.0; +/// The rate used in place of an unusable one. +pub const FALLBACK_SAMPLE_RATE: f32 = 48_000.0; +/// Most channels an effect or meter builds state for. Channels past it pass through untouched. +pub const MAX_CHANNELS: usize = 64; + +/// A sample rate the crate can build filters for: `rate` within [`MIN_SAMPLE_RATE`] ..= +/// [`MAX_SAMPLE_RATE`], or [`FALLBACK_SAMPLE_RATE`] when it is below the range, zero or not finite. +pub fn sane_sample_rate(rate: f32) -> f32 { + if rate.is_finite() && rate >= MIN_SAMPLE_RATE { rate.min(MAX_SAMPLE_RATE) } else { FALLBACK_SAMPLE_RATE } +} + +/// A channel count the crate builds state for: at least 1, at most [`MAX_CHANNELS`]. +pub fn sane_channels(channels: usize) -> usize { + channels.clamp(1, MAX_CHANNELS) +} + +/// Unit of a parameter value (for display and control construction). +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum Unit { + /// Unitless scalar. + None, + Decibels, + Hertz, + Milliseconds, + Seconds, + Percent, + /// Filter quality factor. + Q, + /// Compression ratio (`x:1`). + Ratio, + Semitones, + Bpm, + /// Pan / balance position, −100 (left) … +100 (right). + Pan, + /// Boolean toggle: 0 = off, 1 = on. + Toggle, + /// Index into [`ParamSpec::choices`]. + Choice, +} + +/// Static description of one effect parameter. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct ParamSpec { + /// Stable id used by `set_param` / automation (e.g. `"threshold"`, `"b3.freq"`). + pub id: &'static str, + /// Human-readable label. + pub name: &'static str, + pub min: f32, + pub max: f32, + pub default: f32, + pub unit: Unit, + /// Hint that the control should be logarithmic (frequencies, times). + pub log_scale: bool, + /// Option labels when `unit == Unit::Choice` (value is the index). + pub choices: &'static [&'static str], +} + +impl ParamSpec { + /// A continuous (linear) parameter. + pub const fn new(id: &'static str, name: &'static str, min: f32, max: f32, default: f32, unit: Unit) -> Self { + ParamSpec { id, name, min, max, default, unit, log_scale: false, choices: &[] } + } + /// A continuous parameter best shown on a logarithmic control. + pub const fn log(id: &'static str, name: &'static str, min: f32, max: f32, default: f32, unit: Unit) -> Self { + ParamSpec { id, name, min, max, default, unit, log_scale: true, choices: &[] } + } + /// An on/off toggle. + pub const fn toggle(id: &'static str, name: &'static str, default: bool) -> Self { + ParamSpec { id, name, min: 0.0, max: 1.0, default: if default { 1.0 } else { 0.0 }, unit: Unit::Toggle, log_scale: false, choices: &[] } + } + /// A discrete choice; the value is the index into `choices`. A default past the last choice + /// is read as 0, and an empty list has the single value 0. + pub const fn choice(id: &'static str, name: &'static str, choices: &'static [&'static str], default: usize) -> Self { + let default = if default < choices.len() { default } else { 0 }; + let max = choices.len().saturating_sub(1) as f32; + ParamSpec { id, name, min: 0.0, max, default: default as f32, unit: Unit::Choice, log_scale: false, choices } + } + /// Clamp (and for choices/toggles, round) a value into this parameter's domain. + /// NaN maps to the default. When `min` is above `max`, the value is `max`. + pub fn sanitize(&self, v: f32) -> f32 { + if v.is_nan() { + return self.default; + } + let v = v.max(self.min).min(self.max); + match self.unit { + Unit::Choice | Unit::Toggle => v.round(), + _ => v, + } + } +} + +/// A real-time audio effect operating in place on planar channels. +/// +/// Implementations are constructed (allocating) with a sample rate and channel count; after that +/// `process`, `process_keyed`, `set_param` and `reset` never allocate. If `process` receives more +/// channels than the effect was built for, the extra channels are passed through untouched +/// (channel-generic effects such as gain process all of them). +/// +/// The methods after [`AudioEffect::transfer_db`] have defaults, so an effect implements only +/// what it supports. [`AudioEffect::events`], [`AudioEffect::editor`] and the state methods are +/// for instruments and hosted third-party plugins; the built-in effects return `None` and +/// `false`. The editor and state-reader handles are used on the interface thread while the +/// effect keeps processing on the audio thread, and may allocate. +pub trait AudioEffect: Send { + /// Registry id (e.g. `"compressor"`). + fn id(&self) -> &'static str; + /// Parameter descriptions (same as the registry entry's). + fn params(&self) -> &'static [ParamSpec]; + /// Set a parameter by id; the value is clamped to its range. Returns `false` for unknown ids. + /// Takes effect from the next processed sample. Gains, mix amounts and equalizer bands move to + /// the new value smoothly; the crate documentation lists which other parameters change at once. + fn set_param(&mut self, id: &str, value: f32) -> bool; + /// Current (target) value of a parameter. + fn param(&self, id: &str) -> Option; + /// Clear all internal state (delay lines, envelopes, filter memories); smoothed parameters + /// jump to their targets. + fn reset(&mut self); + /// Process one block in place. All channel slices must have the same length (the shortest + /// length is used otherwise). Zero-length blocks are allowed. + fn process(&mut self, channels: &mut [&mut [f32]]); + /// Processing latency in samples (look-ahead / STFT delay) for delay compensation. + fn latency(&self) -> usize { + 0 + } + /// Analytic magnitude response (dB) at `freq` Hz for the current target settings, for + /// filter/EQ effects (drives the graphical EQ editors). `None` when not applicable. + fn response_db(&self, _freq: f64) -> Option { + None + } + /// Static input → output level curve (dB) of a dynamics effect for `band` (0 for + /// single-band processors), at the current settings. `None` when not applicable. + fn transfer_db(&self, _band: usize, _input_db: f32) -> Option { + None + } + /// How long the output keeps sounding after the input stops, in samples (reverb and delay + /// tails), so an offline render can run past the end of its input. + fn tail_samples(&self) -> usize { + 0 + } + /// Gain reduction applied to the last processed block, as a non-negative amount in dB, for + /// metering. 0 for effects that do not reduce gain. + fn gain_reduction_db(&self) -> f32 { + 0.0 + } + /// Whether the effect renders offline (an export, faster or slower than real time) rather + /// than live. Effects start live. + fn set_offline(&mut self, _offline: bool) {} + /// Channels of key (sidechain) input the effect reads in [`AudioEffect::process_keyed`]; 0 + /// when it has no key input. + fn key_channels(&self) -> usize { + 0 + } + /// [`AudioEffect::process`] with a key input: read-only planar channels that drive the + /// effect's detector instead of its own input (a voice pushing music down, a kick drum + /// opening a gate). A key whose channels are shorter than the block, or an empty key, means + /// the effect detects on its own input. Effects without a key input ignore it. + fn process_keyed(&mut self, channels: &mut [&mut [f32]], key: &[&[f32]]) { + let _ = key; + self.process(channels); + } + /// The effect's note and transport input (instruments, tempo-synced effects), or `None`. + fn events(&mut self) -> Option<&mut dyn EventInput> { + None + } + /// The effect's complete internal state as an opaque blob, as its + /// [`AudioEffect::state_reader`] reads it. `None` when it has no state beyond its parameters. + /// May allocate: never call it while processing. + fn save_state(&mut self) -> Option> { + self.state_reader()?.save_state() + } + /// Restores a blob from [`AudioEffect::save_state`]. `false` when unsupported or rejected + /// (the effect keeps its previous state). The data is hostile input. + fn load_state(&mut self, _data: &[u8]) -> bool { + false + } + /// A handle that reads this effect's state from the interface thread while the effect + /// processes on the audio thread, or `None`. + fn state_reader(&mut self) -> Option> { + None + } + /// A handle to the effect's own editor window, or `None`. The handle stays valid after the + /// effect is dropped; its calls then do nothing. + fn editor(&mut self) -> Option> { + None + } +} + +/// The host's transport at the start of a block, for tempo-synced effects and instruments. +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct Transport { + pub playing: bool, + pub recording: bool, + /// Quarter notes per minute. + pub tempo: f64, + pub numerator: u32, + pub denominator: u32, + /// Timeline position. + pub samples: i64, + pub seconds: f64, + pub quarters: f64, + /// Start of the current bar, in quarter notes, and its number (0 for the first bar). + pub bar_start: f64, + pub bar: i64, +} + +/// Note and transport input of an instrument or tempo-synced effect. Every call refers to the +/// next processed block; `offset` is a frame within it. Calls never allocate. +pub trait EventInput { + /// The transport for the next block. + fn set_transport(&mut self, transport: &Transport); + fn note_on(&mut self, offset: usize, note: u8, velocity: u8); + fn note_off(&mut self, offset: usize, note: u8); + /// Any other MIDI 1.0 channel message (control change, pitch bend, pressure, program change). + fn midi(&mut self, offset: usize, message: [u8; 3]); + fn all_notes_off(&mut self); +} + +/// An effect's own editor window, driven from the interface thread while the effect may be +/// processing on the audio thread. +pub trait Editor: Send { + /// Opens (or raises) the editor window. The error says why it cannot. + fn open(&mut self) -> Result<(), String>; + /// Closes the editor window. + fn close(&mut self); + fn is_open(&self) -> bool; + /// Call every interface frame while open: services the editor, notices a window the user + /// closed, and returns the parameter edits made in it as `(parameter id, value)`. + fn idle(&mut self) -> Vec<(String, f32)>; + /// `true` once after the effect's state changed in a way its parameters do not show, so the + /// host saves the new state. + fn state_changed(&mut self) -> bool { + false + } + /// Tells the editor that a parameter changed elsewhere, so it shows the new value. + fn set_param(&mut self, _id: &str, _value: f32) {} + /// The effect's own text for a parameter value, or `None` when the host formats it. + fn value_text(&mut self, _id: &str, _value: f32) -> Option { + None + } +} + +/// Reads an effect's state from the interface thread. Closures returning the blob are readers. +pub trait StateReader: Send { + /// What [`AudioEffect::save_state`] would return; `None` once the effect is gone. + fn save_state(&mut self) -> Option>; +} + +impl Option> + Send> StateReader for F { + fn save_state(&mut self) -> Option> { + self() + } +} + +/// The key channels to detect on: `key` when it has channels and each covers the block's +/// `frames`, else `None` (the effect detects on its own input). +#[inline] +pub(crate) fn usable_key<'a>(key: &'a [&'a [f32]], frames: usize) -> Option<&'a [&'a [f32]]> { + (!key.is_empty() && key.iter().all(|k| k.len() >= frames)).then_some(key) +} + +/// Parameter value storage shared by the effect implementations. +#[derive(Clone, Debug)] +pub(crate) struct ParamValues { + specs: &'static [ParamSpec], + values: Vec, +} + +impl ParamValues { + pub(crate) fn new(specs: &'static [ParamSpec]) -> Self { + ParamValues { specs, values: specs.iter().map(|s| s.default).collect() } + } + pub(crate) fn index_of(&self, id: &str) -> Option { + self.specs.iter().position(|s| s.id == id) + } + /// Returns `true` if the id exists. + pub(crate) fn set(&mut self, id: &str, v: f32) -> bool { + match self.index_of(id) { + Some(i) => { + self.values[i] = self.specs[i].sanitize(v); + true + } + None => false, + } + } + pub(crate) fn get(&self, id: &str) -> Option { + self.index_of(id).map(|i| self.values[i]) + } + /// Value of a parameter that is known to exist (0 otherwise; a missing id is a + /// programming error that debug builds catch). + pub(crate) fn v(&self, id: &str) -> f32 { + debug_assert!(self.get(id).is_some(), "unknown parameter {id}"); + self.get(id).unwrap_or(0.0) + } + pub(crate) fn on(&self, id: &str) -> bool { + self.v(id) >= 0.5 + } + pub(crate) fn idx(&self, id: &str) -> usize { + self.v(id).max(0.0) as usize + } +} + +/// Generates the id/params/set_param/param methods of [`AudioEffect`] for a struct with a +/// `pv: ParamValues` field, a `PARAMS` const and an `apply_params(&mut self, snap: bool)` method. +macro_rules! param_plumbing { + ($id:expr) => { + fn id(&self) -> &'static str { + $id + } + fn params(&self) -> &'static [$crate::ParamSpec] { + Self::PARAMS + } + fn set_param(&mut self, id: &str, value: f32) -> bool { + if self.pv.set(id, value) { + self.apply_params(false); + true + } else { + false + } + } + fn param(&self, id: &str) -> Option { + self.pv.get(id) + } + }; +} +pub(crate) use param_plumbing; + +/// Decibels → linear amplitude. +#[inline] +pub(crate) fn db_to_gain(db: f32) -> f32 { + 10f32.powf(db / 20.0) +} + +/// Linear amplitude → decibels (−inf for 0). +#[cfg(test)] +pub(crate) fn gain_to_db(g: f32) -> f32 { + 20.0 * g.abs().log10() +} + +/// Flush tiny values to zero (denormal protection for recursive state). Non-finite values are +/// zeroed too, so one NaN or infinite input sample cannot poison the state until `reset`. +#[inline(always)] +pub(crate) fn flush(x: f64) -> f64 { + if (1e-30..=f64::MAX).contains(&x.abs()) { x } else { 0.0 } +} + +/// f32 variant of [`flush`] for f32 delay lines. +#[inline(always)] +pub(crate) fn flush32(x: f32) -> f32 { + if (1e-25..=f32::MAX).contains(&x.abs()) { x } else { 0.0 } +} + +/// Common block length of planar channels. +#[inline] +pub(crate) fn block_len(channels: &[&mut [f32]]) -> usize { + channels.iter().map(|c| c.len()).min().unwrap_or(0) +} + +#[cfg(test)] +pub(crate) mod testutil { + /// Tiny deterministic PRNG (xorshift64*) for tests. + pub struct Rng(u64); + impl Rng { + pub fn new(seed: u64) -> Self { + Rng(seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) | 1) + } + pub fn next_u64(&mut self) -> u64 { + let mut x = self.0; + x ^= x >> 12; + x ^= x << 25; + x ^= x >> 27; + self.0 = x; + x.wrapping_mul(0x2545_F491_4F6C_DD1D) + } + /// Uniform in [-1, 1). + pub fn uniform(&mut self) -> f32 { + ((self.next_u64() >> 40) as f32 / (1u64 << 24) as f32) * 2.0 - 1.0 + } + } + + pub fn sine(freq: f64, amp: f64, sr: f64, n: usize, phase: f64) -> Vec { + (0..n).map(|i| (amp * (2.0 * std::f64::consts::PI * freq * i as f64 / sr + phase).sin()) as f32).collect() + } + + pub fn rms(x: &[f32]) -> f64 { + if x.is_empty() { + return 0.0; + } + (x.iter().map(|&v| (v as f64) * (v as f64)).sum::() / x.len() as f64).sqrt() + } + + pub fn db(x: f64) -> f64 { + 20.0 * x.log10() + } + + /// Amplitude of the `freq` component of `x` (single-bin DFT / Goertzel-style correlation). + pub fn tone_amplitude(x: &[f32], freq: f64, sr: f64) -> f64 { + let (mut re, mut im) = (0.0f64, 0.0f64); + for (i, &v) in x.iter().enumerate() { + let w = 2.0 * std::f64::consts::PI * freq * i as f64 / sr; + re += v as f64 * w.cos(); + im += v as f64 * w.sin(); + } + 2.0 * (re * re + im * im).sqrt() / x.len() as f64 + } +} diff --git a/crates/audio-dsp/src/loudness.rs b/crates/audio-dsp/src/loudness.rs new file mode 100644 index 000000000..d8de87a15 --- /dev/null +++ b/crates/audio-dsp/src/loudness.rs @@ -0,0 +1,955 @@ +//! ITU-R BS.1770-4 / EBU R128 loudness metering. +//! +//! * K-weighting: the two BS.1770 stages (high-shelf "pre-filter" and the RLB high-pass) are +//! derived from their analog prototypes (center frequency, Q, gain) through the bilinear +//! transform, so any sample rate is supported; at 48 kHz they reproduce the coefficient table in +//! the recommendation. +//! * Momentary (400 ms), short-term (3 s) windows are evaluated every 100 ms (75 % overlap for the +//! 400 ms gating blocks, as specified). +//! * Integrated loudness uses the two-stage gate (−70 LUFS absolute, −10 LU relative). Gating +//! blocks are accumulated in a fixed 0.01 LU histogram that also stores exact energy sums, so the +//! meter can run for arbitrarily long programs without allocating and the result is exact up +//! to the placement of blocks within 0.01 LU of the relative threshold. +//! * Loudness range (EBU Tech 3342): short-term values, −70 LUFS absolute and −20 LU relative +//! gate, LRA = 95th − 10th percentile. +//! * Sample peak and true peak (polyphase oversampling to ≥ 176.4 kHz, see [`crate::oversample`]). + +use crate::biquad::{Biquad, Coeffs}; +use crate::oversample::{Interpolator, PolyphaseBank, TAPS_PER_PHASE, true_peak_factor}; +use crate::pan::SpeakerPos; +use std::f64::consts::PI; + +const HIST_MIN: f64 = -70.0; +const HIST_MAX: f64 = 20.0; +const HIST_STEP: f64 = 0.01; +const HIST_BINS: usize = ((HIST_MAX - HIST_MIN) / HIST_STEP) as usize; +/// Short-term window in 100 ms sub-blocks. +const ST_SUBBLOCKS: usize = 30; +/// Momentary window in 100 ms sub-blocks. +const M_SUBBLOCKS: usize = 4; + +/// Loudness of a mean-square energy (already channel-weighted), in LUFS. +#[inline] +pub fn energy_to_lufs(e: f64) -> f64 { + if e <= 0.0 { f64::NEG_INFINITY } else { -0.691 + 10.0 * e.log10() } +} + +#[cfg(test)] +fn lufs_to_energy(l: f64) -> f64 { + 10f64.powf((l + 0.691) / 10.0) +} + +/// The shelf or high-pass frequency `f0`, kept below Nyquist at `sample_rate` so the digital +/// filter stays stable, and the rate made usable as [`crate::sane_sample_rate`] describes. +fn usable(f0: f64, sample_rate: f64) -> (f64, f64) { + let sr = f64::from(crate::sane_sample_rate(sample_rate as f32)); + (f0.min(sr * 0.45), sr) +} + +/// Stage 1 of K-weighting: the high-shelf ("head") pre-filter for `sample_rate`. Below about +/// 3.7 kHz the shelf frequency is lowered to 0.45 × the rate so the filter stays stable. +pub fn k_prefilter(sample_rate: f64) -> Coeffs { + // Analog prototype parameters of the BS.1770 shelving stage. + let (f0, sample_rate) = usable(1_681.974_450_955_533, sample_rate); + let gain_db = 3.999_843_853_973_347; + let q = 0.707_175_236_955_419_6; + let k = (PI * f0 / sample_rate).tan(); + let vh = 10f64.powf(gain_db / 20.0); + let vb = vh.powf(0.499_666_774_154_541_6); + let a0 = 1.0 + k / q + k * k; + Coeffs { + b0: (vh + vb * k / q + k * k) / a0, + b1: 2.0 * (k * k - vh) / a0, + b2: (vh - vb * k / q + k * k) / a0, + a1: 2.0 * (k * k - 1.0) / a0, + a2: (1.0 - k / q + k * k) / a0, + } +} + +/// Stage 2 of K-weighting: the RLB high-pass for `sample_rate`. +pub fn k_rlb(sample_rate: f64) -> Coeffs { + let (f0, sample_rate) = usable(38.135_470_876_024_44, sample_rate); + let q = 0.500_327_037_323_877_3; + let k = (PI * f0 / sample_rate).tan(); + let a0 = 1.0 + k / q + k * k; + Coeffs { b0: 1.0, b1: -2.0, b2: 1.0, a1: 2.0 * (k * k - 1.0) / a0, a2: (1.0 - k / q + k * k) / a0 } +} + +/// Default BS.1770 channel weights for a channel count, in the WAV channel order: 5.0 is +/// L R C Ls Rs, 5.1 is L R C LFE Ls Rs, 7.1 is L R C LFE Lb Rb Ls Rs, and 7.1.4 adds four height +/// channels. The weights are those [`channel_weights`] gives for those speaker positions. Any other +/// count weights every channel 1.0. +pub fn default_channel_weights(channels: usize) -> Vec { + let s = |az: f32, el: f32, lfe: bool| SpeakerPos { az, el, lfe }; + let bed = [s(-30.0, 0.0, false), s(30.0, 0.0, false), s(0.0, 0.0, false)]; + let lfe = [s(0.0, 0.0, true)]; + let surround = [s(-110.0, 0.0, false), s(110.0, 0.0, false)]; + let back = [s(-150.0, 0.0, false), s(150.0, 0.0, false)]; + let side = [s(-90.0, 0.0, false), s(90.0, 0.0, false)]; + let height = [s(-45.0, 45.0, false), s(45.0, 45.0, false), s(-135.0, 45.0, false), s(135.0, 45.0, false)]; + let layout: Vec = match channels { + 5 => [&bed[..], &surround].concat(), + 6 => [&bed[..], &lfe, &surround].concat(), + 8 => [&bed[..], &lfe, &back, &side].concat(), + 12 => [&bed[..], &lfe, &back, &side, &height].concat(), + n => return vec![1.0; n], + }; + channel_weights(&layout) +} + +/// BS.1770-4 channel weights from speaker positions: 0 for the LFE, 1.41 (about +1.5 dB) for a +/// speaker below 30 degrees of elevation at an azimuth of 60 to 120 degrees either side, and 1.0 +/// for every other speaker. +pub fn channel_weights(layout: &[SpeakerPos]) -> Vec { + layout + .iter() + .map(|p| { + if p.lfe { + 0.0 + } else if p.el.abs() < 30.0 && (60.0..=120.0).contains(&p.az.abs()) { + 1.41 + } else { + 1.0 + } + }) + .collect() +} + +/// Histogram of block loudness values with exact energy sums per bin. +#[derive(Clone, Debug)] +struct Histogram { + count: Vec, + energy: Vec, +} + +impl Histogram { + fn new() -> Self { + Histogram { count: vec![0; HIST_BINS], energy: vec![0.0; HIST_BINS] } + } + fn clear(&mut self) { + self.count.iter_mut().for_each(|c| *c = 0); + self.energy.iter_mut().for_each(|e| *e = 0.0); + } + fn bin_of(l: f64) -> usize { + (((l - HIST_MIN) / HIST_STEP).floor().max(0.0) as usize).min(HIST_BINS - 1) + } + fn bin_center(i: usize) -> f64 { + HIST_MIN + (i as f64 + 0.5) * HIST_STEP + } + /// Add a block if it passes the absolute gate. + fn add(&mut self, energy: f64) { + let l = energy_to_lufs(energy); + if l >= HIST_MIN { + let b = Self::bin_of(l); + self.count[b] += 1; + self.energy[b] += energy; + } + } + /// Power mean (energy) of bins from `from` upward; None if empty. + fn mean_energy_from(&self, from: usize) -> Option<(f64, u64)> { + let (mut e, mut n) = (0.0, 0u64); + for i in from..HIST_BINS { + e += self.energy[i]; + n += self.count[i]; + } + (n > 0).then(|| (e / n as f64, n)) + } + /// Relative-gate start bin for a gate of `rel` LU below the absolute-gated mean. + fn relative_gate_bin(&self, rel: f64) -> Option { + let (e, _) = self.mean_energy_from(0)?; + let thr = energy_to_lufs(e) + rel; + Some(if thr < HIST_MIN { 0 } else { Self::bin_of(thr) }) + } +} + +/// Streaming BS.1770-4 / EBU R128 loudness meter for planar or interleaved f32 audio. +#[derive(Clone, Debug)] +pub struct LoudnessMeter { + sample_rate: f64, + channels: usize, + weights: Vec, + pre: Coeffs, + rlb: Coeffs, + filt: Vec<(Biquad, Biquad)>, + /// Per-channel sum of squares in the current 100 ms sub-block. + acc: Vec, + sub_len: usize, + sub_pos: usize, + /// Ring of (weighted energy sum, sample count) for the last 30 sub-blocks. + ring: [(f64, usize); ST_SUBBLOCKS], + ring_pos: usize, + subblocks_seen: u64, + momentary: f64, + short_term: f64, + max_momentary: f64, + max_short_term: f64, + integrated_hist: Histogram, + lra_hist: Histogram, + /// The program readings, recomputed from the histograms at each 100 ms step. + integrated: f64, + relative_threshold: f64, + loudness_range: f64, + sample_peak: Vec, + true_peak: Vec, + bank: PolyphaseBank, + interp: Vec, +} + +impl LoudnessMeter { + /// A meter for `channels` channels at `sample_rate` Hz with default BS.1770 weights. The + /// channel count is clamped to 1 ..= [`crate::MAX_CHANNELS`], and an unusable rate is + /// replaced as [`crate::sane_sample_rate`] describes. + pub fn new(sample_rate: f64, channels: usize) -> Self { + let channels = crate::sane_channels(channels); + let sample_rate = f64::from(crate::sane_sample_rate(sample_rate as f32)); + let sub_len = ((sample_rate * 0.1).round() as usize).max(1); + LoudnessMeter { + sample_rate, + channels, + weights: default_channel_weights(channels), + pre: k_prefilter(sample_rate), + rlb: k_rlb(sample_rate), + filt: vec![(Biquad::new(), Biquad::new()); channels], + acc: vec![0.0; channels], + sub_len, + sub_pos: 0, + ring: [(0.0, 0); ST_SUBBLOCKS], + ring_pos: 0, + subblocks_seen: 0, + momentary: f64::NEG_INFINITY, + short_term: f64::NEG_INFINITY, + max_momentary: f64::NEG_INFINITY, + max_short_term: f64::NEG_INFINITY, + integrated_hist: Histogram::new(), + lra_hist: Histogram::new(), + integrated: f64::NEG_INFINITY, + relative_threshold: f64::NEG_INFINITY, + loudness_range: 0.0, + sample_peak: vec![0.0; channels], + true_peak: vec![0.0; channels], + bank: PolyphaseBank::new(true_peak_factor(sample_rate)), + interp: vec![Interpolator::default(); channels], + } + } + + pub fn sample_rate(&self) -> f64 { + self.sample_rate + } + pub fn channels(&self) -> usize { + self.channels + } + + /// Override the per-channel weights (missing entries are 1.0, extra ignored). A negative or + /// non-finite weight counts as 0, which leaves that channel out. + pub fn set_channel_weights(&mut self, weights: &[f64]) { + for (i, w) in self.weights.iter_mut().enumerate() { + let v = weights.get(i).copied().unwrap_or(1.0); + *w = if v.is_finite() && v > 0.0 { v } else { 0.0 }; + } + } + + /// Clear all measurements and filter state, for a new program that does not continue the + /// audio fed so far. + pub fn reset(&mut self) { + self.filt.iter_mut().for_each(|(a, b)| { + a.reset(); + b.reset() + }); + self.reset_program(); + } + + /// Clear every measurement (momentary, short-term, their maximums, integrated loudness, + /// loudness range, sample peak and true peak) but keep the K-weighting filter state, for a + /// new program that continues a live stream: the loudness readings do not see a filter + /// transient. The true-peak interpolator starts empty, so samples from before the reset do + /// not count for the new program. + pub fn reset_program(&mut self) { + self.interp.iter_mut().for_each(Interpolator::reset); + self.integrated_hist.clear(); + self.lra_hist.clear(); + self.integrated = f64::NEG_INFINITY; + self.relative_threshold = f64::NEG_INFINITY; + self.loudness_range = 0.0; + self.acc.iter_mut().for_each(|a| *a = 0.0); + self.sample_peak.iter_mut().for_each(|p| *p = 0.0); + self.true_peak.iter_mut().for_each(|p| *p = 0.0); + self.sub_pos = 0; + self.ring = [(0.0, 0); ST_SUBBLOCKS]; + self.ring_pos = 0; + self.subblocks_seen = 0; + self.momentary = f64::NEG_INFINITY; + self.short_term = f64::NEG_INFINITY; + self.max_momentary = f64::NEG_INFINITY; + self.max_short_term = f64::NEG_INFINITY; + } + + /// One sample of channel `ch`. A non-finite sample is measured as silence, so one bad + /// sample does not leave the filters and every later reading at NaN. + #[inline(always)] + fn feed(&mut self, ch: usize, x: f32) { + let x = if x.is_finite() { x } else { 0.0 }; + let (pre, rlb) = &mut self.filt[ch]; + let y = rlb.tick(&self.rlb, pre.tick(&self.pre, x as f64)); + self.acc[ch] += y * y; + let a = x.abs(); + if a > self.sample_peak[ch] { + self.sample_peak[ch] = a; + } + let tp = self.interp[ch].push_peak(&self.bank, x).max(a); + if tp > self.true_peak[ch] { + self.true_peak[ch] = tp; + } + } + + /// Feed a block of planar audio (one slice per channel; extra channels are ignored, missing + /// channels count as silence). + pub fn process(&mut self, channels: &[&[f32]]) { + let n = channels.iter().take(self.channels).map(|c| c.len()).min().unwrap_or(0); + let mut pos = 0; + while pos < n { + let take = (n - pos).min(self.sub_len - self.sub_pos); + for (ch, data) in channels.iter().take(self.channels).enumerate() { + for &x in &data[pos..pos + take] { + self.feed(ch, x); + } + } + for ch in channels.len()..self.channels { + for _ in 0..take { + self.feed(ch, 0.0); + } + } + pos += take; + self.sub_pos += take; + if self.sub_pos == self.sub_len { + self.finish_subblock(); + } + } + } + + /// Feed a block of interleaved audio with `self.channels()` channels per frame. + pub fn process_interleaved(&mut self, data: &[f32]) { + let nch = self.channels; + let frames = data.len() / nch; + let mut f = 0; + while f < frames { + let take = (frames - f).min(self.sub_len - self.sub_pos); + for i in f..f + take { + for ch in 0..nch { + self.feed(ch, data[i * nch + ch]); + } + } + f += take; + self.sub_pos += take; + if self.sub_pos == self.sub_len { + self.finish_subblock(); + } + } + } + + fn finish_subblock(&mut self) { + let mut e = 0.0; + for ch in 0..self.channels { + e += self.weights[ch] * self.acc[ch]; + self.acc[ch] = 0.0; + } + self.ring[self.ring_pos] = (e, self.sub_pos); + self.ring_pos = (self.ring_pos + 1) % ST_SUBBLOCKS; + self.sub_pos = 0; + self.subblocks_seen += 1; + + let window = |k: usize, ring: &[(f64, usize); ST_SUBBLOCKS], pos: usize, sub_len: usize| { + let mut s = 0.0; + for i in 0..k { + s += ring[(pos + ST_SUBBLOCKS - 1 - i) % ST_SUBBLOCKS].0; + } + s / (k * sub_len) as f64 + }; + // A window reads −∞ until it holds a full 400 ms or 3 s of audio: a reading over a + // part-filled ring would count the empty sub-blocks as silence and read low. + if self.subblocks_seen >= M_SUBBLOCKS as u64 { + let em = window(M_SUBBLOCKS, &self.ring, self.ring_pos, self.sub_len); + self.momentary = energy_to_lufs(em); + self.integrated_hist.add(em); + self.max_momentary = self.max_momentary.max(self.momentary); + self.integrated = self.compute_integrated(); + self.relative_threshold = self.compute_relative_threshold(); + } + if self.subblocks_seen >= ST_SUBBLOCKS as u64 { + let es = window(ST_SUBBLOCKS, &self.ring, self.ring_pos, self.sub_len); + self.short_term = energy_to_lufs(es); + self.lra_hist.add(es); + self.max_short_term = self.max_short_term.max(self.short_term); + self.loudness_range = self.compute_loudness_range(); + } + } + + /// Momentary loudness (last 400 ms), LUFS; updated every 100 ms. −∞ for silence and for the + /// first 400 ms after the meter is made or reset. + pub fn momentary(&self) -> f64 { + self.momentary + } + /// Short-term loudness (last 3 s), LUFS; updated every 100 ms. −∞ for silence and for the + /// first 3 s after the meter is made or reset. + pub fn short_term(&self) -> f64 { + self.short_term + } + /// Maximum momentary loudness so far. + pub fn max_momentary(&self) -> f64 { + self.max_momentary + } + /// Maximum short-term loudness so far. + pub fn max_short_term(&self) -> f64 { + self.max_short_term + } + + /// Gated integrated loudness (BS.1770-4), LUFS. −∞ if nothing passed the gates. The value is + /// computed once per 100 ms gating step, so reading it does not scan the histogram. + pub fn integrated(&self) -> f64 { + self.integrated + } + + fn compute_integrated(&self) -> f64 { + let h = &self.integrated_hist; + match h.relative_gate_bin(-10.0).and_then(|b| h.mean_energy_from(b)) { + Some((e, _)) => energy_to_lufs(e), + None => f64::NEG_INFINITY, + } + } + + /// Relative gate threshold used for the integrated loudness (LUFS). + pub fn relative_threshold(&self) -> f64 { + self.relative_threshold + } + + fn compute_relative_threshold(&self) -> f64 { + match self.integrated_hist.mean_energy_from(0) { + Some((e, _)) => energy_to_lufs(e) - 10.0, + None => f64::NEG_INFINITY, + } + } + + /// Loudness range (EBU Tech 3342), LU. 0 when too little signal. The value is computed once + /// per 100 ms step, so reading it does not scan the histogram. + pub fn loudness_range(&self) -> f64 { + self.loudness_range + } + + fn compute_loudness_range(&self) -> f64 { + let h = &self.lra_hist; + let Some(start) = h.relative_gate_bin(-20.0) else { return 0.0 }; + let n: u64 = h.count[start..].iter().sum(); + if n == 0 { + return 0.0; + } + let percentile = |p: f64| { + // Nearest-rank on the sorted gated values. + let rank = ((p * (n - 1) as f64).round() as u64).min(n - 1); + let mut c = 0u64; + for i in start..HIST_BINS { + c += h.count[i]; + if c > rank { + return Histogram::bin_center(i); + } + } + Histogram::bin_center(HIST_BINS - 1) + }; + (percentile(0.95) - percentile(0.10)).max(0.0) + } + + /// Maximum absolute sample value over all channels (linear). + pub fn sample_peak(&self) -> f64 { + self.sample_peak.iter().fold(0.0f32, |a, &b| a.max(b)) as f64 + } + /// Per-channel sample peak (linear). + pub fn sample_peak_channel(&self, ch: usize) -> f64 { + self.sample_peak.get(ch).copied().unwrap_or(0.0) as f64 + } + /// Maximum true peak over all channels (linear). + pub fn true_peak(&self) -> f64 { + self.true_peak.iter().fold(0.0f32, |a, &b| a.max(b)) as f64 + } + /// Per-channel true peak (linear). + pub fn true_peak_channel(&self, ch: usize) -> f64 { + self.true_peak.get(ch).copied().unwrap_or(0.0) as f64 + } + /// Maximum true peak in dBTP. + pub fn true_peak_dbtp(&self) -> f64 { + 20.0 * self.true_peak().log10() + } + + /// Count the inter-sample peaks the last samples make once the program has ended, as if + /// silence followed: the interpolator lags its input by a few samples, so a peak near the end + /// is otherwise missed. Audio fed afterwards is measured as a continuation, unaffected. + pub fn end_program(&mut self) { + for (ch, interp) in self.interp.iter().enumerate() { + let mut tail = interp.clone(); + for _ in 0..TAPS_PER_PHASE { + let tp = tail.push_peak(&self.bank, 0.0); + if let Some(peak) = self.true_peak.get_mut(ch) { + *peak = peak.max(tp); + } + } + } + } + + /// Snapshot of all program measurements. + pub fn summary(&self) -> LoudnessSummary { + LoudnessSummary { + integrated_lufs: self.integrated(), + loudness_range_lu: self.loudness_range(), + max_momentary_lufs: self.max_momentary, + max_short_term_lufs: self.max_short_term, + sample_peak_dbfs: 20.0 * self.sample_peak().log10(), + true_peak_dbtp: self.true_peak_dbtp(), + } + } +} + +/// Program loudness measurements (EBU R128 set). +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct LoudnessSummary { + pub integrated_lufs: f64, + pub loudness_range_lu: f64, + pub max_momentary_lufs: f64, + pub max_short_term_lufs: f64, + pub sample_peak_dbfs: f64, + pub true_peak_dbtp: f64, +} + +/// Measure a whole planar program in one call. +pub fn measure(channels: &[&[f32]], sample_rate: f64) -> LoudnessSummary { + let mut m = LoudnessMeter::new(sample_rate, channels.len()); + m.process(channels); + m.end_program(); + m.summary() +} + +/// Gain (dB) that moves a program measured at `measured_lufs` to `target_lufs`. +/// Returns 0 for silent / unmeasurable input. +pub fn normalize_gain_db(measured_lufs: f64, target_lufs: f64) -> f64 { + if measured_lufs.is_finite() && target_lufs.is_finite() { target_lufs - measured_lufs } else { 0.0 } +} + +/// Like [`normalize_gain_db`] but limited so that the resulting true peak does not exceed +/// `max_true_peak_dbtp`. A linear gain cannot lower peaks on its own, so the result falls short +/// of the loudness target when the peak limit binds. +pub fn normalize_gain_db_peak_limited(measured_lufs: f64, target_lufs: f64, true_peak_dbtp: f64, max_true_peak_dbtp: f64) -> f64 { + let g = normalize_gain_db(measured_lufs, target_lufs); + if true_peak_dbtp.is_finite() { g.min(max_true_peak_dbtp - true_peak_dbtp) } else { g } +} + +/// Expected loudness energy weighting of a pure tone at `freq` through K-weighting (|H|², for +/// tests and analytical tooling). +pub fn k_weighting_power(freq: f64, sample_rate: f64) -> f64 { + let a = k_prefilter(sample_rate).magnitude(freq, sample_rate); + let b = k_rlb(sample_rate).magnitude(freq, sample_rate); + (a * b).powi(2) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::*; + + fn dbfs(db: f64) -> f64 { + 10f64.powf(db / 20.0) + } + + /// Stereo program made of (seconds, dBFS) sine segments. + fn segments(freq: f64, sr: f64, segs: &[(f64, f64)]) -> Vec { + let mut out = Vec::new(); + let mut phase_idx = 0usize; + for &(secs, level) in segs { + let n = (secs * sr).round() as usize; + let a = dbfs(level); + for _ in 0..n { + out.push((a * (2.0 * PI * freq * phase_idx as f64 / sr).sin()) as f32); + phase_idx += 1; + } + } + out + } + + fn stereo_measure(x: &[f32], sr: f64) -> LoudnessMeter { + let mut m = LoudnessMeter::new(sr, 2); + // Feed in odd-sized blocks to exercise the sub-block splitting. + for chunk in x.chunks(1237) { + m.process(&[chunk, chunk]); + } + m + } + + #[test] + fn k_weighting_matches_bs1770_table_at_48k() { + let p = k_prefilter(48000.0); + assert!((p.b0 - 1.535_124_859_586_97).abs() < 1e-8); + assert!((p.b1 + 2.691_696_189_406_38).abs() < 1e-8); + assert!((p.b2 - 1.198_392_810_852_85).abs() < 1e-8); + assert!((p.a1 + 1.690_659_293_182_41).abs() < 1e-8); + assert!((p.a2 - 0.732_480_774_215_85).abs() < 1e-8); + let r = k_rlb(48000.0); + assert!((r.a1 + 1.990_047_454_833_98).abs() < 1e-8); + assert!((r.a2 - 0.990_072_250_366_21).abs() < 1e-8); + } + + #[test] + fn k_weighting_shape_is_sample_rate_independent() { + for sr in [32000.0, 44100.0, 48000.0, 96000.0, 192000.0] { + let db = |f| 10.0 * k_weighting_power(f, sr).log10(); + // ~+0.69 dB at 1 kHz, ~+4 dB high shelf, strong low-cut. + assert!((db(1000.0) - 0.691).abs() < 0.03, "sr {sr}: {}", db(1000.0)); + assert!((db(10000.0) - 4.0).abs() < 0.3, "sr {sr}"); + assert!(db(20.0) < -10.0, "sr {sr}"); + } + } + + #[test] + fn tech3341_case1_and_2_stereo_sine() { + for (sr, freq) in [(48000.0, 1000.0), (44100.0, 997.0), (96000.0, 1000.0)] { + for level in [-23.0, -33.0] { + let x = segments(freq, sr, &[(20.0, level)]); + let m = stereo_measure(&x, sr); + assert!((m.integrated() - level).abs() < 0.1, "sr {sr} I {}", m.integrated()); + assert!((m.momentary() - level).abs() < 0.1, "M {}", m.momentary()); + assert!((m.short_term() - level).abs() < 0.1, "S {}", m.short_term()); + assert!((m.max_momentary() - level).abs() < 0.1); + assert!(m.loudness_range() < 0.1); + } + } + } + + #[test] + fn interleaved_matches_planar() { + let sr = 48000.0; + let x = segments(1000.0, sr, &[(5.0, -20.0)]); + let il: Vec = x.iter().flat_map(|&v| [v, v]).collect(); + let mut m = LoudnessMeter::new(sr, 2); + m.process_interleaved(&il); + let p = stereo_measure(&x, sr); + assert!((m.integrated() - p.integrated()).abs() < 1e-9); + } + + #[test] + fn tech3341_case3_4_gating() { + let sr = 48000.0; + // Case 3: -36 / -23 / -36 dBFS for 10 / 60 / 10 s → -23.0 LUFS. + let x = segments(1000.0, sr, &[(10.0, -36.0), (60.0, -23.0), (10.0, -36.0)]); + let m = stereo_measure(&x, sr); + assert!((m.integrated() + 23.0).abs() < 0.1, "{}", m.integrated()); + // Case 4: -72 / -36 / -23 / -36 / -72 dBFS for 10/10/60/10/10 s → -23.0 LUFS. + let x = segments(1000.0, sr, &[(10.0, -72.0), (10.0, -36.0), (60.0, -23.0), (10.0, -36.0), (10.0, -72.0)]); + let m = stereo_measure(&x, sr); + assert!((m.integrated() + 23.0).abs() < 0.1, "{}", m.integrated()); + } + + #[test] + fn tech3341_case5_relative_gate() { + let sr = 48000.0; + let x = segments(1000.0, sr, &[(20.0, -26.0), (20.1, -20.0), (20.0, -26.0)]); + let m = stereo_measure(&x, sr); + assert!((m.integrated() + 23.0).abs() < 0.1, "{}", m.integrated()); + } + + #[test] + fn silence_and_below_gate() { + let sr = 48000.0; + let mut m = LoudnessMeter::new(sr, 2); + let z = vec![0.0f32; 48000 * 2]; + m.process(&[&z, &z]); + assert_eq!(m.integrated(), f64::NEG_INFINITY); + assert_eq!(m.loudness_range(), 0.0); + let x = segments(1000.0, sr, &[(5.0, -80.0)]); + let m = stereo_measure(&x, sr); + assert_eq!(m.integrated(), f64::NEG_INFINITY); + } + + #[test] + fn tech3342_loudness_range() { + let sr = 48000.0; + let cases: [(&[(f64, f64)], f64); 4] = [ + (&[(20.0, -20.0), (20.0, -30.0)], 10.0), + (&[(20.0, -20.0), (20.0, -15.0)], 5.0), + (&[(20.0, -40.0), (20.0, -20.0)], 20.0), + (&[(20.0, -50.0), (20.0, -35.0), (20.0, -20.0), (20.0, -35.0), (20.0, -50.0)], 15.0), + ]; + for (segs, expect) in cases { + let x = segments(1000.0, sr, segs); + let m = stereo_measure(&x, sr); + assert!((m.loudness_range() - expect).abs() < 1.0, "LRA {} expected {expect}", m.loudness_range()); + } + } + + #[test] + fn log_sweep_matches_analytic_k_weighting() { + let sr = 48000.0; + let secs = 20.0; + let n = (sr * secs) as usize; + let (f1, f2) = (20.0f64, 20000.0f64); + let k = (f2 / f1).ln(); + let amp = dbfs(-20.0); + let mut phase = 0.0f64; + let mut x = Vec::with_capacity(n); + let mut expected_e = 0.0; + for i in 0..n { + let f = f1 * (k * i as f64 / n as f64).exp(); + x.push((amp * phase.sin()) as f32); + phase += 2.0 * PI * f / sr; + // Stereo: 2 channels × A²/2 × |H(f)|². + expected_e += amp * amp * k_weighting_power(f, sr); + } + expected_e /= n as f64; + // Ungated average of the same signal: compare with the mean of momentary energies, i.e. + // the integrated value is gated, so build the expectation the same way using short blocks. + let m = stereo_measure(&x, sr); + let expect = energy_to_lufs(expected_e); + // Gating removes the quiet low-frequency start, so integrated ≥ ungated expectation; the + // difference must be small for a sweep that is mostly well above the gates. + let i = m.integrated(); + assert!(i >= expect - 0.1 && i - expect < 0.6, "I {i} vs ungated analytic {expect}"); + } + + #[test] + fn surround_weights() { + let sr = 48000.0; + let x = segments(1000.0, sr, &[(10.0, -30.0)]); + let z = vec![0.0f32; x.len()]; + // Signal only in Ls of a 5.1 layout → +1.5 dB weighting vs. front channel. + let mut front = LoudnessMeter::new(sr, 6); + front.process(&[&x, &z, &z, &z, &z, &z]); + let mut surr = LoudnessMeter::new(sr, 6); + surr.process(&[&z, &z, &z, &z, &x, &z]); + let mut lfe = LoudnessMeter::new(sr, 6); + lfe.process(&[&z, &z, &z, &x, &z, &z]); + assert!((surr.integrated() - front.integrated() - 10.0 * 1.41f64.log10()).abs() < 0.01); + assert_eq!(lfe.integrated(), f64::NEG_INFINITY); + } + + /// In 7.1 (L R C LFE Lb Rb Ls Rs) the back pair at 150 degrees weighs 1.0 and the side pair at + /// 90 degrees weighs 1.41; 7.1.4's height channels weigh 1.0. + #[test] + fn surround_weights_follow_speaker_positions() { + let sr = 48000.0; + let x = segments(1000.0, sr, &[(10.0, -30.0)]); + let z = vec![0.0f32; x.len()]; + let only = |n: usize, ch: usize| { + let mut m = LoudnessMeter::new(sr, n); + let io: Vec<&[f32]> = (0..n).map(|c| if c == ch { &x[..] } else { &z[..] }).collect(); + m.process(&io); + m.integrated() + }; + let front = only(8, 0); + assert!((only(8, 4) - front).abs() < 0.01, "back {}", only(8, 4) - front); + assert!((only(8, 6) - front - 10.0 * 1.41f64.log10()).abs() < 0.01); + assert_eq!(only(8, 3), f64::NEG_INFINITY); + assert_eq!(default_channel_weights(12), vec![1.0, 1.0, 1.0, 0.0, 1.0, 1.0, 1.41, 1.41, 1.0, 1.0, 1.0, 1.0]); + assert_eq!(default_channel_weights(3), vec![1.0; 3]); + } + + #[test] + fn true_peak_of_intersample_peak_signal() { + for sr in [48000.0, 44100.0] { + // fs/4 sine with 45° phase: every sample is at ±0.5·√2·A, true peak A (0 dBFS). + let n = sr as usize; + let x: Vec = (0..n).map(|i| (PI / 2.0 * i as f64 + PI / 4.0).sin() as f32).collect(); + let m = stereo_measure(&x, sr); + assert!((20.0 * m.sample_peak().log10() + 3.01).abs() < 0.01); + // EBU Tech 3341 true-peak tolerance: +0.2 / −0.4 dB. + let tp = m.true_peak_dbtp(); + assert!((-0.4..=0.2).contains(&tp), "sr {sr} TP {tp}"); + } + // A tone at an off-grid frequency: the true peak is its amplitude. + let x = sine(997.0, dbfs(-6.0), 48000.0, 48000, 0.3); + let m = stereo_measure(&x, 48000.0); + assert!((m.true_peak_dbtp() + 6.0).abs() < 0.2); + let x = sine(11025.0, 1.0, 44100.0, 44100, 0.0); + let m = stereo_measure(&x, 44100.0); + assert!((-0.4..=0.2).contains(&m.true_peak_dbtp()), "{}", m.true_peak_dbtp()); + } + + /// EBU Tech 3341 true-peak cases 15 to 18, generated here: -6 dBFS sines at 48 kHz at fs/4 + /// with 0 and 45 degrees of phase, fs/6 with 60 degrees and fs/8 with 67.5 degrees. Each reads + /// -6.0 dBTP within the tolerance of +0.2 / -0.4 dB, while the sample peaks sit lower. The + /// first 10 ms fade in: a sine that starts at 0.87 of its amplitude on the first sample is a + /// step, and the interpolator's overshoot on that step reads 0.3 dB over the sine's peak. + #[test] + fn tech3341_true_peak_cases_15_to_18() { + let sr = 48_000.0; + let fade = 480; + for (div, phase_deg) in [(4.0, 0.0), (4.0, 45.0), (6.0, 60.0), (8.0, 67.5)] { + let a = dbfs(-6.0); + let w = 2.0 * PI / div; + let ph = f64::to_radians(phase_deg); + let ramp = |i: usize| if i < fade { 0.5 - 0.5 * (PI * i as f64 / fade as f64).cos() } else { 1.0 }; + let x: Vec = (0..48_000).map(|i| (ramp(i) * a * (w * i as f64 + ph).sin()) as f32).collect(); + let m = stereo_measure(&x, sr); + let tp = m.true_peak_dbtp(); + assert!((-6.4..=-5.8).contains(&tp), "fs/{div} at {phase_deg} degrees: TP {tp}"); + assert!(20.0 * m.sample_peak().log10() <= -6.0 + 1e-3); + } + } + + /// EBU Tech 3341 case 9 shape: a stereo -20 dBFS sine of 1.34 s, then 1.66 s of -30 dBFS, + /// repeated: the short-term window spans exactly one period and reads the same at every + /// update once it is full. + #[test] + fn short_term_is_constant_over_a_whole_period() { + let sr = 48_000.0; + let period = [(1.34, -20.0), (1.66, -30.0)]; + let segs: Vec<(f64, f64)> = period.iter().copied().cycle().take(10).collect(); + let x = segments(1000.0, sr, &segs); + let mut m = LoudnessMeter::new(sr, 2); + let block = 4_800; + let mut readings = Vec::new(); + for (i, chunk) in x.chunks(block).enumerate() { + m.process(&[chunk, chunk]); + if i >= 30 && chunk.len() == block { + readings.push(m.short_term()); + } + } + let first = readings[0]; + assert!(readings.iter().all(|s| (s - first).abs() < 0.1), "{readings:?}"); + // A stereo 1 kHz sine at L dBFS reads L LUFS, so the window reads the power mean of + // the two levels weighted by their durations. + let expect = 10.0 * ((1.34 * 10f64.powf(-2.0) + 1.66 * 10f64.powf(-3.0)) / 3.0).log10(); + assert!((first - expect).abs() < 0.1, "S {first} expected {expect}"); + } + + #[test] + fn hostile_rates_channels_and_samples() { + let m = LoudnessMeter::new(f64::NAN, 0); + assert_eq!((m.sample_rate(), m.channels()), (f64::from(crate::FALLBACK_SAMPLE_RATE), 1)); + assert_eq!(LoudnessMeter::new(48_000.0, usize::MAX).channels(), crate::MAX_CHANNELS); + let sr = 48_000.0; + let mut x = segments(1000.0, sr, &[(5.0, -23.0)]); + x[1000] = f32::NAN; + x[2000] = f32::INFINITY; + let m = stereo_measure(&x, sr); + assert!((m.integrated() + 23.0).abs() < 0.1, "I {}", m.integrated()); + assert!(m.true_peak().is_finite() && m.momentary().is_finite()); + // A NaN or negative weight leaves its channel out instead of poisoning the sum. + let x = segments(1000.0, sr, &[(5.0, -23.0)]); + let mut m = LoudnessMeter::new(sr, 3); + m.set_channel_weights(&[1.0, f64::NAN, -2.0]); + m.process(&[&x, &x, &x]); + let mut mono = LoudnessMeter::new(sr, 1); + mono.process(&[&x]); + assert!((m.integrated() - mono.integrated()).abs() < 1e-9, "I {}", m.integrated()); + } + + #[test] + fn reset_clears_everything() { + let sr = 48000.0; + let x = segments(1000.0, sr, &[(5.0, -20.0)]); + let mut m = stereo_measure(&x, sr); + m.reset(); + assert_eq!(m.integrated(), f64::NEG_INFINITY); + assert_eq!(m.true_peak(), 0.0); + let x = segments(1000.0, sr, &[(5.0, -30.0)]); + m.process(&[&x, &x]); + assert!((m.integrated() + 30.0).abs() < 0.1); + } + + /// A program reset between a full-scale tone and silence leaves a true peak of 0: the old + /// samples still in the true-peak filter do not count for the new program. + #[test] + fn a_program_reset_does_not_carry_the_old_true_peak() { + let sr = 48_000.0; + let x = segments(997.0, sr, &[(0.5, 0.0)]); + let mut m = LoudnessMeter::new(sr, 2); + m.process(&[&x, &x]); + assert!(m.true_peak() > 0.9, "{}", m.true_peak()); + m.reset_program(); + let silence = vec![0.0f32; 4_800]; + m.process(&[&silence, &silence]); + assert_eq!(m.true_peak(), 0.0); + } + + /// The momentary and short-term windows read −∞ until they hold 400 ms and 3 s of audio, + /// instead of a low value over a part-filled window, and read the level once they are full. + #[test] + fn the_windows_read_nothing_until_they_are_full() { + let sr = 48_000.0; + let x = segments(1000.0, sr, &[(4.0, -23.0)]); + let sub = 4_800; + let mut m = LoudnessMeter::new(sr, 2); + m.process(&[&x[..3 * sub], &x[..3 * sub]]); + assert_eq!(m.momentary(), f64::NEG_INFINITY); + m.process(&[&x[3 * sub..4 * sub], &x[3 * sub..4 * sub]]); + assert!((m.momentary() + 23.0).abs() < 0.1, "M {}", m.momentary()); + m.process(&[&x[4 * sub..29 * sub], &x[4 * sub..29 * sub]]); + assert_eq!(m.short_term(), f64::NEG_INFINITY); + m.process(&[&x[29 * sub..30 * sub], &x[29 * sub..30 * sub]]); + assert!((m.short_term() + 23.0).abs() < 0.1, "S {}", m.short_term()); + // A program reset in the middle of the stream starts the windows again. + m.reset_program(); + m.process(&[&x[30 * sub..33 * sub], &x[30 * sub..33 * sub]]); + assert_eq!(m.momentary(), f64::NEG_INFINITY); + assert_eq!((m.integrated(), m.loudness_range(), m.short_term()), (f64::NEG_INFINITY, 0.0, f64::NEG_INFINITY)); + m.process(&[&x[33 * sub..34 * sub], &x[33 * sub..34 * sub]]); + assert!((m.momentary() + 23.0).abs() < 0.1, "M {}", m.momentary()); + assert!((m.integrated() + 23.0).abs() < 0.1, "I {}", m.integrated()); + } + + #[test] + fn normalize_helpers() { + assert_eq!(normalize_gain_db(-30.0, -23.0), 7.0); + assert_eq!(normalize_gain_db(f64::NEG_INFINITY, -23.0), 0.0); + assert_eq!(normalize_gain_db_peak_limited(-30.0, -23.0, -3.0, -1.0), 2.0); + assert_eq!(normalize_gain_db_peak_limited(-30.0, -23.0, -10.0, -1.0), 7.0); + // Applying the gain lands on target. + let sr = 48000.0; + let x = segments(1000.0, sr, &[(10.0, -31.3)]); + let m = stereo_measure(&x, sr); + let g = 10f64.powf(normalize_gain_db(m.integrated(), -16.0) / 20.0) as f32; + let y: Vec = x.iter().map(|v| v * g).collect(); + let m2 = stereo_measure(&y, sr); + assert!((m2.integrated() + 16.0).abs() < 0.02); + assert!((lufs_to_energy(energy_to_lufs(0.3)) - 0.3).abs() < 1e-12); + } + + #[test] + fn tiny_blocks_equal_big_blocks() { + let sr = 48000.0; + let x = segments(440.0, sr, &[(4.0, -18.0)]); + let mut a = LoudnessMeter::new(sr, 1); + a.process(&[&x]); + let mut b = LoudnessMeter::new(sr, 1); + b.process(&[&[]]); + for s in x.chunks(1) { + b.process(&[s]); + } + assert_eq!(a.integrated(), b.integrated()); + assert_eq!(a.true_peak(), b.true_peak()); + // Mono is summed without the dual-mono +3 dB (BS.1770). + let expect = -0.691 + 20.0 * rms(&x).log10() + 10.0 * k_weighting_power(440.0, sr).log10(); + assert!((a.integrated() - expect).abs() < 0.1, "{} vs {expect}", a.integrated()); + } + + #[test] + fn a_peak_at_the_very_end_counts() { + // Silence, then four samples of a tone at a quarter of the rate, 45° off its samples, and + // the clip ends: the inter-sample peak between them lies above the samples. + let mut x = vec![0.0f32; 40]; + x.extend((0..4).map(|i| (PI / 2.0 * i as f64 + PI / 4.0).sin() as f32)); + let mut padded = x.clone(); + padded.extend([0.0; 64]); + let (ended, followed) = (measure(&[&x], 48_000.0), measure(&[&padded], 48_000.0)); + assert_eq!(ended.true_peak_dbtp, followed.true_peak_dbtp); + assert!(ended.true_peak_dbtp > ended.sample_peak_dbfs, "{ended:?}"); + } + + #[test] + fn the_k_filters_are_stable_at_every_usable_rate() { + for sr in [crate::MIN_SAMPLE_RATE as f64, 2_000.0, 3_000.0, 8_000.0, 0.0, f64::NAN] { + for c in [k_prefilter(sr), k_rlb(sr)] { + // Poles inside the unit circle: |a2| < 1 and |a1| < 1 + a2. + assert!(c.a2.abs() < 1.0 && c.a1.abs() < 1.0 + c.a2, "{sr}: {c:?}"); + } + } + let sr = f64::from(crate::MIN_SAMPLE_RATE); + let x = segments(100.0, sr, &[(5.0, -20.0)]); + let mut m = LoudnessMeter::new(sr, 1); + m.process(&[&x]); + assert!(m.integrated().is_finite() && m.integrated() < 0.0, "{}", m.integrated()); + } +} diff --git a/crates/audio-dsp/src/offline.rs b/crates/audio-dsp/src/offline.rs new file mode 100644 index 000000000..34bbd0f3b --- /dev/null +++ b/crates/audio-dsp/src/offline.rs @@ -0,0 +1,312 @@ +//! Whole-buffer sample-rate conversion with a Kaiser-windowed sinc filter, for files and +//! exports rather than live streams (see [`crate::resample`] for those). +//! +//! The filter has 32 zero crossings either side at the cutoff and a Kaiser window with +//! beta 9. Its cutoff sits at 0.97 of the input's Nyquist frequency when converting up and at +//! 0.94 of the output's when converting down, so content above the new Nyquist frequency is +//! removed. For rates with a small common ratio (44.1 and 48 kHz and their multiples) the +//! kernel is precomputed for every phase, which makes each output sample one dot product over +//! contiguous input; other pairs evaluate the kernel per tap. Both give the same samples. + +use std::f64::consts::PI; + +use crate::{MAX_CHANNELS, MAX_SAMPLE_RATE, MIN_SAMPLE_RATE}; + +/// Most frames [`resample`] writes per channel (about 93 minutes at 48 kHz). +pub const MAX_OFFLINE_FRAMES: usize = 1 << 28; + +/// Zero crossings of the kernel either side of its center, at the cutoff. +const SINC_ZC: f64 = 32.0; +/// Kernel table entries per zero crossing. +const SINC_RES: usize = 512; +/// Most kernel weights a [`Polyphase`] bank may hold (16 MiB of f32). +const MAX_POLYPHASE_WEIGHTS: usize = 1 << 22; + +fn bessel_i0(x: f64) -> f64 { + let mut sum = 1.0; + let mut term = 1.0; + let y = x * x / 4.0; + for k in 1..64 { + term *= y / (k as f64 * k as f64); + sum += term; + if term < sum * 1e-12 { + break; + } + } + sum +} + +/// One side of the windowed-sinc kernel for a cutoff (a fraction of the input's Nyquist +/// frequency), tabulated at [`SINC_RES`] points per zero crossing, so the table has the same +/// size at every cutoff. +struct SincTable { + table: Vec, + cutoff: f64, + half_width: f64, +} + +impl SincTable { + fn new(cutoff: f64) -> Self { + // The lowest cutoff `resample` asks for is 1 kHz from 1.536 MHz: 0.94 / 1536. + let cutoff = if cutoff.is_finite() { cutoff.clamp(1e-4, 1.0) } else { 1.0 }; + let half_width = SINC_ZC / cutoff; + let n = SINC_ZC as usize * SINC_RES + 2; + let beta = 9.0; + let i0b = bessel_i0(beta); + let table = (0..n) + .map(|i| { + // `u` is the distance from the center in zero crossings: input samples × cutoff. + let u = i as f64 / SINC_RES as f64; + let x = u / SINC_ZC; + if x >= 1.0 { + return 0.0; + } + let arg = PI * u; + let sinc = if arg.abs() < 1e-12 { 1.0 } else { arg.sin() / arg }; + let w = bessel_i0(beta * (1.0 - x * x).max(0.0).sqrt()) / i0b; + (cutoff * sinc * w) as f32 + }) + .collect(); + SincTable { table, cutoff, half_width } + } + + /// The kernel at `t` input samples from its center. + #[inline] + fn at(&self, t: f64) -> f32 { + let pos = t.abs() * self.cutoff * SINC_RES as f64; + let i = pos as usize; + let f = (pos - i as f64) as f32; + match (self.table.get(i), self.table.get(i + 1)) { + (Some(a), Some(b)) => a + (b - a) * f, + (Some(a), None) => *a, + _ => 0.0, + } + } +} + +/// Input sample `j`, with a non-finite sample read as 0 (one NaN would otherwise spread to +/// every output within the kernel's reach). +#[inline] +fn sample(x: &[f32], j: usize) -> f32 { + x.get(j).copied().filter(|v| v.is_finite()).unwrap_or(0.0) +} + +/// One channel resampled to exactly `out_len` samples; output sample `n` is read at input time +/// `n / ratio`. +fn resample_channel(x: &[f32], ratio: f64, out_len: usize, table: &SincTable) -> Vec { + let len = x.len() as i64; + let hw = table.half_width; + (0..out_len) + .map(|n| { + let t = n as f64 / ratio; + let lo = (t - hw).ceil().max(0.0) as i64; + let hi = ((t + hw).floor() as i64).min(len - 1); + let mut acc = 0.0f32; + let mut j = lo; + while j <= hi { + acc += sample(x, j as usize) * table.at(t - j as f64); + j += 1; + } + acc + }) + .collect() +} + +/// The kernel of [`resample_channel`] precomputed for every phase of a rational rate change +/// `from` to `to` (reduced to `step / phases`). Output sample `n` reads input time +/// `n * step / phases`: whole part `i`, phase `p`. Its taps are input samples `i + first ..`, one +/// weight each. The weights are the ones `resample_channel` computes, taps beyond the kernel's +/// half width weigh 0, and taps are summed in the same order. +struct Polyphase { + phases: u64, + step: u64, + /// Offset of the first tap from `i`. + first: i64, + taps: usize, + /// `phases * taps` weights, phase-major. + weights: Vec, +} + +impl Polyphase { + /// `None` when the bank would be too large (rates with no small common ratio); the caller + /// then uses [`resample_channel`]. + fn new(from: u32, to: u32, table: &SincTable) -> Option { + let g = gcd(from, to); + let (step, phases) = (u64::from(from / g), u64::from(to / g)); + let hw = table.half_width; + let first = (-hw).floor() as i64; + let last = hw.ceil() as i64 + 1; + let taps = usize::try_from(last - first + 1).ok()?; + if usize::try_from(phases).ok()?.checked_mul(taps)? > MAX_POLYPHASE_WEIGHTS { + return None; + } + let mut weights = Vec::with_capacity(taps * phases as usize); + for p in 0..phases { + let frac = p as f64 / phases as f64; + for k in first..first + taps as i64 { + let d = frac - k as f64; + weights.push(if d.abs() <= hw { table.at(d) } else { 0.0 }); + } + } + Some(Polyphase { phases, step, first, taps, weights }) + } + + fn run(&self, x: &[f32], out_len: usize) -> Vec { + let len = x.len() as i64; + let clean = x.iter().all(|v| v.is_finite()); + let mut out = Vec::with_capacity(out_len); + for n in 0..out_len as u64 { + let Some(pos) = n.checked_mul(self.step) else { break }; + let (i, p) = ((pos / self.phases) as i64, (pos % self.phases) as usize); + let w = self.weights.get(p * self.taps..(p + 1) * self.taps).unwrap_or_default(); + let start = i + self.first; + let inside = usize::try_from(start).ok().and_then(|s| x.get(s..s + self.taps)); + let acc = match inside { + // Inside a finite signal: a plain dot product. + Some(xs) if clean => xs.iter().zip(w).fold(0.0f32, |a, (v, k)| a + v * k), + // At the edges taps outside the signal are skipped, as in `resample_channel`. + _ => (0..self.taps as i64) + .filter(|k| (0..len).contains(&(start + k))) + .fold(0.0f32, |a, k| a + sample(x, (start + k) as usize) * w.get(k as usize).copied().unwrap_or(0.0)), + }; + out.push(acc); + } + out.resize(out_len, 0.0); + out + } +} + +fn gcd(mut a: u32, mut b: u32) -> u32 { + while b != 0 { + (a, b) = (b, a % b); + } + a.max(1) +} + +fn usable_rate(rate: u32) -> bool { + (MIN_SAMPLE_RATE as u32..=MAX_SAMPLE_RATE as u32).contains(&rate) +} + +/// Converts planar audio from `from` Hz to `to` Hz. Each output channel has +/// `round(len * to / from)` samples, capped at [`MAX_OFFLINE_FRAMES`]; at most +/// [`crate::MAX_CHANNELS`] channels are converted. Equal rates return a copy. `None` when a rate +/// is outside [`crate::MIN_SAMPLE_RATE`] ..= [`crate::MAX_SAMPLE_RATE`]. Non-finite input samples +/// are read as 0. +pub fn resample(channels: &[&[f32]], from: u32, to: u32) -> Option>> { + if !usable_rate(from) || !usable_rate(to) { + return None; + } + let channels = channels.get(..channels.len().min(MAX_CHANNELS)).unwrap_or_default(); + if from == to { + let copy = |c: &&[f32]| c.iter().take(MAX_OFFLINE_FRAMES).map(|&v| if v.is_finite() { v } else { 0.0 }).collect(); + return Some(channels.iter().map(copy).collect()); + } + let ratio = f64::from(to) / f64::from(from); + let cutoff = if ratio < 1.0 { ratio * 0.94 } else { 0.97 }; + let table = SincTable::new(cutoff); + let bank = Polyphase::new(from, to, &table); + Some( + channels + .iter() + .map(|c| { + let out_len = ((c.len() as f64 * ratio).round() as usize).min(MAX_OFFLINE_FRAMES); + match &bank { + Some(b) => b.run(c, out_len), + None => resample_channel(c, ratio, out_len, &table), + } + }) + .collect(), + ) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::{db, sine, tone_amplitude}; + + /// The polyphase bank gives what the per-tap kernel gives, at common rate pairs in both + /// directions and at the signal's edges. + #[test] + fn polyphase_matches_the_per_tap_kernel() { + let x: Vec = (0..3_000).map(|i| (i as f32 * 0.071).sin() * 0.6 + (i as f32 * 0.53).sin() * 0.3).collect(); + let pairs = [(44_100, 48_000), (48_000, 44_100), (48_000, 96_000), (96_000, 48_000), (22_050, 48_000), (8_000, 44_100), (48_000, 22_050)]; + for (from, to) in pairs { + let ratio = f64::from(to) / f64::from(from); + let out_len = (x.len() as f64 * ratio).round() as usize; + let cutoff = if ratio < 1.0 { ratio * 0.94 } else { 0.97 }; + let table = SincTable::new(cutoff); + let reference = resample_channel(&x, ratio, out_len, &table); + let bank = Polyphase::new(from, to, &table).expect("small common ratio"); + let fast = bank.run(&x, out_len); + assert_eq!(fast.len(), reference.len(), "{from}->{to}"); + let worst = fast.iter().zip(&reference).map(|(a, b)| (a - b).abs()).fold(0.0f32, f32::max); + assert!(worst < 1e-5, "{from}->{to}: worst difference {worst}"); + assert_eq!(resample(&[&x], from, to).unwrap()[0], fast, "resample uses the bank"); + } + // Signals shorter than the kernel are all edge. + let short = [0.5f32, -0.25, 0.75]; + let table = SincTable::new(0.97); + let reference = resample_channel(&short, 48_000.0 / 44_100.0, 3, &table); + let fast = Polyphase::new(44_100, 48_000, &table).expect("bank").run(&short, 3); + assert!(fast.iter().zip(&reference).all(|(a, b)| (a - b).abs() < 1e-6), "{fast:?} {reference:?}"); + // Rates with no small common ratio use the per-tap kernel. + assert!(Polyphase::new(44_100, 96_001, &table).is_none()); + assert_eq!(resample(&[&short], 44_100, 96_001).unwrap()[0].len(), 7); + } + + /// Checked against the signal itself: a tone keeps its frequency and level, and a tone above + /// the new Nyquist frequency is removed. + #[test] + fn tones_keep_frequency_and_level_and_aliases_are_removed() { + let x = sine(1_000.0, 0.5, 48_000.0, 48_000, 0.0); + let out = resample(&[&x], 48_000, 44_100).unwrap(); + assert_eq!(out[0].len(), 44_100); + let a = tone_amplitude(&out[0][2_000..42_000], 1_000.0, 44_100.0); + assert!(db(a / 0.5).abs() < 0.05, "passband {} dB", db(a / 0.5)); + let up = resample(&[&out[0]], 44_100, 96_000).unwrap(); + assert_eq!(up[0].len(), 96_000); + assert!(db(tone_amplitude(&up[0][4_000..90_000], 1_000.0, 96_000.0) / 0.5).abs() < 0.05); + // 23 kHz is above 22.05 kHz's Nyquist frequency of 11.025 kHz. + let hi = sine(23_000.0, 0.5, 48_000.0, 48_000, 0.0); + let down = resample(&[&hi], 48_000, 22_050).unwrap(); + let peak = down[0][1_000..20_000].iter().fold(0.0f32, |m, v| m.max(v.abs())); + assert!(peak < 0.005, "alias {peak}"); + } + + /// The widest accepted ratio, 1.536 MHz to 1 kHz: a 100 Hz tone passes and a 5.3 kHz tone, + /// above the new Nyquist frequency of 500 Hz (it would fold to 300 Hz), is removed. + #[test] + fn the_widest_downsampling_ratio_still_removes_aliases() { + let (from, to) = (1_536_000u32, 1_000u32); + let low = sine(100.0, 0.5, f64::from(from), 1_536_000, 0.0); + let out = resample(&[&low], from, to).unwrap(); + assert_eq!(out[0].len(), 1_000); + let a = tone_amplitude(&out[0][100..900], 100.0, f64::from(to)); + assert!(db(a / 0.5).abs() < 0.1, "passband {} dB", db(a / 0.5)); + let high = sine(5_300.0, 0.5, f64::from(from), 1_536_000, 0.0); + let out = resample(&[&high], from, to).unwrap(); + let peak = out[0][100..900].iter().fold(0.0f32, |m, v| m.max(v.abs())); + assert!(peak < 0.005, "alias {peak}"); + } + + #[test] + fn hostile_rates_and_samples() { + assert!(resample(&[&[1.0; 10]], 0, 48_000).is_none()); + assert!(resample(&[&[1.0; 10]], 48_000, 1).is_none()); + assert!(resample(&[&[1.0; 10]], 48_000, u32::MAX).is_none()); + assert_eq!(resample(&[&[1.0; 10]], 48_000, 48_000).unwrap(), vec![vec![1.0; 10]]); + assert!(resample(&[], 44_100, 48_000).unwrap().is_empty()); + assert!(resample(&[&[]], 44_100, 48_000).unwrap()[0].is_empty()); + // A NaN sample does not spread through the kernel, on either path. + let mut x = sine(500.0, 0.5, 48_000.0, 4_800, 0.0); + x[2_000] = f32::NAN; + x[3_000] = f32::INFINITY; + for to in [44_100, 44_101] { + assert!(resample(&[&x], 48_000, to).unwrap()[0].iter().all(|v| v.is_finite()), "to {to}"); + } + // Equal rates read non-finite samples as 0 too. + assert_eq!(resample(&[&[1.0, f32::NAN, f32::NEG_INFINITY]], 48_000, 48_000).unwrap(), vec![vec![1.0, 0.0, 0.0]]); + let many: Vec<&[f32]> = vec![&[0.0f32; 4]; 100]; + assert_eq!(resample(&many, 44_100, 48_000).unwrap().len(), MAX_CHANNELS); + } +} diff --git a/crates/audio-dsp/src/oversample.rs b/crates/audio-dsp/src/oversample.rs new file mode 100644 index 000000000..6974c0128 --- /dev/null +++ b/crates/audio-dsp/src/oversample.rs @@ -0,0 +1,197 @@ +//! Polyphase FIR interpolator used for true-peak estimation (BS.1770-4 Annex 2 style). +//! +//! The prototype is a Kaiser-windowed sinc low-pass (cut-off at the original Nyquist) split into +//! `factor` phases of [`TAPS_PER_PHASE`] taps; each phase is normalized to unity DC gain. + +use std::f64::consts::PI; + +/// Taps per polyphase branch. +pub const TAPS_PER_PHASE: usize = 16; + +/// Oversampling factor giving an effective rate of at least 176.4 kHz (4× at 44.1/48 kHz, +/// 2× at 88.2/96 kHz, 1× above), as recommended by BS.1770-4 for true-peak metering. +pub fn true_peak_factor(sample_rate: f64) -> usize { + if sample_rate < 88_200.0 { + 4 + } else if sample_rate < 176_400.0 { + 2 + } else { + 1 + } +} + +fn bessel_i0(x: f64) -> f64 { + let mut sum = 1.0; + let mut term = 1.0; + let q = x * x / 4.0; + for k in 1..50 { + term *= q / (k * k) as f64; + sum += term; + if term < sum * 1e-17 { + break; + } + } + sum +} + +/// Polyphase coefficient bank shared by all channels. +#[derive(Clone, Debug)] +pub struct PolyphaseBank { + factor: usize, + /// `coeffs[p * TAPS_PER_PHASE + j]` multiplies `x[n - j]` for output phase `p`. + coeffs: Vec, +} + +impl PolyphaseBank { + pub fn new(factor: usize) -> Self { + let factor = factor.max(1); + let len = factor * TAPS_PER_PHASE; + let center = (len - 1) as f64 / 2.0; + let beta = 8.0; + let i0b = bessel_i0(beta); + let proto: Vec = (0..len) + .map(|m| { + let t = (m as f64 - center) / factor as f64; + let sinc = if t.abs() < 1e-12 { 1.0 } else { (PI * t).sin() / (PI * t) }; + let r = (m as f64 - center) / (center + 1.0); + let w = bessel_i0(beta * (1.0 - r * r).max(0.0).sqrt()) / i0b; + sinc * w + }) + .collect(); + let mut coeffs = vec![0.0f32; len]; + for p in 0..factor { + let sum: f64 = (0..TAPS_PER_PHASE).map(|j| proto[p + factor * j]).sum(); + for j in 0..TAPS_PER_PHASE { + coeffs[p * TAPS_PER_PHASE + j] = (proto[p + factor * j] / sum) as f32; + } + } + PolyphaseBank { factor, coeffs } + } + /// Approximate delay (in input samples) between an input sample and the interpolated + /// values around it. + pub fn delay(&self) -> usize { + TAPS_PER_PHASE / 2 + } +} + +/// Per-channel interpolator history. +#[derive(Clone, Debug)] +pub struct Interpolator { + /// Double-written ring so a contiguous window of TAPS_PER_PHASE is always available. + hist: [f32; 2 * TAPS_PER_PHASE], + pos: usize, +} + +impl Default for Interpolator { + fn default() -> Self { + Interpolator { hist: [0.0; 2 * TAPS_PER_PHASE], pos: 0 } + } +} + +impl Interpolator { + pub fn reset(&mut self) { + *self = Self::default(); + } + + /// Push one input sample; returns the maximum absolute value of the `factor` interpolated + /// output samples produced for it. + #[inline] + pub fn push_peak(&mut self, bank: &PolyphaseBank, x: f32) -> f32 { + if bank.factor == 1 { + return x.abs(); + } + // Newest sample at window[TAPS-1-0]... store so that window[j] = x[n - j]. + self.pos = if self.pos == 0 { TAPS_PER_PHASE - 1 } else { self.pos - 1 }; + self.hist[self.pos] = x; + self.hist[self.pos + TAPS_PER_PHASE] = x; + let win = &self.hist[self.pos..self.pos + TAPS_PER_PHASE]; + let mut peak = 0.0f32; + for c in bank.coeffs.as_chunks::().0 { + peak = peak.max(dot(c, win).abs()); + } + peak + } +} + +/// Dot product of one phase with the window. Eight partial sums (instead of one sequential sum) +/// let the compiler vectorize it; the result differs from the sequential sum only by rounding. +#[inline(always)] +fn dot(c: &[f32; TAPS_PER_PHASE], win: &[f32]) -> f32 { + let mut acc = [0.0f32; 8]; + for (cc, ww) in c.as_chunks::<8>().0.iter().zip(win.as_chunks::<8>().0) { + for ((a, &ci), &wi) in acc.iter_mut().zip(cc).zip(ww) { + *a += ci * wi; + } + } + (acc[0] + acc[4]) + (acc[1] + acc[5]) + (acc[2] + acc[6]) + (acc[3] + acc[7]) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn phases_have_unity_dc_and_interpolate_sines() { + let bank = PolyphaseBank::new(4); + for p in 0..4 { + let s: f32 = bank.coeffs[p * TAPS_PER_PHASE..(p + 1) * TAPS_PER_PHASE].iter().sum(); + assert!((s - 1.0).abs() < 1e-5); + } + // Sine at fs/4 with 45° phase: samples at ±0.707, true peak 1.0. + let mut ip = Interpolator::default(); + let mut peak = 0.0f32; + for n in 0..400 { + let x = (std::f64::consts::FRAC_PI_2 * n as f64 + std::f64::consts::FRAC_PI_4).sin() as f32; + let p = ip.push_peak(&bank, x); + if n > 40 { + peak = peak.max(p); + } + } + assert!((peak - 1.0).abs() < 0.02, "peak {peak}"); + } + + /// The previous sequential-sum interpolator. + fn push_peak_reference(ip: &mut Interpolator, bank: &PolyphaseBank, x: f32) -> f32 { + ip.pos = if ip.pos == 0 { TAPS_PER_PHASE - 1 } else { ip.pos - 1 }; + ip.hist[ip.pos] = x; + ip.hist[ip.pos + TAPS_PER_PHASE] = x; + let win = &ip.hist[ip.pos..ip.pos + TAPS_PER_PHASE]; + let mut peak = 0.0f32; + for p in 0..bank.factor { + let c = &bank.coeffs[p * TAPS_PER_PHASE..(p + 1) * TAPS_PER_PHASE]; + let y: f32 = c.iter().zip(win).map(|(a, b)| a * b).sum(); + peak = peak.max(y.abs()); + } + peak + } + + #[test] + fn partial_sums_match_sequential_sum_to_rounding() { + let mut rng = crate::testutil::Rng::new(9); + let mut signals: Vec> = vec![(0..48_000).map(|_| rng.uniform()).collect(), (0..48_000).map(|_| 1e-4 * rng.uniform()).collect()]; + for f in [997.0, 11_025.0, 19_000.0, 23_900.0] { + signals.push(crate::testutil::sine(f, 0.99, 48_000.0, 48_000, 0.3)); + } + let (mut max_abs, mut max_rel, mut max_db) = (0.0f32, 0.0f32, 0.0f64); + for factor in [2, 4] { + let bank = PolyphaseBank::new(factor); + for x in &signals { + let (mut a, mut b) = (Interpolator::default(), Interpolator::default()); + let (mut pa, mut pb) = (0.0f32, 0.0f32); + for &v in x { + let (ya, yb) = (a.push_peak(&bank, v), push_peak_reference(&mut b, &bank, v)); + max_abs = max_abs.max((ya - yb).abs()); + if yb > 0.0 { + max_rel = max_rel.max((ya - yb).abs() / yb); + } + pa = pa.max(ya); + pb = pb.max(yb); + } + max_db = max_db.max((20.0 * (pa as f64 / pb as f64).log10()).abs()); + } + } + println!("true-peak interpolator vs sequential sum: max abs {max_abs:e}, max rel {max_rel:e}, max peak {max_db:e} dB"); + assert!(max_abs < 1e-6, "abs {max_abs}"); + assert!(max_db < 1e-5, "dB {max_db}"); + } +} diff --git a/crates/audio-dsp/src/pan.rs b/crates/audio-dsp/src/pan.rs new file mode 100644 index 000000000..a397b132c --- /dev/null +++ b/crates/audio-dsp/src/pan.rs @@ -0,0 +1,436 @@ +//! Panning: mono-to-stereo pan laws, a surround panner over any loudspeaker layout of up to +//! [`MAX_SPEAKERS`] speakers, and first-order ambisonics. +//! +//! Directions are in degrees. Azimuth 0 is straight ahead and positive azimuths are to the +//! right (clockwise seen from above); elevation is positive upward. Every function here is +//! allocation-free and returns finite gains for any input, NaN and infinities included. + +use std::f32::consts::{FRAC_PI_2, FRAC_PI_4}; + +/// How much a centered signal is attenuated. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum PanLaw { + /// Constant power: -3 dB at center. + #[default] + Minus3, + /// Compromise: -4.5 dB at center. + Minus4_5, + /// Constant voltage: -6 dB at center. + Minus6, + /// Balance: 0 dB at center, the far side fades out linearly. + Zero, +} + +impl PanLaw { + /// Center attenuation in dB (0 or negative). + pub fn center_db(self) -> f32 { + match self { + PanLaw::Minus3 => -3.0, + PanLaw::Minus4_5 => -4.5, + PanLaw::Minus6 => -6.0, + PanLaw::Zero => 0.0, + } + } +} + +/// Left and right gains for `pan` in -1 (hard left) ..= 1 (hard right). NaN pans to center. +pub fn gains(pan: f32, law: PanLaw) -> (f32, f32) { + let pan = if pan.is_nan() { 0.0 } else { pan.clamp(-1.0, 1.0) }; + if law == PanLaw::Zero { + return ((1.0 - pan).min(1.0), (1.0 + pan).min(1.0)); + } + let theta = (pan + 1.0) * FRAC_PI_4; + let (l, r) = (theta.cos().max(0.0), theta.sin().max(0.0)); + // cos(pi/4) is -3.0103 dB; a power of it reaches the requested center level. + let exp = law.center_db() / -3.010_3; + let l = if pan <= -1.0 { 1.0 } else { l.powf(exp) }; + let r = if pan >= 1.0 { 1.0 } else { r.powf(exp) }; + (l, r) +} + +/// Most loudspeakers the surround panner handles (9.1.6 is 16). +pub const MAX_SPEAKERS: usize = 16; + +/// One loudspeaker of a layout: its direction, and whether it is the LFE (never panned to). +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct SpeakerPos { + /// Azimuth in degrees, positive to the right. + pub az: f32, + /// Elevation in degrees; above 1 degree counts as the height layer. + pub el: f32, + pub lfe: bool, +} + +/// Surround panner controls. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct SurroundParams { + /// -1 (left) ..= 1 (right). + pub x: f32, + /// -1 (back) ..= 1 (front). + pub y: f32, + /// 0 (ear level) ..= 1 (overhead). + pub z: f32, + /// 0 is a point source ..= 1 is every speaker. + pub divergence: f32, + /// 0 ..= 1: the share of center-speaker energy kept on the center; the rest goes to a + /// phantom center on left and right. + pub center: f32, +} + +fn fin(v: f32, d: f32) -> f32 { + if v.is_finite() { v } else { d } +} + +fn wrap180(a: f32) -> f32 { + let mut a = fin(a, 0.0) % 360.0; + if a > 180.0 { + a -= 360.0; + } else if a <= -180.0 { + a += 360.0; + } + a +} + +/// Azimuth of a position on the panner's square. The square's front corners land on the front +/// left and right speakers (30 degrees when the layout has them, else 45), its side midpoints at +/// 90 degrees and its rear corners on the layout's rearmost surround (110 for 5.x, 150 for 7.x, +/// 135 when there is none), so a puck in a corner hits exactly one speaker. +pub fn puck_azimuth(layout: &[SpeakerPos], x: f32, y: f32) -> f32 { + let (x, y) = (fin(x, 0.0).clamp(-1.0, 1.0), fin(y, 1.0).clamp(-1.0, 1.0)); + if x.abs() < 1e-9 && y.abs() < 1e-9 { + return 0.0; + } + let rear = + layout.iter().filter(|s| !s.lfe && s.el.abs() < 1.0 && s.az.abs() > 90.5 && s.az.abs() < 179.5).map(|s| s.az.abs()).fold(0.0f32, f32::max); + let rear = if rear > 0.0 { rear } else { 135.0 }; + let front = if layout.iter().any(|s| !s.lfe && s.el.abs() < 1.0 && (s.az.abs() - 30.0).abs() < 0.5) { 30.0 } else { 45.0 }; + let phi = x.atan2(y).to_degrees(); + let a = phi.abs(); + let warped = if a <= 45.0 { + a / 45.0 * front + } else if a <= 90.0 { + front + (a - 45.0) / 45.0 * (90.0 - front) + } else if a <= 135.0 { + 90.0 + (a - 90.0) / 45.0 * (rear - 90.0) + } else { + rear + (a - 135.0) / 45.0 * (180.0 - rear) + }; + warped.copysign(phi) +} + +/// The point on the square's edge whose [`puck_azimuth`] is `az`, for drawing speakers on a +/// square panner. +pub fn azimuth_to_puck(layout: &[SpeakerPos], az: f32) -> (f32, f32) { + // Bisect the monotonic warp on the square's angle. + let target = wrap180(az); + let (mut lo, mut hi) = (0.0f32, 180.0f32); + for _ in 0..40 { + let mid = 0.5 * (lo + hi); + let r = mid.to_radians(); + let w = puck_azimuth(layout, r.sin(), r.cos()); + if w < target.abs() { + lo = mid; + } else { + hi = mid; + } + } + let phi = (0.5 * (lo + hi)).to_radians().copysign(if target < 0.0 { -1.0 } else { 1.0 }); + let (sx, sy) = (phi.sin(), phi.cos()); + let m = sx.abs().max(sy.abs()).max(1e-6); + (sx / m, sy / m) +} + +/// Constant-power pairwise pan of a direction onto one layer (bed or height) of `layout`, +/// adding `weight * gain^2` into `pow`. Returns `false` when the layer has no speakers. +fn pair_power(layout: &[SpeakerPos], height: bool, az: f32, weight: f32, pow: &mut [f32; MAX_SPEAKERS]) -> bool { + let mut idx = [0usize; MAX_SPEAKERS]; + let mut n = 0; + for (i, s) in layout.iter().enumerate().take(MAX_SPEAKERS) { + if !s.lfe + && (s.el > 1.0) == height + && let Some(slot) = idx.get_mut(n) + { + *slot = i; + n += 1; + } + } + let ids = idx.get(..n).unwrap_or(&[]); + let az_of = |i: usize| layout.get(i).map_or(0.0, |s| wrap180(s.az)); + match ids { + [] => false, + [only] => { + if let Some(p) = pow.get_mut(*only) { + *p += weight; + } + true + } + [first, ..] => { + let a = wrap180(az); + // The nearest speaker clockwise (increasing azimuth) and the nearest counterclockwise. + let (mut cw, mut cw_d) = (*first, f32::MAX); + let (mut acw, mut acw_d) = (*first, f32::MAX); + for &i in ids { + let d = (az_of(i) - a).rem_euclid(360.0); + if d < cw_d { + cw_d = d; + cw = i; + } + let d2 = (a - az_of(i)).rem_euclid(360.0); + if d2 < acw_d { + acw_d = d2; + acw = i; + } + } + if cw == acw || cw_d < 1e-4 { + if let Some(p) = pow.get_mut(cw) { + *p += weight; + } + return true; + } + let span = (cw_d + acw_d).max(1e-6); + let t = (acw_d / span).clamp(0.0, 1.0) * FRAC_PI_2; + if let Some(p) = pow.get_mut(acw) { + *p += weight * t.cos() * t.cos(); + } + if let Some(p) = pow.get_mut(cw) { + *p += weight * t.sin() * t.sin(); + } + true + } + } +} + +/// Point-source gains for a direction on `layout`: pairwise constant power on the layer +/// nearest in elevation. A height direction on a layout without heights folds to the bed at +/// -3 dB, and an ear-level direction on a layout with only heights goes to the heights at full +/// level, as in [`surround_gains`]. Writes `out[..layout.len()]`. +pub fn direction_gains(layout: &[SpeakerPos], az: f32, el: f32, out: &mut [f32]) { + let mut pow = [0.0f32; MAX_SPEAKERS]; + let height = fin(el, 0.0) > 1.0; + if height && !pair_power(layout, true, az, 1.0, &mut pow) { + pair_power(layout, false, az, 0.5, &mut pow); + } else if !height && !pair_power(layout, false, az, 1.0, &mut pow) { + pair_power(layout, true, az, 1.0, &mut pow); + } + for (o, p) in out.iter_mut().zip(pow.iter()) { + *o = p.max(0.0).sqrt(); + } +} + +/// Surround panner: a gain for every speaker of `layout` (the LFE gets 0; the caller adds an LFE +/// send). The squared gains of the other speakers always sum to 1. +/// +/// The puck's azimuth comes from [`puck_azimuth`]. Divergence, and moving the puck toward the +/// middle of the room, spread the image: the gains are the power average of point sources +/// sampled across `spread * 180` degrees either side. `center` below 1 moves that share of the +/// center speaker's power to a phantom center on left and right. Elevation crossfades the bed +/// and height layers at constant power. +pub fn surround_gains(layout: &[SpeakerPos], p: &SurroundParams, out: &mut [f32]) { + out.iter_mut().for_each(|g| *g = 0.0); + let layout = layout.get(..layout.len().min(MAX_SPEAKERS)).unwrap_or(&[]); + if layout.is_empty() { + return; + } + let az = puck_azimuth(layout, p.x, p.y); + let dist = fin(p.x, 0.0).abs().max(fin(p.y, 1.0).abs()).clamp(0.0, 1.0); + let div = fin(p.divergence, 0.0).clamp(0.0, 1.0); + let spread = 1.0 - dist * (1.0 - div); + let k = 1 + (spread * 24.0).round() as usize; + let width = spread * 180.0; + let has_height = layout.iter().any(|s| !s.lfe && s.el > 1.0); + let z = if has_height { fin(p.z, 0.0).clamp(0.0, 1.0) } else { 0.0 }; + let (bed_w, top_w) = { + let a = z * FRAC_PI_2; + (a.cos() * a.cos(), a.sin() * a.sin()) + }; + let mut pow = [0.0f32; MAX_SPEAKERS]; + for i in 0..k { + let a = if k == 1 { az } else { az - width + 2.0 * width * (i as f32 + 0.5) / k as f32 }; + let w = 1.0 / k as f32; + if bed_w > 1e-9 && !pair_power(layout, false, a, w * bed_w, &mut pow) { + pair_power(layout, true, a, w * bed_w, &mut pow); + } + if top_w > 1e-9 { + pair_power(layout, true, a, w * top_w, &mut pow); + } + } + // Center share: move energy from the center speaker to a phantom center on left and right. + let find = |az: f32| layout.iter().position(|s| !s.lfe && s.el.abs() < 1.0 && (s.az - az).abs() < 0.5); + let c_share = fin(p.center, 1.0).clamp(0.0, 1.0); + if let (Some(c), Some(l), Some(r)) = (find(0.0), find(-30.0), find(30.0)) + && c_share < 1.0 + { + let pc = pow.get(c).copied().unwrap_or(0.0); + let moved = pc * (1.0 - c_share); + if let Some(x) = pow.get_mut(c) { + *x = pc - moved; + } + for i in [l, r] { + if let Some(x) = pow.get_mut(i) { + *x += 0.5 * moved; + } + } + } + for (o, p) in out.iter_mut().zip(pow.iter()) { + *o = p.max(0.0).sqrt(); + } +} + +/// First-order ambisonic encoding gains for a direction, in ACN channel order (W, Y, Z, X) with +/// SN3D normalization, with the directional components scaled by `1 - spread`. Channels past +/// the fourth get 0. +pub fn ambisonic_encode(az: f32, el: f32, spread: f32, out: &mut [f32]) { + out.iter_mut().for_each(|g| *g = 0.0); + let (a, e) = (fin(az, 0.0).to_radians(), fin(el, 0.0).to_radians()); + let d = 1.0 - fin(spread, 0.0).clamp(0.0, 1.0); + // Ambisonic azimuth runs counterclockwise (left positive); this module's runs clockwise. + let vals = [1.0, -a.sin() * e.cos() * d, e.sin() * d, a.cos() * e.cos() * d]; + for (o, v) in out.iter_mut().zip(vals) { + *o = v; + } +} + +/// Basic (sampling) first-order decode gains (W, Y, Z, X) for one speaker of an `n`-speaker +/// layout spread evenly over the sphere. Each speaker's feed is the dot product of these gains +/// with the SN3D signals [`ambisonic_encode`] makes. +pub fn ambisonic_decode(az: f32, el: f32, n: usize) -> [f32; 4] { + let (a, e) = (fin(az, 0.0).to_radians(), fin(el, 0.0).to_radians()); + let k = 1.0 / n.max(1) as f32; + [k, 3.0 * k * -a.sin() * e.cos(), 3.0 * k * e.sin(), 3.0 * k * a.cos() * e.cos()] +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::gain_to_db; + + #[test] + fn center_levels() { + for law in [PanLaw::Minus3, PanLaw::Minus4_5, PanLaw::Minus6, PanLaw::Zero] { + let (l, r) = gains(0.0, law); + assert!((gain_to_db(l) - law.center_db()).abs() < 0.02, "{law:?}"); + assert!((l - r).abs() < 1e-6); + let (l, r) = gains(-1.0, law); + assert!((l - 1.0).abs() < 1e-6 && r.abs() < 1e-6); + } + assert_eq!(gains(f32::NAN, PanLaw::Minus6), gains(0.0, PanLaw::Minus6)); + } + + fn layout_51() -> Vec { + [(-30.0, false), (30.0, false), (0.0, false), (0.0, true), (-110.0, false), (110.0, false)] + .iter() + .map(|&(az, lfe)| SpeakerPos { az, el: 0.0, lfe }) + .collect() + } + + fn layout_714() -> Vec { + let mut v: Vec = + [-30.0, 30.0, 0.0, 0.0, -150.0, 150.0, -90.0, 90.0].iter().enumerate().map(|(i, &az)| SpeakerPos { az, el: 0.0, lfe: i == 3 }).collect(); + for az in [-45.0, 45.0, -135.0, 135.0] { + v.push(SpeakerPos { az, el: 45.0, lfe: false }); + } + v + } + + fn params(x: f32, y: f32) -> SurroundParams { + SurroundParams { x, y, z: 0.0, divergence: 0.0, center: 1.0 } + } + + #[test] + fn surround_energy_is_constant() { + for layout in [layout_51(), layout_714()] { + let mut g = [0.0f32; MAX_SPEAKERS]; + for xi in -4..=4 { + for yi in -4..=4 { + for div in [0.0, 0.3, 1.0] { + for z in [0.0, 0.5, 1.0] { + for center in [0.0, 0.5, 1.0] { + let p = SurroundParams { x: xi as f32 / 4.0, y: yi as f32 / 4.0, z, divergence: div, center }; + surround_gains(&layout, &p, &mut g); + let e: f32 = g.iter().zip(layout.iter()).filter(|(_, s)| !s.lfe).map(|(x, _)| x * x).sum(); + assert!((e - 1.0).abs() < 1e-4, "energy {e} at {p:?}"); + assert!(g.iter().zip(layout.iter()).all(|(x, s)| !s.lfe || *x == 0.0), "the LFE is never panned to"); + } + } + } + } + } + } + } + + #[test] + fn surround_point_positions() { + let l = layout_51(); + let mut g = [0.0f32; MAX_SPEAKERS]; + // Front center with no divergence: the center speaker only. + surround_gains(&l, ¶ms(0.0, 1.0), &mut g); + assert!((g[2] - 1.0).abs() < 1e-5 && g.iter().enumerate().all(|(i, x)| i == 2 || x.abs() < 1e-3), "{g:?}"); + // Divergence spreads the center image. + surround_gains(&l, &SurroundParams { divergence: 0.5, ..params(0.0, 1.0) }, &mut g); + assert!(g[2] < 0.99 && g[0] > 0.05 && g[1] > 0.05); + // Front-left corner: the left speaker only. + surround_gains(&l, ¶ms(-1.0, 1.0), &mut g); + assert!((g[0] - 1.0).abs() < 1e-5 && g.iter().enumerate().all(|(i, x)| i == 0 || x.abs() < 1e-3), "{g:?}"); + // Rear-right corner: the right surround only. + surround_gains(&l, ¶ms(1.0, -1.0), &mut g); + assert!((g[5] - 1.0).abs() < 1e-5, "{g:?}"); + // Phantom center (center share 0): left and right at -3 dB, nothing on the center. + surround_gains(&l, &SurroundParams { center: 0.0, ..params(0.0, 1.0) }, &mut g); + assert!(g[2].abs() < 1e-6 && (g[0] - std::f32::consts::FRAC_1_SQRT_2).abs() < 1e-4); + // Overhead on 7.1.4: the heights only. + let l = layout_714(); + surround_gains(&l, &SurroundParams { z: 1.0, ..params(-1.0, 1.0) }, &mut g); + let top: f32 = g[8..12].iter().map(|x| x * x).sum(); + assert!((top - 1.0).abs() < 1e-4 && g[8] > 0.9, "{g:?}"); + // Corner positions map onto speaker angles and back. + let (x, y) = azimuth_to_puck(&l, -150.0); + assert!((x + 1.0).abs() < 1e-3 && (y + 1.0).abs() < 1e-3, "{x} {y}"); + assert!((puck_azimuth(&l, 0.0, -1.0).abs() - 180.0).abs() < 1e-3); + // Hostile input never produces NaN, and an empty layout gives silence. + surround_gains(&l, &SurroundParams { x: f32::NAN, y: f32::INFINITY, z: f32::NAN, divergence: f32::NAN, center: f32::NAN }, &mut g); + assert!(g.iter().all(|x| x.is_finite())); + surround_gains(&[], ¶ms(0.0, 1.0), &mut g); + assert!(g.iter().all(|x| *x == 0.0)); + } + + #[test] + fn direction_gains_fold_heights_to_the_bed() { + let mut g = [0.0f32; MAX_SPEAKERS]; + direction_gains(&layout_51(), 30.0, 45.0, &mut g); + assert!((g[1] - std::f32::consts::FRAC_1_SQRT_2).abs() < 1e-5, "{g:?}"); + } + + #[test] + fn direction_gains_use_the_heights_when_there_is_no_bed() { + let layout: Vec = [-45.0, 45.0, -135.0, 135.0].iter().map(|&az| SpeakerPos { az, el: 45.0, lfe: false }).collect(); + let mut g = [0.0f32; MAX_SPEAKERS]; + direction_gains(&layout, 45.0, 0.0, &mut g); + assert!((g[1] - 1.0).abs() < 1e-5, "{g:?}"); + let power: f32 = g.iter().map(|v| v * v).sum(); + assert!((power - 1.0).abs() < 1e-5, "{g:?}"); + } + + #[test] + fn ambisonics_encode_and_decode_point_at_the_source() { + // SN3D: an undiffused source has W = 1 and directional components of unit length. + let mut b = [0.0f32; 6]; + ambisonic_encode(40.0, 20.0, 0.0, &mut b); + assert_eq!(b[0], 1.0); + assert!(((b[1] * b[1] + b[2] * b[2] + b[3] * b[3]) - 1.0).abs() < 1e-5); + assert_eq!(&b[4..], &[0.0, 0.0]); + // Hard left (-90 degrees here) is +Y in ambisonic coordinates. + ambisonic_encode(-90.0, 0.0, 0.0, &mut b); + assert!((b[1] - 1.0).abs() < 1e-6 && b[3].abs() < 1e-6); + // Full spread leaves only W. + ambisonic_encode(40.0, 20.0, 1.0, &mut b); + assert_eq!(&b[..4], &[1.0, 0.0, 0.0, 0.0]); + // On a cube of 8 speakers the speaker nearest the source gets the most. + let cube: Vec<(f32, f32)> = [-45.0, 45.0, 135.0, -135.0].iter().flat_map(|&az| [(az, 35.26), (az, -35.26)]).collect(); + ambisonic_encode(50.0, 30.0, 0.0, &mut b); + let feed = |&(az, el): &(f32, f32)| ambisonic_decode(az, el, cube.len()).iter().zip(&b).map(|(d, s)| d * s).sum::(); + let feeds: Vec = cube.iter().map(feed).collect(); + let best = feeds.iter().enumerate().fold((0, f32::MIN), |m, (i, &v)| if v > m.1 { (i, v) } else { m }).0; + assert_eq!(cube[best], (45.0, 35.26), "{feeds:?}"); + assert!(ambisonic_decode(f32::NAN, f32::INFINITY, 0).iter().all(|v| v.is_finite())); + } +} diff --git a/crates/audio-dsp/src/resample.rs b/crates/audio-dsp/src/resample.rs new file mode 100644 index 000000000..42f594bd0 --- /dev/null +++ b/crates/audio-dsp/src/resample.rs @@ -0,0 +1,424 @@ +//! Streaming sample-rate conversion for playback, when the output device runs at another rate +//! than the sequence (a 44.1 kHz device playing a 48 kHz sequence). +//! +//! Every output sample's source position comes from its absolute output frame, as an exact +//! rational (`frame × from / to`), and is linearly interpolated, so the output is identical however +//! the stream is cut into blocks: no phase jump at block boundaries. Source frames are pulled in +//! contiguous, non-overlapping spans, so whatever produces them (the mixer, with its effect state) +//! sees one continuous stream. Output lags the source by one source sample (≈21 µs at 48 kHz), +//! which is what lets each block interpolate without reading ahead. +//! +//! When the rate goes down, the source first passes an elliptic low-pass (9th order, 0.1 dB +//! ripple up to 0.42 × the output rate, 80 dB stop band) as it is pulled, so content above the +//! output's Nyquist frequency does not fold back into the audible band. The filter delays the +//! source a little more (its group delay, a few output samples in the pass band) and starts from +//! silence after a seek. + +use crate::biquad::Biquad; +use crate::design::{Band, Family, Sections, Spec, design}; + +/// Converts a planar stream from `from` Hz to `to` Hz, block by block. +#[derive(Debug, Clone)] +pub struct StreamResampler { + from: u32, + to: u32, + /// Source frames `[held_start, held_start + held[c].len())` kept from the last pull. + held_start: i64, + held: Vec>, + /// The output frame the next block is expected to start at (contiguous playback). + next_out: Option, + /// The anti-aliasing low-pass when the rate goes down, and its state per channel. + aa: Option, + aa_state: Vec>, +} + +/// Maximum source frames fetched in a single resampler pull. +pub const MAX_RESAMPLE_SOURCE_SPAN: usize = 384_000 * 10; + +/// Largest output position, either side of 0, that [`StreamResampler::process`] reads (about 23 +/// years at 1.536 MHz); a position or block end beyond it is clamped to it. Source positions then +/// stay far inside `i64`. +pub const MAX_RESAMPLE_POSITION: i64 = 1 << 50; + +/// Most output frames one [`StreamResampler::process`] call returns. +pub const MAX_RESAMPLE_BLOCK: usize = 65_536; + +/// Most source samples, over all channels, the resampler holds at once (16 MiB of `f32`). +pub const MAX_RESAMPLE_HELD: usize = 1 << 22; + +impl StreamResampler { + /// Both rates are clamped to [`crate::MIN_SAMPLE_RATE`] ..= [`crate::MAX_SAMPLE_RATE`] (1 kHz + /// to 1.536 MHz), so one output frame never needs more than 1,536 source frames. + pub fn new(from: u32, to: u32) -> Self { + let sane = |r: u32| r.clamp(crate::MIN_SAMPLE_RATE as u32, crate::MAX_SAMPLE_RATE as u32); + let (from, to) = (sane(from), sane(to)); + let aa = (from > to).then(|| { + let spec = Spec { family: Family::Elliptic, band: Band::LowPass, order: 9, f1: 0.42 * to as f64, f2: 0.0, ripple_db: 0.1, stop_db: 80.0 }; + design(&spec, from as f64) + }); + Self { from, to, held_start: 0, held: Vec::new(), next_out: None, aa, aa_state: Vec::new() } + } + + /// Append `want` frames of `got` to the held source, through the anti-aliasing filter when + /// there is one. The first span after a seek sets the channel count and starts the filter + /// from silence. + fn append(&mut self, got: &[Vec], want: usize) { + if self.held.is_empty() { + let channels = crate::sane_channels(got.len()); + self.held = vec![Vec::new(); channels]; + let sections = self.aa.map_or(0, |s| s.n); + self.aa_state = vec![vec![Biquad::new(); sections]; channels]; + } + for (c, (h, state)) in self.held.iter_mut().zip(&mut self.aa_state).enumerate() { + let src = got.get(c).map(Vec::as_slice).unwrap_or_default(); + let raw = (0..want).map(|i| src.get(i).copied().filter(|v| v.is_finite()).unwrap_or(0.0)); + match &self.aa { + Some(aa) => h.extend(raw.map(|x| { + let mut y = f64::from(x); + for (s, coeffs) in state.iter_mut().zip(aa.as_slice()) { + y = s.tick(coeffs, y); + } + y as f32 + })), + None => h.extend(raw), + } + } + } + + pub fn rates(&self) -> (u32, u32) { + (self.from, self.to) + } + + /// The source frame whose sample lands at (or just before) output frame `out`, and the + /// remainder of the exact position in units of `1 / to` source frames. + fn source_index(&self, out: i64) -> (i64, i64) { + let p = out as i128 * self.from as i128; + let to = self.to as i128; + (p.div_euclid(to) as i64, p.rem_euclid(to) as i64) + } + + /// Output frames `[out, out + n)`, planar. `pull(start, frames)` returns source frames + /// `[start, start + frames)`, planar (missing samples read as silence). A block that does not + /// continue the previous one (a seek) starts the stream afresh. + /// + /// A block longer than [`MAX_RESAMPLE_BLOCK`] frames returns its first `MAX_RESAMPLE_BLOCK` + /// frames. The block is resampled in parts whose source span holds at most + /// [`MAX_RESAMPLE_HELD`] samples across 64 channels, so a pull asks for at most + /// `MAX_RESAMPLE_HELD / 64` frames. + pub fn process(&mut self, out: i64, n: usize, mut pull: impl FnMut(i64, usize) -> Vec>) -> Vec> { + let n = n.min(MAX_RESAMPLE_BLOCK); + if n == 0 { + return vec![Vec::new(); self.held.len().max(1)]; + } + let ratio = self.from.div_ceil(self.to) as usize + 2; + let part = (MAX_RESAMPLE_HELD / crate::MAX_CHANNELS / ratio).max(1); + let mut dst: Vec> = Vec::new(); + let mut done = 0; + while done < n { + let len = part.min(n - done); + let got = self.block(out.saturating_add(done as i64), len, &mut pull); + if dst.is_empty() { + dst = got.iter().map(|_| Vec::with_capacity(n)).collect(); + } + for (d, g) in dst.iter_mut().zip(&got) { + d.extend_from_slice(g); + } + done += len; + } + dst + } + + fn block(&mut self, out: i64, n: usize, pull: &mut impl FnMut(i64, usize) -> Vec>) -> Vec> { + let out = out.clamp(-MAX_RESAMPLE_POSITION, MAX_RESAMPLE_POSITION); + let end = out.saturating_add(i64::try_from(n - 1).unwrap_or(i64::MAX)).min(MAX_RESAMPLE_POSITION); + let (first, first_rem) = self.source_index(out); + let (last, _) = self.source_index(end); + // interpolation reads source frames first - 1 ..= last + if self.next_out != Some(out) || self.held.is_empty() { + self.held_start = first - 1; + self.held.clear(); + } + // A block that needs more than one span pulls several, in order. + loop { + let held_end = self.held_start + self.held.first().map_or(0, Vec::len) as i64; + if last < held_end { + break; + } + let want = ((last + 1 - held_end) as usize).min(MAX_RESAMPLE_SOURCE_SPAN); + let got = pull(held_end, want); + self.append(&got, want); + } + let mut dst = vec![vec![0.0f32; n]; self.held.len()]; + let to = self.to as i64; + let (step, rem_step) = ((self.from / self.to) as i64, (self.from % self.to) as i64); + let (mut s, mut rem) = (first, first_rem); + for i in 0..n { + let frac = (rem as f64 / to as f64) as f32; + // held starts at first - 1, so the earlier frame is always held + let k = usize::try_from(s - self.held_start).unwrap_or(0); + for (d, h) in dst.iter_mut().zip(&self.held) { + let a = k.checked_sub(1).and_then(|j| h.get(j)).copied().unwrap_or(0.0); + let b = h.get(k).copied().unwrap_or(0.0); + if let Some(x) = d.get_mut(i) { + *x = a + (b - a) * frac; + } + } + s = s.wrapping_add(step); + rem += rem_step; + if rem >= to { + rem -= to; + s = s.wrapping_add(1); + } + } + // keep what the next block can still read: from its first frame - 1 on + let (next_first, _) = self.source_index(out.saturating_add(n as i64)); + let drop = (next_first - 1 - self.held_start).clamp(0, self.held.first().map_or(0, Vec::len) as i64) as usize; + for h in &mut self.held { + h.drain(..drop); + } + self.held_start += drop as i64; + self.next_out = Some(out.saturating_add(n as i64)); + dst + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A sine at `hz`, sampled at `rate`, from absolute frame `start`; logs every pull. + fn sine(hz: f64, rate: u32, pulls: &mut Vec<(i64, usize)>) -> impl FnMut(i64, usize) -> Vec> + '_ { + move |start, frames| { + pulls.push((start, frames)); + let ch: Vec = + (0..frames).map(|i| (2.0 * std::f64::consts::PI * hz * (start + i as i64) as f64 / rate as f64).sin() as f32).collect(); + vec![ch.clone(), ch] + } + } + + fn convert(from: u32, to: u32, blocks: &[usize], total: usize) -> (Vec, Vec<(i64, usize)>) { + let mut r = StreamResampler::new(from, to); + let mut pulls = Vec::new(); + let mut out = Vec::new(); + let mut pos = 0i64; + let mut k = 0; + while (pos as usize) < total { + let n = blocks[k % blocks.len()].min(total - pos as usize); + let b = r.process(pos, n, sine(1000.0, from, &mut pulls)); + assert_eq!(b.len(), 2); + assert!(b.iter().all(|c| c.len() == n)); + out.extend_from_slice(&b[0]); + pos += n as i64; + k += 1; + } + (out, pulls) + } + + #[test] + fn output_is_the_same_however_the_stream_is_cut() { + for (from, to) in [(48_000, 44_100), (44_100, 48_000), (48_000, 96_000), (96_000, 48_000)] { + let (whole, _) = convert(from, to, &[20_000], 20_000); + for blocks in [&[512][..], &[333], &[1, 7, 512, 64]] { + let (cut, _) = convert(from, to, blocks, 20_000); + assert_eq!(cut, whole, "{from}→{to} in blocks {blocks:?}"); + } + } + } + + /// `process` as it was with one i128 division per output sample. + fn reference_process(r: &mut StreamResampler, out: i64, n: usize, mut pull: impl FnMut(i64, usize) -> Vec>) -> Vec> { + let (from, to) = (r.from as i128, r.to as i128); + let index = |out: i64| { + let p = out as i128 * from; + (p.div_euclid(to) as i64, (p.rem_euclid(to) as f64 / to as f64) as f32) + }; + if n == 0 { + return vec![Vec::new(); r.held.len().max(1)]; + } + let (first, _) = index(out); + let (last, _) = index(out.saturating_add(n as i64 - 1)); + if r.next_out != Some(out) || r.held.is_empty() { + r.held_start = first - 1; + r.held.clear(); + } + let held_end = r.held_start + r.held.first().map_or(0, Vec::len) as i64; + if last + 1 > held_end { + let want = ((last + 1 - held_end) as usize).min(MAX_RESAMPLE_SOURCE_SPAN); + let got = pull(held_end, want); + r.append(&got, want); + } + let mut dst = vec![vec![0.0f32; n]; r.held.len()]; + for (i, frame) in (out..).take(n).enumerate() { + let (s, frac) = index(frame); + let k = usize::try_from(s - r.held_start).unwrap_or(0); + for (d, h) in dst.iter_mut().zip(&r.held) { + let a = k.checked_sub(1).and_then(|j| h.get(j)).copied().unwrap_or(0.0); + let b = h.get(k).copied().unwrap_or(0.0); + if let Some(x) = d.get_mut(i) { + *x = a + (b - a) * frac; + } + } + } + let (next_first, _) = index(out.saturating_add(n as i64)); + let drop = (next_first - 1 - r.held_start).clamp(0, r.held.first().map_or(0, Vec::len) as i64) as usize; + for h in &mut r.held { + h.drain(..drop); + } + r.held_start += drop as i64; + r.next_out = Some(out.saturating_add(n as i64)); + dst + } + + #[test] + fn stepped_source_positions_are_bit_identical_to_per_sample_division() { + let bits = |b: &[Vec]| b.iter().map(|c| c.iter().map(|v| v.to_bits()).collect::>()).collect::>(); + for (from, to) in [ + (48_000, 44_100), + (44_100, 48_000), + (96_000, 48_000), + (48_000, 48_000), + (48_000, 96_000), + (44_100, 22_050), + (7, 384_000), + (176_400, 1_001), + ] { + let (mut new, mut old) = (StreamResampler::new(from, to), StreamResampler::new(from, to)); + let mut k = 0; + for start in [0i64, -5_000, 1_000_000_007, -3, i64::MAX / 2_000_000] { + let mut pos = start; + for _ in 0..12 { + let n = [1, 7, 333, 512, 64][k % 5]; + k += 1; + let (mut pa, mut pb) = (Vec::new(), Vec::new()); + let a = new.process(pos, n, sine(440.0, from, &mut pa)); + let b = reference_process(&mut old, pos, n, sine(440.0, from, &mut pb)); + assert_eq!(bits(&a), bits(&b), "{from}→{to} at {pos} + {n}"); + // `process` may split a span into several consecutive pulls. + let merged = pa.iter().fold(Vec::<(i64, usize)>::new(), |mut m, &(s, f)| { + match m.last_mut() { + Some(last) if last.0 + last.1 as i64 == s => last.1 += f, + _ => m.push((s, f)), + } + m + }); + assert_eq!(merged, pb); + pos += n as i64; + } + } + } + } + + #[test] + fn a_tone_converts_to_the_same_tone() { + // 1 kHz at 44.1 kHz played on a 48 kHz device: within linear interpolation's error of the + // ideal tone, one source sample late + let (from, to) = (44_100u32, 48_000u32); + let (out, _) = convert(from, to, &[512], 20_000); + for (o, x) in out.iter().enumerate().skip(2) { + let t = o as f64 / to as f64 - 1.0 / from as f64; + let want = (2.0 * std::f64::consts::PI * 1000.0 * t).sin() as f32; + assert!((x - want).abs() < 3e-3, "frame {o}: {x} vs {want}"); + } + // Going down, the low-pass keeps the tone's level (0.1 dB ripple) and frequency. + let (from, to) = (48_000u32, 44_100u32); + let (out, _) = convert(from, to, &[512], 20_000); + let a = crate::testutil::tone_amplitude(&out[4_000..], 1000.0, to as f64); + assert!((a - 1.0).abs() < 0.015, "{a}"); + } + + #[test] + fn going_down_does_not_fold_content_above_the_output_nyquist_back() { + // 30 kHz at 96 kHz on a 48 kHz device would land at 18 kHz without the low-pass. + let (from, to) = (96_000u32, 48_000u32); + let mut r = StreamResampler::new(from, to); + let mut pulls = Vec::new(); + let out = r.process(0, 24_000, |s, f| { + pulls.push((s, f)); + let ch: Vec = (0..f).map(|i| (2.0 * std::f64::consts::PI * 30_000.0 * (s + i as i64) as f64 / from as f64).sin() as f32).collect(); + vec![ch] + }); + let alias = crate::testutil::tone_amplitude(&out[0][4_000..], 18_000.0, to as f64); + assert!(alias < 1e-3, "the 18 kHz alias is at {alias}"); + } + + #[test] + fn the_source_is_pulled_as_one_continuous_stream() { + for (from, to) in [(48_000, 44_100), (44_100, 48_000)] { + let (_, pulls) = convert(from, to, &[512, 333], 20_000); + for w in pulls.windows(2) { + assert_eq!(w[0].0 + w[0].1 as i64, w[1].0, "{from}→{to}: {:?} then {:?}", w[0], w[1]); + } + } + } + + #[test] + fn a_seek_starts_afresh_and_hostile_input_stays_finite() { + let mut r = StreamResampler::new(48_000, 44_100); + let mut pulls = Vec::new(); + let _ = r.process(0, 512, sine(1000.0, 48_000, &mut pulls)); + let _ = r.process(1_000_000, 512, sine(1000.0, 48_000, &mut pulls)); + assert_eq!(pulls.last().map(|p| p.0), Some(1_000_000 * 48_000 / 44_100 - 1)); + // a mixer returning too few channels and samples, and zero rates + let mut r = StreamResampler::new(0, 0); + let b = r.process(5, 64, |_, _| vec![vec![1.0; 3]]); + assert_eq!(b.len(), 1); + assert!(b[0].iter().all(|x| x.is_finite())); + assert!(r.process(0, 0, |_, _| Vec::new()).iter().all(Vec::is_empty)); + // A rate far outside the range is clamped, so a short block pulls a bounded span. + let mut r = StreamResampler::new(u32::MAX, 1); + assert_eq!(r.rates(), (1_536_000, 1_000)); + let mut pulled = 0usize; + let _ = r.process(0, 4, |_, frames| { + pulled += frames; + vec![vec![0.0; frames]] + }); + assert!(pulled <= 4 * 1_536 + 2, "{pulled}"); + // Extreme positions are clamped instead of overflowing. + for pos in [i64::MIN, i64::MAX, -MAX_RESAMPLE_POSITION - 1] { + let mut r = StreamResampler::new(1_536_000, 1_000); + let out = r.process(pos, 8, |_, frames| vec![vec![0.25; frames]]); + assert!(out[0].iter().all(|v| v.is_finite()), "{pos}"); + } + // A pull that returns too many channels keeps the first `MAX_CHANNELS`. + let mut r = StreamResampler::new(48_000, 48_000); + let out = r.process(0, 1, |_, frames| vec![vec![0.5; frames]; 1_000]); + assert_eq!(out.len(), crate::MAX_CHANNELS); + } + + /// A block whose source span is longer than one pull is filled from several pulls. + #[test] + fn a_block_longer_than_one_pull_is_filled_completely() { + let mut r = StreamResampler::new(1_536_000, 1_000); + let mut spans = Vec::new(); + let out = r.process(0, 2_501, |start, frames| { + spans.push((start, frames)); + vec![vec![1.0; frames]] + }); + assert!(spans.len() > 1, "{spans:?}"); + assert!(spans.iter().all(|&(_, f)| f <= MAX_RESAMPLE_SOURCE_SPAN)); + assert!(spans.windows(2).all(|w| w[0].0 + w[0].1 as i64 == w[1].0), "{spans:?}"); + // The low-pass rings for a while after the stream starts, then settles on the constant; + // no sample is left silent. + assert!(out[0][3..].iter().all(|&x| x > 0.5), "a sample of the block was left silent"); + assert!(out[0][500..].iter().all(|&x| (x - 1.0).abs() < 1e-2), "{:?}", &out[0][500..520]); + } + + /// The widest ratio with 64 channels holds and pulls a bounded span, and an oversized block + /// returns `MAX_RESAMPLE_BLOCK` frames. + #[test] + fn source_held_and_block_length_are_bounded() { + let mut r = StreamResampler::new(1_536_000, 1_000); + let mut widest = 0; + let out = r.process(0, 1_024, |_, frames| { + widest = widest.max(frames); + vec![vec![0.5; frames]; 64] + }); + assert_eq!((out.len(), out[0].len()), (64, 1_024)); + assert!(widest <= MAX_RESAMPLE_HELD / 64, "{widest}"); + assert!(r.held.iter().map(Vec::len).sum::() <= MAX_RESAMPLE_HELD); + let mut r = StreamResampler::new(48_000, 48_000); + let out = r.process(0, usize::MAX, |_, frames| vec![vec![0.5; frames]]); + assert_eq!(out[0].len(), MAX_RESAMPLE_BLOCK); + assert!(out[0].iter().all(|&x| x == 0.5)); + } +} diff --git a/crates/audio-dsp/src/smooth.rs b/crates/audio-dsp/src/smooth.rs new file mode 100644 index 000000000..001279736 --- /dev/null +++ b/crates/audio-dsp/src/smooth.rs @@ -0,0 +1,100 @@ +//! Per-sample parameter smoothing (linear ramps) to avoid zipper noise. + +/// A value that ramps linearly to its target over a fixed number of samples. +#[derive(Clone, Copy, Debug)] +pub struct Smoothed { + current: f64, + target: f64, + step: f64, + remaining: u32, + ramp: u32, +} + +impl Smoothed { + /// `ramp_samples` = length of a full transition (0 = no smoothing). + pub fn new(value: f32, ramp_samples: u32) -> Self { + Smoothed { current: value as f64, target: value as f64, step: 0.0, remaining: 0, ramp: ramp_samples } + } + /// Convenience: ramp length from a time in milliseconds. + pub fn with_ms(value: f32, sample_rate: f32, ms: f32) -> Self { + Self::new(value, (sample_rate * ms / 1000.0).round().max(0.0) as u32) + } + /// Start ramping towards `target`. + pub fn set(&mut self, target: f32) { + let t = target as f64; + if t == self.target { + return; + } + self.target = t; + if self.ramp == 0 { + self.current = t; + self.remaining = 0; + } else { + self.remaining = self.ramp; + self.step = (t - self.current) / self.ramp as f64; + } + } + /// Jump straight to the target. + pub fn snap(&mut self) { + self.current = self.target; + self.remaining = 0; + } + /// Advance one sample and return the new value. + #[inline] + pub fn tick(&mut self) -> f32 { + if self.remaining > 0 { + self.remaining -= 1; + if self.remaining == 0 { + self.current = self.target; + } else { + self.current += self.step; + } + } + self.current as f32 + } + /// Current value without advancing. + #[inline] + pub fn value(&self) -> f32 { + self.current as f32 + } + pub fn target(&self) -> f32 { + self.target as f32 + } + pub fn is_smoothing(&self) -> bool { + self.remaining > 0 + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn ramps_linearly_and_lands_exactly() { + let mut s = Smoothed::new(0.0, 4); + s.set(1.0); + let v: Vec = (0..6).map(|_| s.tick()).collect(); + assert_eq!(v, vec![0.25, 0.5, 0.75, 1.0, 1.0, 1.0]); + assert!(!s.is_smoothing()); + } + + #[test] + fn retarget_mid_ramp_is_continuous() { + let mut s = Smoothed::new(0.0, 10); + s.set(1.0); + for _ in 0..5 { + s.tick(); + } + let mid = s.value(); + s.set(0.0); + let n = s.tick(); + assert!((n - mid).abs() <= 0.1 + 1e-6); + } + + #[test] + fn zero_ramp_is_immediate() { + let mut s = Smoothed::new(0.0, 0); + s.set(3.0); + assert_eq!(s.value(), 3.0); + } +} diff --git a/crates/audio-dsp/src/stretch.rs b/crates/audio-dsp/src/stretch.rs new file mode 100644 index 000000000..7e8c2ace9 --- /dev/null +++ b/crates/audio-dsp/src/stretch.rs @@ -0,0 +1,231 @@ +//! Time stretch that keeps the pitch: WSOLA (waveform-similarity overlap-add). +//! +//! The output is made of grains two hops long, overlapped by one hop with a raised-cosine window +//! (the falling half of one grain plus the rising half of the next always sums to one). Grain `k` +//! is read from the input near its nominal position (where the speed puts output hop `k`), shifted +//! by at most the tolerance to the position whose first hop best matches the previous grain's +//! natural continuation: the input that would have followed that grain at speed 1. The two halves +//! that are crossfaded are then in phase, so a steady tone keeps its level and its pitch. +//! +//! [`Wsola`] holds the sizes and the window; the caller keeps the chain of grain positions (each +//! one follows from the one before, see [`Wsola::align`]) and reads the input however it is +//! stored. Nothing here allocates per call or keeps state between calls. + +/// WSOLA sizes and window for one sample rate. +#[derive(Clone, Debug)] +pub struct Wsola { + hop: usize, + tolerance: usize, + /// The window's rising half, `hop` samples; the falling half is `1 - rise`. + rise: Vec, +} + +impl Wsola { + /// Sizes for `sample_rate`: 15 ms hops (30 ms grains) and an 8 ms search either side, which + /// covers a period of every pitch above 62 Hz. + pub fn new(sample_rate: u32) -> Self { + let sr = f64::from(sample_rate.clamp(1_000, 768_000)); + let hop = ((sr * 0.015).round() as usize).max(16); + let tolerance = ((sr * 0.008).round() as usize).max(4); + let rise = (0..hop) + .map(|t| { + let s = (std::f64::consts::FRAC_PI_2 * (t as f64 + 0.5) / hop as f64).sin(); + (s * s) as f32 + }) + .collect(); + Wsola { hop, tolerance, rise } + } + + /// Output samples between grains (half a grain). + pub fn hop(&self) -> usize { + self.hop + } + + /// How far (samples) a grain may move from its nominal position. + pub fn tolerance(&self) -> usize { + self.tolerance + } + + /// Where to read the next grain: the position within the tolerance of `nominal` whose first + /// hop of `guide` best matches the hop at `continuation` (the previous grain's position plus + /// one hop). Positions index `guide` (a mono mix of the input); candidates whose hop would + /// leave it are skipped, and `nominal` is returned when there is nothing to match (the + /// continuation is outside `guide`, or silent). Ties go to the candidate closest to `nominal`. + pub fn align(&self, guide: &[f32], continuation: i64, nominal: i64) -> i64 { + let h = self.hop; + let len = guide.len() as i64; + let window = |p: i64| -> Option<&[f32]> { + if p < 0 || p.checked_add(h as i64)? > len { + return None; + } + guide.get(p as usize..p as usize + h) + }; + let Some(template) = window(continuation) else { return nominal }; + if template.iter().all(|x| x.abs() < 1e-9) { + return nominal; + } + // normalized cross-correlation (the template's own energy is the same for every candidate) + let score = |p: i64, step: usize| -> Option { + let cand = window(p)?; + let (mut xy, mut yy) = (0.0f64, 0.0f64); + for (x, y) in template.iter().zip(cand).step_by(step) { + xy += f64::from(*x) * f64::from(*y); + yy += f64::from(*y) * f64::from(*y); + } + Some(if yy > 1e-18 { xy / yy.sqrt() } else { 0.0 }) + }; + let tol = self.tolerance as i64; + // coarse pass on every other offset and sample, nearest offsets first so ties keep them; + // then the neighbors of the best at full resolution + let consider = |d: i64, step: usize, best: &mut Option<(i64, f64)>| { + if let Some(s) = score(nominal.saturating_add(d), step) + && best.is_none_or(|(_, b)| s > b) + { + *best = Some((d, s)); + } + }; + let mut best = None; + let mut d = 0; + while d <= tol { + consider(d, 2, &mut best); + if d > 0 { + consider(-d, 2, &mut best); + } + d += 2; + } + let Some((coarse, _)) = best else { return nominal }; + let mut fine = None; + for d in [coarse, coarse - 1, coarse + 1] { + if d.abs() <= tol { + consider(d, 1, &mut fine); + } + } + nominal.saturating_add(fine.map_or(coarse, |(d, _)| d)) + } + + /// One output hop: the previous grain's falling half (`prev`, the samples one hop into it) + /// crossfaded into the next grain's rising half (`cur`). Writes `out.len()` samples, at most a + /// hop; missing input reads as silence. + pub fn overlap(&self, prev: &[f32], cur: &[f32], out: &mut [f32]) { + for (t, o) in out.iter_mut().enumerate().take(self.hop) { + let r = self.rise(t); + let a = prev.get(t).copied().unwrap_or(0.0); + let b = cur.get(t).copied().unwrap_or(0.0); + *o = a * (1.0 - r) + b * r; + } + } + + /// The window's weight for the next grain at sample `t` of a hop (the previous grain gets one + /// minus this). + pub fn rise(&self, t: usize) -> f32 { + self.rise.get(t).copied().unwrap_or(1.0) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// `input` stretched to play at `speed` (2.0 = twice as fast) the way a caller chains grains: + /// hop `k` reads grain `k` near `k * hop * speed`, aligned to the previous grain. + fn stretch(w: &Wsola, input: &[f32], speed: f64) -> Vec { + let h = w.hop() as i64; + let out_len = (input.len() as f64 / speed) as usize; + let hops = out_len as i64 / h; + let mut pos = vec![0i64]; + for k in 1..=hops { + let nominal = (k as f64 * h as f64 * speed).round() as i64; + let prev = *pos.last().unwrap(); + pos.push(w.align(input, prev + h, nominal)); + } + let mut out = vec![0.0f32; (hops as usize) * w.hop()]; + let slice = |p: i64| input.get(p.max(0) as usize..).unwrap_or(&[]); + for k in 1..=hops as usize { + let (prev, cur) = (pos[k - 1] + h, pos[k]); + let o = &mut out[(k - 1) * w.hop()..k * w.hop()]; + w.overlap(slice(prev), slice(cur), o); + } + out + } + + fn sine(freq: f64, sr: f64, n: usize) -> Vec { + (0..n).map(|i| (2.0 * std::f64::consts::PI * freq * i as f64 / sr).sin() as f32 * 0.8).collect() + } + + /// Positive-going zero crossings per second. + fn frequency(x: &[f32], sr: f64) -> f64 { + let n = x.windows(2).filter(|w| w[0] < 0.0 && w[1] >= 0.0).count(); + n as f64 * sr / x.len() as f64 + } + + fn rms(x: &[f32]) -> f64 { + (x.iter().map(|v| f64::from(*v) * f64::from(*v)).sum::() / x.len().max(1) as f64).sqrt() + } + + #[test] + fn the_window_halves_sum_to_one() { + for sr in [8_000, 44_100, 48_000, 96_000] { + let w = Wsola::new(sr); + assert!(w.hop() >= 16 && w.tolerance() >= 4); + let (ones, mut out) = (vec![1.0; w.hop()], vec![0.0; w.hop()]); + w.overlap(&ones, &ones, &mut out); + assert!(out.iter().all(|v| (v - 1.0).abs() < 1e-6), "{sr}"); + assert!(w.rise(0) < 0.01 && w.rise(w.hop() - 1) > 0.99); + } + } + + #[test] + fn a_tone_keeps_its_pitch_and_level_faster_and_slower() { + let sr = 48_000.0; + let w = Wsola::new(sr as u32); + for freq in [110.0, 440.0, 1000.0] { + let input = sine(freq, sr, 48_000 * 2); + for speed in [0.5, 0.8, 1.25, 2.0, 3.0] { + let out = stretch(&w, &input, speed); + let expect = (input.len() as f64 / speed) as usize; + assert!(out.len() + w.hop() >= expect && out.len() <= expect, "{freq} Hz × {speed}: {} vs {expect}", out.len()); + let f = frequency(&out[w.hop()..], sr); + assert!((f - freq).abs() < freq * 0.02 + 2.0, "{freq} Hz × {speed}: {f} Hz"); + // in-phase crossfades: no dips in level, no clicks (a step bigger than the sine's own slope) + let level = rms(&out[w.hop()..]); + assert!((level - 0.8 / 2f64.sqrt()).abs() < 0.03, "{freq} Hz × {speed}: rms {level}"); + let slope = 0.8 * 2.0 * std::f64::consts::PI * freq / sr; + let step = out[w.hop()..].windows(2).map(|p| f64::from((p[1] - p[0]).abs())).fold(0.0, f64::max); + assert!(step < slope * 1.3, "{freq} Hz × {speed}: step {step} vs slope {slope}"); + } + } + } + + #[test] + fn silence_and_out_of_range_positions_keep_the_nominal_position() { + let w = Wsola::new(48_000); + let quiet = vec![0.0f32; 10_000]; + assert_eq!(w.align(&quiet, 2_000, 3_000), 3_000); + let tone = sine(440.0, 48_000.0, 10_000); + // the continuation is outside the guide: nothing to match + for c in [-5, -(w.hop() as i64), 9_999, i64::MAX, i64::MIN] { + assert_eq!(w.align(&tone, c, 3_000), 3_000); + } + // candidates outside the guide are skipped; nothing fits at all: nominal + assert_eq!(w.align(&tone, 100, i64::MAX), i64::MAX); + assert_eq!(w.align(&tone, 100, i64::MIN), i64::MIN); + let p = w.align(&tone, 100, 2); + assert!((0..=2 + w.tolerance() as i64).contains(&p), "{p}"); + // empty and tiny guides never panic + assert_eq!(w.align(&[], 0, 7), 7); + assert_eq!(w.align(&[0.5; 3], 0, 1), 1); + let mut out = vec![9.0; 4]; + w.overlap(&[], &[], &mut out); + assert_eq!(out, vec![0.0; 4]); + } + + #[test] + fn the_aligned_grain_stays_within_the_tolerance_of_its_nominal_position() { + let w = Wsola::new(44_100); + let tone = sine(97.0, 44_100.0, 44_100); + for nominal in (1_000..30_000).step_by(997) { + let p = w.align(&tone, nominal - 500, nominal); + assert!((p - nominal).abs() <= w.tolerance() as i64, "{nominal} → {p}"); + } + } +} diff --git a/crates/audio-dsp/src/sync.rs b/crates/audio-dsp/src/sync.rs new file mode 100644 index 000000000..52e6407b1 --- /dev/null +++ b/crates/audio-dsp/src/sync.rs @@ -0,0 +1,614 @@ +//! Synchronizing recordings of the same event by their audio (Synchronize, Merge Clips and +//! Create Multi-Camera Source Sequence "Audio"). +//! +//! [`find_offset`] returns the lag `L` (in samples) for which `b[n] ≈ g · a[n + L]`: when `b` +//! started recording two seconds after `a`, `L = 2 · sample_rate`. It works in two passes: +//! +//! 1. **Coarse.** Both signals are DC-removed, normalized, low-pass filtered (windowed sinc) and +//! decimated to ≤ 8 kHz (further for very long recordings, so the transform stays ≤ 4 M points). +//! The generalized cross-correlation with partial phase transform weighting (GCC-PHAT-β: +//! `R = A·B* / |A·B*|^β`) is computed with one complex FFT of both signals packed as `a + i·b`. +//! PHAT weighting whitens the spectra, so the peak is sharp and independent of the microphones' +//! gains and frequency responses; β < 1 keeps noise-only bins from dominating. +//! 2. **Refine.** Around the coarse peak, the same correlation is computed at the full sample rate +//! on the loudest common window (≤ 2.7 s at 48 kHz). Its highest peak, of either sign, gives the +//! lag and the polarity, and is refined by parabolic interpolation to a fraction of a sample. +//! +//! Two figures say how much to trust the result: `confidence`, the coarse peak's height over the +//! RMS of the correlation, and `distinct`, its height over the highest peak more than 50 ms away +//! (periodic material such as music or a steady hum can match at several lags). +//! +//! References: Knapp & Carter, "The generalized correlation method for estimation of time delay", +//! IEEE Trans. ASSP 24(4), 1976; the β-weighted PHAT variant is standard textbook practice. + +use crate::fft::Fft; + +/// Tuning of [`find_offset`]. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct SyncOptions { + /// Largest |lag| considered, in samples (None = anything with enough overlap). + pub max_lag: Option, + /// Upper bound of the coarse search's sample rate (Hz). + pub coarse_rate: u32, + /// Most samples (both signals together) the coarse transform may hold, at least 4,096; longer + /// recordings are decimated further, by at most [`MAX_DECIMATION`]. The coarse signals + /// therefore hold the larger of this and 1/4,096 of the input, and the transform is the next + /// power of two above that. + pub max_coarse_samples: usize, + /// PHAT weighting exponent (1 = full whitening, 0 = plain cross-correlation). + pub phat_beta: f32, + /// Length of the full-rate refinement window (samples). + pub refine_window: usize, +} + +impl Default for SyncOptions { + fn default() -> Self { + Self { max_lag: None, coarse_rate: 8000, max_coarse_samples: 1 << 22, phat_beta: 0.75, refine_window: 1 << 17 } + } +} + +/// The offset found between two recordings. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct SyncResult { + /// `b[n]` lines up with `a[n + lag]` (samples at the input rate). + pub lag: i64, + /// The same with sub-sample precision (parabolic interpolation of the refined peak). + pub lag_fine: f64, + /// Coarse peak height over the RMS of the correlation. + pub confidence: f32, + /// Coarse peak height over the next-highest peak more than 50 ms away. + pub distinct: f32, + /// True when the signals correlate negatively (one recording has inverted polarity). + pub inverted: bool, +} + +impl SyncResult { + /// Whether the match is clear enough to trust. + pub fn reliable(&self) -> bool { + self.confidence >= 8.0 && self.distinct >= 1.5 + } +} + +/// Average interleaved or planar channels into one mono signal. +pub fn mixdown(channels: &[&[f32]]) -> Vec { + let n = channels.iter().map(|c| c.len()).min().unwrap_or(0); + let k = channels.len().max(1) as f32; + (0..n).map(|i| channels.iter().map(|c| c[i]).sum::() / k).collect() +} + +/// Largest factor [`decimate`] uses; a larger request decimates by this factor. +pub const MAX_DECIMATION: usize = 4096; + +/// Low-pass filter (Blackman-windowed sinc, cutoff at 0.42 × the new sample rate) and keep every +/// `d`-th sample. +pub fn decimate(x: &[f32], d: usize) -> Vec { + decimate_map(x.len(), d, |i| x[i]) +} + +/// [`decimate`] of the `len` samples `sample(0) .. sample(len - 1)`, read one at a time, so a +/// transformed input needs no full-length copy. +fn decimate_map(len: usize, d: usize, sample: impl Fn(usize) -> f32) -> Vec { + if len == 0 { + return Vec::new(); + } + if d <= 1 { + return (0..len).map(sample).collect(); + } + // Factors above the input length cannot produce another output sample. Cap the useful factor + // as well as the filter width so a public caller cannot turn a tiny input into a huge plan. + let d = d.min(len).min(MAX_DECIMATION); + let half = 8 * d; + let fc = 0.42 / d as f64; // cycles per input sample + let taps: Vec = { + let n = 2 * half + 1; + let mut h: Vec = (0..n) + .map(|k| { + let t = k as f64 - half as f64; + let sinc = if t == 0.0 { 2.0 * fc } else { (2.0 * std::f64::consts::PI * fc * t).sin() / (std::f64::consts::PI * t) }; + let w = 0.42 - 0.5 * (2.0 * std::f64::consts::PI * k as f64 / (n - 1) as f64).cos() + + 0.08 * (4.0 * std::f64::consts::PI * k as f64 / (n - 1) as f64).cos(); + sinc * w + }) + .collect(); + let s: f64 = h.iter().sum(); + h.iter_mut().for_each(|v| *v /= s); + h.into_iter().map(|v| v as f32).collect() + }; + let out_len = len.div_ceil(d); + let mut out = Vec::with_capacity(out_len); + for i in 0..out_len { + let c = (i * d) as isize; + let lo = (c - half as isize).max(0) as usize; + let hi = ((c + half as isize + 1) as usize).min(len); + let k0 = (lo as isize - (c - half as isize)) as usize; + let mut acc = 0.0f32; + for (j, s) in (lo..hi).enumerate() { + acc += sample(s) * taps[k0 + j]; + } + out.push(acc); + } + out +} + +/// Remove the mean and scale to unit RMS (silence stays silence). +fn normalize(x: &mut [f32]) { + if x.is_empty() { + return; + } + // A non-finite sample counts as silence. + x.iter_mut().filter(|v| !v.is_finite()).for_each(|v| *v = 0.0); + let mean = (x.iter().map(|&v| v as f64).sum::() / x.len() as f64) as f32; + x.iter_mut().for_each(|v| *v -= mean); + let rms = (x.iter().map(|&v| (v as f64) * (v as f64)).sum::() / x.len() as f64).sqrt(); + if rms > 1e-12 { + let k = (1.0 / rms) as f32; + x.iter_mut().for_each(|v| *v *= k); + } +} + +/// [`decimate`] of `x` with its mean removed and scaled to unit RMS (silence stays silence; a +/// non-finite sample counts as silence), without a full-length copy of `x`. +fn normalized_decimate(x: &[f32], d: usize) -> Vec { + let clean = |v: f32| if v.is_finite() { v } else { 0.0 }; + let n = x.len().max(1) as f64; + let mean = (x.iter().map(|&v| clean(v) as f64).sum::() / n) as f32; + let rms = (x.iter().map(|&v| ((clean(v) - mean) as f64).powi(2)).sum::() / n).sqrt(); + let k = if rms > 1e-12 { (1.0 / rms) as f32 } else { 1.0 }; + decimate_map(x.len(), d, |i| (clean(x[i]) - mean) * k) +} + +/// GCC-PHAT-β of `a` and `b` (zero-padded to `n`, a power of two ≥ `a.len() + b.len()`): +/// `r[L mod n] = Σ a[i + L]·b[i]` with whitened spectra. Only bins whose frequency (cycles per +/// sample) lies in `band` contribute. +fn gcc(a: &[f32], b: &[f32], n: usize, beta: f32, band: (f32, f32)) -> Vec { + let fft = Fft::new(n); + let mut re = vec![0.0f32; n]; + let mut im = vec![0.0f32; n]; + re[..a.len()].copy_from_slice(a); + im[..b.len()].copy_from_slice(b); + fft.forward(&mut re, &mut im); + // X = A + iB for real a, b: A(k) = (X(k) + X*(n-k)) / 2, B(k) = (X(k) - X*(n-k)) / 2i. + let weigh = |k: usize, xr: f32, xi: f32, yr: f32, yi: f32| -> (f32, f32) { + // y = X*(n-k) given as (yr, yi) already conjugated + let (ar, ai) = (0.5 * (xr + yr), 0.5 * (xi + yi)); + let (dr, di) = (xr - yr, xi - yi); + let (br, bi) = (0.5 * di, -0.5 * dr); + // R = A·conj(B) + let rr = ar * br + ai * bi; + let ri = ai * br - ar * bi; + let f = k.min(n - k) as f32 / n as f32; + if f < band.0 || f > band.1 { + return (0.0, 0.0); + } + let mag = (rr * rr + ri * ri).sqrt(); + if mag <= 1e-30 { + return (0.0, 0.0); + } + let w = mag.powf(-beta); + (rr * w, ri * w) + }; + for k in 0..=n / 2 { + let j = (n - k) % n; + let (xkr, xki, xjr, xji) = (re[k], im[k], re[j], im[j]); + let rk = weigh(k, xkr, xki, xjr, -xji); + let rj = weigh(j, xjr, xji, xkr, -xki); + re[k] = rk.0; + im[k] = rk.1; + re[j] = rj.0; + im[j] = rj.1; + } + fft.inverse(&mut re, &mut im); + re +} + +fn corr_at(r: &[f32], lag: i64) -> f32 { + let n = r.len() as i64; + r[lag.rem_euclid(n) as usize] +} + +/// Find the lag `L` with `b[n] ≈ g·a[n + L]` (see the module docs). `None` when either signal is +/// too short or silent, or no lag leaves enough overlap. +pub fn find_offset(a: &[f32], b: &[f32], sample_rate: u32, opts: &SyncOptions) -> Option { + let sr = sample_rate.max(1) as usize; + let min_len = (sr / 10).max(64); + if a.len() < min_len || b.len() < min_len { + return None; + } + let energy = |x: &[f32]| x.iter().map(|&v| v as f64).filter(|v| v.is_finite()).map(|v| v * v).sum::(); + if energy(a) < 1e-12 || energy(b) < 1e-12 { + return None; + } + // ---- coarse + // The factor `decimate` really applies to both signals, so the coarse lag scales back exactly. + let d = (sr.div_ceil(opts.coarse_rate.max(500) as usize)) + .max((a.len() + b.len()).div_ceil(opts.max_coarse_samples.max(1 << 12))) + .min(MAX_DECIMATION) + .min(a.len().min(b.len())) + .max(1); + let (ca, cb) = (normalized_decimate(a, d), normalized_decimate(b, d)); + let (la, lb) = (ca.len() as i64, cb.len() as i64); + let n = ((la + lb) as usize).next_power_of_two(); + let rate_c = sr as f32 / d as f32; + let band = ((40.0 / rate_c).min(0.05), if d > 1 { 0.40 } else { 0.5 }); + let r = gcc(&ca, &cb, n, opts.phat_beta, band); + // valid lags: b[0..lb) against a[L..L+lb) must overlap by a minimum amount + let min_overlap = ((rate_c as i64) / 2).min(la.min(lb) / 4).max(8); + let max_lag_c = opts.max_lag.map(|m| i64::try_from(m.unsigned_abs() / d as u64).unwrap_or(i64::MAX).saturating_add(1)); + let lo = -(lb - min_overlap); + let hi = la - min_overlap; + if hi < lo { + return None; + } + let mut best = (0i64, 0.0f32); + let mut sum2 = 0.0f64; + let mut count = 0usize; + for l in lo..=hi { + if max_lag_c.is_some_and(|m| l.abs() > m) { + continue; + } + let v = corr_at(&r, l); + sum2 += (v as f64) * (v as f64); + count += 1; + if v.abs() > best.1.abs() { + best = (l, v); + } + } + if count == 0 || best.1 == 0.0 { + return None; + } + let rms = (sum2 / count as f64).sqrt().max(1e-30) as f32; + let confidence = best.1.abs() / rms; + let guard = ((rate_c * 0.05) as i64).max(2); + let mut second = 0.0f32; + for l in lo..=hi { + if (l - best.0).abs() <= guard || max_lag_c.is_some_and(|m| l.abs() > m) { + continue; + } + second = second.max(corr_at(&r, l).abs()); + } + let distinct = if second > 0.0 { best.1.abs() / second } else { f32::INFINITY }; + let inverted = best.1 < 0.0; + let coarse = best.0 * d as i64; + // ---- refine at the full rate + let margin = (2 * d + 4) as i64; + let (fa, fb) = (a.len() as i64, b.len() as i64); + let ov0 = (-coarse).max(0); + let ov1 = fb.min(fa - coarse); + if ov1 - ov0 < 16 { + return Some(SyncResult { lag: coarse, lag_fine: coarse as f64, confidence, distinct, inverted }); + } + let w = ((ov1 - ov0) as usize).min(opts.refine_window.max(256)) as i64; + // the window of b with the most energy (both sides: a lag-shifted) + let start = { + let hop = (w / 4).max(1); + // Each window's energy is summed afresh (about four reads per sample), so no array the + // length of the input is built. + let window = + |x: &[f32], at: i64| x[at as usize..(at + w) as usize].iter().map(|&v| v as f64).filter(|v| v.is_finite()).map(|v| v * v).sum::(); + let mut s = ov0; + let mut best_s = ov0; + let mut best_e = -1.0f64; + while s + w <= ov1 { + let e = window(b, s).min(window(a, s + coarse)); + if e > best_e { + best_e = e; + best_s = s; + } + s += hop; + } + best_s + }; + let bw: Vec = b[start as usize..(start + w) as usize].to_vec(); + let aw: Vec = (start + coarse - margin..start + coarse + w + margin).map(|i| if i >= 0 && i < fa { a[i as usize] } else { 0.0 }).collect(); + let mut aw = aw; + let mut bw = bw; + normalize(&mut aw); + normalize(&mut bw); + let n2 = (aw.len() + bw.len()).next_power_of_two(); + let r2 = gcc(&aw, &bw, n2, opts.phat_beta, (20.0 / sr as f32, 0.5)); + // r2[L'] = Σ aw[i + L']·bw[i]; L' = margin + δ. The highest peak of either sign sets the lag + // and the polarity: when one recording's phase is turned (a band-limited scratch track), the + // coarse peak and the opposite-signed lobe beside it can come out nearly equal. + // Only refined lags within `max_lag` are candidates. + let limit = opts.max_lag.map(|m| i64::try_from(m.unsigned_abs()).unwrap_or(i64::MAX)); + let (l_lo, l_hi) = match limit { + Some(m) => (margin.saturating_sub(m).saturating_sub(coarse).max(0), margin.saturating_add(m).saturating_sub(coarse).min(2 * margin)), + None => (0, 2 * margin), + }; + if l_lo > l_hi { + let lag = limit.map_or(coarse, |m| coarse.clamp(-m, m)); + return Some(SyncResult { lag, lag_fine: lag as f64, confidence, distinct, inverted }); + } + let mut bl = l_lo; + let mut bv = 0.0f32; + for l in l_lo..=l_hi { + let v = corr_at(&r2, l); + if v.abs() > bv.abs() { + bv = v; + bl = l; + } + } + let inverted = if bv == 0.0 { inverted } else { bv < 0.0 }; + let sign = if inverted { -1.0 } else { 1.0 }; + let (y0, y1, y2) = (corr_at(&r2, bl - 1) * sign, bv * sign, corr_at(&r2, bl + 1) * sign); + let den = y0 - 2.0 * y1 + y2; + let frac = if den.abs() > 1e-20 { (0.5 * (y0 - y2) / den).clamp(-0.5, 0.5) } else { 0.0 }; + let delta = bl - margin; + let lag = coarse + delta; + Some(SyncResult { lag, lag_fine: lag as f64 + frac as f64, confidence, distinct, inverted }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testutil::Rng; + + /// Speech-like test signal: voiced syllables (harmonics of a gliding pitch under an envelope), + /// noise bursts (consonants) and pauses. + fn speechy(sr: f64, secs: f64, seed: u64) -> Vec { + let n = (sr * secs) as usize; + let mut rng = Rng::new(seed); + let mut out = vec![0.0f32; n]; + let mut i = 0usize; + while i < n { + let len = ((0.08 + 0.25 * (rng.uniform() * 0.5 + 0.5) as f64) * sr) as usize; + let kind = rng.uniform(); + let f0 = 110.0 + 120.0 * (rng.uniform() as f64 * 0.5 + 0.5); + let glide = 1.0 + 0.3 * rng.uniform() as f64; + let amp = 0.2 + 0.3 * (rng.uniform() * 0.5 + 0.5); + for k in 0..len.min(n - i) { + let t = k as f64 / sr; + let env = (std::f64::consts::PI * k as f64 / len as f64).sin() as f32; + let v = if kind > 0.3 { + let f = f0 * (1.0 + (glide - 1.0) * k as f64 / len as f64); + (1..8).map(|h| ((2.0 * std::f64::consts::PI * f * h as f64 * t).sin() / h as f64) as f32).sum::() + } else if kind > -0.4 { + rng.uniform() + } else { + 0.0 + }; + out[i + k] = v * env * amp; + } + i += len + ((rng.uniform() * 0.5 + 0.5) * 0.15 * sr as f32) as usize; + } + out + } + + /// `x` delayed by `delay` samples (fractional: windowed-sinc interpolation), scaled by `gain`, + /// optionally colored by a zero-phase low-pass (`[k, 1-2k, k]`, so the delay stays exact), with + /// white noise `snr_db` below the signal. + fn mic(x: &[f32], delay: f64, gain: f32, lowpass: Option, snr_db: f32, len: usize, seed: u64) -> Vec { + let mut out = vec![0.0f32; len]; + let di = delay.floor() as i64; + let fr = delay - di as f64; + for (n, o) in out.iter_mut().enumerate() { + let src = n as i64 - di; + if fr == 0.0 { + if src >= 0 && (src as usize) < x.len() { + *o = x[src as usize]; + } + } else { + let mut acc = 0.0f64; + for k in -16i64..=16 { + let j = src - k; + if j < 0 || j as usize >= x.len() { + continue; + } + let t = k as f64 - fr; + let s = (std::f64::consts::PI * t).sin() / (std::f64::consts::PI * t); + let w = 0.5 + 0.5 * (std::f64::consts::PI * t / 17.0).cos(); + acc += x[j as usize] as f64 * s * w; + } + *o = acc as f32; + } + } + if let Some(k) = lowpass { + let src = out.clone(); + for i in 1..len.saturating_sub(1) { + out[i] = k * src[i - 1] + (1.0 - 2.0 * k) * src[i] + k * src[i + 1]; + } + } + let rms = crate::testutil::rms(&out) as f32; + let nrms = rms * 10f32.powf(-snr_db / 20.0) * 3f32.sqrt(); + let mut rng = Rng::new(seed); + for v in &mut out { + *v = *v * gain + rng.uniform() * nrms * gain; + } + out + } + + #[test] + fn decimate_keeps_low_frequencies_and_removes_high_ones() { + let sr = 48_000.0; + let low = crate::testutil::sine(300.0, 1.0, sr, 48_000, 0.0); + let high = crate::testutil::sine(7_000.0, 1.0, sr, 48_000, 0.0); + let dl = decimate(&low, 6); + let dh = decimate(&high, 6); + assert_eq!(dl.len(), 8000); + let rl = crate::testutil::rms(&dl[100..7900]); + let rh = crate::testutil::rms(&dh[100..7900]); + assert!((rl - std::f64::consts::FRAC_1_SQRT_2).abs() < 0.01, "{rl}"); + assert!(rh < 0.01, "{rh}"); + } + + #[test] + fn decimate_does_not_plan_a_filter_for_empty_or_extreme_requests() { + assert!(decimate(&[], usize::MAX).is_empty()); + let tiny = [1.0, -1.0]; + assert_eq!(decimate(&tiny, usize::MAX), decimate(&tiny, tiny.len())); + } + + #[test] + fn pure_delay_exact_both_signs() { + let sr = 48_000; + let s = speechy(sr as f64, 12.0, 1); + for delay in [0i64, 1, 7, 12_345, 96_001, -4_321, -50_000] { + // b = s shifted: b[n] = s[n + delay] + let b: Vec = + (0..400_000i64).map(|n| if n + delay >= 0 && ((n + delay) as usize) < s.len() { s[(n + delay) as usize] } else { 0.0 }).collect(); + let r = find_offset(&s, &b, sr, &SyncOptions::default()).unwrap(); + assert_eq!(r.lag, delay, "{r:?}"); + assert!(r.reliable(), "{r:?}"); + assert!(!r.inverted); + } + } + + /// Three microphones recording one talker: different gains (−20…+10 dB), noise (SNR 25, 10 and + /// 3 dB), one colored by a low-pass, fractional delays. Every offset within one sample. + #[test] + fn multi_mic_offsets_within_one_sample() { + let sr = 48_000u32; + let src = speechy(sr as f64, 30.0, 7); + let len = 30 * sr as usize; + // mic k records src delayed by d_k: mic_k[n] = src[n - d_k] + let cases: [(f64, f32, Option, f32); 4] = + [(0.0, 1.0, None, 40.0), (2_345.0, 0.1, None, 25.0), (-31_337.4, 3.0, Some(0.3), 10.0), (150_000.6, 0.5, None, 3.0)]; + let mics: Vec> = cases.iter().enumerate().map(|(i, c)| mic(&src, c.0, c.1, c.2, c.3, len, 100 + i as u64)).collect(); + let mut worst = 0.0f64; + let mut worst_fine = 0.0f64; + for (k, c) in cases.iter().enumerate().skip(1) { + // b = mic_k: b[n] = src[n - d_k] = a[n - d_k + d_0] → lag = d_0 - d_k + let expect = cases[0].0 - c.0; + let r = find_offset(&mics[0], &mics[k], sr, &SyncOptions::default()).unwrap(); + let err = (r.lag as f64 - expect).abs(); + let err_fine = (r.lag_fine - expect).abs(); + worst = worst.max(err); + worst_fine = worst_fine.max(err_fine); + assert!(err <= 1.0, "mic {k}: lag {} vs {expect} ({r:?})", r.lag); + assert!(err_fine < 0.75, "mic {k}: fine {} vs {expect}", r.lag_fine); + assert!(r.reliable(), "{r:?}"); + } + eprintln!("multi-mic worst error: {worst} samples (integer lag), {worst_fine:.3} samples (sub-sample estimate)"); + } + + /// A room: the far microphone hears the direct sound plus a strong reflection 23 ms later, at + /// 0 dB SNR. The direct path wins. + #[test] + fn echo_and_heavy_noise() { + let sr = 48_000u32; + let src = speechy(sr as f64, 20.0, 21); + let len = src.len(); + let near = mic(&src, 0.0, 1.0, None, 35.0, len, 1); + let direct = mic(&src, 777.0, 1.0, None, 60.0, len, 2); + let echo = mic(&src, 777.0 + 0.023 * sr as f64, 0.6, None, 60.0, len, 3); + let mut rng = Rng::new(9); + let room: Vec = direct.iter().zip(&echo).map(|(a, b)| a + b).collect(); + let nrms = crate::testutil::rms(&room) as f32 * 3f32.sqrt(); + let far: Vec = room.iter().map(|v| (v + rng.uniform() * nrms) * 0.3).collect(); + let r = find_offset(&near, &far, sr, &SyncOptions::default()).unwrap(); + assert!((r.lag + 777).abs() <= 1, "{r:?}"); + assert!(r.reliable(), "{r:?}"); + } + + /// Two 10-minute recordings (run with `--ignored --nocapture` in release for the timing). + #[test] + #[ignore] + fn long_recordings_timing() { + let sr = 48_000u32; + let src = speechy(sr as f64, 600.0, 31); + let a = mic(&src, 0.0, 1.0, None, 20.0, src.len(), 1); + let b = mic(&src, -1_234_567.0, 0.5, None, 10.0, src.len() - 2_000_000, 2); + let t = std::time::Instant::now(); + let r = find_offset(&a, &b, sr, &SyncOptions::default()).unwrap(); + eprintln!("10 min + 9.3 min at 48 kHz: {:?} in {:.2} s", r, t.elapsed().as_secs_f64()); + assert!((r.lag - 1_234_567).abs() <= 1); + } + + #[test] + fn inverted_polarity_is_found() { + let sr = 48_000; + let s = speechy(sr as f64, 8.0, 3); + let b: Vec = (0..300_000usize).map(|n| if n + 1000 < s.len() { -0.5 * s[n + 1000] } else { 0.0 }).collect(); + let r = find_offset(&s, &b, sr, &SyncOptions::default()).unwrap(); + assert_eq!(r.lag, 1000); + assert!(r.inverted); + } + + #[test] + fn unrelated_signals_are_not_reliable() { + let sr = 48_000; + let a = speechy(sr as f64, 10.0, 11); + let b = speechy(sr as f64, 10.0, 12); + let r = find_offset(&a, &b, sr, &SyncOptions::default()).unwrap(); + assert!(!r.reliable(), "{r:?}"); + assert!(find_offset(&a, &[0.0; 48_000], sr, &SyncOptions::default()).is_none()); + assert!(find_offset(&a[..100], &a, sr, &SyncOptions::default()).is_none()); + } + + #[test] + fn max_lag_limits_the_search() { + let sr = 48_000; + let s = speechy(sr as f64, 10.0, 5); + let b: Vec = s[48_000..].to_vec(); + let r = find_offset(&s, &b, sr, &SyncOptions { max_lag: Some(60_000), ..Default::default() }).unwrap(); + assert_eq!(r.lag, 48_000); + let r = find_offset(&s, &b, sr, &SyncOptions { max_lag: Some(10_000), ..Default::default() }).unwrap(); + assert!(!r.reliable() || r.lag != 48_000); + // Non-finite samples count as silence (also in the refinement's window search). + let mut t = s.clone(); + t[1_000] = f32::NAN; + t[300_000] = f32::INFINITY; + let r = find_offset(&t, &b, sr, &SyncOptions::default()).unwrap(); + assert_eq!(r.lag, 48_000); + assert!(r.confidence.is_finite() && r.lag_fine.is_finite(), "{r:?}"); + // The most negative limit is read as its magnitude, without overflow. + let r = find_offset(&s, &b, sr, &SyncOptions { max_lag: Some(i64::MIN), ..Default::default() }).unwrap(); + assert_eq!(r.lag, 48_000); + // The refined lag stays within the limit too. + for m in [0i64, 7, 47_990] { + let r = find_offset(&s, &b, sr, &SyncOptions { max_lag: Some(m), ..Default::default() }).unwrap(); + assert!(r.lag.abs() <= m && r.lag_fine.abs() <= m as f64 + 0.5, "max {m}: {r:?}"); + } + } + + /// A coarse budget that asks for more than [`MAX_DECIMATION`] still scales the coarse lag by + /// the factor applied: 2 × 9 M samples at 8 kHz with a 4,096-sample budget asks for 4,395. + #[test] + fn a_coarse_factor_above_the_cap_still_finds_the_lag() { + let sr = 8_000; + let s = speechy(sr as f64, 2_300.0, 9); + let lag = 400_000usize; + let b: Vec = s[lag..].to_vec(); + let opts = SyncOptions { max_coarse_samples: 4_096, ..Default::default() }; + let r = find_offset(&s, &b, sr, &opts).unwrap(); + assert_eq!(r.lag, lag as i64, "{r:?}"); + } + + /// A camera's scratch track: `x` through a 400 Hz high-pass and a 2.5 kHz low-pass, with + /// echoes 60 and 110 ms later, much quieter, plus noise. The filters turn the phase, so + /// next to the correlation peak with the clean recording sits a negative lobe almost as high. + fn scratch_track(x: &[f32], sr: u32, seed: u64) -> Vec { + use crate::biquad::{Biquad, Coeffs, FilterType}; + let q = std::f64::consts::FRAC_1_SQRT_2; + let mut y = x.to_vec(); + Biquad::new().process(&Coeffs::design(FilterType::HighPass, sr as f64, 400.0, q, 0.0), &mut y); + Biquad::new().process(&Coeffs::design(FilterType::LowPass, sr as f64, 2500.0, q, 0.0), &mut y); + let (d1, d2) = ((0.060 * sr as f64) as usize, (0.110 * sr as f64) as usize); + let at = |n: usize, d: usize| if n >= d { y[n - d] } else { 0.0 }; + let mut rng = Rng::new(seed); + (0..y.len()).map(|n| (0.8 * y[n] + 0.5 * at(n, d1) + 0.4 * at(n, d2)) * 0.14 + 0.01 * rng.uniform()).collect() + } + + /// At the coarse rate the scratch track's peak and the negative lobe beside it came out nearly + /// equal, and the lobe won. The refine then looked only for a negative peak: the result said + /// `inverted` and landed about 20 samples early. The full-rate peak now sets both; an inverted + /// scratch track is still found inverted. + #[test] + fn a_band_limited_scratch_track_keeps_its_polarity() { + let sr = 48_000u32; + let delay = 112_560i64; + for seed in [1, 3, 7] { + let src = speechy(sr as f64, 24.0, seed); + let scratch = scratch_track(&src, sr, 100 + seed); + for sign in [1.0f32, -1.0] { + // b[n] = scratch[n + delay] + let b: Vec = (0..16 * sr as i64).map(|n| sign * scratch.get((n + delay) as usize).copied().unwrap_or(0.0)).collect(); + let r = find_offset(&src, &b, sr, &SyncOptions::default()).unwrap(); + assert_eq!(r.inverted, sign < 0.0, "seed {seed}, sign {sign}: {r:?}"); + // the filters delay the scratch track by a few samples + assert!((r.lag - delay).abs() <= 4, "seed {seed}, sign {sign}: {r:?}"); + assert!(r.reliable(), "{r:?}"); + } + } + } +} From 0f985639e9619874296d7f1cd186fcbd0f535451 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 04:23:08 -0800 Subject: [PATCH 13/84] craft-update: the macOS partway-install test retries a busy disk-image attach an_install_that_ended_partway_does_not_block_the_next attaches its leftover image with one hdiutil call. A detach elsewhere can keep the disk-image helper busy, and the attach then fails with "Resource temporarily unavailable" (seen on the macos-latest runner). The test now tries the attach up to five times while the helper reports busy, as install_dmg retries its own attach, and skips with a message when the helper stays busy, as a_copy_on_a_read_only_image_gets_the_download_link does in self_update.rs. Other attach failures still fail the test. --- crates/update/src/install.rs | 43 ++++++++++++++++++++++++++++++------ 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/crates/update/src/install.rs b/crates/update/src/install.rs index 6cf91868a..755523928 100644 --- a/crates/update/src/install.rs +++ b/crates/update/src/install.rs @@ -4250,6 +4250,19 @@ exit 0 } } + /// Whether hdiutil's `stderr` says the disk-image helper turned the request away because it + /// was busy. + fn busy(stderr: &[u8]) -> bool { + String::from_utf8_lossy(stderr).contains("Resource temporarily unavailable") + } + + #[test] + fn hdiutil_busy_replies_are_recognized() { + assert!(busy(b"hdiutil: attach failed - Resource temporarily unavailable\n")); + assert!(!busy(b"hdiutil: attach failed - image not recognized\n")); + assert!(!busy(b"")); + } + #[cfg(target_os = "macos")] mod macos_checks { use crate::process::HelperFailure; @@ -4719,17 +4732,33 @@ exit 0 ended.wait().unwrap(); let mount = paths.cache.join(format!("mount-photocraft-{pid}-1")); std::fs::create_dir_all(&mount).unwrap(); - // One request at a time, as in `dmg`. + // One request at a time, as in `dmg`. A detach elsewhere can still keep the disk-image + // helper busy, and it turns the attach away; the attach is tried a few times, as + // `install_dmg` does. let output = { let _one_at_a_time = macos::disk_image_turn(); - std::process::Command::new("hdiutil") - .args(["attach", "-nobrowse", "-readonly", "-noautoopen", "-noverify", "-mountpoint"]) - .arg(&mount) - .arg(&image) - .output() - .unwrap() + let attach = || { + std::process::Command::new("hdiutil") + .args(["attach", "-nobrowse", "-readonly", "-noautoopen", "-noverify", "-mountpoint"]) + .arg(&mount) + .arg(&image) + .output() + .unwrap() + }; + let mut output = attach(); + for _ in 0..4 { + if output.status.success() || !busy(&output.stderr) { + break; + } + output = attach(); + } + output }; let _attached = Attached(mount.clone()); + if !output.status.success() && busy(&output.stderr) { + eprintln!("skipped: the disk-image helper stayed busy: {}", String::from_utf8_lossy(&output.stderr).trim()); + return; + } assert!(output.status.success(), "hdiutil attach failed: {}", String::from_utf8_lossy(&output.stderr).trim()); let staging = apps.join(format!(".artcraft-launcher-staging-{pid}-Ab12Cd")); bundle(&staging, "0.6.0"); From e3a4c0b2bd2f9923b1a70fc83ab3d84c833fafef Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 06:02:12 -0800 Subject: [PATCH 14/84] audio-dsp: Dynamics make-up comes before the limiter; Mastering covers every channel Dynamics applied the compressor's make-up gain together with the output gain after the limiter, so make-up raised the signal past the limiter threshold (constant 1.0 with 6 dB make-up and a -1 dB limiter came out at about +5 dBFS). Make-up now goes into the gain the limiter detects, the output gain stays after the limiter, and transfer_db reports the same order. Mastering ran the EQ on every channel but the exciter, the loudness maximizer and the output gain on the first two only. Those stages now run on every channel, with the maximizer taking its peak across all of them; reverb and the widener stay on the first two channels. --- .../audio-dsp/src/effects/behavior_tests.rs | 42 +++++++++++++++++++ crates/audio-dsp/src/effects/multiband.rs | 22 +++++++--- crates/audio-dsp/src/effects/special.rs | 34 ++++++++------- 3 files changed, 78 insertions(+), 20 deletions(-) diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index a4e574583..31c5314c9 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -245,6 +245,23 @@ fn dynamics_rack_sections() { assert!(ys.iter().all(|v| v.abs() <= db_to_gain(-6.0) + 1e-6)); } +#[test] +fn dynamics_rack_applies_makeup_before_the_limiter() { + let params = [("comp_ratio", 1.0), ("comp_makeup", 6.0), ("lim_on", 1.0), ("lim_threshold", -1.0), ("output", 0.0)]; + let mut e = fx("dynamics_rack", ¶ms); + assert!((e.transfer_db(0, 0.0).unwrap() + 1.0).abs() < 1e-4); + let n = SR as usize / 10; + let x = vec![1.0f32; n]; + let (y, _) = run(e.as_mut(), &x, &x); + assert!(y.iter().all(|v| v.abs() <= db_to_gain(-1.0) + 1e-6), "peak {}", gain_db(y.iter().fold(0.0f32, |a, v| a.max(v.abs())))); + assert!((gain_db(y[n - 1]) + 1.0).abs() < 0.01, "{}", gain_db(y[n - 1])); + // The output gain still follows the limiter. + let mut o = fx("dynamics_rack", &[("comp_ratio", 1.0), ("comp_makeup", 6.0), ("lim_on", 1.0), ("lim_threshold", -1.0), ("output", -6.0)]); + assert!((o.transfer_db(0, 0.0).unwrap() + 7.0).abs() < 1e-4); + let (yo, _) = run(o.as_mut(), &x, &x); + assert!((gain_db(yo[n - 1]) + 7.0).abs() < 0.01, "{}", gain_db(yo[n - 1])); +} + #[test] fn multiband_crossovers_sum_flat_and_bands_compress_independently() { let mut e = fx("multiband_compressor", &[("b1_ratio", 1.0), ("b2_ratio", 1.0), ("b3_ratio", 1.0), ("b4_ratio", 1.0)]); @@ -484,6 +501,31 @@ fn mastering_and_vocal_enhancer() { assert!((tone_db(music.as_mut(), 1500.0, 0.3) - music.response_db(1500.0).unwrap()).abs() < 0.1); } +#[test] +fn mastering_output_and_maximizer_reach_every_channel() { + let six = |params: &[(&str, f32)]| { + let mut e = create_effect("mastering", SR, 6).unwrap_or_else(|| panic!("no effect mastering")); + for (p, v) in params { + assert!(e.set_param(p, *v), "mastering.{p}"); + } + e.reset(); + let n = SR as usize / 10; + let mut bufs = vec![vec![0.25f32; n]; 6]; + let mut refs: Vec<&mut [f32]> = bufs.iter_mut().map(|b| b.as_mut_slice()).collect(); + e.process(&mut refs); + bufs.iter().map(|b| b[n - 1]).collect::>() + }; + let out = six(&[("output", -6.0)]); + for (ch, v) in out.iter().enumerate() { + assert!((gain_db(*v) - (gain_db(0.25) - 6.0)).abs() < 0.01, "channel {ch}: {} dB", gain_db(*v)); + } + let loud = six(&[("loudness", 100.0)]); + for (ch, v) in loud.iter().enumerate() { + assert!(v.abs() <= db_to_gain(-0.3) + 1e-6, "channel {ch}: {v}"); + assert!((v - loud[0]).abs() < 1e-6, "channel {ch}: {v}, channel 0: {}", loud[0]); + } +} + #[test] fn binaural_and_ambisonic_rendering() { let n = SR as usize; diff --git a/crates/audio-dsp/src/effects/multiband.rs b/crates/audio-dsp/src/effects/multiband.rs index a27de3c3d..7f4a207a7 100644 --- a/crates/audio-dsp/src/effects/multiband.rs +++ b/crates/audio-dsp/src/effects/multiband.rs @@ -40,7 +40,8 @@ pub fn soft_clip(x: f32, t: f32) -> f32 { // --------------------------------------------------------------------------------- dynamics /// Dynamics rack: Auto Gate, Compressor, Expander and Limiter sections in series -/// (stereo-linked peak detection), plus output gain. +/// (stereo-linked peak detection), plus output gain. The compressor's make-up gain is applied +/// before the limiter, and the output gain after it. pub struct DynamicsRack { pv: ParamValues, sr: f32, @@ -49,6 +50,8 @@ pub struct DynamicsRack { exp_env: f32, comp_env: f32, lim_env: f32, + /// Compressor make-up gain (dB). + makeup: Smoothed, out: Smoothed, /// Cached coefficients. c: [f32; 8], @@ -89,6 +92,7 @@ impl DynamicsRack { exp_env: 0.0, comp_env: 0.0, lim_env: 0.0, + makeup: Smoothed::with_ms(0.0, sample_rate, 20.0), out: Smoothed::with_ms(1.0, sample_rate, 20.0), c: [0.0; 8], hold: 0, @@ -111,8 +115,10 @@ impl DynamicsRack { coef(p.v("lim_release"), sr), ]; self.hold = (p.v("gate_hold") * 0.001 * sr) as u32; - self.out.set(db_to_gain(p.v("output") + self.makeup_db())); + self.makeup.set(self.makeup_db()); + self.out.set(db_to_gain(p.v("output"))); if snap { + self.makeup.snap(); self.out.snap(); } } @@ -131,7 +137,8 @@ impl DynamicsRack { p.v("comp_makeup") + auto } - /// Static gain (dB) of the enabled sections for a detector level, before make-up/output. + /// Static gain (dB) of the enabled sections for a detector level, including the compressor's + /// make-up gain and before the output gain. fn static_gain(&self, level: f32) -> f32 { let p = &self.pv; let mut l = level; @@ -142,7 +149,7 @@ impl DynamicsRack { l = expander_curve(l, p.v("exp_threshold"), p.v("exp_ratio"), EXP_RANGE); } if p.on("comp_on") { - l = compressor_curve(l, p.v("comp_threshold"), p.v("comp_ratio"), 0.0); + l = compressor_curve(l, p.v("comp_threshold"), p.v("comp_ratio"), 0.0) + self.makeup_db(); } if p.on("lim_on") { l = l.min(p.v("lim_threshold")); @@ -154,7 +161,7 @@ impl DynamicsRack { impl AudioEffect for DynamicsRack { param_plumbing!("dynamics_rack"); fn transfer_db(&self, band: usize, input_db: f32) -> Option { - (band == 0).then(|| input_db + self.static_gain(input_db) + self.pv.v("output") + self.makeup_db()) + (band == 0).then(|| input_db + self.static_gain(input_db) + self.pv.v("output")) } fn reset(&mut self) { self.gate_env = 0.0; @@ -162,6 +169,7 @@ impl AudioEffect for DynamicsRack { self.exp_env = 0.0; self.comp_env = 0.0; self.lim_env = 0.0; + self.makeup.snap(); self.out.snap(); } fn process(&mut self, channels: &mut [&mut [f32]]) { @@ -203,6 +211,10 @@ impl AudioEffect for DynamicsRack { g += self.comp_env; l += self.comp_env; } + // Make-up gain (0 dB with the compressor off) comes before the limiter. + let makeup = self.makeup.tick(); + g += makeup; + l += makeup; if lim_on { let target = (lt - l).min(0.0); if target < self.lim_env { diff --git a/crates/audio-dsp/src/effects/special.rs b/crates/audio-dsp/src/effects/special.rs index 5ae18c762..73676ce15 100644 --- a/crates/audio-dsp/src/effects/special.rs +++ b/crates/audio-dsp/src/effects/special.rs @@ -345,7 +345,9 @@ impl AudioEffect for GuitarSuite { pub const EXCITER_MODES: &[&str] = &["Retro", "Tape", "Tube"]; /// Mastering chain: three-band EQ → reverb → exciter → widener → loudness maximiser → output. -/// At its defaults it is transparent. +/// At its defaults it is transparent. Reverb and the widener work on the first two channels; +/// the other stages work on every channel, and the loudness maximizer takes its peak across all +/// of them. pub struct Mastering { pv: ParamValues, sr: f32, @@ -473,10 +475,10 @@ impl AudioEffect for Mastering { } for i in 0..len { let (ra, ex, w, boost, out) = (self.rev_amt.tick(), self.exc.tick(), self.width.tick(), self.boost.tick(), self.out.tick()); - let mut y = [0.0f32; 2]; - for ch in 0..nch.min(2) { - let mut v = channels[ch][start + i]; - if use_rev { + let j = start + i; + for ch in 0..nch { + let mut v = channels[ch][j]; + if use_rev && ch < 2 { v += ra * self.scratch[ch][i]; } if ex > 0.0 { @@ -488,17 +490,19 @@ impl AudioEffect for Mastering { }; v += ex * (s - h * 0.5) * 2.0; } - y[ch] = v; + channels[ch][j] = v; } if nch >= 2 { - let (m, s) = (0.5 * (y[0] + y[1]), 0.5 * (y[0] - y[1]) * w); - y = [m + s, m - s]; + let (l, r) = (channels[0][j], channels[1][j]); + let (m, s) = (0.5 * (l + r), 0.5 * (l - r) * w); + channels[0][j] = m + s; + channels[1][j] = m - s; } if loud { - for v in y.iter_mut().take(nch.min(2)) { - *v *= boost; + for c in channels[..nch].iter_mut() { + c[j] *= boost; } - let peak = y[..nch.min(2)].iter().fold(0.0f32, |a, v| a.max(v.abs())); + let peak = channels[..nch].iter().fold(0.0f32, |a, c| a.max(c[j].abs())); let target = (lin_db(ceiling) - lin_db(peak)).min(0.0); if target < self.lim_env { // An inf input sample gives -inf, which the release would never leave. @@ -507,12 +511,12 @@ impl AudioEffect for Mastering { self.lim_env = rel * self.lim_env + (1.0 - rel) * target; } let g = db_to_gain(self.lim_env); - for v in y.iter_mut().take(nch.min(2)) { - *v = soft_clip(*v * g, ceiling); + for c in channels[..nch].iter_mut() { + c[j] = soft_clip(c[j] * g, ceiling); } } - for ch in 0..nch.min(2) { - channels[ch][start + i] = y[ch] * out; + for c in channels[..nch].iter_mut() { + c[j] *= out; } } start += len; From e8b366dbf10442a74da5b98513b5d23eb8813e78 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 06:11:34 -0800 Subject: [PATCH 15/84] audio-dsp: report Mastering and flanger tails, band-limit the triangle, bound Sections - Mastering reports its reverb's tail while the reverb is on, Chorus/Flanger the echoes of its longest voice delay, and Flanger those of the longer sweep delay, so an offline render no longer cuts their tails off. - The triangle oscillator rounds its corners with PolyBLAMP: a 10 kHz triangle at 48 kHz no longer has the naive -18.7 dB alias at 18 kHz. - Sections::as_slice and magnitude_db read a count above MAX_SECTIONS as every section instead of panicking. --- crates/audio-dsp/src/design.rs | 15 ++++++- .../audio-dsp/src/effects/behavior_tests.rs | 4 ++ crates/audio-dsp/src/effects/modulation.rs | 11 +++++ crates/audio-dsp/src/effects/special.rs | 4 ++ crates/audio-dsp/src/generator.rs | 45 +++++++++++++++++-- 5 files changed, 74 insertions(+), 5 deletions(-) diff --git a/crates/audio-dsp/src/design.rs b/crates/audio-dsp/src/design.rs index afc6176a1..64b034151 100644 --- a/crates/audio-dsp/src/design.rs +++ b/crates/audio-dsp/src/design.rs @@ -159,7 +159,7 @@ pub enum Band { BandStop, } -/// A cascade of second-order sections. +/// A cascade of second-order sections: the first `n` of `c` (at most [`MAX_SECTIONS`]). #[derive(Clone, Copy, Debug)] pub struct Sections { pub c: [Coeffs; MAX_SECTIONS], @@ -167,8 +167,9 @@ pub struct Sections { } impl Sections { + /// The sections in use. A count above [`MAX_SECTIONS`] reads as all of them. pub fn as_slice(&self) -> &[Coeffs] { - &self.c[..self.n] + &self.c[..self.n.min(MAX_SECTIONS)] } /// Magnitude of the cascade in dB. pub fn magnitude_db(&self, freq: f64, sample_rate: f64) -> f64 { @@ -770,4 +771,14 @@ mod tests { } } } + + #[test] + fn an_oversized_section_count_reads_as_every_section() { + let mut s = design(&spec(Family::Butterworth, Band::LowPass, 4, 1000.0, 0.0), 48_000.0); + s.n = MAX_SECTIONS + 5; + assert_eq!(s.as_slice().len(), MAX_SECTIONS); + assert!(s.magnitude_db(100.0, 48_000.0).is_finite()); + s.n = usize::MAX; + assert_eq!(s.as_slice().len(), MAX_SECTIONS); + } } diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index 31c5314c9..28a2f193b 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -608,6 +608,10 @@ fn delays_and_reverbs_report_their_tails() { ("reverb", &[("mix", 100.0)][..]), ("convolution_reverb", &[("mix", 100.0)][..]), ("surround_reverb", &[][..]), + ("mastering", &[("reverb", 100.0)][..]), + ("chorus_flanger", &[("mode", 1.0), ("width", 100.0), ("intensity", 100.0), ("mix", 100.0)][..]), + ("chorus_flanger", &[("width", 100.0), ("intensity", 100.0), ("mix", 100.0)][..]), + ("flanger", &[("final_delay", 20.0), ("feedback", 100.0), ("mix", 100.0)][..]), ] { let mut e = fx(id, params); let tail = e.tail_samples(); diff --git a/crates/audio-dsp/src/effects/modulation.rs b/crates/audio-dsp/src/effects/modulation.rs index 57fa6f49c..9c661d65f 100644 --- a/crates/audio-dsp/src/effects/modulation.rs +++ b/crates/audio-dsp/src/effects/modulation.rs @@ -70,6 +70,12 @@ impl ChorusFlanger { impl AudioEffect for ChorusFlanger { param_plumbing!("chorus_flanger"); + /// Echoes of the longest voice delay at the current width, falling by the feedback each pass. + fn tail_samples(&self) -> usize { + let (w, inten) = (self.pv.v("width") / 100.0, self.pv.v("intensity") / 100.0); + let (delay, g) = if self.pv.idx("mode") == 1 { (0.3 + 4.7 * w, 0.95 * inten) } else { (15.0 + 20.0 * w, 0.6 * inten) }; + super::util::echo_tail(delay, g, self.sr) + } fn reset(&mut self) { self.lines.iter_mut().for_each(DelayLine::reset); self.lfo.reset(); @@ -190,6 +196,11 @@ impl Flanger { impl AudioEffect for Flanger { param_plumbing!("flanger"); + /// Echoes of the longer of the two sweep delays, falling by the feedback each pass. + fn tail_samples(&self) -> usize { + let delay = self.pv.v("initial_delay").max(self.pv.v("final_delay")); + super::util::echo_tail(delay, 0.95 * self.pv.v("feedback").abs() / 100.0, self.sr) + } fn reset(&mut self) { self.lines.iter_mut().for_each(DelayLine::reset); self.lfo.reset(); diff --git a/crates/audio-dsp/src/effects/special.rs b/crates/audio-dsp/src/effects/special.rs index 73676ce15..278c60396 100644 --- a/crates/audio-dsp/src/effects/special.rs +++ b/crates/audio-dsp/src/effects/special.rs @@ -428,6 +428,10 @@ impl Mastering { impl AudioEffect for Mastering { param_plumbing!("mastering"); + /// The reverb's tail while the reverb is on. + fn tail_samples(&self) -> usize { + if self.pv.v("reverb") > 0.0 { self.rev.tail_samples() } else { 0 } + } fn response_db(&self, freq: f64) -> Option { Some(self.eq.iter().map(|c| c.magnitude_db(freq, self.sr as f64)).sum::() + self.pv.v("output") as f64) } diff --git a/crates/audio-dsp/src/generator.rs b/crates/audio-dsp/src/generator.rs index 8003e02c5..1a60fc151 100644 --- a/crates/audio-dsp/src/generator.rs +++ b/crates/audio-dsp/src/generator.rs @@ -1,5 +1,5 @@ -//! Test signals: band-limited (PolyBLEP) sine, square, saw and triangle oscillators, and white -//! and pink noise. +//! Test signals: band-limited sine, square and saw (PolyBLEP) and triangle (PolyBLAMP) +//! oscillators, and white and pink noise. //! //! [`Oscillator`] produces one sample per call and never allocates, for real-time use (the //! `signal_generator` effect). [`signal`] renders a whole buffer offline. @@ -47,6 +47,22 @@ fn poly_blep(t: f32, dt: f32) -> f32 { } } +/// PolyBLAMP residual of a unit change of slope per sample at phase 0: `t` is the phase since the +/// corner (0..1), `dt` the phase step per sample. +#[inline] +fn poly_blamp(t: f32, dt: f32) -> f32 { + let cube = |x: f32| x * x * x / 6.0; + if dt <= 0.0 { + 0.0 + } else if t < dt { + cube(1.0 - t / dt) + } else if t > 1.0 - dt { + cube(1.0 - (1.0 - t) / dt) + } else { + 0.0 + } +} + /// Xorshift32 noise source: deterministic for a seed, and it does not allocate. #[derive(Clone, Copy, Debug)] pub(crate) struct Noise(u32); @@ -135,7 +151,10 @@ impl Oscillator { // Starts at 0 and rises, like the sine. let u = t + 0.25; let u = if u >= 1.0 { u - 1.0 } else { u }; - 1.0 - 4.0 * (u - 0.5).abs() + // The slope changes by -8·dt per sample at the peak (u = 0.5) and by +8·dt at + // the trough (u = 0); PolyBLAMP rounds both corners. + let since_peak = if u >= 0.5 { u - 0.5 } else { u + 0.5 }; + 1.0 - 4.0 * (u - 0.5).abs() + 8.0 * dt * (poly_blamp(u, dt) - poly_blamp(since_peak, dt)) } Waveform::WhiteNoise => self.noise.bipolar(), Waveform::PinkNoise => { @@ -212,6 +231,26 @@ mod tests { assert!(alias(&blep) < alias(&naive) / 4.0, "alias {} dB, naive {} dB", db(alias(&blep)), db(alias(&naive))); } + #[test] + fn the_triangle_is_band_limited() { + // A 10 kHz triangle's 3rd harmonic (30 kHz) folds to 18 kHz. PolyBLAMP keeps that alias + // well below the one a naive triangle has. + let blamp = signal(Waveform::Triangle, 10_000.0, 0.0, 48_000.0, 48_000, 1).remove(0); + let mut phase = 0.25f32; + let naive: Vec = (0..48_000) + .map(|_| { + let v = 1.0 - 4.0 * (phase - 0.5).abs(); + phase += 10_000.0 / 48_000.0; + if phase >= 1.0 { + phase -= 1.0; + } + v + }) + .collect(); + let alias = |x: &[f32]| tone_amplitude(x, 18_000.0, 48_000.0) / tone_amplitude(x, 10_000.0, 48_000.0); + assert!(alias(&blamp) < alias(&naive) / 4.0, "alias {} dB, naive {} dB", db(alias(&blamp)), db(alias(&naive))); + } + #[test] fn pink_noise_falls_3_db_per_octave() { let x = signal(Waveform::PinkNoise, 0.0, 0.0, 48_000.0, 1 << 17, 1).remove(0); From 2625ee59f85453a3971f593cb758b2c9da234cf4 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 06:22:48 -0800 Subject: [PATCH 16/84] audio-dsp: reverbs keep the side signal; fix delay tails and crossover ramps - Reverb feeds the side signal (even channels minus odd channels) into its network as well as the mid, and Surround Reverb's early reflections carry the side too. Opposite-polarity stereo input, or Surround Reverb with Center Input at 0, no longer gives a silent reverb. - Analog Delay reports the tail of its longest channel delay, which Spread lengthens by up to half. - The multiband compressor designs its crossovers once more after a ramp ends, so they reach the frequency that was set. - Mastering keeps running its reverb while the amount fades to 0 and then clears it, so turning the reverb off fades the tail and turning it back on starts from silence. --- .../audio-dsp/src/effects/behavior_tests.rs | 55 +++++++++++++++++++ crates/audio-dsp/src/effects/modulation.rs | 4 +- crates/audio-dsp/src/effects/multiband.rs | 35 +++++++++++- crates/audio-dsp/src/effects/reverbs.rs | 16 +++++- crates/audio-dsp/src/effects/special.rs | 15 ++++- crates/audio-dsp/src/effects/time.rs | 25 ++++++--- 6 files changed, 134 insertions(+), 16 deletions(-) diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index 28a2f193b..a6a2f2143 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -419,6 +419,61 @@ fn surround_reverb_tail_decays() { assert!(r.iter().all(|v| v.is_finite())); } +#[test] +fn reverbs_reverberate_the_side_signal() { + let n = SR as usize / 2; + let imp: Vec = (0..n).map(|i| if i == 0 { 1.0 } else { 0.0 }).collect(); + let neg: Vec = imp.iter().map(|v| -v).collect(); + // Opposite channels: the mid is silent, so everything heard comes from the side. + for (id, params) in [ + ("surround_reverb", &[("center_input", 0.0), ("dry", 0.0), ("wet", 100.0)][..]), + ("surround_reverb", &[("center_input", 0.0), ("early", 0.0), ("dry", 0.0), ("wet", 100.0)][..]), + ("surround_reverb", &[("dry", 0.0), ("wet", 100.0)][..]), + ("reverb", &[("mix", 100.0)][..]), + ] { + let mut e = fx(id, params); + let (l, r) = run(e.as_mut(), &imp, &neg); + let late = SR as usize / 10; + assert!(rms(&l[late..]) > 1e-4, "{id} {params:?}: left {}", rms(&l[late..])); + assert!(rms(&r[late..]) > 1e-4, "{id} {params:?}: right {}", rms(&r[late..])); + } +} + +#[test] +fn analog_delay_tail_covers_the_spread_channel() { + let mut e = fx("analog_delay", &[("delay", 100.0), ("feedback", 0.0), ("spread", 100.0), ("dry", 0.0), ("wet", 100.0)]); + let tail = e.tail_samples(); + let n = SR as usize / 2; + let mut x = vec![0.0f32; n]; + x[0] = 1.0; + let (a, b) = run(e.as_mut(), &x, &x); + let last = |s: &[f32]| s.iter().rposition(|v| v.abs() > 1e-6).unwrap_or(0); + let last = last(&a).max(last(&b)); + assert!(last > SR as usize / 10, "the second channel's echo at {last}"); + assert!(last <= e.latency() + tail, "echo at {last} after a tail of {tail}"); +} + +#[test] +fn mastering_reverb_fades_out_and_restarts_from_silence() { + let mut e = fx("mastering", &[("reverb", 100.0)]); + let n = SR as usize / 2; + let x = noise(21, n, 0.3); + run(e.as_mut(), &x, &x); + assert!(e.set_param("reverb", 0.0)); + assert!(e.tail_samples() > 0, "the fade still has a tail"); + let quiet = vec![0.0f32; SR as usize / 200]; + let (fade, _) = run(e.as_mut(), &quiet, &quiet); + assert!(fade.iter().any(|v| v.abs() > 1e-4), "the reverb stopped at once instead of fading"); + let rest = vec![0.0f32; SR as usize / 10]; + run(e.as_mut(), &rest, &rest); + run(e.as_mut(), &rest, &rest); + assert_eq!(e.tail_samples(), 0); + assert!(e.set_param("reverb", 100.0)); + let (again, _) = run(e.as_mut(), &rest, &rest); + let peak = again.iter().fold(0.0f32, |m, v| m.max(v.abs())); + assert!(peak < 1e-6, "the old reverb came back at {peak}"); +} + #[test] fn click_remover_repairs_clicks() { let n = SR as usize * 2; diff --git a/crates/audio-dsp/src/effects/modulation.rs b/crates/audio-dsp/src/effects/modulation.rs index 9c661d65f..d9bcac5db 100644 --- a/crates/audio-dsp/src/effects/modulation.rs +++ b/crates/audio-dsp/src/effects/modulation.rs @@ -419,8 +419,10 @@ impl AnalogDelay { impl AudioEffect for AnalogDelay { param_plumbing!("analog_delay"); + /// Echoes of the longest channel delay: Spread lengthens the second channel's by up to half. fn tail_samples(&self) -> usize { - super::util::echo_tail(self.pv.v("delay"), self.pv.v("feedback") / 100.0, self.sr) + let delay = self.pv.v("delay") * (1.0 + 0.25 * self.pv.v("spread") / 100.0); + super::util::echo_tail(delay, self.pv.v("feedback") / 100.0, self.sr) } fn reset(&mut self) { self.lines.iter_mut().for_each(DelayLine::reset); diff --git a/crates/audio-dsp/src/effects/multiband.rs b/crates/audio-dsp/src/effects/multiband.rs index 7f4a207a7..bd49da09e 100644 --- a/crates/audio-dsp/src/effects/multiband.rs +++ b/crates/audio-dsp/src/effects/multiband.rs @@ -343,6 +343,8 @@ pub struct MultibandCompressor { rel: [f32; MB_BANDS], lim_rel: f32, counter: u32, + /// The crossovers were last designed during a ramp, so the end of the ramp needs a design. + xo_pending: bool, } const Q_BW: f64 = std::f64::consts::FRAC_1_SQRT_2; @@ -367,6 +369,7 @@ impl MultibandCompressor { rel: [0.0; MB_BANDS], lim_rel: 0.0, counter: 0, + xo_pending: false, }; s.apply_params(true); s @@ -408,6 +411,7 @@ impl MultibandCompressor { self.band_gain.iter_mut().for_each(Smoothed::snap); self.out.snap(); self.update_xo(); + self.xo_pending = false; } } @@ -453,6 +457,7 @@ impl AudioEffect for MultibandCompressor { self.band_gain.iter_mut().for_each(Smoothed::snap); self.out.snap(); self.update_xo(); + self.xo_pending = false; self.state.iter_mut().for_each(|s| *s = XoState::default()); self.env.iter_mut().for_each(|e| *e = [0.0; MB_BANDS]); self.lim_env = 0.0; @@ -475,8 +480,12 @@ impl AudioEffect for MultibandCompressor { } let mut bands = [[0.0f64; MB_BANDS]; MB_MAX_CH]; for i in 0..n { - if self.counter == 0 && self.xo.iter().any(Smoothed::is_smoothing) { - self.update_xo(); + if self.counter == 0 { + let smoothing = self.xo.iter().any(Smoothed::is_smoothing); + if smoothing || self.xo_pending { + self.update_xo(); + } + self.xo_pending = smoothing; } self.counter = (self.counter + 1) % 16; for x in &mut self.xo { @@ -636,3 +645,25 @@ impl AudioEffect for TubeCompressor { } } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn crossovers_reach_their_target_after_a_ramp() { + let sr = 48_000.0; + let mut e = MultibandCompressor::new(sr, 2); + assert!(e.set_param("xo1", 20.0)); + e.reset(); + assert!(e.set_param("xo1", 1000.0)); + let mut l = vec![0.0f32; 4096]; + let mut r = vec![0.0f32; 4096]; + for _ in 0..4 { + e.process(&mut [&mut l, &mut r]); + } + let f = 2f64.powf(e.crossovers()[0].log2() as f64); + assert_eq!(e.xc.lp[0], Coeffs::design(FilterType::LowPass, sr as f64, f, Q_BW, 0.0)); + assert_eq!(e.xc.hp[0], Coeffs::design(FilterType::HighPass, sr as f64, f, Q_BW, 0.0)); + } +} diff --git a/crates/audio-dsp/src/effects/reverbs.rs b/crates/audio-dsp/src/effects/reverbs.rs index c4e805c89..91d97d8b2 100644 --- a/crates/audio-dsp/src/effects/reverbs.rs +++ b/crates/audio-dsp/src/effects/reverbs.rs @@ -413,12 +413,15 @@ const CHUNK: usize = 256; /// Early reflections (8 taps, alternating sides) plus the 8-line FDN late field, with /// low/high cut on the wet signal, wet width, and separate dry/wet levels. The center input -/// level controls how much of the mid (L+R) signal feeds the reverb. +/// level controls how much of the mid (L+R) signal feeds the late reverb; the side (L−R) +/// signal always feeds both the early reflections and the late reverb. pub struct SurroundReverb { pv: ParamValues, sr: f32, late: Reverb, er: DelayLine, + /// Early-reflection line for the side (L−R) signal. + er_side: DelayLine, lc: [OnePole; 2], hc: [OnePole; 2], scratch: [[f32; CHUNK]; 2], @@ -455,6 +458,7 @@ impl SurroundReverb { sr: sample_rate, late, er: DelayLine::new((0.1 * sample_rate) as usize), + er_side: DelayLine::new((0.1 * sample_rate) as usize), lc: [OnePole::default(); 2], hc: [OnePole::default(); 2], scratch: [[0.0; CHUNK]; 2], @@ -498,6 +502,7 @@ impl AudioEffect for SurroundReverb { fn reset(&mut self) { self.late.reset(); self.er.reset(); + self.er_side.reset(); self.lc = [OnePole::default(); 2]; self.hc = [OnePole::default(); 2]; for s in [&mut self.dry, &mut self.wet, &mut self.early, &mut self.width, &mut self.center, &mut self.size] { @@ -530,12 +535,17 @@ impl AudioEffect for SurroundReverb { } for i in 0..len { let x = if nch == 2 { 0.5 * (channels[0][start + i] + channels[1][start + i]) } else { channels[0][start + i] }; + let xs = if nch == 2 { 0.5 * (channels[0][start + i] - channels[1][start + i]) } else { 0.0 }; let size = self.size.tick(); self.er.push(x); + self.er_side.push(xs); let (mut el, mut er) = (0.0, 0.0); for k in 0..ER_TAPS { - let v = ER_GAIN[k] * self.er.read(ER_MS[k] * size * ms); - if k % 2 == 0 { el += v } else { er += v } + let d = ER_MS[k] * size * ms; + let v = ER_GAIN[k] * self.er.read(d); + // The side reflects with opposite signs on the two sides. + let vs = ER_GAIN[k] * self.er_side.read(d); + if k % 2 == 0 { el += v + vs } else { er += v - vs } } let early = self.early.tick(); let (dry, wet, width) = (self.dry.tick(), self.wet.tick(), self.width.tick()); diff --git a/crates/audio-dsp/src/effects/special.rs b/crates/audio-dsp/src/effects/special.rs index 278c60396..d84d91a7f 100644 --- a/crates/audio-dsp/src/effects/special.rs +++ b/crates/audio-dsp/src/effects/special.rs @@ -357,6 +357,8 @@ pub struct Mastering { scratch: [[f32; CHUNK]; 2], hp: Vec, lim_env: f32, + /// The reverb ran in the last block. + rev_on: bool, rev_amt: Smoothed, exc: Smoothed, width: Smoothed, @@ -395,6 +397,7 @@ impl Mastering { scratch: [[0.0; CHUNK]; 2], hp: vec![OnePole::default(); ch], lim_env: 0.0, + rev_on: false, rev_amt: sm(0.0, sample_rate), exc: sm(0.0, sample_rate), width: sm(1.0, sample_rate), @@ -428,9 +431,9 @@ impl Mastering { impl AudioEffect for Mastering { param_plumbing!("mastering"); - /// The reverb's tail while the reverb is on. + /// The reverb's tail while the reverb is on or fading out. fn tail_samples(&self) -> usize { - if self.pv.v("reverb") > 0.0 { self.rev.tail_samples() } else { 0 } + if self.pv.v("reverb") > 0.0 || self.rev_amt.is_smoothing() { self.rev.tail_samples() } else { 0 } } fn response_db(&self, freq: f64) -> Option { Some(self.eq.iter().map(|c| c.magnitude_db(freq, self.sr as f64)).sum::() + self.pv.v("output") as f64) @@ -440,6 +443,7 @@ impl AudioEffect for Mastering { self.rev.reset(); self.hp.iter_mut().for_each(OnePole::reset); self.lim_env = 0.0; + self.rev_on = false; for s in [&mut self.rev_amt, &mut self.exc, &mut self.width, &mut self.boost, &mut self.out] { s.snap(); } @@ -451,7 +455,12 @@ impl AudioEffect for Mastering { return; } let loud = self.pv.v("loudness") > 0.0; - let use_rev = self.pv.v("reverb") > 0.0; + // The reverb runs until its amount has faded to 0, then starts from silence next time. + let use_rev = self.pv.v("reverb") > 0.0 || self.rev_amt.is_smoothing(); + if self.rev_on && !use_rev { + self.rev.reset(); + } + self.rev_on = use_rev; let mode = self.pv.idx("exciter_mode"); let ahp = OnePole::alpha(3000.0, self.sr); let ceiling = db_to_gain(-0.3); diff --git a/crates/audio-dsp/src/effects/time.rs b/crates/audio-dsp/src/effects/time.rs index 7710d0188..e2dd61c3e 100644 --- a/crates/audio-dsp/src/effects/time.rs +++ b/crates/audio-dsp/src/effects/time.rs @@ -137,13 +137,16 @@ const MAX_SIZE_SCALE: f32 = 2.0; /// Output tap signs (left, right) for decorrelated stereo. const SIGN_L: [f32; FDN] = [1.0, -1.0, 1.0, -1.0, 1.0, 1.0, -1.0, -1.0]; const SIGN_R: [f32; FDN] = [1.0, 1.0, -1.0, -1.0, 1.0, -1.0, 1.0, -1.0]; +/// Input signs for the side signal, (SIGN_L − SIGN_R) / 2. +const SIGN_SIDE: [f32; FDN] = [0.0, -1.0, 1.0, 0.0, 0.0, 1.0, -1.0, 0.0]; fn size_scale(size_pct: f32) -> f32 { 0.35 + (MAX_SIZE_SCALE - 0.35) * size_pct / 100.0 } /// 8×8 feedback-delay-network reverb with a Householder feedback matrix, per-line RT60 gains, -/// one-pole HF damping in each loop, pre-delay, size and dry/wet mix. +/// one-pole HF damping in each loop, pre-delay, size and dry/wet mix. With two or more channels +/// the side signal (even channels minus odd channels) feeds the network as well as the mid. pub struct Reverb { pv: ParamValues, sr: f32, @@ -157,6 +160,8 @@ pub struct Reverb { rt60: Smoothed, mix: Smoothed, pre: Vec, + /// Pre-delay of the side signal, written at `pre_w` with `pre`. + pre_side: Vec, pre_w: usize, pre_len: Smoothed, counter: u32, @@ -189,6 +194,7 @@ impl Reverb { rt60: sm(1.0), mix: sm(0.0), pre: vec![0.0; pre_len], + pre_side: vec![0.0; pre_len], pre_w: 0, pre_len: Smoothed::with_ms(1.0, sample_rate, 100.0), counter: 0, @@ -239,6 +245,7 @@ impl AudioEffect for Reverb { fn reset(&mut self) { self.lines.iter_mut().for_each(|l| l.iter_mut().for_each(|v| *v = 0.0)); self.pre.iter_mut().for_each(|v| *v = 0.0); + self.pre_side.iter_mut().for_each(|v| *v = 0.0); self.lp = [0.0; FDN]; self.w = 0; self.pre_w = 0; @@ -274,16 +281,20 @@ impl AudioEffect for Reverb { let mix = self.mix.tick(); let pd = self.pre_len.tick(); - let mut mono = 0.0; - for ch in channels.iter() { + let (mut mono, mut side) = (0.0, 0.0); + for (c, ch) in channels.iter().enumerate() { mono += ch[i]; + side += if c % 2 == 0 { ch[i] } else { -ch[i] }; } mono /= nch as f32; + side = if nch >= 2 { side / nch as f32 } else { 0.0 }; self.pre[self.pre_w] = mono; - let input = match predelay { - Some(delay) => read_prepared(&self.pre, self.pre_w, delay), - None => read_frac(&self.pre, self.pre_w, pd), + self.pre_side[self.pre_w] = side; + let (input, side_in) = match predelay { + Some(delay) => (read_prepared(&self.pre, self.pre_w, delay), read_prepared(&self.pre_side, self.pre_w, delay)), + None => (read_frac(&self.pre, self.pre_w, pd), read_frac(&self.pre_side, self.pre_w, pd)), }; + let side_in = side_in * std::f32::consts::SQRT_2; self.pre_w = if self.pre_w + 1 == pre_len { 0 } else { self.pre_w + 1 }; let mut v = [0.0f32; FDN]; @@ -297,7 +308,7 @@ impl AudioEffect for Reverb { let (mut wl, mut wr) = (0.0, 0.0); for k in 0..FDN { let fbk = v[k] - hh * sum; - self.lines[k][self.w] = flush32(fbk + input * 0.5); + self.lines[k][self.w] = flush32(fbk + (input + SIGN_SIDE[k] * side_in) * 0.5); wl += SIGN_L[k] * v[k]; wr += SIGN_R[k] * v[k]; } From 267a66cfd54c57caf245eb50389202c2e43242cc Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 06:34:35 -0800 Subject: [PATCH 17/84] audio-dsp: meter Dynamics, multiband and tube compressor gain reduction; smooth Mastering bypasses - Dynamics, the multiband compressor and the tube-modeled compressor report their deepest gain reduction in the last block through gain_reduction_db, and clear it on reset. Dynamics leaves out the compressor's make-up gain; the multiband compressor adds the limiter to the most reduced band. - Mastering keeps the loudness maximizer in while its boost ramps back to 0 dB, and clears the limiter once it is out. - Mastering clears its reverb at the end of the chunk in which the fade ends, so the result does not depend on the block size. --- .../audio-dsp/src/effects/behavior_tests.rs | 33 +++++++++++++- crates/audio-dsp/src/effects/multiband.rs | 45 +++++++++++++++++++ crates/audio-dsp/src/effects/special.rs | 23 ++++++---- 3 files changed, 92 insertions(+), 9 deletions(-) diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index a6a2f2143..d5ae9b8d5 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -464,9 +464,9 @@ fn mastering_reverb_fades_out_and_restarts_from_silence() { let quiet = vec![0.0f32; SR as usize / 200]; let (fade, _) = run(e.as_mut(), &quiet, &quiet); assert!(fade.iter().any(|v| v.abs() > 1e-4), "the reverb stopped at once instead of fading"); + // One call that runs past the end of the fade clears the reverb. let rest = vec![0.0f32; SR as usize / 10]; run(e.as_mut(), &rest, &rest); - run(e.as_mut(), &rest, &rest); assert_eq!(e.tail_samples(), 0); assert!(e.set_param("reverb", 100.0)); let (again, _) = run(e.as_mut(), &rest, &rest); @@ -474,6 +474,37 @@ fn mastering_reverb_fades_out_and_restarts_from_silence() { assert!(peak < 1e-6, "the old reverb came back at {peak}"); } +#[test] +fn mastering_maximizer_ramps_out() { + let mut e = fx("mastering", &[("loudness", 100.0)]); + let x = vec![0.01f32; SR as usize / 10]; + let (y, _) = run(e.as_mut(), &x, &x); + assert!((y[y.len() - 1] - 0.04).abs() < 1e-3, "{}", y[y.len() - 1]); + assert!(e.set_param("loudness", 0.0)); + let (z, _) = run(e.as_mut(), &x, &x); + assert!(z[0] > 0.035, "the boost dropped at once: {}", z[0]); + assert!((z[z.len() - 1] - 0.01).abs() < 1e-4, "{}", z[z.len() - 1]); +} + +#[test] +fn dynamics_effects_report_gain_reduction() { + let n = SR as usize / 2; + let x = sine(1000.0, 0.5, SR as f64, n, 0.0); + for (id, params) in + [("dynamics_rack", &[("comp_threshold", -20.0), ("comp_ratio", 4.0)][..]), ("multiband_compressor", &[][..]), ("tube_compressor", &[][..])] + { + let mut e = fx(id, params); + run(e.as_mut(), &x, &x); + assert!(e.gain_reduction_db() > 3.0, "{id}: {}", e.gain_reduction_db()); + e.reset(); + assert_eq!(e.gain_reduction_db(), 0.0, "{id}"); + } + // Make-up gain is not reduction. + let mut m = fx("dynamics_rack", &[("comp_ratio", 1.0), ("comp_makeup", 6.0)]); + run(m.as_mut(), &x, &x); + assert_eq!(m.gain_reduction_db(), 0.0); +} + #[test] fn click_remover_repairs_clicks() { let n = SR as usize * 2; diff --git a/crates/audio-dsp/src/effects/multiband.rs b/crates/audio-dsp/src/effects/multiband.rs index bd49da09e..32d2f9f34 100644 --- a/crates/audio-dsp/src/effects/multiband.rs +++ b/crates/audio-dsp/src/effects/multiband.rs @@ -56,6 +56,8 @@ pub struct DynamicsRack { /// Cached coefficients. c: [f32; 8], hold: u32, + /// Deepest gain reduction of the sections in the last block (dB, ≥ 0). + gr_meter: f32, } impl DynamicsRack { @@ -96,6 +98,7 @@ impl DynamicsRack { out: Smoothed::with_ms(1.0, sample_rate, 20.0), c: [0.0; 8], hold: 0, + gr_meter: 0.0, }; s.apply_params(true); s @@ -171,9 +174,16 @@ impl AudioEffect for DynamicsRack { self.lim_env = 0.0; self.makeup.snap(); self.out.snap(); + self.gr_meter = 0.0; + } + /// The deepest gain reduction of the gate, expander, compressor and limiter together during + /// the last block, in dB (≥ 0), without the make-up gain. + fn gain_reduction_db(&self) -> f32 { + self.gr_meter } fn process(&mut self, channels: &mut [&mut [f32]]) { let n = block_len(channels); + let mut deepest = 0.0f32; let p = &self.pv; let (gate_on, gt) = (p.on("gate_on"), p.v("gate_threshold")); let (exp_on, et, er) = (p.on("exp_on"), p.v("exp_threshold"), p.v("exp_ratio")); @@ -224,6 +234,7 @@ impl AudioEffect for DynamicsRack { } g += self.lim_env; } + deepest = deepest.min(g - makeup); let gain = db_to_gain(g); let o = self.out.tick(); for ch in channels.iter_mut() { @@ -234,6 +245,9 @@ impl AudioEffect for DynamicsRack { ch[i] = y * o; } } + if n > 0 { + self.gr_meter = -deepest; + } } } @@ -345,6 +359,8 @@ pub struct MultibandCompressor { counter: u32, /// The crossovers were last designed during a ramp, so the end of the ramp needs a design. xo_pending: bool, + /// Deepest gain reduction of a band plus the limiter in the last block (dB, ≥ 0). + gr_meter: f32, } const Q_BW: f64 = std::f64::consts::FRAC_1_SQRT_2; @@ -370,6 +386,7 @@ impl MultibandCompressor { lim_rel: 0.0, counter: 0, xo_pending: false, + gr_meter: 0.0, }; s.apply_params(true); s @@ -462,10 +479,17 @@ impl AudioEffect for MultibandCompressor { self.env.iter_mut().for_each(|e| *e = [0.0; MB_BANDS]); self.lim_env = 0.0; self.counter = 0; + self.gr_meter = 0.0; + } + /// The deepest gain reduction of the most reduced band plus the limiter during the last + /// block, in dB (≥ 0). + fn gain_reduction_db(&self) -> f32 { + self.gr_meter } fn process(&mut self, channels: &mut [&mut [f32]]) { let n = block_len(channels); let nch = channels.len().min(self.state.len()); + let mut deepest = 0.0f32; let link = self.pv.on("link"); let lim_on = self.pv.on("lim_on"); let lt = self.pv.v("lim_threshold"); @@ -501,6 +525,7 @@ impl AudioEffect for MultibandCompressor { } // Detection (per band; linked = loudest channel drives all). let mut gains = [[1.0f32; MB_BANDS]; MB_MAX_CH]; + let mut band_red = 0.0f32; for b in 0..MB_BANDS { if byp[b] { continue; @@ -510,6 +535,7 @@ impl AudioEffect for MultibandCompressor { let l = lin_db(peak); let target = compressor_curve(l, thr[b], ratio[b], 0.0) - l; smooth(&mut self.env[0][b], target, self.att[b], self.rel[b]); + band_red = band_red.min(self.env[0][b]); let g = db_to_gain(self.env[0][b]); for gc in gains.iter_mut().take(nch.min(MB_MAX_CH)) { gc[b] = g; @@ -519,6 +545,7 @@ impl AudioEffect for MultibandCompressor { let l = lin_db(bands[ch][b].abs() as f32); let target = compressor_curve(l, thr[b], ratio[b], 0.0) - l; smooth(&mut self.env[ch][b], target, self.att[b], self.rel[b]); + band_red = band_red.min(self.env[ch][b]); gains[ch][b] = db_to_gain(self.env[ch][b]); } } @@ -543,11 +570,16 @@ impl AudioEffect for MultibandCompressor { for y in ys.iter_mut().take(nch.min(MB_MAX_CH)) { *y = (*y * g).clamp(-ceiling, ceiling); } + band_red += self.lim_env; } + deepest = deepest.min(band_red); for ch in 0..nch.min(MB_MAX_CH) { channels[ch][i] = ys[ch]; } } + if n > 0 { + self.gr_meter = -deepest; + } } } @@ -565,6 +597,8 @@ pub struct TubeCompressor { rel: f32, rms_c: f32, out: Smoothed, + /// Deepest gain reduction in the last block (dB, ≥ 0). + gr_meter: f32, } const TUBE_K: f32 = 0.5; @@ -591,6 +625,7 @@ impl TubeCompressor { rel: 0.0, rms_c: coef(5.0, sample_rate), out: Smoothed::with_ms(1.0, sample_rate, 20.0), + gr_meter: 0.0, }; s.apply_params(true); s @@ -616,9 +651,15 @@ impl AudioEffect for TubeCompressor { self.env = 0.0; self.slow = 0.0; self.out.snap(); + self.gr_meter = 0.0; + } + /// The deepest gain reduction during the last block, in dB (≥ 0). + fn gain_reduction_db(&self) -> f32 { + self.gr_meter } fn process(&mut self, channels: &mut [&mut [f32]]) { let n = block_len(channels); + let mut deepest = 0.0f32; let (t, r) = (self.pv.v("threshold"), self.pv.v("ratio")); let slow_c = coef(1500.0, self.sr); for i in 0..n { @@ -636,6 +677,7 @@ impl AudioEffect for TubeCompressor { } let rel = self.rel + (self.slow / -20.0).clamp(0.0, 1.0) * (1.0 - self.rel) * 0.5; smooth(&mut self.env, target, self.att, rel.min(0.999_999)); + deepest = deepest.min(self.env); let g = db_to_gain(self.env); let o = self.out.tick(); for buf in channels.iter_mut() { @@ -643,6 +685,9 @@ impl AudioEffect for TubeCompressor { buf[i] = (TUBE_K * y).tanh() / TUBE_K * o; } } + if n > 0 { + self.gr_meter = -deepest; + } } } diff --git a/crates/audio-dsp/src/effects/special.rs b/crates/audio-dsp/src/effects/special.rs index d84d91a7f..67c3b8458 100644 --- a/crates/audio-dsp/src/effects/special.rs +++ b/crates/audio-dsp/src/effects/special.rs @@ -357,7 +357,7 @@ pub struct Mastering { scratch: [[f32; CHUNK]; 2], hp: Vec, lim_env: f32, - /// The reverb ran in the last block. + /// The reverb has run since it was last cleared. rev_on: bool, rev_amt: Smoothed, exc: Smoothed, @@ -454,13 +454,8 @@ impl AudioEffect for Mastering { if nch == 0 { return; } - let loud = self.pv.v("loudness") > 0.0; - // The reverb runs until its amount has faded to 0, then starts from silence next time. - let use_rev = self.pv.v("reverb") > 0.0 || self.rev_amt.is_smoothing(); - if self.rev_on && !use_rev { - self.rev.reset(); - } - self.rev_on = use_rev; + let loud_on = self.pv.v("loudness") > 0.0; + let rev_param = self.pv.v("reverb") > 0.0; let mode = self.pv.idx("exciter_mode"); let ahp = OnePole::alpha(3000.0, self.sr); let ceiling = db_to_gain(-0.3); @@ -468,6 +463,9 @@ impl AudioEffect for Mastering { let mut start = 0; while start < n { let len = (n - start).min(CHUNK); + // The reverb runs until its amount has faded to 0. + let use_rev = rev_param || self.rev_amt.is_smoothing(); + self.rev_on = use_rev; // EQ in place. for ch in 0..nch { for v in channels[ch][start..start + len].iter_mut() { @@ -487,6 +485,8 @@ impl AudioEffect for Mastering { self.rev.process(&mut [&mut a[..len], &mut b[..len]]); } for i in 0..len { + // The maximizer stays in while its boost ramps back to 0 dB. + let loud = loud_on || self.boost.is_smoothing(); let (ra, ex, w, boost, out) = (self.rev_amt.tick(), self.exc.tick(), self.width.tick(), self.boost.tick(), self.out.tick()); let j = start + i; for ch in 0..nch { @@ -527,11 +527,18 @@ impl AudioEffect for Mastering { for c in channels[..nch].iter_mut() { c[j] = soft_clip(c[j] * g, ceiling); } + } else { + self.lim_env = 0.0; } for c in channels[..nch].iter_mut() { c[j] *= out; } } + // Once the fade has ended, the next use of the reverb starts from silence. + if self.rev_on && !rev_param && !self.rev_amt.is_smoothing() { + self.rev.reset(); + self.rev_on = false; + } start += len; } } From 07370abc7ec8b7f5d91eb0c220387b9b70666c8f Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 07:06:41 -0800 Subject: [PATCH 18/84] audio-dsp: Analog Delay tail covers its ramps; Mastering maximizer crossfades - Analog Delay's tail counts the delay, spread and feedback at the larger of their current and target values, so a shortened delay still reports the echoes left in the line while the delay ramps down. - The Mastering loudness maximizer crossfades in and out over the 20 ms smoothing ramp instead of switching its soft clip on or off at once. During the fade the output stays within the -0.3 dB ceiling. --- .../audio-dsp/src/effects/behavior_tests.rs | 50 +++++++++++++++++++ crates/audio-dsp/src/effects/modulation.rs | 8 ++- crates/audio-dsp/src/effects/special.rs | 25 ++++++---- 3 files changed, 70 insertions(+), 13 deletions(-) diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index d5ae9b8d5..af6b240a2 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -453,6 +453,56 @@ fn analog_delay_tail_covers_the_spread_channel() { assert!(last <= e.latency() + tail, "echo at {last} after a tail of {tail}"); } +#[test] +fn analog_delay_tail_covers_a_shortening_ramp() { + let mut e = fx("analog_delay", &[("delay", 500.0), ("feedback", 0.0), ("dry", 0.0), ("wet", 100.0)]); + let x = noise(31, SR as usize / 10, 0.5); + run(e.as_mut(), &x, &x); + // The delay ramps down from 500 ms while the noise is still in the line. + assert!(e.set_param("delay", 5.0)); + let tail = e.tail_samples(); + let silence = vec![0.0f32; SR as usize]; + let (a, b) = run(e.as_mut(), &silence, &silence); + let last = |s: &[f32]| s.iter().rposition(|v| v.abs() > 1e-6).unwrap_or(0); + let last = last(&a).max(last(&b)); + assert!(last > SR as usize / 100, "the ramped echo at {last}"); + assert!(last <= e.latency() + tail, "echo at {last} after a tail of {tail}"); +} + +#[test] +fn mastering_maximizer_switches_without_a_step() { + let mut e = fx("mastering", &[]); + let x = vec![0.9f32; SR as usize / 10]; + let (y, _) = run(e.as_mut(), &x, &x); + let mut prev = y[y.len() - 1]; + let mut steps = |z: &[f32]| { + let mut worst = 0.0f32; + for &v in z { + worst = worst.max((v - prev).abs()); + prev = v; + } + worst + }; + assert!(e.set_param("loudness", 1.0)); + let (on, _) = run(e.as_mut(), &x, &x); + let on_step = steps(&on); + assert!(on_step < 0.005, "switching on stepped by {on_step}"); + assert!(e.set_param("loudness", 0.0)); + let (off, _) = run(e.as_mut(), &x, &x); + let off_step = steps(&off); + assert!(off_step < 0.005, "switching off stepped by {off_step}"); + assert!((off[off.len() - 1] - y[y.len() - 1]).abs() < 1e-6, "{} {}", off[off.len() - 1], y[y.len() - 1]); + // Input above the ceiling is held to it from the first sample of the fade. + let mut e = fx("mastering", &[]); + let x = vec![1.0f32; SR as usize / 10]; + run(e.as_mut(), &x, &x); + assert!(e.set_param("loudness", 1.0)); + let (on, _) = run(e.as_mut(), &x, &x); + let ceiling = crate::db_to_gain(-0.3); + let peak = on.iter().fold(0.0f32, |a, v| a.max(v.abs())); + assert!(peak <= ceiling + 1e-6, "{peak} over the ceiling {ceiling}"); +} + #[test] fn mastering_reverb_fades_out_and_restarts_from_silence() { let mut e = fx("mastering", &[("reverb", 100.0)]); diff --git a/crates/audio-dsp/src/effects/modulation.rs b/crates/audio-dsp/src/effects/modulation.rs index d9bcac5db..b7b93e9c9 100644 --- a/crates/audio-dsp/src/effects/modulation.rs +++ b/crates/audio-dsp/src/effects/modulation.rs @@ -420,9 +420,13 @@ impl AnalogDelay { impl AudioEffect for AnalogDelay { param_plumbing!("analog_delay"); /// Echoes of the longest channel delay: Spread lengthens the second channel's by up to half. + /// While a ramp runs, each of delay, spread and feedback counts at the larger of its current + /// and target values. fn tail_samples(&self) -> usize { - let delay = self.pv.v("delay") * (1.0 + 0.25 * self.pv.v("spread") / 100.0); - super::util::echo_tail(delay, self.pv.v("feedback") / 100.0, self.sr) + let delay_ms = self.time.value().max(self.time.target()) * 1000.0 / self.sr; + let spread = self.spread.value().max(self.spread.target()); + let feedback = self.fb.value().max(self.fb.target()); + super::util::echo_tail(delay_ms * (1.0 + 0.25 * spread), feedback, self.sr) } fn reset(&mut self) { self.lines.iter_mut().for_each(DelayLine::reset); diff --git a/crates/audio-dsp/src/effects/special.rs b/crates/audio-dsp/src/effects/special.rs index 67c3b8458..2e3bb3813 100644 --- a/crates/audio-dsp/src/effects/special.rs +++ b/crates/audio-dsp/src/effects/special.rs @@ -363,6 +363,8 @@ pub struct Mastering { exc: Smoothed, width: Smoothed, boost: Smoothed, + /// Crossfade from the bypassed signal (0) to the maximized one (1). + loud_mix: Smoothed, out: Smoothed, } @@ -402,6 +404,7 @@ impl Mastering { exc: sm(0.0, sample_rate), width: sm(1.0, sample_rate), boost: sm(1.0, sample_rate), + loud_mix: sm(0.0, sample_rate), out: sm(1.0, sample_rate), }; s.apply_params(true); @@ -420,9 +423,10 @@ impl Mastering { self.exc.set(0.6 * self.pv.v("exciter") / 100.0); self.width.set(self.pv.v("widener") / 100.0); self.boost.set(db_to_gain(12.0 * self.pv.v("loudness") / 100.0)); + self.loud_mix.set(if self.pv.v("loudness") > 0.0 { 1.0 } else { 0.0 }); self.out.set(db_to_gain(self.pv.v("output"))); if snap { - for s in [&mut self.rev_amt, &mut self.exc, &mut self.width, &mut self.boost, &mut self.out] { + for s in [&mut self.rev_amt, &mut self.exc, &mut self.width, &mut self.boost, &mut self.loud_mix, &mut self.out] { s.snap(); } } @@ -444,7 +448,7 @@ impl AudioEffect for Mastering { self.hp.iter_mut().for_each(OnePole::reset); self.lim_env = 0.0; self.rev_on = false; - for s in [&mut self.rev_amt, &mut self.exc, &mut self.width, &mut self.boost, &mut self.out] { + for s in [&mut self.rev_amt, &mut self.exc, &mut self.width, &mut self.boost, &mut self.loud_mix, &mut self.out] { s.snap(); } } @@ -454,7 +458,6 @@ impl AudioEffect for Mastering { if nch == 0 { return; } - let loud_on = self.pv.v("loudness") > 0.0; let rev_param = self.pv.v("reverb") > 0.0; let mode = self.pv.idx("exciter_mode"); let ahp = OnePole::alpha(3000.0, self.sr); @@ -485,9 +488,9 @@ impl AudioEffect for Mastering { self.rev.process(&mut [&mut a[..len], &mut b[..len]]); } for i in 0..len { - // The maximizer stays in while its boost ramps back to 0 dB. - let loud = loud_on || self.boost.is_smoothing(); let (ra, ex, w, boost, out) = (self.rev_amt.tick(), self.exc.tick(), self.width.tick(), self.boost.tick(), self.out.tick()); + // The maximizer crossfades in and out over the smoothing ramp. + let mix = self.loud_mix.tick(); let j = start + i; for ch in 0..nch { let mut v = channels[ch][j]; @@ -511,11 +514,8 @@ impl AudioEffect for Mastering { channels[0][j] = m + s; channels[1][j] = m - s; } - if loud { - for c in channels[..nch].iter_mut() { - c[j] *= boost; - } - let peak = channels[..nch].iter().fold(0.0f32, |a, c| a.max(c[j].abs())); + if mix > 0.0 { + let peak = channels[..nch].iter().fold(0.0f32, |a, c| a.max((c[j] * boost).abs())); let target = (lin_db(ceiling) - lin_db(peak)).min(0.0); if target < self.lim_env { // An inf input sample gives -inf, which the release would never leave. @@ -525,7 +525,10 @@ impl AudioEffect for Mastering { } let g = db_to_gain(self.lim_env); for c in channels[..nch].iter_mut() { - c[j] = soft_clip(c[j] * g, ceiling); + let x = c[j]; + let y = soft_clip(x * boost * g, ceiling); + // The blend stays within the ceiling, which the maximized signal holds. + c[j] = if mix < 1.0 { (x + mix * (y - x)).clamp(-ceiling, ceiling) } else { y }; } } else { self.lim_env = 0.0; From 9d24360e523fc9c0b635de5a709bdd3f0171fd15 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 07:11:15 -0800 Subject: [PATCH 19/84] audio-dsp: resampler frames past the position limit read at the limit A block that starts near MAX_RESAMPLE_POSITION and runs past it now reads every later frame at the limit's position, as the constant's docs say, instead of reading past the held source and returning silence. --- crates/audio-dsp/src/resample.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/crates/audio-dsp/src/resample.rs b/crates/audio-dsp/src/resample.rs index 42f594bd0..150eba11c 100644 --- a/crates/audio-dsp/src/resample.rs +++ b/crates/audio-dsp/src/resample.rs @@ -152,6 +152,8 @@ impl StreamResampler { let to = self.to as i64; let (step, rem_step) = ((self.from / self.to) as i64, (self.from % self.to) as i64); let (mut s, mut rem) = (first, first_rem); + // Frames past `end` (the position limit) stay at its position. + let advancing = (end - out) as usize; for i in 0..n { let frac = (rem as f64 / to as f64) as f32; // held starts at first - 1, so the earlier frame is always held @@ -163,6 +165,9 @@ impl StreamResampler { *x = a + (b - a) * frac; } } + if i >= advancing { + continue; + } s = s.wrapping_add(step); rem += rem_step; if rem >= to { @@ -379,6 +384,12 @@ mod tests { let out = r.process(pos, 8, |_, frames| vec![vec![0.25; frames]]); assert!(out[0].iter().all(|v| v.is_finite()), "{pos}"); } + // Frames of a block past the limit read at the limit. + for (from, to) in [(48_000, 48_000), (44_100, 48_000)] { + let mut r = StreamResampler::new(from, to); + let out = r.process(MAX_RESAMPLE_POSITION - 2, 8, |_, frames| vec![vec![0.5; frames]]); + assert!(out[0].iter().all(|&v| v == 0.5), "{from} -> {to}: {:?}", out[0]); + } // A pull that returns too many channels keeps the first `MAX_CHANNELS`. let mut r = StreamResampler::new(48_000, 48_000); let out = r.process(0, 1, |_, frames| vec![vec![0.5; frames]; 1_000]); From 1a8548c2b52baa9e008b834489c60ce157866684 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 10:32:29 -0800 Subject: [PATCH 20/84] audio-dsp: Mastering maximizer fade stays finite on overflowed samples A sample that the widener overflows to infinity takes the maximized value during the maximizer's crossfade, as it does once the maximizer is fully on, instead of turning the blend into NaN. --- crates/audio-dsp/src/effects/behavior_tests.rs | 5 +++++ crates/audio-dsp/src/effects/special.rs | 5 +++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index af6b240a2..f100015aa 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -501,6 +501,11 @@ fn mastering_maximizer_switches_without_a_step() { let ceiling = crate::db_to_gain(-0.3); let peak = on.iter().fold(0.0f32, |a, v| a.max(v.abs())); assert!(peak <= ceiling + 1e-6, "{peak} over the ceiling {ceiling}"); + // A widener sum that overflows stays finite through the fade. + let mut e = fx("mastering", &[]); + assert!(e.set_param("loudness", 1.0)); + let (l, r) = run(e.as_mut(), &[3e38; 64], &[-3e38; 64]); + assert!(l.iter().chain(&r).all(|v| v.is_finite()), "{l:?} {r:?}"); } #[test] diff --git a/crates/audio-dsp/src/effects/special.rs b/crates/audio-dsp/src/effects/special.rs index 2e3bb3813..894a4393c 100644 --- a/crates/audio-dsp/src/effects/special.rs +++ b/crates/audio-dsp/src/effects/special.rs @@ -527,8 +527,9 @@ impl AudioEffect for Mastering { for c in channels[..nch].iter_mut() { let x = c[j]; let y = soft_clip(x * boost * g, ceiling); - // The blend stays within the ceiling, which the maximized signal holds. - c[j] = if mix < 1.0 { (x + mix * (y - x)).clamp(-ceiling, ceiling) } else { y }; + // The blend stays within the ceiling, which the maximized signal holds. A + // non-finite sample takes the maximized value, as it does once fully on. + c[j] = if mix < 1.0 && x.is_finite() { (x + mix * (y - x)).clamp(-ceiling, ceiling) } else { y }; } } else { self.lim_env = 0.0; From 3ec7639bf72cfce92a2d89daa7a6dcc353d79e75 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 10:38:19 -0800 Subject: [PATCH 21/84] audio-dsp: filter design takes 1 kHz for a NaN edge frequency `realize` and `design` replaced a NaN edge frequency with nothing, so the prewarp gave NaN coefficients and the filter output NaN. A NaN edge now takes 1 kHz in every band, as a NaN ripple or attenuation takes its usual value. --- crates/audio-dsp/src/design.rs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/crates/audio-dsp/src/design.rs b/crates/audio-dsp/src/design.rs index 64b034151..eb4b166f9 100644 --- a/crates/audio-dsp/src/design.rs +++ b/crates/audio-dsp/src/design.rs @@ -615,8 +615,11 @@ pub fn prototype(family: Family, order: usize, ripple_db: f64, stop_db: f64) -> } /// Transform a prototype to `band` at `f1` (and `f2` for band-pass/stop) and digitize it. An -/// unusable rate is replaced as [`crate::sane_sample_rate`] describes. +/// unusable rate is replaced as [`crate::sane_sample_rate`] describes, and a NaN edge frequency +/// takes 1 kHz. pub fn realize(proto: &Prototype, band: Band, f1: f64, f2: f64, sample_rate: f64) -> Sections { + let edge = |hz: f64| if hz.is_nan() { 1000.0 } else { hz }; + let (f1, f2) = (edge(f1), edge(f2)); let sample_rate = f64::from(crate::sane_sample_rate(sample_rate as f32)); let mut f = proto.0; let nyq = sample_rate * 0.5; @@ -770,6 +773,15 @@ mod tests { assert!(db.is_finite(), "{family:?} at {sr}: {db}"); } } + // A NaN edge frequency gives a finite filter in every band. + let p = prototype(Family::Butterworth, 4, 1.0, 60.0); + for band in [Band::LowPass, Band::HighPass, Band::BandPass, Band::BandStop] { + for (f1, f2) in [(f64::NAN, 2000.0), (500.0, f64::NAN), (f64::NAN, f64::NAN)] { + let s = realize(&p, band, f1, f2, 48_000.0); + let db = s.magnitude_db(100.0, 48_000.0); + assert!(db.is_finite(), "{band:?} at {f1}, {f2}: {db}"); + } + } } #[test] From a43ffece021d3dc56e8b1ca06a3c72dea0e67697 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 18:36:32 -0800 Subject: [PATCH 22/84] audio-dsp: document the event, transport, parameter and biquad items EventInput::note_on and note_off state the MIDI 1.0 note and velocity ranges, and the trait states that callers keep offset below the next block's frame count. The Transport fields, the ParamSpec range fields, the Coeffs fields, FilterType::from_index and the Biquad methods gain doc comments. --- crates/audio-dsp/src/biquad.rs | 11 +++++++++++ crates/audio-dsp/src/lib.rs | 19 ++++++++++++++++++- 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/crates/audio-dsp/src/biquad.rs b/crates/audio-dsp/src/biquad.rs index cc108220a..668af6bb5 100644 --- a/crates/audio-dsp/src/biquad.rs +++ b/crates/audio-dsp/src/biquad.rs @@ -31,6 +31,7 @@ impl FilterType { FilterType::Notch, FilterType::BandPass, ]; + /// The entry of [`FilterType::ALL`] at `i`; an index past the end gives the last entry. pub fn from_index(i: usize) -> FilterType { Self::ALL[i.min(Self::ALL.len() - 1)] } @@ -39,10 +40,15 @@ impl FilterType { /// Normalized biquad coefficients (`a0 == 1`). #[derive(Clone, Copy, Debug, PartialEq)] pub struct Coeffs { + /// Feed-forward coefficient of the input sample. pub b0: f64, + /// Feed-forward coefficient of the input one sample back. pub b1: f64, + /// Feed-forward coefficient of the input two samples back. pub b2: f64, + /// Feedback coefficient of the output one sample back. pub a1: f64, + /// Feedback coefficient of the output two samples back. pub a2: f64, } @@ -128,9 +134,13 @@ pub struct Biquad { } impl Biquad { + /// A section with zero state. pub const fn new() -> Self { Biquad { s1: 0.0, s2: 0.0 } } + /// Filters one sample `x` through `c` and returns the output sample. A state value whose + /// magnitude is below 1e-30 or that is not finite is stored as zero, so a NaN or infinite + /// input sample makes that one output non-finite and leaves the state at zero. #[inline(always)] pub fn tick(&mut self, c: &Coeffs, x: f64) -> f64 { let y = c.b0 * x + self.s1; @@ -138,6 +148,7 @@ impl Biquad { self.s2 = flush(c.b2 * x - c.a2 * y); y } + /// Sets the state back to zero. pub fn reset(&mut self) { *self = Biquad::new(); } diff --git a/crates/audio-dsp/src/lib.rs b/crates/audio-dsp/src/lib.rs index 2e3a74327..2c6e4c733 100644 --- a/crates/audio-dsp/src/lib.rs +++ b/crates/audio-dsp/src/lib.rs @@ -105,9 +105,13 @@ pub struct ParamSpec { pub id: &'static str, /// Human-readable label. pub name: &'static str, + /// Lowest value [`ParamSpec::sanitize`] keeps. pub min: f32, + /// Highest value [`ParamSpec::sanitize`] keeps. pub max: f32, + /// Value a new effect starts with, and the value NaN is read as. pub default: f32, + /// Unit the value is in. pub unit: Unit, /// Hint that the control should be logarithmic (frequencies, times). pub log_scale: bool, @@ -248,15 +252,21 @@ pub trait AudioEffect: Send { /// The host's transport at the start of a block, for tempo-synced effects and instruments. #[derive(Clone, Copy, Debug, Default, PartialEq)] pub struct Transport { + /// Whether the timeline is playing. pub playing: bool, + /// Whether the host is recording. pub recording: bool, /// Quarter notes per minute. pub tempo: f64, + /// Beats per bar, the upper number of the time signature. pub numerator: u32, + /// Note value of one beat, the lower number of the time signature (4 for a quarter note). pub denominator: u32, - /// Timeline position. + /// Timeline position of the block's first frame, in samples. pub samples: i64, + /// The same position in seconds. pub seconds: f64, + /// The same position in quarter notes. pub quarters: f64, /// Start of the current bar, in quarter notes, and its number (0 for the first bar). pub bar_start: f64, @@ -265,13 +275,20 @@ pub struct Transport { /// Note and transport input of an instrument or tempo-synced effect. Every call refers to the /// next processed block; `offset` is a frame within it. Calls never allocate. +/// +/// Callers keep `offset` below the frame count of the next block. The trait does not define what +/// an implementation does with a larger offset. pub trait EventInput { /// The transport for the next block. fn set_transport(&mut self, transport: &Transport); + /// Starts `note`, a MIDI 1.0 key number from 0 to 127 (60 is middle C), at `velocity` from 1 + /// to 127. Callers send a MIDI note-on with velocity 0 as [`EventInput::note_off`]. fn note_on(&mut self, offset: usize, note: u8, velocity: u8); + /// Releases `note`, a MIDI 1.0 key number from 0 to 127. fn note_off(&mut self, offset: usize, note: u8); /// Any other MIDI 1.0 channel message (control change, pitch bend, pressure, program change). fn midi(&mut self, offset: usize, message: [u8; 3]); + /// Releases every sounding note at the start of the next block. fn all_notes_off(&mut self); } From 3af8718e64cd2cb4bc03786fa27a34e60c5b6b31 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 18:41:17 -0800 Subject: [PATCH 23/84] audio-dsp: multiband crossovers stay in order at low sample rates The low and mid crossovers are capped below the high one's sample-rate limit before the next is derived. At 1 kHz with the low crossover at 1000 Hz, crossovers() returned [1000, 360, 450], so the low band sat above the other two. crossovers_stay_increasing_at_the_lowest_sample_rate fails without the change. Rates whose limit is above the parameter ranges get the same crossovers as before. --- crates/audio-dsp/src/effects/multiband.rs | 26 ++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/crates/audio-dsp/src/effects/multiband.rs b/crates/audio-dsp/src/effects/multiband.rs index 32d2f9f34..9c20431dd 100644 --- a/crates/audio-dsp/src/effects/multiband.rs +++ b/crates/audio-dsp/src/effects/multiband.rs @@ -392,12 +392,14 @@ impl MultibandCompressor { s } - /// Crossover frequencies (Hz) at the current settings, kept strictly increasing. + /// Crossover frequencies (Hz) at the current settings, kept strictly increasing, each at least + /// 1.25 times the one below it, and at most 0.45 times the sample rate. pub fn crossovers(&self) -> [f32; 3] { - let a = self.pv.v("xo1"); - let b = self.pv.v("xo2").max(a * 1.25); - let c = self.pv.v("xo3").max(b * 1.25).min(self.sr * 0.45); - [a, b.min(c / 1.25), c] + let top = self.sr * 0.45; + let a = self.pv.v("xo1").min(top / (1.25 * 1.25)); + let b = self.pv.v("xo2").max(a * 1.25).min(top / 1.25); + let c = self.pv.v("xo3").max(b * 1.25).min(top); + [a, b, c] } fn update_xo(&mut self) { @@ -711,4 +713,18 @@ mod tests { assert_eq!(e.xc.lp[0], Coeffs::design(FilterType::LowPass, sr as f64, f, Q_BW, 0.0)); assert_eq!(e.xc.hp[0], Coeffs::design(FilterType::HighPass, sr as f64, f, Q_BW, 0.0)); } + + #[test] + fn crossovers_stay_increasing_at_the_lowest_sample_rate() { + for sr in [crate::MIN_SAMPLE_RATE, 2_000.0, 48_000.0] { + let mut e = MultibandCompressor::new(sr, 2); + for (xo1, xo2, xo3) in [(1000.0, 100.0, 1000.0), (1000.0, 8000.0, 20000.0), (20.0, 100.0, 1000.0), (120.0, 2000.0, 10000.0)] { + assert!(e.set_param("xo1", xo1)); + assert!(e.set_param("xo2", xo2)); + assert!(e.set_param("xo3", xo3)); + let [a, b, c] = e.crossovers(); + assert!(a < b && b < c && c <= sr * 0.45, "{sr} Hz, ({xo1}, {xo2}, {xo3}): {a}, {b}, {c}"); + } + } + } } From e6fc8fccdda96d9f40e79effd2c9ec44e4cade03 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 18:48:02 -0800 Subject: [PATCH 24/84] audio-dsp: true-peak oversampling reaches 176.4 kHz at every sample rate true_peak_factor returns the smallest factor whose effective rate is at least 176.4 kHz, after the rate is replaced as sane_sample_rate describes. Below 44.1 kHz it returned 4, so at 32 kHz the loudness meter and the limiter checked 128 kHz. The factors at 44.1, 48, 88.2, 96, 176.4 and 192 kHz do not change. true_peak_factor_reaches_176_4_khz_at_every_rate fails without the change. noise_shaping_error_stays_bounded_at_full_scale checks that the dither's fed-back error stays within two steps on sustained full-scale input. --- crates/audio-dsp/src/effects/dither.rs | 10 +++++++++ crates/audio-dsp/src/oversample.rs | 30 ++++++++++++++++++-------- 2 files changed, 31 insertions(+), 9 deletions(-) diff --git a/crates/audio-dsp/src/effects/dither.rs b/crates/audio-dsp/src/effects/dither.rs index 5eb609bea..6fe85d816 100644 --- a/crates/audio-dsp/src/effects/dither.rs +++ b/crates/audio-dsp/src/effects/dither.rs @@ -109,6 +109,16 @@ mod tests { assert!((x[2] - 0.25).abs() < 4.0 * lsb && (x[5] - 0.1).abs() < 4.0 * lsb, "{x:?}"); } + #[test] + fn noise_shaping_error_stays_bounded_at_full_scale() { + let mut d = Dither::new(48_000.0, 1); + assert!(d.set_param("noise_shaping", 1.0)); + let mut x = vec![1.0f32; 48_000]; + d.process(&mut [&mut x]); + assert!(d.err[0].abs() <= 2.0 * d.lsb, "error {} LSB", d.err[0] / d.lsb); + assert!(x.iter().all(|v| (1.0 - 2.0 * d.lsb..=1.0 - d.lsb).contains(v))); + } + #[test] fn noise_shaping_moves_the_error_up_in_frequency() { let run = |shape: bool| { diff --git a/crates/audio-dsp/src/oversample.rs b/crates/audio-dsp/src/oversample.rs index 6974c0128..c24aaed9c 100644 --- a/crates/audio-dsp/src/oversample.rs +++ b/crates/audio-dsp/src/oversample.rs @@ -8,16 +8,13 @@ use std::f64::consts::PI; /// Taps per polyphase branch. pub const TAPS_PER_PHASE: usize = 16; -/// Oversampling factor giving an effective rate of at least 176.4 kHz (4× at 44.1/48 kHz, -/// 2× at 88.2/96 kHz, 1× above), as recommended by BS.1770-4 for true-peak metering. +/// Smallest oversampling factor giving an effective rate of at least 176.4 kHz (4× at 44.1/48 kHz, +/// 2× at 88.2/96 kHz, 1× from 176.4 kHz, 6× at 32 kHz), as recommended by BS.1770-4 for +/// true-peak metering. The rate is first replaced as [`crate::sane_sample_rate`] describes, so the +/// factor is at most 177. pub fn true_peak_factor(sample_rate: f64) -> usize { - if sample_rate < 88_200.0 { - 4 - } else if sample_rate < 176_400.0 { - 2 - } else { - 1 - } + let rate = f64::from(crate::sane_sample_rate(sample_rate as f32)); + ((176_400.0 / rate).ceil() as usize).max(1) } fn bessel_i0(x: f64) -> f64 { @@ -130,6 +127,21 @@ fn dot(c: &[f32; TAPS_PER_PHASE], win: &[f32]) -> f32 { mod tests { use super::*; + #[test] + fn true_peak_factor_reaches_176_4_khz_at_every_rate() { + for (rate, factor) in [(44_100.0, 4), (48_000.0, 4), (88_200.0, 2), (96_000.0, 2), (176_400.0, 1), (192_000.0, 1)] { + assert_eq!(true_peak_factor(rate), factor, "{rate} Hz"); + } + for rate in [1_000.0, 8_000.0, 22_050.0, 32_000.0, 44_099.0, 60_000.0, 100_000.0, 1_536_000.0] { + let factor = true_peak_factor(rate); + assert!(factor as f64 * rate >= 176_400.0, "{rate} Hz: {factor}"); + assert!((factor - 1) as f64 * rate < 176_400.0, "{rate} Hz: {factor}"); + } + for rate in [0.0, -1.0, f64::NAN, f64::INFINITY] { + assert_eq!(true_peak_factor(rate), 4, "{rate}"); + } + } + #[test] fn phases_have_unity_dc_and_interpolate_sines() { let bank = PolyphaseBank::new(4); From 518d94bdf59d496d370cc3237f8afcfc119d9d8b Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 19:32:39 -0800 Subject: [PATCH 25/84] audio-dsp: a NaN frequency or gain designs a finite biquad Coeffs::design clamped a NaN frequency to NaN, so every coefficient was NaN and the section's output stayed NaN after the next finite sample. A NaN frequency now designs at 1000 Hz, as design::realize does, and a NaN gain at 0 dB. --- crates/audio-dsp/src/biquad.rs | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/crates/audio-dsp/src/biquad.rs b/crates/audio-dsp/src/biquad.rs index 668af6bb5..9adbe9650 100644 --- a/crates/audio-dsp/src/biquad.rs +++ b/crates/audio-dsp/src/biquad.rs @@ -62,9 +62,12 @@ impl Coeffs { /// RBJ cookbook design. `freq` in Hz (clamped below Nyquist), `q` > 0, `gain_db` used by /// peaking and shelving types (shelves use `q` as the shelf "Q", S=1 ≙ Q=1/√2). An unusable - /// rate is replaced as [`crate::sane_sample_rate`] describes. + /// rate is replaced as [`crate::sane_sample_rate`] describes. A NaN `freq` designs at 1000 Hz, + /// as [`crate::design::realize`] does, and a NaN `gain_db` designs at 0 dB. pub fn design(kind: FilterType, sample_rate: f64, freq: f64, q: f64, gain_db: f64) -> Coeffs { let sample_rate = f64::from(crate::sane_sample_rate(sample_rate as f32)); + let freq = if freq.is_nan() { 1000.0 } else { freq }; + let gain_db = if gain_db.is_nan() { 0.0 } else { gain_db }; let f = freq.clamp(1.0, sample_rate * 0.49); let q = q.max(1e-3); let w0 = 2.0 * PI * f / sample_rate; @@ -189,6 +192,20 @@ mod tests { } } + #[test] + fn a_nan_frequency_or_gain_gives_finite_coefficients_and_output() { + for kind in [FilterType::LowPass, FilterType::Peaking, FilterType::HighShelf] { + for (freq, gain) in [(f64::NAN, 6.0), (1000.0, f64::NAN), (f64::NAN, f64::NAN)] { + let c = Coeffs::design(kind, SR, freq, 0.7, gain); + assert!([c.b0, c.b1, c.b2, c.a1, c.a2].iter().all(|v| v.is_finite()), "{kind:?} {freq} {gain}: {c:?}"); + let mut bq = Biquad::new(); + let mut x = sine(440.0, 0.5, SR, 256, 0.0); + bq.process(&c, &mut x); + assert!(x.iter().all(|v| v.is_finite()), "{kind:?} {freq} {gain}: output is not finite"); + } + } + } + #[test] fn peaking_hits_gain_at_center() { let c = Coeffs::design(FilterType::Peaking, SR, 1000.0, 1.0, 6.0); From e000dc5f765dcdbe96396fc0d2ca8145bc9544d9 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 19:32:40 -0800 Subject: [PATCH 26/84] audio-dsp: Mastering EQ changes ramp, Binauralizer reports its tail - Mastering: a change to an EQ gain or the peak frequency replaced the coefficients at once, under the old filter memories, which gave a transient. The four EQ settings now ramp over 20 ms, the coefficients designed again for each sample while they ramp; reset goes straight to the target. - Binauralizer: tail_samples was 0, so an offline render stopped before the far ear's delayed sound. It now covers the longer of the current and target delay and the head-shadow filters' decay. - The neutral identity test fails on a sample that is not finite. --- .../audio-dsp/src/effects/behavior_tests.rs | 76 +++++++++++++++++- crates/audio-dsp/src/effects/special.rs | 78 +++++++++++++++---- 2 files changed, 139 insertions(+), 15 deletions(-) diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index f100015aa..eb1a60e4c 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -103,7 +103,9 @@ fn neutral_settings_are_delayed_identity() { let (a, b) = run(e.as_mut(), &l, &r); let mut worst = 0.0f32; for i in lat..n { - worst = worst.max((a[i] - l[i - lat]).abs()).max((b[i] - r[i - lat]).abs()); + let (el, er) = ((a[i] - l[i - lat]).abs(), (b[i] - r[i - lat]).abs()); + assert!(el.is_finite() && er.is_finite(), "{id}: neutral output at {i} is not finite"); + worst = worst.max(el).max(er); } assert!(worst < 2e-4, "{id}: neutral output differs by {worst}"); checked += 1; @@ -541,6 +543,78 @@ fn mastering_maximizer_ramps_out() { assert!((z[z.len() - 1] - 0.01).abs() < 1e-4, "{}", z[z.len() - 1]); } +#[test] +fn mastering_eq_gain_ramps_and_reset_snaps() { + let n = SR as usize / 10; + let (pre, post) = (noise(41, n, 0.25), noise(42, n, 0.25)); + for (id, gain) in [("eq_high", 12.0), ("eq_low", -12.0), ("eq_mid", 12.0)] { + let (mut a, mut b) = (fx("mastering", &[]), fx("mastering", &[])); + run(a.as_mut(), &pre, &pre); + run(b.as_mut(), &pre, &pre); + assert!(a.set_param(id, gain)); + let (ya, _) = run(a.as_mut(), &post, &post); + let (yb, _) = run(b.as_mut(), &post, &post); + // The first samples after the change still sound like the old setting. + let step = ya[..8].iter().zip(&yb[..8]).fold(0.0f32, |m, (x, y)| m.max((x - y).abs())); + assert!(step < 0.03, "{id}: the output jumped by {step} at the change"); + // After the ramp the output is what the new setting gives. + let mut c = fx("mastering", &[(id, gain)]); + run(c.as_mut(), &pre, &pre); + let (yc, _) = run(c.as_mut(), &post, &post); + let late = ya[n / 2..].iter().zip(&yc[n / 2..]).fold(0.0f32, |m, (x, y)| m.max((x - y).abs())); + assert!(late < 1e-4, "{id}: after the ramp the output differs by {late}"); + // Reset goes straight to the new setting. + assert!(b.set_param(id, gain)); + b.reset(); + c.reset(); + assert_eq!(run(b.as_mut(), &post, &post), run(c.as_mut(), &post, &post), "{id}: reset did not snap"); + } +} + +#[test] +fn mastering_eq_ramp_does_not_depend_on_the_block_size() { + let n = SR as usize / 20; + let x = noise(43, n, 0.25); + let ramp = |block: usize| { + let mut e = fx("mastering", &[]); + run(e.as_mut(), &x[..1000], &x[..1000]); + assert!(e.set_param("eq_high", 12.0)); + let mut out = vec![]; + for part in x.chunks(block) { + out.extend(run(e.as_mut(), part, part).0); + } + out + }; + let whole = ramp(n); + for block in [1, 7, 100] { + let worst = whole.iter().zip(&ramp(block)).fold(0.0f32, |m, (a, b)| m.max((a - b).abs())); + assert!(worst <= 1e-6, "blocks of {block} differ by {worst}"); + } +} + +#[test] +fn binauralizer_tail_covers_the_far_ear() { + let n = SR as usize / 10; + for angle in [30.0, 90.0] { + let mut e = fx("binauralizer", &[("angle", angle), ("head_size", 24.0)]); + // A left-only impulse in the last frame of the input. + let mut l = vec![0.0f32; n]; + l[n - 1] = 1.0; + run(e.as_mut(), &l, &vec![0.0; n]); + let tail = e.tail_samples(); + let silence = vec![0.0f32; SR as usize / 10]; + let (a, b) = run(e.as_mut(), &silence, &silence); + let last = |s: &[f32]| s.iter().rposition(|v| v.abs() > 1e-6).map_or(0, |i| i + 1); + assert!(last(&b) > 10, "{angle}: the right ear's delayed sound ends at {}", last(&b)); + assert!(last(&a).max(last(&b)) <= tail, "{angle}: sound until {} after a tail of {tail}", last(&a).max(last(&b))); + } + // A delay that ramps longer is covered from the start of the ramp. + let mut e = fx("binauralizer", &[("angle", 0.0)]); + assert!(e.set_param("angle", 90.0)); + let itd = 0.0875 / 343.0 * (std::f32::consts::FRAC_PI_2 + 1.0) * SR; + assert!(e.tail_samples() as f32 >= itd, "{} below the target delay {itd}", e.tail_samples()); +} + #[test] fn dynamics_effects_report_gain_reduction() { let n = SR as usize / 2; diff --git a/crates/audio-dsp/src/effects/special.rs b/crates/audio-dsp/src/effects/special.rs index 894a4393c..99cd70894 100644 --- a/crates/audio-dsp/src/effects/special.rs +++ b/crates/audio-dsp/src/effects/special.rs @@ -352,6 +352,9 @@ pub struct Mastering { pv: ParamValues, sr: f32, eq: [Coeffs; 3], + /// The EQ settings the coefficients ramp through: low shelf gain, peak frequency (log2 Hz), + /// peak gain and high shelf gain. + eq_set: [Smoothed; 4], st: Vec<[Biquad; 3]>, rev: Reverb, scratch: [[f32; CHUNK]; 2], @@ -394,6 +397,7 @@ impl Mastering { pv: ParamValues::new(Self::PARAMS), sr: sample_rate, eq: [Coeffs::IDENTITY; 3], + eq_set: [sm(0.0, sample_rate), sm(1000f32.log2(), sample_rate), sm(0.0, sample_rate), sm(0.0, sample_rate)], st: vec![[Biquad::new(); 3]; ch], rev, scratch: [[0.0; CHUNK]; 2], @@ -411,14 +415,28 @@ impl Mastering { s } - fn apply_params(&mut self, snap: bool) { + /// The EQ's coefficients at the ramps' current values, or at their targets. + fn eq_coeffs(&self, target: bool) -> [Coeffs; 3] { let sr = self.sr as f64; let q = std::f64::consts::FRAC_1_SQRT_2; - self.eq = [ - Coeffs::design(FilterType::LowShelf, sr, 100.0, q, self.pv.v("eq_low") as f64), - Coeffs::design(FilterType::Peaking, sr, self.pv.v("eq_mid_freq") as f64, 1.0, self.pv.v("eq_mid") as f64), - Coeffs::design(FilterType::HighShelf, sr, 8000.0, q, self.pv.v("eq_high") as f64), - ]; + let [low, freq, mid, high] = self.eq_set.map(|s| f64::from(if target { s.target() } else { s.value() })); + [ + Coeffs::design(FilterType::LowShelf, sr, 100.0, q, low), + Coeffs::design(FilterType::Peaking, sr, 2f64.powf(freq), 1.0, mid), + Coeffs::design(FilterType::HighShelf, sr, 8000.0, q, high), + ] + } + + fn apply_params(&mut self, snap: bool) { + let [low, freq, mid, high] = &mut self.eq_set; + low.set(self.pv.v("eq_low")); + freq.set(self.pv.v("eq_mid_freq").max(1.0).log2()); + mid.set(self.pv.v("eq_mid")); + high.set(self.pv.v("eq_high")); + if snap { + self.eq_set.iter_mut().for_each(Smoothed::snap); + } + self.eq = self.eq_coeffs(false); self.rev_amt.set(0.4 * self.pv.v("reverb") / 100.0); self.exc.set(0.6 * self.pv.v("exciter") / 100.0); self.width.set(self.pv.v("widener") / 100.0); @@ -440,9 +458,11 @@ impl AudioEffect for Mastering { if self.pv.v("reverb") > 0.0 || self.rev_amt.is_smoothing() { self.rev.tail_samples() } else { 0 } } fn response_db(&self, freq: f64) -> Option { - Some(self.eq.iter().map(|c| c.magnitude_db(freq, self.sr as f64)).sum::() + self.pv.v("output") as f64) + Some(self.eq_coeffs(true).iter().map(|c| c.magnitude_db(freq, self.sr as f64)).sum::() + self.pv.v("output") as f64) } fn reset(&mut self) { + self.eq_set.iter_mut().for_each(Smoothed::snap); + self.eq = self.eq_coeffs(false); self.st.iter_mut().for_each(|s| s.iter_mut().for_each(Biquad::reset)); self.rev.reset(); self.hp.iter_mut().for_each(OnePole::reset); @@ -469,15 +489,28 @@ impl AudioEffect for Mastering { // The reverb runs until its amount has faded to 0. let use_rev = rev_param || self.rev_amt.is_smoothing(); self.rev_on = use_rev; - // EQ in place. - for ch in 0..nch { - for v in channels[ch][start..start + len].iter_mut() { - let mut y = *v as f64; - for (k, c) in self.eq.iter().enumerate() { - y = self.st[ch][k].tick(c, y); + // EQ in place. While a setting ramps, the coefficients are designed again for every + // sample; once the ramps end, the rest of the chunk runs on fixed coefficients. + let mut i = 0; + while i < len { + let ramping = self.eq_set.iter().any(Smoothed::is_smoothing); + if ramping { + for s in &mut self.eq_set { + s.tick(); } - *v = y as f32; + self.eq = self.eq_coeffs(false); } + let step = if ramping { 1 } else { len - i }; + for ch in 0..nch { + for v in channels[ch][start + i..start + i + step].iter_mut() { + let mut y = *v as f64; + for (k, c) in self.eq.iter().enumerate() { + y = self.st[ch][k].tick(c, y); + } + *v = y as f32; + } + } + i += step; } if use_rev { for i in 0..len { @@ -783,6 +816,23 @@ impl Binauralizer { impl AudioEffect for Binauralizer { param_plumbing!("binauralizer"); + /// The far ear's delay (the longer of the current and target delay while it ramps) and the + /// head-shadow filters' decay to a millionth. + fn tail_samples(&self) -> usize { + if self.mix.target() <= 0.0 && !self.mix.is_smoothing() { + return 0; + } + let delay = self.itd.value().max(self.itd.target()).max(0.0).ceil() as usize + 2; + let pole = self.sh.iter().fold(0.0f32, |p, s| p.max(s.a1.abs())); + let decay = if pole <= 0.0 { + 1 + } else if pole < 1.0 { + (1e-6f32.ln() / pole.ln()).ceil() as usize + 1 + } else { + super::util::tail_samples(f32::INFINITY, self.sr) + }; + delay + decay + } fn reset(&mut self) { self.lines.iter_mut().for_each(DelayLine::reset); for s in &mut self.sh { From ad05996bc3998fcda1bde9551c53e21c0bcb72df Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 19:38:44 -0800 Subject: [PATCH 27/84] audio-dsp: the click remover keeps a sample that is not finite as silence A NaN or infinite input sample went into the analysis span unchanged. It stopped the prediction for that span and came out of a later block. Such a sample is now kept as silence. --- crates/audio-dsp/src/effects/behavior_tests.rs | 17 +++++++++++++++++ crates/audio-dsp/src/effects/declick.rs | 4 +++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index eb1a60e4c..b2f405450 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -653,6 +653,23 @@ fn click_remover_repairs_clicks() { assert!(db(after / before) < -20.0, "error {before} → {after}"); } +#[test] +fn click_remover_keeps_a_non_finite_sample_as_silence() { + let n = SR as usize / 2; + let clean = sine(440.0, 0.3, SR as f64, n, 0.0); + let mut dirty = clean.clone(); + dirty[5000] = f32::NAN; + dirty[9000] = f32::INFINITY; + // A click in the same span as the NaN. + dirty[5100] += 0.6; + let mut e = fx("click_remover", &[]); + let lat = e.latency(); + let (y, _) = run(e.as_mut(), &dirty, &dirty); + assert!(y.iter().all(|v| v.is_finite()), "a sample that is not finite came out"); + let click = (y[5100 + lat] - clean[5100]).abs(); + assert!(click < 0.1, "the click next to the NaN was left at {click}"); +} + #[test] fn channel_and_stereo_tools() { let n = 4800; diff --git a/crates/audio-dsp/src/effects/declick.rs b/crates/audio-dsp/src/effects/declick.rs index 988816e7e..21044b5cd 100644 --- a/crates/audio-dsp/src/effects/declick.rs +++ b/crates/audio-dsp/src/effects/declick.rs @@ -220,7 +220,9 @@ impl AudioEffect for ClickRemover { for (ci, chan) in channels.iter_mut().enumerate().take(nch) { let c = &mut self.ch[ci]; for v in chan[..n].iter_mut() { - let x = *v; + // A sample that is not finite is kept as silence, so it does not stop the + // analysis of the span it is in or come out of a later block. + let x = if v.is_finite() { *v } else { 0.0 }; *v = c.out[c.pos]; c.buf[SPAN - BLOCK + c.pos] = x; c.pos += 1; From 8effb287097102a7a0c401c7fc78bfd9e948b43d Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 22:48:50 -0800 Subject: [PATCH 28/84] wordmodel: number formats keep a trailing space that is part of the code clean_fmt trimmed every trailing space, so `#,##0_ ` became `#,##0_` and the `_` lost the space it pads with. A trailing space now stays when it follows `_`, `*` or `\`, or sits inside quotes. Other spaces at the ends and control characters are still removed. --- crates/wordmodel/src/chart.rs | 42 ++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/crates/wordmodel/src/chart.rs b/crates/wordmodel/src/chart.rs index 6c7296647..7328c7d13 100644 --- a/crates/wordmodel/src/chart.rs +++ b/crates/wordmodel/src/chart.rs @@ -222,10 +222,26 @@ impl ChartAxis { pub const MAX_FMT: usize = 128; /// A number format code: control characters as spaces, ends trimmed, at most [`MAX_FMT`] -/// characters. +/// characters. A trailing space stays when it is part of the code: the character after `_`, +/// `*` or `\`, or text inside quotes. pub fn clean_fmt(s: &str) -> String { - let s: String = s.chars().take(MAX_FMT * 4).map(|c| if c.is_control() { ' ' } else { c }).collect(); - s.trim().chars().take(MAX_FMT).collect::().trim_end().to_string() + let chars: Vec = s.chars().take(MAX_FMT * 4).skip_while(|c| c.is_whitespace() || c.is_control()).take(MAX_FMT).collect(); + let mut keep = 0; + let mut quoted = false; + let mut operand = false; + for (i, &c) in chars.iter().enumerate() { + if !c.is_control() && (!c.is_whitespace() || operand || quoted) { + keep = i + 1; + } + if operand { + operand = false; + } else if c == '"' { + quoted = !quoted; + } else if !quoted && matches!(c, '_' | '*' | '\\') { + operand = true; + } + } + chars[..keep].iter().map(|&c| if c.is_control() { ' ' } else { c }).collect() } /// A chart the app can edit. @@ -447,4 +463,24 @@ mod tests { spec.sanitize(); assert_eq!(spec.series[0].line_w, Some(20.0), "a wild width clamps to 20 pt"); } + + #[test] + fn format_keeps_a_trailing_space_that_is_an_operand() { + // `_`, `*` and `\` take the next character, so a final space after one is part of the code. + assert_eq!(clean_fmt("#,##0_ "), "#,##0_ "); + assert_eq!(clean_fmt("0* "), "0* "); + assert_eq!(clean_fmt("0\\ "), "0\\ "); + assert_eq!(clean_fmt("0_ \n "), "0_ "); + assert_eq!(clean_fmt("0\"a "), "0\"a ", "a space inside quotes is text"); + // Other spaces at the ends, and control characters, still go. + assert_eq!(clean_fmt(" 0.00 \t"), "0.00"); + assert_eq!(clean_fmt("0_\n"), "0_"); + assert_eq!(clean_fmt("0\"a\" "), "0\"a\""); + assert_eq!(clean_fmt("\\_ "), "\\_", "an escaped `_` takes no operand"); + assert_eq!(clean_fmt("0\u{1}0"), "0 0"); + assert_eq!(clean_fmt("_\u{1}"), "_"); + assert_eq!(clean_fmt(" \n "), ""); + let long = format!("{}_ ", "0".repeat(MAX_FMT - 2)); + assert_eq!(clean_fmt(&long), long, "a code of exactly MAX_FMT characters keeps its operand"); + } } From 89b3ab976e24aec2eb44844588ec21782a6abb32 Mon Sep 17 00:00:00 2001 From: arnav-hiwarkar Date: Wed, 18 Nov 2026 15:29:58 +0530 Subject: [PATCH 29/84] cms: validate SPI3D rows before reserving the lattice (storytold/effectcraft#3831) --- crates/cms/src/sony_lut.rs | 76 ++++++++++++++++++++++++++++++------ crates/cms/tests/sony_lut.rs | 16 ++++++++ 2 files changed, 80 insertions(+), 12 deletions(-) diff --git a/crates/cms/src/sony_lut.rs b/crates/cms/src/sony_lut.rs index cc3f8fb00..38936c817 100644 --- a/crates/cms/src/sony_lut.rs +++ b/crates/cms/src/sony_lut.rs @@ -61,22 +61,74 @@ pub fn parse_spi3d(text: &str) -> Option { return None; } let count = n * n * n; - let mut values = vec![[0.0f32; 3]; count]; + // Validate every row and the row count before reserving the lattice, so a short or + // malformed file never allocates the table its header claims. The rows are then read + // again in file order, which keeps the last value of a duplicate coordinate. let mut seen = 0usize; - for line in lines { + for line in lines.clone() { if seen == count { return None; } - let mut fields = line.split_whitespace(); - let r: usize = fields.next()?.parse().ok()?; - let g: usize = fields.next()?.parse().ok()?; - let b: usize = fields.next()?.parse().ok()?; - let color = [fields.next()?.parse().ok()?, fields.next()?.parse().ok()?, fields.next()?.parse().ok()?]; - if fields.next().is_some() || r >= n || g >= n || b >= n { - return None; - } - *values.get_mut(r + g * n + b * n * n)? = color; + spi3d_row(line, n)?; seen += 1; } - (seen == count).then_some(Lattice { size: n, values }) + if seen != count { + return None; + } + #[cfg(test)] + tests::LATTICES_RESERVED.with(|r| r.set(r.get() + 1)); + let mut values = vec![[0.0f32; 3]; count]; + for line in lines { + let (index, color) = spi3d_row(line, n)?; + *values.get_mut(index)? = color; + } + Some(Lattice { size: n, values }) +} + +/// One `r g b R G B` row of a side-`n` lattice: its red-fastest index and its colour. +fn spi3d_row(line: &str, n: usize) -> Option<(usize, [f32; 3])> { + let mut fields = line.split_whitespace(); + let r: usize = fields.next()?.parse().ok()?; + let g: usize = fields.next()?.parse().ok()?; + let b: usize = fields.next()?.parse().ok()?; + let color = [fields.next()?.parse().ok()?, fields.next()?.parse().ok()?, fields.next()?.parse().ok()?]; + if fields.next().is_some() || r >= n || g >= n || b >= n { + return None; + } + Some((r + g * n + b * n * n, color)) +} + +#[cfg(test)] +#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)] +mod tests { + use super::*; + + thread_local! { + /// How many lattices [`parse_spi3d`] has reserved on this thread. + pub(super) static LATTICES_RESERVED: std::cell::Cell = const { std::cell::Cell::new(0) }; + } + + fn reserved() -> usize { + LATTICES_RESERVED.with(std::cell::Cell::get) + } + + #[test] + fn spi3d_reserves_the_lattice_only_once_its_rows_are_valid() { + // A header-only maximal claim, a short table and a full count of malformed rows. + let max = format!("SPILUT 1.0\n3 3\n{MAX_SIDE} {MAX_SIDE} {MAX_SIDE}\n"); + let short = "SPILUT 1.0\n3 3\n2 2 2\n0 0 0 1 1 1\n".to_owned(); + let junk = "SPILUT 1.0\n3 3\n2 2 2\n".to_owned() + &"x\n".repeat(8); + for bad in [max, short, junk] { + let before = reserved(); + assert!(parse_spi3d(&bad).is_none()); + assert_eq!(reserved(), before, "{bad}"); + } + let mut ok = "SPILUT 1.0\n3 3\n2 2 2\n".to_owned(); + for i in 0..8 { + ok += &format!("{} {} {} 0 0 0\n", i & 1, (i >> 1) & 1, i >> 2); + } + let before = reserved(); + assert!(parse_spi3d(&ok).is_some()); + assert_eq!(reserved(), before + 1); + } } diff --git a/crates/cms/tests/sony_lut.rs b/crates/cms/tests/sony_lut.rs index 065792a27..3add8f263 100644 --- a/crates/cms/tests/sony_lut.rs +++ b/crates/cms/tests/sony_lut.rs @@ -44,3 +44,19 @@ fn inherited_tolerance_is_explicit() { assert!(lut.values[0][2].is_nan()); assert_eq!(lut.values[1], [0.0; 3]); } + +#[test] +fn spi3d_duplicate_coordinates_keep_the_last_value() { + // Forward order: the last row (1 1 1) is replaced by a second 0 0 0, which wins, and 1 1 1 + // keeps the lattice's zero. + let mut text = String::from("SPILUT 1.0\n3 3\n2 2 2\n"); + for i in 0..7 { + let (r, g, b) = (i & 1, (i >> 1) & 1, i >> 2); + text.push_str(&format!("{r} {g} {b} 1 1 1\n")); + } + text.push_str("0 0 0 5 5 5\n"); + let lut = parse_spi3d(&text).unwrap(); + assert_eq!(lut.values[0], [5.0; 3]); + assert_eq!(lut.values[7], [0.0; 3]); + assert_eq!(lut.values[1], [1.0; 3]); +} From 39c3797be9eccfb467ff601ab27cbe735592ab3e Mon Sep 17 00:00:00 2001 From: arnav-hiwarkar Date: Wed, 18 Nov 2026 15:35:01 +0530 Subject: [PATCH 30/84] cms: SPI3D allocation test covers a bad last row and an extra row --- crates/cms/src/sony_lut.rs | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/crates/cms/src/sony_lut.rs b/crates/cms/src/sony_lut.rs index 38936c817..27ea0321c 100644 --- a/crates/cms/src/sony_lut.rs +++ b/crates/cms/src/sony_lut.rs @@ -114,19 +114,22 @@ mod tests { #[test] fn spi3d_reserves_the_lattice_only_once_its_rows_are_valid() { - // A header-only maximal claim, a short table and a full count of malformed rows. - let max = format!("SPILUT 1.0\n3 3\n{MAX_SIDE} {MAX_SIDE} {MAX_SIDE}\n"); - let short = "SPILUT 1.0\n3 3\n2 2 2\n0 0 0 1 1 1\n".to_owned(); - let junk = "SPILUT 1.0\n3 3\n2 2 2\n".to_owned() + &"x\n".repeat(8); - for bad in [max, short, junk] { - let before = reserved(); - assert!(parse_spi3d(&bad).is_none()); - assert_eq!(reserved(), before, "{bad}"); - } let mut ok = "SPILUT 1.0\n3 3\n2 2 2\n".to_owned(); for i in 0..8 { ok += &format!("{} {} {} 0 0 0\n", i & 1, (i >> 1) & 1, i >> 2); } + // A header-only maximal claim, a short table, a full count of malformed rows, a table + // whose last row is bad and one with a valid row too many. + let max = format!("SPILUT 1.0\n3 3\n{MAX_SIDE} {MAX_SIDE} {MAX_SIDE}\n"); + let short = "SPILUT 1.0\n3 3\n2 2 2\n0 0 0 1 1 1\n".to_owned(); + let junk = "SPILUT 1.0\n3 3\n2 2 2\n".to_owned() + &"x\n".repeat(8); + let last_bad = ok.replace("1 1 1 0 0 0", "1 1 2 0 0 0"); + let extra = ok.clone() + "0 0 0 0 0 0\n"; + for bad in [max, short, junk, last_bad, extra] { + let before = reserved(); + assert!(parse_spi3d(&bad).is_none()); + assert_eq!(reserved(), before, "{bad}"); + } let before = reserved(); assert!(parse_spi3d(&ok).is_some()); assert_eq!(reserved(), before + 1); From 276461be2c98e27d73042e56f09a2efc4a53a6ca Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Wed, 18 Nov 2026 07:38:56 -0800 Subject: [PATCH 31/84] audio-dsp: name the crate's own copyright holder as the Craft contributors NOTICE and the README carry "The Craft contributors" as the crate's own holder. ATTRIBUTION.md names FilmCraft and SoundCraft as the two sources. --- ATTRIBUTION.md | 2 +- crates/audio-dsp/NOTICE | 2 +- crates/audio-dsp/README.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 18d320a21..be686e0a1 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -117,7 +117,7 @@ The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper ## Audio DSP -`crates/audio-dsp` is moved from StudioCraft's `crates/craft-audio-dsp` ([blamejs/StudioCraft](https://github.com/blamejs/StudioCraft) at `98224a9cc3e9eb353844908b2a676b2e6a9327d5`, MIT OR Apache-2.0). That crate combines FilmCraft `crates/audio-dsp` at `3f137a7ed420cac79b32145f5243b7f98b31f71c` and SoundCraft `crates/dsp` at `648ed9db9a0e98cc55643babffac381521a556c8` (both MIT OR Apache-2.0). `crates/audio-dsp/NOTICE` keeps the copyright notices of all three projects. +`crates/audio-dsp` combines FilmCraft `crates/audio-dsp` at `3f137a7ed420cac79b32145f5243b7f98b31f71c` and SoundCraft `crates/dsp` at `648ed9db9a0e98cc55643babffac381521a556c8` (both MIT OR Apache-2.0). `crates/audio-dsp/NOTICE` keeps the copyright notices of both projects. ## GIMP palette reader diff --git a/crates/audio-dsp/NOTICE b/crates/audio-dsp/NOTICE index 708b38d72..69ca3746e 100644 --- a/crates/audio-dsp/NOTICE +++ b/crates/audio-dsp/NOTICE @@ -1,5 +1,5 @@ craft-audio-dsp -Copyright (c) 2026 The StudioCraft contributors. +Copyright (c) 2026 The Craft contributors. Licensed under the MIT License or the Apache License, Version 2.0, at your option (LICENSE-MIT and LICENSE-APACHE at the repository root). diff --git a/crates/audio-dsp/README.md b/crates/audio-dsp/README.md index 609fce7b3..fce5926b9 100644 --- a/crates/audio-dsp/README.md +++ b/crates/audio-dsp/README.md @@ -85,4 +85,4 @@ MIT OR Apache-2.0. Copyright (c) 2026 ArtCraft Team and the FilmCraft contributors. Copyright (c) 2026 ArtCraft Team and the SoundCraft contributors. -Copyright (c) 2026 The StudioCraft contributors. +Copyright (c) 2026 The Craft contributors. From 54dd37aa09df2d297e05f08fa95d65531131c72d Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Wed, 18 Nov 2026 07:48:41 -0800 Subject: [PATCH 32/84] audio-dsp: an infinite or huge gain designs a finite biquad Coeffs::design turned an infinite gain into infinite or NaN coefficients, so the section's output was not finite. The gain is now clamped to +/-240 dB. --- crates/audio-dsp/src/biquad.rs | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/crates/audio-dsp/src/biquad.rs b/crates/audio-dsp/src/biquad.rs index 9adbe9650..12d00f5a9 100644 --- a/crates/audio-dsp/src/biquad.rs +++ b/crates/audio-dsp/src/biquad.rs @@ -63,11 +63,12 @@ impl Coeffs { /// RBJ cookbook design. `freq` in Hz (clamped below Nyquist), `q` > 0, `gain_db` used by /// peaking and shelving types (shelves use `q` as the shelf "Q", S=1 ≙ Q=1/√2). An unusable /// rate is replaced as [`crate::sane_sample_rate`] describes. A NaN `freq` designs at 1000 Hz, - /// as [`crate::design::realize`] does, and a NaN `gain_db` designs at 0 dB. + /// as [`crate::design::realize`] does, and a NaN `gain_db` designs at 0 dB. `gain_db` is + /// clamped to ±240 dB, so an infinite or huge gain still gives finite coefficients. pub fn design(kind: FilterType, sample_rate: f64, freq: f64, q: f64, gain_db: f64) -> Coeffs { let sample_rate = f64::from(crate::sane_sample_rate(sample_rate as f32)); let freq = if freq.is_nan() { 1000.0 } else { freq }; - let gain_db = if gain_db.is_nan() { 0.0 } else { gain_db }; + let gain_db = if gain_db.is_nan() { 0.0 } else { gain_db.clamp(-240.0, 240.0) }; let f = freq.clamp(1.0, sample_rate * 0.49); let q = q.max(1e-3); let w0 = 2.0 * PI * f / sample_rate; @@ -206,6 +207,20 @@ mod tests { } } + #[test] + fn an_infinite_or_huge_gain_gives_finite_coefficients_and_output() { + for kind in [FilterType::Cut, FilterType::Peaking, FilterType::LowShelf, FilterType::HighShelf] { + for gain in [f64::INFINITY, f64::NEG_INFINITY, 1e6, -1e6, f64::MAX, f64::MIN] { + let c = Coeffs::design(kind, SR, 1000.0, 0.7, gain); + assert!([c.b0, c.b1, c.b2, c.a1, c.a2].iter().all(|v| v.is_finite()), "{kind:?} {gain}: {c:?}"); + let mut bq = Biquad::new(); + let mut x = sine(440.0, 0.5, SR, 256, 0.0); + bq.process(&c, &mut x); + assert!(x.iter().all(|v| v.is_finite()), "{kind:?} {gain}: output is not finite"); + } + } + } + #[test] fn peaking_hits_gain_at_center() { let c = Coeffs::design(FilterType::Peaking, SR, 1000.0, 1.0, 6.0); From adb01c12d8b4efc36475ae0a5551ecb5068702b3 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Wed, 18 Nov 2026 13:48:27 -0800 Subject: [PATCH 33/84] audio-dsp: finite filter designs at the limits; fix tails, thresholds and searches - Complex division scales by the divisor's larger component, so a 24-pole band-pass at 1.536 MHz keeps its gain instead of going silent. - The elliptic selectivity comes from the nomes when k1 is below 1e-6, so 0.01 dB ripple with 150 dB attenuation designs a finite filter. - Fft::new rounds a size up to a power of two between 2 and 16 M points, and a transform leaves slices shorter than the size unchanged. - A NaN delay reads the newest sample instead of NaN. - Ducking activity reads its hop and limits as their decimals: a region of exactly min_on_s is kept, a gap of exactly bridge_s is not bridged, and a one-sample hop no longer drifts over a long envelope. - WSOLA searches every offset when the coarse pass finds no match. - Sync confidence compares the peak with the RMS over every lag, so a narrow max_lag can still give a reliable result; the coarse and refinement sizes are bounded. - measure() reports the file loudness range, counting the windows of 1.5 s of silence after the program (EBU Tech 3342). - Scientific Filter clears the sections an order change drops. - The click remover repairs a click in digital silence. - Flanger Special Effects subtracts the opposite sweep. - Phaser reports the tail of its all-pass ring. --- crates/audio-dsp/src/design.rs | 101 ++++++++++++++++-- crates/audio-dsp/src/ducking.rs | 41 ++++++- .../audio-dsp/src/effects/behavior_tests.rs | 66 +++++++++++- crates/audio-dsp/src/effects/declick.rs | 8 +- crates/audio-dsp/src/effects/filters.rs | 6 ++ crates/audio-dsp/src/effects/modulation.rs | 15 ++- crates/audio-dsp/src/effects/util.rs | 9 +- crates/audio-dsp/src/fft.rs | 39 ++++++- crates/audio-dsp/src/loudness.rs | 42 +++++++- crates/audio-dsp/src/stretch.rs | 25 ++++- crates/audio-dsp/src/sync.rs | 51 ++++++--- 11 files changed, 358 insertions(+), 45 deletions(-) diff --git a/crates/audio-dsp/src/design.rs b/crates/audio-dsp/src/design.rs index eb4b166f9..2aea959ed 100644 --- a/crates/audio-dsp/src/design.rs +++ b/crates/audio-dsp/src/design.rs @@ -95,9 +95,18 @@ impl Mul for C { impl Div for C { type Output = C; + /// Smith's algorithm: the divisor is scaled by its larger component, so no intermediate + /// squares it and a divisor above about 1e154 does not overflow to infinity. fn div(self, o: C) -> C { - let d = o.re * o.re + o.im * o.im; - C::new((self.re * o.re + self.im * o.im) / d, (self.im * o.re - self.re * o.im) / d) + if o.re.abs() >= o.im.abs() { + let r = o.im / o.re; + let d = o.re + o.im * r; + C::new((self.re + self.im * r) / d, (self.im - self.re * r) / d) + } else { + let r = o.re / o.im; + let d = o.re * r + o.im; + C::new((self.re * r + self.im) / d, (self.im * r - self.re) / d) + } } } @@ -335,19 +344,58 @@ fn asne(w: C, k: f64) -> C { C::real(1.0).sub(acde(w, k)) } +/// Arithmetic-geometric mean of `a` and `b` (both ≥ 0). +fn agm(a: f64, b: f64) -> f64 { + let (mut a, mut b) = (a, b); + for _ in 0..64 { + if (a - b).abs() <= 1e-15 * a { + break; + } + (a, b) = (0.5 * (a + b), (a * b).sqrt()); + } + a +} + +/// Selectivity modulus `k` that the degree equation gives for order `n` and discrimination +/// modulus `k1` (Orfanidis, "Lecture Notes on Elliptic Filter Design", 2006, `ellipdeg`). +/// Below `k1` = 1e-6, `1 − k1²` rounds toward 1 and the product form below gives `k = 0`, so +/// `k` comes from the nomes instead: q = q1^(1/N), with q1 = exp(−π·K′(k1)/K(k1)). +fn selectivity(n: usize, k1: f64) -> f64 { + if k1 < 1e-6 { selectivity_from_nome(n, k1) } else { selectivity_from_product(n, k1) } +} + +fn selectivity_from_nome(n: usize, k1: f64) -> f64 { + let kk = PI / (2.0 * agm(1.0, (1.0 - k1 * k1).sqrt())); + let kkp = PI / (2.0 * agm(1.0, k1)); + let q = (-PI * kkp / (kk * n as f64)).exp(); + // k = 4·√q · (Σ_{m≥0} q^(m(m+1)))² / (1 + 2·Σ_{m≥1} q^(m²))² + let (mut num, mut den) = (0.0f64, 1.0f64); + for m in 0..16i32 { + num += q.powi(m * (m + 1)); + if m > 0 { + den += 2.0 * q.powi(m * m); + } + } + (4.0 * q.sqrt() * num * num / (den * den)).min(1.0) +} + +fn selectivity_from_product(n: usize, k1: f64) -> f64 { + let k1p = (1.0 - k1 * k1).sqrt(); + // Degree equation: k' = k1'^N · Π sn⁴(u_i K', k1'). + let mut kp = k1p.powi(n as i32); + for i in 1..=n / 2 { + let ui = (2 * i - 1) as f64 / n as f64; + kp *= sne(C::real(ui), k1p).re.powi(4); + } + (1.0 - kp * kp).max(0.0).sqrt() +} + fn elliptic(n: usize, rp: f64, rs: f64) -> Zpk { let ep = (10f64.powf(rp / 10.0) - 1.0).sqrt(); let es = (10f64.powf(rs / 10.0) - 1.0).sqrt(); let k1 = ep / es; - let k1p = (1.0 - k1 * k1).sqrt(); let l = n / 2; - // Degree equation: k' = k1'^N · Π sn⁴(u_i K', k1'). - let mut kp = k1p.powi(n as i32); - for i in 1..=l { - let ui = (2 * i - 1) as f64 / n as f64; - kp *= sne(C::real(ui), k1p).re.powi(4); - } - let k = (1.0 - kp * kp).max(0.0).sqrt(); + let k = selectivity(n, k1); // v0 = −j·asn(j/εp, k1) / N (normalized). let a = asne(C::new(0.0, 1.0 / ep), k1); let v0 = C::new(a.im, -a.re).scale(1.0 / n as f64); // −j·a/N @@ -759,10 +807,43 @@ mod tests { // sn(K, k) = 1; cd(0, k) = 1 assert!((sne(C::real(1.0), 0.7).re - 1.0).abs() < 1e-9); assert!((cde(C::real(0.0), 0.7).re - 1.0).abs() < 1e-9); + // A divisor whose squared components overflow still divides. + let q = C::new(3e200, 4e200).div(C::new(6e200, -8e200)); + assert!((q.re + 0.14).abs() < 1e-12 && (q.im - 0.48).abs() < 1e-12, "{q:?}"); let u = asne(C::real(0.5), 0.7); assert!((sne(u, 0.7).re - 0.5).abs() < 1e-9); } + /// At 1.536 MHz the 24-pole band-pass's bilinear denominator exceeds 1e155, whose square + /// overflowed: the gain came out 0 and the filter silent. + #[test] + fn a_high_order_band_pass_at_a_high_rate_keeps_its_gain() { + let sr = 1_536_000.0; + let s = design(&spec(Family::Butterworth, Band::BandPass, MAX_ORDER, 1000.0, 2000.0), sr); + let center = s.magnitude_db(1414.2, sr); + assert!(center.is_finite() && center.abs() < 0.5, "center {center} dB"); + assert!(s.magnitude_db(100.0, sr) < -100.0, "{}", s.magnitude_db(100.0, sr)); + } + + /// With 0.01 dB ripple and 150 dB attenuation, 1 − k1² rounds to 1; the degree equation then + /// gave a selectivity of 0 and every coefficient came out non-finite. + #[test] + fn elliptic_at_the_attenuation_limits_is_finite() { + for n in 1..=MAX_ORDER { + let s = design(&Spec { ripple_db: 0.01, stop_db: 150.0, ..spec(Family::Elliptic, Band::LowPass, n, 1000.0, 0.0) }, SR); + assert!(s.as_slice().iter().all(|c| [c.b0, c.b1, c.b2, c.a1, c.a2].iter().all(|v| v.is_finite())), "n={n}"); + let pass = s.magnitude_db(300.0, SR); + assert!(pass.is_finite() && pass > -0.02 && pass < 1e-6, "n={n}: {pass}"); + } + // The nome form agrees with the degree equation where both are accurate. + for n in [2, 5, 8, 12] { + for k1 in [1e-5, 1e-4, 1e-3] { + let (a, b) = (selectivity_from_nome(n, k1), selectivity_from_product(n, k1)); + assert!(((a - b) / b).abs() < 1e-6, "n={n} k1={k1}: {a} vs {b}"); + } + } + } + #[test] fn hostile_ripple_and_sample_rates_give_a_finite_filter() { for family in [Family::Chebyshev, Family::Elliptic] { diff --git a/crates/audio-dsp/src/ducking.rs b/crates/audio-dsp/src/ducking.rs index 263f6ab5c..02fab30f5 100644 --- a/crates/audio-dsp/src/ducking.rs +++ b/crates/audio-dsp/src/ducking.rs @@ -59,9 +59,13 @@ pub fn envelope_db(channels: &[&[f32]], sample_rate: f32, hop_s: f32, window_s: /// `bridge_s` are merged first, then regions shorter than `min_on_s` are dropped. A frame `k` /// covers `[k·hop, (k+1)·hop)`. For an envelope from [`envelope_db`], pass /// [`envelope_hop_s`] as `hop_s`. +/// +/// `hop_s`, `min_on_s` and `bridge_s` are each read as the shortest decimal that gives the same +/// `f32` (0.01 is exactly 0.01 s), and every time is a whole number of hops computed in `f64`, so +/// a duration that equals a limit compares as equal and the times do not drift over a long +/// envelope. pub fn activity(env_db: &[f32], hop_s: f32, threshold_db: f32, min_on_s: f32, bridge_s: f32) -> Vec<(f64, f64)> { - // the f32 hop rounded to whole 10 ns, so 0.01 means exactly 0.01 s - let hop = (hop_s as f64 * 1e8).round() / 1e8; + let (hop, min_on_s, bridge_s) = (decimal(hop_s), decimal(min_on_s), decimal(bridge_s)); let mut raw: Vec<(f64, f64)> = Vec::new(); let mut start: Option = None; for (k, &v) in env_db.iter().enumerate() { @@ -80,14 +84,20 @@ pub fn activity(env_db: &[f32], hop_s: f32, threshold_db: f32, min_on_s: f32, br let mut merged: Vec<(f64, f64)> = Vec::new(); for r in raw { match merged.last_mut() { - Some(last) if r.0 - last.1 < bridge_s as f64 - 1e-9 => last.1 = r.1, + Some(last) if r.0 - last.1 < bridge_s - 1e-9 => last.1 = r.1, _ => merged.push(r), } } - merged.retain(|(a, b)| b - a >= min_on_s as f64 - 1e-9); + merged.retain(|(a, b)| b - a >= min_on_s - 1e-9); merged } +/// `v` as the shortest decimal that rounds to it, in `f64` (`0.01f32` becomes `0.01`, not +/// `0.009999999776`). +fn decimal(v: f32) -> f64 { + v.to_string().parse().unwrap_or(f64::from(v)) +} + /// Ducking sensitivity (0…10) → detection threshold in dBFS: /// `−20 − 4·s` (5 → −40 dBFS; higher sensitivity reacts to quieter triggers). pub fn sensitivity_threshold_db(sensitivity: f32) -> f32 { @@ -287,6 +297,29 @@ mod tests { assert!(e.iter().skip(2).all(|v| (v - 20.0 * 0.5f32.log10()).abs() < 0.1), "{e:?}"); } + /// A region of exactly `min_on_s` is kept and a gap of exactly `bridge_s` is not bridged: both + /// limits are strict, and the f32 limits used to compare a little above their decimals. + #[test] + fn durations_equal_to_the_limits_compare_as_equal() { + let on = |frames: &[bool]| frames.iter().map(|&a| if a { 0.0 } else { FLOOR_DB }).collect::>(); + let ten = on(&[[false; 5].as_slice(), &[true; 10], &[false; 5]].concat()); + assert_eq!(activity(&ten, 0.01, -40.0, 0.1, 0.0), vec![(0.05, 0.15)]); + let gap = on(&[[true; 10].as_slice(), &[false; 20], &[true; 10]].concat()); + assert_eq!(activity(&gap, 0.01, -40.0, 0.0, 0.2), vec![(0.0, 0.1), (0.3, 0.4)]); + assert_eq!(activity(&gap, 0.01, -40.0, 0.0, 0.21), vec![(0.0, 0.4)]); + } + + /// At 44.1 kHz a one-sample hop rounded to 10 ns was 22.68 µs, so the end of a 60 s envelope + /// landed at 60.011 s. + #[test] + fn a_one_sample_hop_does_not_drift() { + let frames = 60 * 44_100; + let hop = envelope_hop_s(44_100.0, 0.0, frames); + let r = activity(&vec![0.0f32; frames], hop, -40.0, 0.0, 0.0); + assert_eq!(r.len(), 1); + assert!(r[0].0 == 0.0 && (r[0].1 - 60.0).abs() < 1e-5, "{r:?}"); + } + #[test] fn regions_stay_on_the_audio_when_the_hop_is_not_whole_samples() { // 15 ms at 44.1 kHz is 661.5 samples; the envelope steps 662. diff --git a/crates/audio-dsp/src/effects/behavior_tests.rs b/crates/audio-dsp/src/effects/behavior_tests.rs index b2f405450..dee405664 100644 --- a/crates/audio-dsp/src/effects/behavior_tests.rs +++ b/crates/audio-dsp/src/effects/behavior_tests.rs @@ -144,8 +144,10 @@ fn every_effect_is_deterministic_and_latency_is_constant() { #[test] fn latency_is_where_the_impulse_lands() { // Effects with latency: an impulse comes out exactly `latency` samples later at neutral - // settings (FFT filter / convolution / click remover / existing STFT effects). - for (id, p) in [("fft_filter", vec![]), ("convolution_reverb", vec![("mix", 0.0)]), ("click_remover", vec![("threshold", 100.0)])] { + // settings (FFT filter / convolution / existing STFT effects). The click remover repairs a + // lone impulse in silence as a click, so its latency is checked on noise by + // `neutral_settings_are_delayed_identity`. + for (id, p) in [("fft_filter", vec![]), ("convolution_reverb", vec![("mix", 0.0)])] { let mut e = fx(id, &p); let lat = e.latency(); assert!(lat > 0, "{id}"); @@ -212,6 +214,22 @@ fn scientific_filter_matches_its_design() { } } +/// Lowering the order left the dropped sections holding the earlier audio; raising it again +/// played that audio back as a burst after a second of silence. +#[test] +fn scientific_filter_order_changes_start_new_sections_clean() { + let mut e = fx("scientific_filter", &[("type", 1.0), ("order", 8.0)]); + let x = noise(21, SR as usize / 2, 0.5); + run(e.as_mut(), &x, &x); + assert!(e.set_param("order", 2.0)); + let quiet = vec![0.0f32; SR as usize]; + run(e.as_mut(), &quiet, &quiet); + assert!(e.set_param("order", 8.0)); + let (y, _) = run(e.as_mut(), &quiet, &quiet); + let peak = y.iter().fold(0.0f32, |a, v| a.max(v.abs())); + assert!(peak < 1e-6, "burst of {peak} after the order rose"); +} + #[test] fn fft_filter_applies_its_curve() { let mut e = fx("fft_filter", &[("p5_gain", -30.0), ("interp", 0.0)]); @@ -307,6 +325,33 @@ fn flanger_static_comb_notch() { assert!(tone_db(e.as_mut(), 2.0 * notch, 0.3).abs() < 0.2); } +/// Special Effects subtracts the opposite sweep: with equal sweep ends both reads match and the +/// wet signal cancels. It used to keep half of the normal sweep. +#[test] +fn flanger_special_mode_subtracts_the_opposite_sweep() { + let mut e = fx("flanger", &[("initial_delay", 2.0), ("final_delay", 2.0), ("feedback", 0.0), ("mix", 100.0), ("special", 1.0)]); + let x = noise(12, SR as usize / 4, 0.5); + let (y, _) = run(e.as_mut(), &x, &x); + let peak = y.iter().fold(0.0f32, |a, v| a.max(v.abs())); + assert!(peak < 1e-6, "{peak}"); +} + +/// The phaser reported no tail, so an offline render stopped while its all-pass chain still rang. +#[test] +fn phaser_tail_covers_its_ring() { + for (fb, upper, depth) in [(0.0, 2500.0, 70.0), (60.0, 2500.0, 70.0), (-90.0, 2500.0, 70.0), (90.0, 12000.0, 0.0)] { + let mut e = fx("phaser", &[("mix", 100.0), ("feedback", fb), ("stages", 12.0), ("upper_freq", upper), ("depth", depth)]); + let tail = e.tail_samples(); + assert!(tail > 0, "feedback {fb}"); + let mut x = vec![0.0f32; tail + 4800]; + x[0] = 1.0; + let (y, _) = run(e.as_mut(), &x, &x); + let peak = y.iter().fold(0.0f32, |a, v| a.max(v.abs())); + let after = y[tail..].iter().fold(0.0f32, |a, v| a.max(v.abs())); + assert!(after < 1e-3 * peak, "feedback {fb}: {after} after a tail of {tail} (peak {peak})"); + } +} + #[test] fn chorus_flanger_and_phaser_modulate() { for id in ["chorus_flanger", "phaser"] { @@ -670,6 +715,23 @@ fn click_remover_keeps_a_non_finite_sample_as_silence() { assert!(click < 0.1, "the click next to the NaN was left at {click}"); } +/// In digital silence the residual's median is 0, and a zero σ skipped the repair: the click +/// came out unchanged. All-zero input still comes out as exact silence. +#[test] +fn click_remover_repairs_a_click_in_silence() { + let n = SR as usize / 2; + let mut x = vec![0.0f32; n]; + x[6000] = 0.8; + let mut e = fx("click_remover", &[]); + let lat = e.latency(); + let (y, _) = run(e.as_mut(), &x, &x); + let peak = y.iter().fold(0.0f32, |a, v| a.max(v.abs())); + assert!(peak < 0.1, "the click came out at {peak} (sample {})", 6000 + lat); + let zero = vec![0.0f32; n]; + let (y, _) = run(e.as_mut(), &zero, &zero); + assert!(y.iter().all(|v| v.to_bits() == 0), "silence did not stay exact"); +} + #[test] fn channel_and_stereo_tools() { let n = 4800; diff --git a/crates/audio-dsp/src/effects/declick.rs b/crates/audio-dsp/src/effects/declick.rs index 21044b5cd..6dea450d7 100644 --- a/crates/audio-dsp/src/effects/declick.rs +++ b/crates/audio-dsp/src/effects/declick.rs @@ -142,10 +142,10 @@ impl ClickRemover { let valid = &mut s.sorted[p..]; let mid = valid.len() / 2; valid.select_nth_unstable_by(mid, |x, y| x.total_cmp(y)); - let sigma = valid[mid] / 0.6745; - if sigma <= 1e-9 { - return 0; - } + // A background the predictor matches exactly (digital silence) has a median residual of + // 0; the floor of 1e-6 (−120 dBFS) still lets a click in it stand out. An all-zero span + // never gets here: `lpc` turns it away, so it stays exact silence. + let sigma = (valid[mid] / 0.6745).max(1e-6); let thr = k * sigma; s.marks.iter_mut().for_each(|m| *m = false); let mut n = CONTEXT; diff --git a/crates/audio-dsp/src/effects/filters.rs b/crates/audio-dsp/src/effects/filters.rs index 444ec5120..a7c06f4cc 100644 --- a/crates/audio-dsp/src/effects/filters.rs +++ b/crates/audio-dsp/src/effects/filters.rs @@ -495,6 +495,12 @@ impl ScientificFilter { fn redesign(&mut self) { let (f1, f2) = (2f64.powf(self.f1.value() as f64), 2f64.powf(self.f2.value() as f64)); self.sections = design::realize(&self.proto, self.band, f1, f2, self.sr as f64); + // Sections past the cascade stop running; clear them so a later, higher order starts + // them from silence instead of from the audio they held before. + let active = self.sections.as_slice().len(); + for st in &mut self.state { + st.iter_mut().skip(active).for_each(Biquad::reset); + } self.dirty = self.f1.is_smoothing() || self.f2.is_smoothing(); } diff --git a/crates/audio-dsp/src/effects/modulation.rs b/crates/audio-dsp/src/effects/modulation.rs index b7b93e9c9..20bbe37b6 100644 --- a/crates/audio-dsp/src/effects/modulation.rs +++ b/crates/audio-dsp/src/effects/modulation.rs @@ -226,7 +226,7 @@ impl AudioEffect for Flanger { let y = line.read(d0 + (d1 - d0) * shape(p)); let wet = if special { let y2 = line.read(d0 + (d1 - d0) * shape(wrap_phase(p + 0.5))); - 0.5 * (y - y2) + 0.5 * y + 0.5 * (y - y2) } else { y }; @@ -306,6 +306,19 @@ impl Phaser { impl AudioEffect for Phaser { param_plumbing!("phaser"); + /// The all-pass ring of the lowest frequency the sweep reaches: each stage's pole has a time + /// constant τ, the cascade of `stages` poles falls 60 dB within (6.9 + 2·stages)·τ, and each + /// pass around the feedback loop repeats that ring at the feedback gain. + fn tail_samples(&self) -> usize { + let stages = ((self.pv.v("stages").round() as usize / 2) * 2).clamp(2, MAX_STAGES) as f64; + let lowest = self.pv.v("upper_freq") * 2f32.powf(-6.0 * self.pv.v("depth") / 100.0); + let pole = AllPass1::coef(lowest, self.sr).abs().min(1.0 - 1e-12); + // Each stage delays by at least one sample, also when its pole is at 0. + let tau = (-1.0 / pole.ln()).max(1.0); + let fb = (0.9 * self.pv.v("feedback").abs() / 100.0) as f64; + let repeats = if fb > 0.0 { (0.001f64.ln() / fb.ln()).ceil() + 1.0 } else { 1.0 }; + super::util::tail_samples(((6.9 + 2.0 * stages) * tau * repeats / self.sr as f64) as f32, self.sr) + } fn reset(&mut self) { self.ap.iter_mut().for_each(|a| a.iter_mut().for_each(AllPass1::reset)); self.fbs.iter_mut().for_each(|v| *v = 0.0); diff --git a/crates/audio-dsp/src/effects/util.rs b/crates/audio-dsp/src/effects/util.rs index a9e352402..eb19d70d7 100644 --- a/crates/audio-dsp/src/effects/util.rs +++ b/crates/audio-dsp/src/effects/util.rs @@ -69,11 +69,12 @@ impl DelayLine { pub(crate) fn max_delay(&self) -> f32 { (self.buf.len() - 3) as f32 } - /// Sample written `d` samples ago (`d` ≥ 0; 0 = the sample written by the last `push`). + /// Sample written `d` samples ago (`d` ≥ 0; 0 = the sample written by the last `push`). A NaN + /// delay reads as 0. #[inline] pub(crate) fn read(&self, d: f32) -> f32 { let len = self.buf.len(); - let d = d.clamp(0.0, self.max_delay()); + let d = if d.is_nan() { 0.0 } else { d.clamp(0.0, self.max_delay()) }; let di = d.floor(); let frac = d - di; // `w < len` and `di <= len - 3`, so one conditional subtract wraps the index. @@ -279,7 +280,7 @@ mod tests { fn delay_read_matches_modulo_indexing() { let reference = |line: &DelayLine, d: f32| { let len = line.buf.len(); - let d = d.clamp(0.0, line.max_delay()); + let d = if d.is_nan() { 0.0 } else { d.clamp(0.0, line.max_delay()) }; let di = d.floor(); let frac = d - di; let i0 = (line.w + len - 1 - di as usize) % len; @@ -293,6 +294,8 @@ mod tests { for d in (-8..=4 * max as i32 + 12).map(|i| i as f32 * 0.25).chain([f32::NAN, f32::INFINITY, -f32::INFINITY, 1e30]) { assert_eq!(line.read(d).to_bits(), reference(&line, d).to_bits(), "max {max} w {} d {d}", line.w); } + // A NaN delay reads the newest sample, not NaN. + assert_eq!(line.read(f32::NAN).to_bits(), line.tap(0).to_bits(), "max {max} w {}", line.w); } } } diff --git a/crates/audio-dsp/src/fft.rs b/crates/audio-dsp/src/fft.rs index c530bc01b..9f2447c11 100644 --- a/crates/audio-dsp/src/fft.rs +++ b/crates/audio-dsp/src/fft.rs @@ -19,9 +19,10 @@ pub struct Fft { } impl Fft { - /// Plan an FFT of size `n` (must be a power of two ≥ 2). + /// Plan an FFT of size `n`. A size that is not a power of two is rounded up to the next one, + /// and the size is kept between 2 and [`Fft::MAX_SIZE`]. pub fn new(n: usize) -> Fft { - assert!(n >= 2 && n.is_power_of_two(), "FFT size must be a power of two"); + let n = n.clamp(2, Self::MAX_SIZE).next_power_of_two(); let bits = n.trailing_zeros(); let rev = (0..n as u32).map(|i| i.reverse_bits() >> (32 - bits)).collect(); let (mut tw_re, mut tw_im) = (Vec::with_capacity(n - 1), Vec::with_capacity(n - 1)); @@ -39,19 +40,32 @@ impl Fft { Fft { n, tw_re, tw_im, tw_im_inv, rev } } - /// Forward transform (e^{-iωt}), unscaled. + /// Largest size [`Fft::new`] plans (16 M points; the plan then holds 256 MiB). + pub const MAX_SIZE: usize = 1 << 24; + + /// The transform size. + #[cfg(test)] + pub fn size(&self) -> usize { + self.n + } + + /// Forward transform (e^{-iωt}), unscaled, of the first `size` values of `re` and `im`. When + /// either slice is shorter than the size, both are left unchanged. pub fn forward(&self, re: &mut [f32], im: &mut [f32]) { self.run(re, im, false); } - /// Inverse transform (e^{+iωt}), unscaled (divide by `n` yourself). + /// Inverse transform (e^{+iωt}), unscaled (divide by the size yourself). When either slice + /// is shorter than the size, both are left unchanged. pub fn inverse(&self, re: &mut [f32], im: &mut [f32]) { self.run(re, im, true); } fn run(&self, re: &mut [f32], im: &mut [f32], inverse: bool) { let n = self.n; - assert!(re.len() >= n && im.len() >= n); + if re.len() < n || im.len() < n { + return; + } let (re, im) = (&mut re[..n], &mut im[..n]); for i in 0..n { let j = self.rev[i] as usize; @@ -122,6 +136,21 @@ mod tests { } } + /// A size that is not a power of two, or below 2, is rounded up; short slices are left + /// unchanged. Both used to panic. + #[test] + fn odd_sizes_and_short_slices_do_not_panic() { + assert_eq!(Fft::new(0).size(), 2); + assert_eq!(Fft::new(1).size(), 2); + assert_eq!(Fft::new(48).size(), 64); + assert_eq!(Fft::new(64).size(), 64); + let fft = Fft::new(8); + let (mut re, mut im) = (vec![1.0f32; 4], vec![0.0f32; 8]); + fft.forward(&mut re, &mut im); + fft.inverse(&mut re, &mut im); + assert_eq!((re, im), (vec![1.0f32; 4], vec![0.0f32; 8])); + } + /// The previous kernel (strided reads from one n/2-entry twiddle table), kept as reference. fn run_reference(n: usize, re: &mut [f32], im: &mut [f32], inverse: bool) { let rev: Vec = (0..n as u32).map(|i| i.reverse_bits() >> (32 - n.trailing_zeros())).collect(); diff --git a/crates/audio-dsp/src/loudness.rs b/crates/audio-dsp/src/loudness.rs index d8de87a15..aedc8f3a5 100644 --- a/crates/audio-dsp/src/loudness.rs +++ b/crates/audio-dsp/src/loudness.rs @@ -492,6 +492,23 @@ impl LoudnessMeter { } } + /// Loudness range of the program as a file measurement: the short-term windows of 1.5 s of + /// silence after the audio fed so far are counted too, as EBU Tech 3342 asks for file-based + /// measurement, so a program of only a few seconds gets more than one window. The meter + /// itself is unchanged: [`LoudnessMeter::loudness_range`] and audio fed afterwards do not see + /// the silence. + pub fn file_loudness_range(&self) -> f64 { + let mut tail = self.clone(); + let silence = vec![0.0f32; self.sub_len]; + let mut left = (self.sub_len - self.sub_pos) + 15 * self.sub_len; + while left > 0 { + let take = left.min(self.sub_len); + tail.process(&[&silence[..take]]); + left -= take; + } + tail.loudness_range() + } + /// Snapshot of all program measurements. pub fn summary(&self) -> LoudnessSummary { LoudnessSummary { @@ -516,12 +533,13 @@ pub struct LoudnessSummary { pub true_peak_dbtp: f64, } -/// Measure a whole planar program in one call. +/// Measure a whole planar program in one call. The loudness range is the file measurement of +/// [`LoudnessMeter::file_loudness_range`]. pub fn measure(channels: &[&[f32]], sample_rate: f64) -> LoudnessSummary { let mut m = LoudnessMeter::new(sample_rate, channels.len()); m.process(channels); m.end_program(); - m.summary() + LoudnessSummary { loudness_range_lu: m.file_loudness_range(), ..m.summary() } } /// Gain (dB) that moves a program measured at `measured_lufs` to `target_lufs`. @@ -679,6 +697,26 @@ mod tests { } } + /// A 3 s program gives one short-term window, so its loudness range read 0 however much the + /// level changed. The file measurement counts the windows of 1.5 s of silence after it. + #[test] + fn a_short_program_has_a_file_loudness_range() { + let sr = 48000.0; + let x = segments(1000.0, sr, &[(1.5, -20.0), (1.5, -30.0)]); + let s = measure(&[&x, &x], sr); + assert!(s.loudness_range_lu > 1.0, "LRA {}", s.loudness_range_lu); + // The live reading and later audio do not see the silence. + let mut m = LoudnessMeter::new(sr, 2); + m.process(&[&x, &x]); + let before = m.loudness_range(); + assert_eq!(before, 0.0); + assert!((m.file_loudness_range() - s.loudness_range_lu).abs() < 1e-12); + assert_eq!(m.loudness_range(), before); + // A steady program keeps a file range near 0. + let y = segments(1000.0, sr, &[(30.0, -20.0)]); + assert!(measure(&[&y, &y], sr).loudness_range_lu < 1.0); + } + #[test] fn log_sweep_matches_analytic_k_weighting() { let sr = 48000.0; diff --git a/crates/audio-dsp/src/stretch.rs b/crates/audio-dsp/src/stretch.rs index 7e8c2ace9..82ee5e40a 100644 --- a/crates/audio-dsp/src/stretch.rs +++ b/crates/audio-dsp/src/stretch.rs @@ -93,7 +93,19 @@ impl Wsola { } d += 2; } - let Some((coarse, _)) = best else { return nominal }; + let Some((coarse, coarse_score)) = best else { return nominal }; + if coarse_score <= 0.0 { + // The coarse pass found no match (for example, the template's energy sits on odd + // samples only, which it skips): search every offset at full resolution instead. + let mut full = None; + for d in 0..=tol { + consider(d, 1, &mut full); + if d > 0 { + consider(-d, 1, &mut full); + } + } + return nominal.saturating_add(full.map_or(coarse, |(d, _)| d)); + } let mut fine = None; for d in [coarse, coarse - 1, coarse + 1] { if d.abs() <= tol { @@ -196,6 +208,17 @@ mod tests { } } + /// The template's only nonzero sample is at an odd index, so every coarse score was 0 and the + /// search kept the nominal position next to an exact match 101 samples away. + #[test] + fn a_match_the_coarse_pass_skips_is_still_found() { + let w = Wsola::new(48_000); + let mut guide = vec![0.0f32; 4_000]; + guide[359] = 1.0; + guide[2_460] = 1.0; + assert_eq!(w.align(&guide, 0, 2_000), 2_101); + } + #[test] fn silence_and_out_of_range_positions_keep_the_nominal_position() { let w = Wsola::new(48_000); diff --git a/crates/audio-dsp/src/sync.rs b/crates/audio-dsp/src/sync.rs index 52e6407b1..56416ef87 100644 --- a/crates/audio-dsp/src/sync.rs +++ b/crates/audio-dsp/src/sync.rs @@ -30,17 +30,24 @@ pub struct SyncOptions { pub max_lag: Option, /// Upper bound of the coarse search's sample rate (Hz). pub coarse_rate: u32, - /// Most samples (both signals together) the coarse transform may hold, at least 4,096; longer - /// recordings are decimated further, by at most [`MAX_DECIMATION`]. The coarse signals - /// therefore hold the larger of this and 1/4,096 of the input, and the transform is the next - /// power of two above that. + /// Most samples (both signals together) the coarse transform may hold, from 4,096 to + /// [`MAX_COARSE_SAMPLES`]; longer recordings are decimated further, by at most + /// [`MAX_DECIMATION`]. The coarse signals therefore hold the larger of this and 1/4,096 of the + /// input, and the transform is the next power of two above that. When that transform would + /// exceed the FFT's largest size, [`find_offset`] returns `None`. pub max_coarse_samples: usize, /// PHAT weighting exponent (1 = full whitening, 0 = plain cross-correlation). pub phat_beta: f32, - /// Length of the full-rate refinement window (samples). + /// Length of the full-rate refinement window (samples), from 256 to [`MAX_REFINE_WINDOW`]. pub refine_window: usize, } +/// Largest [`SyncOptions::max_coarse_samples`]; a larger value counts as this (8 M samples). +pub const MAX_COARSE_SAMPLES: usize = 1 << 23; + +/// Largest [`SyncOptions::refine_window`]; a larger value counts as this (4 M samples). +pub const MAX_REFINE_WINDOW: usize = 1 << 22; + impl Default for SyncOptions { fn default() -> Self { Self { max_lag: None, coarse_rate: 8000, max_coarse_samples: 1 << 22, phat_beta: 0.75, refine_window: 1 << 17 } @@ -221,13 +228,16 @@ pub fn find_offset(a: &[f32], b: &[f32], sample_rate: u32, opts: &SyncOptions) - // ---- coarse // The factor `decimate` really applies to both signals, so the coarse lag scales back exactly. let d = (sr.div_ceil(opts.coarse_rate.max(500) as usize)) - .max((a.len() + b.len()).div_ceil(opts.max_coarse_samples.max(1 << 12))) + .max((a.len() + b.len()).div_ceil(opts.max_coarse_samples.clamp(1 << 12, MAX_COARSE_SAMPLES))) .min(MAX_DECIMATION) .min(a.len().min(b.len())) .max(1); let (ca, cb) = (normalized_decimate(a, d), normalized_decimate(b, d)); let (la, lb) = (ca.len() as i64, cb.len() as i64); let n = ((la + lb) as usize).next_power_of_two(); + if n > Fft::MAX_SIZE { + return None; + } let rate_c = sr as f32 / d as f32; let band = ((40.0 / rate_c).min(0.05), if d > 1 { 0.40 } else { 0.5 }); let r = gcc(&ca, &cb, n, opts.phat_beta, band); @@ -239,24 +249,27 @@ pub fn find_offset(a: &[f32], b: &[f32], sample_rate: u32, opts: &SyncOptions) - if hi < lo { return None; } + // The peak is taken within `max_lag`; the RMS it is compared with covers every lag with enough + // overlap, so a narrow limit does not cap the confidence at √(lags in the limit). let mut best = (0i64, 0.0f32); let mut sum2 = 0.0f64; - let mut count = 0usize; + let mut inside = 0usize; for l in lo..=hi { + let v = corr_at(&r, l); + sum2 += (v as f64) * (v as f64); if max_lag_c.is_some_and(|m| l.abs() > m) { continue; } - let v = corr_at(&r, l); - sum2 += (v as f64) * (v as f64); - count += 1; + inside += 1; if v.abs() > best.1.abs() { best = (l, v); } } - if count == 0 || best.1 == 0.0 { + if inside == 0 || best.1 == 0.0 { return None; } - let rms = (sum2 / count as f64).sqrt().max(1e-30) as f32; + let count = (hi - lo + 1) as f64; + let rms = (sum2 / count).sqrt().max(1e-30) as f32; let confidence = best.1.abs() / rms; let guard = ((rate_c * 0.05) as i64).max(2); let mut second = 0.0f32; @@ -277,7 +290,7 @@ pub fn find_offset(a: &[f32], b: &[f32], sample_rate: u32, opts: &SyncOptions) - if ov1 - ov0 < 16 { return Some(SyncResult { lag: coarse, lag_fine: coarse as f64, confidence, distinct, inverted }); } - let w = ((ov1 - ov0) as usize).min(opts.refine_window.max(256)) as i64; + let w = ((ov1 - ov0) as usize).min(opts.refine_window.clamp(256, MAX_REFINE_WINDOW)) as i64; // the window of b with the most energy (both sides: a lag-shifted) let start = { let hop = (w / 4).max(1); @@ -561,6 +574,18 @@ mod tests { } } + /// With a 100-sample limit at 48 kHz only 35 coarse lags lie inside it; the confidence was + /// their peak over their own RMS, at most √35 ≈ 5.9, so even identical recordings were never + /// `reliable()`. + #[test] + fn a_narrow_lag_limit_can_still_be_reliable() { + let sr = 48_000; + let s = speechy(sr as f64, 10.0, 5); + let r = find_offset(&s, &s, sr, &SyncOptions { max_lag: Some(100), ..Default::default() }).unwrap(); + assert_eq!(r.lag, 0); + assert!(r.reliable(), "{r:?}"); + } + /// A coarse budget that asks for more than [`MAX_DECIMATION`] still scales the coarse lag by /// the factor applied: 2 × 9 M samples at 8 kHz with a 4,096-sample budget asks for 4,395. #[test] From da4c3caba5fe90f978bfbb656218ee2cd2d6f566 Mon Sep 17 00:00:00 2001 From: Rees Date: Thu, 19 Nov 2026 09:01:42 +0100 Subject: [PATCH 34/84] craft-html: keep zero row spans in their row group --- crates/html/src/doc/builder.rs | 64 +++++++++++++++++++++++++++++----- crates/html/src/doc/tests.rs | 21 +++++++++++ 2 files changed, 77 insertions(+), 8 deletions(-) diff --git a/crates/html/src/doc/builder.rs b/crates/html/src/doc/builder.rs index 022a51015..dce6a5957 100644 --- a/crates/html/src/doc/builder.rs +++ b/crates/html/src/doc/builder.rs @@ -53,6 +53,7 @@ struct El { struct TableB { rows: Vec>, row: Option>, + group_start: usize, /// The table or one of its cells asks for borders. bordered: bool, /// Explicit column widths from `` and childless ``. @@ -62,6 +63,26 @@ struct TableB { } impl TableB { + fn finish_row_group(&mut self) { + if let Some(row) = self.row.take() { + self.rows.push(row); + } + let end = self.rows.len().min(craft_wordmodel::table::MAX_ROWS); + if let Some(rows) = self.rows.get_mut(self.group_start..end) { + let mut remaining = 0u32; + for row in rows.iter_mut().rev() { + if !row.is_empty() { + remaining += 1; + } + // Resolve zero spans before expanding the table's covered cells. + for cell in row.iter_mut().filter(|cell| cell.rowspan == 0) { + cell.rowspan = remaining.clamp(1, 1000); + } + } + } + self.group_start = end; + } + /// Commit pending colgroup widths: if childless, push span columns with group width. /// When child `` elements are present, they have already received the group width /// during `` handling; columns from earlier groups are never backfilled. @@ -219,6 +240,10 @@ pub(super) fn block_kind(n: &str) -> Option { } /// Closes an open `p` (HTML's "close a p element" on block starts). +fn is_row_group(name: &str) -> bool { + matches!(name, "thead" | "tbody" | "tfoot") +} + fn closes_p(n: &str) -> bool { matches!( n, @@ -921,9 +946,7 @@ impl<'r> Builder<'r> { ElKind::Table => { if let Some(mut t) = self.tables.pop() { t.commit_pending_colgroup(); - if let Some(r) = t.row.take() { - t.rows.push(r); - } + t.finish_row_group(); let borderless = !t.bordered; // Keep at most MAX_ROWS rows (the model drops the rest anyway): bounds the // O(rows × rowspan) work of `insert_covered` on a table of millions of ``. @@ -1014,6 +1037,24 @@ impl<'r> Builder<'r> { false } + fn finish_row_group(&mut self) { + let Some(table) = self.stack.iter().rposition(|element| element.name == "table") else { return }; + let owns_rows = self.stack.get(table).is_some_and(|element| element.kind == ElKind::Table); + if let Some((index, _)) = self + .stack + .iter() + .enumerate() + .skip(table + 1) + .find(|(_, element)| is_row_group(&element.name) || matches!(element.name.as_str(), "tr" | "td" | "th")) + { + self.pop_to(index); + } + // A table flattened at the nesting limit does not own the containing table's rows. + if owns_rows && let Some(table) = self.tables.last_mut() { + table.finish_row_group(); + } + } + fn close_implicitly(&mut self, name: &str, is_table_part: bool) { if closes_p(name) && let Some(k) = self.find_open(|e| e.name == "p", |e| matches!(e.kind, ElKind::Cell | ElKind::Table | ElKind::Li | ElKind::Quote)) @@ -1035,10 +1076,8 @@ impl<'r> Builder<'r> { { self.pop_to(k); } - if matches!(name, "tbody" | "thead" | "tfoot") - && let Some(k) = self.find_open(|e| matches!(e.name.as_str(), "tbody" | "thead" | "tfoot"), |e| e.kind == ElKind::Table) - { - self.pop_to(k); + if is_row_group(name) || matches!(name, "caption" | "colgroup" | "col") { + self.finish_row_group(); } if is_table_part && !self.tables.is_empty() { if matches!(name, "td" | "th") @@ -1260,6 +1299,7 @@ impl<'r> Builder<'r> { ElKind::Table => self.tables.push(TableB { rows: Vec::new(), row: None, + group_start: 0, bordered: declares_border(attrs, &css, true), col_widths: Vec::new(), pending_colgroup: None, @@ -1321,7 +1361,7 @@ impl<'r> Builder<'r> { let mso_vmerge = decls(&css).filter(|(k, _)| k == "mso-yfti-vmerge").last().map(|(_, v)| v.trim().to_ascii_lowercase()); let is_mso_vmerge_continue = mso_vmerge.as_deref() == Some("continue"); let is_mso_vmerge_restart = mso_vmerge.as_deref() == Some("restart"); - let rowspan = attr(attrs, "rowspan").and_then(|v| v.trim().parse::().ok()).map(|v| v.clamp(1, 1000)).unwrap_or(1); + let rowspan = attr(attrs, "rowspan").and_then(|v| v.trim().parse::().ok()).map(|v| v.min(1000)).unwrap_or(1); self.cells.push(Cell { blocks: Vec::new(), colspan, @@ -1375,6 +1415,14 @@ impl<'r> Builder<'r> { } return; } + if is_row_group(name) { + let open = self.find_open(|element| is_row_group(&element.name), |element| element.name == "table"); + // Without an explicit group, a row-group end tag ends the implicit group. + if open.is_none_or(|index| self.stack.get(index).is_some_and(|element| element.name == name)) { + self.finish_row_group(); + } + return; + } let crosses = matches!(name, "table"); let target = if matches!(name, "td" | "th") { self.find_open(|e| e.kind == ElKind::Cell, |e| e.kind == ElKind::Table) diff --git a/crates/html/src/doc/tests.rs b/crates/html/src/doc/tests.rs index 2c355a47c..7587e5891 100644 --- a/crates/html/src/doc/tests.rs +++ b/crates/html/src/doc/tests.rs @@ -2049,3 +2049,24 @@ fn zero_alpha_colors_with_none_channels() { let craft_wordmodel::Block::Para(p2) = &*doc2.body[0] else { panic!("expected Para") }; assert_eq!(p2.props.shading, None); } + +#[test] +fn zero_rowspan_stops_at_the_row_group_boundary() { + for boundary in ["", "", "", "Heading", "", ""] { + let html = format!("
AB
C{boundary}
DE
"); + let flow = parse(&html); + let table = flow + .blocks + .iter() + .find_map(|block| match block { + FBlock::Table(table) => Some(table), + _ => None, + }) + .unwrap(); + assert_eq!(table.rows.len(), 3, "{boundary}: expected three rows"); + assert_eq!(table.rows[0][0].rowspan, 2, "{boundary}: A spans the first two rows"); + assert!(table.rows[1][0].covered, "{boundary}: row two continues A"); + assert!(!table.rows[2][0].covered, "{boundary}: the next group starts at column one"); + assert_eq!(table.rows[2].len(), 2, "{boundary}: D and E retain their columns"); + } +} From a2df846270bd727b87c6e874c48c4fff3f27fec2 Mon Sep 17 00:00:00 2001 From: Rees Date: Thu, 19 Nov 2026 09:09:49 +0100 Subject: [PATCH 35/84] craft-docx: preserve bounded hyperlink ScreenTips --- crates/docx/src/lib.rs | 6 ++ crates/docx/src/read/story.rs | 1 + crates/docx/src/read/story/runs.rs | 16 +++-- crates/docx/src/write/story/para.rs | 30 ++++++--- crates/docx/tests/it/roundtrip.rs | 1 + crates/docx/tests/screentips.rs | 80 ++++++++++++++++++++++++ crates/wordmodel/src/props/char_props.rs | 21 ++++++- 7 files changed, 138 insertions(+), 17 deletions(-) create mode 100644 crates/docx/tests/screentips.rs diff --git a/crates/docx/src/lib.rs b/crates/docx/src/lib.rs index 68d41ab4d..bb04a9f4b 100644 --- a/crates/docx/src/lib.rs +++ b/crates/docx/src/lib.rs @@ -165,6 +165,12 @@ impl Flavor { } } +/// Bound the tooltip at both file boundaries. A whole link can have many formatted runs. +fn bounded_link_tooltip(text: &str) -> Option<&str> { + const MAX_BYTES: usize = 4096; + text.get(..text.floor_char_boundary(MAX_BYTES)).filter(|tip| !tip.is_empty()) +} + /// Errors from reading or writing a DOCX package. #[derive(Debug, thiserror::Error, Clone, PartialEq)] pub enum DocxError { diff --git a/crates/docx/src/read/story.rs b/crates/docx/src/read/story.rs index 86ceb1651..9b5b04300 100644 --- a/crates/docx/src/read/story.rs +++ b/crates/docx/src/read/story.rs @@ -48,6 +48,7 @@ const MAX_FORM: usize = 64 * 1024; #[derive(Clone, Default)] pub struct RunCtx { link: Option, + link_tooltip: Option>, ins: Option, del: Option, } diff --git a/crates/docx/src/read/story/runs.rs b/crates/docx/src/read/story/runs.rs index 46cf274d9..0c8b69994 100644 --- a/crates/docx/src/read/story/runs.rs +++ b/crates/docx/src/read/story/runs.rs @@ -23,12 +23,16 @@ impl Reader<'_> { let mut c = ctx.clone(); let url = k.attr("r:id").and_then(|id| rels.by_id(id)).map(|r| r.target.trim().to_string()).filter(|u| !u.is_empty()); let anchor = k.attr("w:anchor").filter(|a| !a.is_empty()); - c.link = match (url, anchor) { + let link = match (url, anchor) { (Some(u), Some(a)) => Some(format!("{u}#{a}")), (Some(u), None) => Some(u), (None, Some(a)) => Some(format!("#{a}")), - (None, None) => ctx.link.clone(), + (None, None) => None, }; + if let Some(link) = link { + c.link = Some(link); + c.link_tooltip = k.attr("w:tooltip").and_then(crate::bounded_link_tooltip).map(std::sync::Arc::from); + } self.read_inline_children(sc, pb, k, rels, &c, depth + 1); } "w:ins" | "w:moveTo" => { @@ -133,6 +137,7 @@ impl Reader<'_> { fn run_props(&mut self, rpr: &El, ctx: &RunCtx) -> CharProps { let mut p = self.pc.rpr(rpr); p.link = ctx.link.clone(); + p.link_tooltip = ctx.link_tooltip.clone(); p.ins = ctx.ins; p.del = ctx.del; p.fmt_change = self.rpr_change(rpr); @@ -140,7 +145,7 @@ impl Reader<'_> { } fn run_props_none(&self, ctx: &RunCtx) -> CharProps { - CharProps { link: ctx.link.clone(), ins: ctx.ins, del: ctx.del, ..Default::default() } + CharProps { link: ctx.link.clone(), link_tooltip: ctx.link_tooltip.clone(), ins: ctx.ins, del: ctx.del, ..Default::default() } } fn read_run(&mut self, sc: &mut StoryCtx, pb: &mut PB, r: &El, rels: &Rels, ctx: &RunCtx, depth: usize) { @@ -395,7 +400,10 @@ impl Reader<'_> { /// [`Self::emit_obj`] for a drawing that carries its own `link`: a link around the run wins. fn emit_linked_obj(&mut self, sc: &mut StoryCtx, pb: &mut PB, o: InlineObject, props: &CharProps, link: Option) { match link.filter(|_| props.link.is_none()) { - Some(link) => self.emit_obj(sc, pb, o, &CharProps { link: Some(link), ..props.clone() }), + Some(link) => { + let link_tooltip = if props.link.as_deref() == Some(link.as_str()) { props.link_tooltip.clone() } else { None }; + self.emit_obj(sc, pb, o, &CharProps { link: Some(link), link_tooltip, ..props.clone() }); + } None => self.emit_obj(sc, pb, o, props), } } diff --git a/crates/docx/src/write/story/para.rs b/crates/docx/src/write/story/para.rs index aa973184e..babed9de5 100644 --- a/crates/docx/src/write/story/para.rs +++ b/crates/docx/src/write/story/para.rs @@ -192,7 +192,7 @@ impl Writer<'_> { } } - let mut open_link: Option = None; + let mut open_link = None; let mut i = 0; while i < pieces.len() { let Some((piece, props)) = pieces.get(i) else { break }; @@ -213,21 +213,31 @@ impl Writer<'_> { i += 1; continue; } - // Hyperlink grouping. - if props.link != open_link { + // Hyperlinks with different ScreenTips stay separate even if their target is shared. + let link = props + .link + .as_deref() + .filter(|target| !target.is_empty()) + .map(|target| (target, props.link_tooltip.as_deref().and_then(crate::bounded_link_tooltip))); + if link != open_link { if open_link.is_some() { w.close("w:hyperlink"); } - open_link = None; - if let Some(l) = props.link.as_deref().filter(|l| !l.is_empty()) { - if let Some(anchor) = l.strip_prefix('#') { - w.open("w:hyperlink", &[("w:anchor", anchor), ("w:history", "1")]); + if let Some((link, tip)) = link { + let id; + let target = if let Some(anchor) = link.strip_prefix('#') { + ("w:anchor", anchor) } else { - let id = rels.add(rt::HYPERLINK, l, true); - w.open("w:hyperlink", &[("r:id", &id), ("w:history", "1")]); + id = rels.add(rt::HYPERLINK, link, true); + ("r:id", id.as_str()) + }; + if let Some(tip) = tip { + w.open("w:hyperlink", &[target, ("w:history", "1"), ("w:tooltip", tip)]); + } else { + w.open("w:hyperlink", &[target, ("w:history", "1")]); } - open_link = Some(l.to_string()); } + open_link = link; } match piece { Piece::Obj(o, _) => { diff --git a/crates/docx/tests/it/roundtrip.rs b/crates/docx/tests/it/roundtrip.rs index 758538e90..4927cd09c 100644 --- a/crates/docx/tests/it/roundtrip.rs +++ b/crates/docx/tests/it/roundtrip.rs @@ -142,6 +142,7 @@ fn every_char_prop_round_trips() { vert_compress: Some(true), }), link: None, + link_tooltip: None, ins: None, del: None, fmt_change: None, diff --git a/crates/docx/tests/screentips.rs b/crates/docx/tests/screentips.rs new file mode 100644 index 000000000..5f939b1a3 --- /dev/null +++ b/crates/docx/tests/screentips.rs @@ -0,0 +1,80 @@ +//! Original OOXML fixtures. ScreenTips are hyperlink data, not run formatting. +use std::io::{Read, Write}; + +use craft_wordmodel::{CharProps, Pos}; + +fn package() -> Vec { + let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new())); + for (name, xml) in [ + ( + "word/document.xml", + r#"Before. FirstSecondInternalTarget."#, + ), + ( + "_rels/.rels", + r#""#, + ), + ( + "word/_rels/document.xml.rels", + r#""#, + ), + ] { + zip.start_file(name, zip::write::SimpleFileOptions::default()).unwrap(); + zip.write_all(xml.as_bytes()).unwrap(); + } + zip.finish().unwrap().into_inner() +} + +#[test] +fn hyperlink_screentips_survive_edited_saves_without_merging_different_hints() { + let mut doc = craft_docx::read(&package()).unwrap(); + for _ in 0..2 { + doc.insert_text(&Pos::body(0, 0), "Edit. ", &CharProps::default()).unwrap(); + let bytes = craft_docx::write(&doc).unwrap(); + let mut xml = String::new(); + zip::ZipArchive::new(std::io::Cursor::new(&bytes)).unwrap().by_name("word/document.xml").unwrap().read_to_string(&mut xml).unwrap(); + assert_eq!(xml.matches("w:tooltip=").count(), 3, "{xml}"); + for tip in ["Original café & "Ω"", "Different hint", "Internal hint"] { + assert!(xml.contains(&format!("w:tooltip=\"{tip}\"")), "{xml}"); + } + assert!(xml.contains("w:anchor=\"target\"")); + doc = craft_docx::read(&bytes).unwrap(); + let paragraph = doc.body[0].as_para().unwrap(); + for (text, tip) in [("First", "Original café & \"Ω\""), ("Second", "Different hint"), ("Internal", "Internal hint")] { + let offset = paragraph.text.find(text).unwrap(); + assert_eq!(paragraph.props_of_char(offset).link_tooltip.as_deref(), Some(tip), "{text}"); + } + assert!(doc.body[0].as_para().unwrap().plain_text().ends_with("FirstSecondInternal")); + } +} + +#[test] +fn oversized_screentips_share_one_utf8_bounded_value_and_save_at_the_same_size() { + use std::sync::Arc; + + let kept = "a".repeat(4095); + let tip = format!("{kept}Ω trailing text"); + let runs: String = (0..32).map(|i| format!("word ", i % 2)).collect(); + let xml = format!( + r##"{runs}"## + ); + let mut zip = zip::ZipWriter::new(std::io::Cursor::new(Vec::new())); + zip.start_file("word/document.xml", zip::write::SimpleFileOptions::default()).unwrap(); + zip.write_all(xml.as_bytes()).unwrap(); + let mut doc = craft_docx::read(&zip.finish().unwrap().into_inner()).unwrap(); + let p = doc.body[0].as_para().unwrap(); + assert_eq!(p.runs.len(), 32); + let first = p.runs[0].props.link_tooltip.as_ref().unwrap(); + assert_eq!(first.as_ref(), kept); + assert!(p.runs.iter().all(|run| Arc::ptr_eq(first, run.props.link_tooltip.as_ref().unwrap()))); + + // Native model data can arrive without going through the XML reader. + let props = CharProps { link: Some("#target".into()), link_tooltip: Some(Arc::from(tip)), ..CharProps::default() }; + doc.insert_text(&Pos::body(0, 0), "Native ", &props).unwrap(); + let saved = craft_docx::write(&doc).unwrap(); + let mut xml = String::new(); + zip::ZipArchive::new(std::io::Cursor::new(&saved)).unwrap().by_name("word/document.xml").unwrap().read_to_string(&mut xml).unwrap(); + assert_eq!(xml.matches("w:tooltip=").count(), 1); + assert!(xml.contains(&format!("w:tooltip=\"{kept}\""))); + assert!(!xml.contains("trailing text")); +} diff --git a/crates/wordmodel/src/props/char_props.rs b/crates/wordmodel/src/props/char_props.rs index a5111dcc6..556d03540 100644 --- a/crates/wordmodel/src/props/char_props.rs +++ b/crates/wordmodel/src/props/char_props.rs @@ -1,3 +1,5 @@ +use std::sync::Arc; + use super::color::{Rgb, TextColor}; use super::para_props::Border; use super::{Deserialize, Serialize}; @@ -430,6 +432,9 @@ pub struct CharProps { /// Hyperlink target: a URL, or `#bookmark` for an internal link. #[serde(skip_serializing_if = "Option::is_none")] pub link: Option, + /// Optional ScreenTip for the hyperlink. Runs from one link can share its text. + #[serde(skip_serializing_if = "Option::is_none")] + pub link_tooltip: Option>, /// Tracked insertion: index into `Document::revisions`. #[serde(skip_serializing_if = "Option::is_none")] pub ins: Option, @@ -566,6 +571,7 @@ impl CharProps { if c.link.take().is_some() && c.style.as_deref() == Some("Hyperlink") { c.style = None; } + c.link_tooltip = None; c } @@ -626,7 +632,11 @@ impl CharProps { } fn minus_document_marks(&mut self, base: &CharProps) { - drop_same_fields!(self, base; link, ins, del, ligatures); + if self.link == base.link && self.link_tooltip == base.link_tooltip { + self.link = None; + self.link_tooltip = None; + } + drop_same_fields!(self, base; ins, del, ligatures); } /// Apply every `Some` field of `patch` on top of `self`. @@ -676,7 +686,11 @@ impl CharProps { } fn overlay_document_marks(&mut self, patch: &CharProps) { - overlay_fields!(self, patch; link, ins, del, fmt_change, ligatures); + if let Some(link) = &patch.link { + self.link = Some(link.clone()); + self.link_tooltip = patch.link_tooltip.clone(); + } + overlay_fields!(self, patch; ins, del, fmt_change, ligatures); } pub fn overlaid(mut self, patch: &CharProps) -> CharProps { self.overlay(patch); @@ -701,6 +715,7 @@ impl CharProps { pub fn cleared(&self) -> CharProps { CharProps { link: self.link.clone(), + link_tooltip: self.link_tooltip.clone(), ins: self.ins, del: self.del, fmt_change: self.fmt_change.clone(), @@ -711,6 +726,6 @@ impl CharProps { } /// Just the formatting: without the link, revision marks and tracked formatting change. pub fn formatting(&self) -> CharProps { - CharProps { link: None, ins: None, del: None, fmt_change: None, ..self.clone() } + CharProps { link: None, link_tooltip: None, ins: None, del: None, fmt_change: None, ..self.clone() } } } From 12482f8671d97dc80c2386c9eff640bcbec2991e Mon Sep 17 00:00:00 2001 From: Rees Date: Thu, 19 Nov 2026 09:11:04 +0100 Subject: [PATCH 36/84] craft-rtf: preserve document properties across nested groups --- crates/rtf/src/doc/parse.rs | 6 --- crates/rtf/src/doc/reader.rs | 5 +- crates/rtf/src/doc/state.rs | 2 + crates/rtf/src/doc/tests.rs | 26 ++++++++++ crates/rtf/src/doc/text.rs | 2 +- crates/rtf/src/doc/word.rs | 92 ++++++++++++++++++++++++------------ 6 files changed, 93 insertions(+), 40 deletions(-) diff --git a/crates/rtf/src/doc/parse.rs b/crates/rtf/src/doc/parse.rs index c51d402a4..c0c3a4fea 100644 --- a/crates/rtf/src/doc/parse.rs +++ b/crates/rtf/src/doc/parse.rs @@ -54,9 +54,6 @@ fn parse_full(bytes: &[u8], marks: bool) -> Result { } b'}' => { r.close(); - if r.info_depth.is_some_and(|d| r.depth() < d) { - r.info_depth = None; - } first_in_group = false; starred = false; i += 1; @@ -124,9 +121,6 @@ fn parse_full(bytes: &[u8], marks: bool) -> Result { first_in_group = false; continue; } - if word == "info" { - r.info_depth = Some(r.depth()); - } r.word(word, param, starred, first_in_group); first_in_group = false; starred = false; diff --git a/crates/rtf/src/doc/reader.rs b/crates/rtf/src/doc/reader.rs index 4bf83184b..e3cac7901 100644 --- a/crates/rtf/src/doc/reader.rs +++ b/crates/rtf/src/doc/reader.rs @@ -95,9 +95,7 @@ pub(super) struct Reader { pub(super) def_cur: CellDef, pub(super) row_header: bool, pub(super) created: Option<(u32, u32, u32, u32, u32)>, - pub(super) in_creatim: bool, pub(super) rule_pending: bool, - pub(super) info_depth: Option, // Notes and comments (only when the caller wants them). pub(super) marks_on: bool, pub(super) sub: Option, @@ -370,7 +368,7 @@ impl Reader { Dest::FontTbl if !self.font_name.is_empty() => self.commit_font(), Dest::StyleSheet if !self.style_name.is_empty() => self.commit_style(), Dest::RevTbl if !self.rev_name.trim().is_empty() => self.commit_author(), - Dest::Info(k) => { + Dest::Info(k) if self.stack.last().is_none_or(|parent| parent.dest != closing) => { let t = std::mem::take(&mut self.info_text).trim().to_string(); match k { 1 => self.meta.title = t, @@ -380,7 +378,6 @@ impl Reader { 5 => self.meta.description = t, _ => {} } - self.in_creatim = false; } Dest::Atn(k) => self.commit_atn(k), Dest::ShpSv => self.commit_shape_prop(), diff --git a/crates/rtf/src/doc/state.rs b/crates/rtf/src/doc/state.rs index a39eacc2f..9091b7af1 100644 --- a/crates/rtf/src/doc/state.rs +++ b/crates/rtf/src/doc/state.rs @@ -28,7 +28,9 @@ pub(super) enum Dest { FontTbl, ColorTbl, StyleSheet, + InfoRoot, Info(u8), + Created, ListTable, ListOverride, FldInst, diff --git a/crates/rtf/src/doc/tests.rs b/crates/rtf/src/doc/tests.rs index 2a7c9d42c..51429d98e 100644 --- a/crates/rtf/src/doc/tests.rs +++ b/crates/rtf/src/doc/tests.rs @@ -2180,3 +2180,29 @@ fn the_generator_names_the_writing_application() { let back = parse(odd.as_bytes()).expect("parses"); assert_eq!(texts(&back), ["Normal:Hello"]); } + +#[test] +fn metadata_text_survives_nested_formatting_without_reading_other_destinations() { + let flow = parse(br"{\rtf1\ansi{\fonttbl{\f0 Arial;}}{\info{\title Before {\b bold {\i caf\u233?}}{\fonttbl{\f0 Wrong;}}{\*\bkmkstart hidden}{\pict\pngblip 00} After}{\author Author}}\f0 Body}").unwrap(); + assert_eq!(flow.meta.title, "Before bold café After"); + assert_eq!(flow.meta.author, "Author"); + assert_eq!(texts(&flow), ["Normal:Body"]); + let FBlock::Para(body) = &flow.blocks[0] else { panic!("expected body text") }; + assert!(matches!(&body.inlines[0], Inline::Text(_, fmt) if fmt.font.as_deref() == Some("Arial"))); +} + +#[test] +fn metadata_creation_date_ignores_other_date_destinations() { + let flow = parse(br"{\rtf1\ansi{\info{\creatim\yr2026{\revtim\yr1999}{\b\mo11}\dy19}}Body}").unwrap(); + assert_eq!(flow.meta.created, "2026-11-19T00:00:00Z"); + assert_eq!(texts(&flow), ["Normal:Body"]); +} + +#[test] +fn metadata_text_controls_keep_punctuation_and_use_the_selected_font_code_page() { + let flow = + parse(br"{\rtf1\ansi{\fonttbl{\f0\fcharset0 Arial;}{\f1\fcharset204 Cyrillic;}}{\info{\title A\emdash {\f1 \'e0\plain \'e0}}}\f0 Body}") + .unwrap(); + assert_eq!(flow.meta.title, "A—аà"); + assert_eq!(texts(&flow), ["Normal:Body"]); +} diff --git a/crates/rtf/src/doc/text.rs b/crates/rtf/src/doc/text.rs index ce77a20d3..ca31e8218 100644 --- a/crates/rtf/src/doc/text.rs +++ b/crates/rtf/src/doc/text.rs @@ -310,7 +310,7 @@ impl Reader { } } Dest::ShpSn | Dest::ShpSv => self.shape_text(s), - Dest::Skip | Dest::ListTable | Dest::ListOverride | Dest::OldProps(_) | Dest::ShpInst => {} + Dest::Skip | Dest::InfoRoot | Dest::Created | Dest::ListTable | Dest::ListOverride | Dest::OldProps(_) | Dest::ShpInst => {} } } diff --git a/crates/rtf/src/doc/word.rs b/crates/rtf/src/doc/word.rs index 0a0df5c68..b0ef9bab3 100644 --- a/crates/rtf/src/doc/word.rs +++ b/crates/rtf/src/doc/word.rs @@ -21,8 +21,11 @@ impl Reader { self.finish_multibyte(); let on = p != Some(0); let pv = p.unwrap_or(0); + if self.info_word(w, p, starred, first_in_group) { + return; + } self.note_defshp(w); - if self.skip_destination_word(w, pv) { + if self.st.dest == Dest::Skip { return; } if self.shape_word(w, p, first_in_group) { @@ -311,12 +314,7 @@ impl Reader { "fonttbl" => Some(Dest::FontTbl), "colortbl" => Some(Dest::ColorTbl), "stylesheet" => Some(Dest::StyleSheet), - "info" => Some(Dest::Skip), - "title" if self.st.dest == Dest::Skip && self.in_info() => Some(Dest::Info(1)), - "author" if self.in_info() => Some(Dest::Info(2)), - "subject" if self.in_info() => Some(Dest::Info(3)), - "keywords" if self.in_info() => Some(Dest::Info(4)), - "doccomm" if self.in_info() => Some(Dest::Info(5)), + "info" => Some(Dest::InfoRoot), "listtable" => Some(Dest::ListTable), "revtbl" => Some(Dest::RevTbl), "oldcprops" => Some(Dest::OldProps(false)), @@ -348,10 +346,6 @@ impl Reader { | "nofwords" | "nofchars" | "edmins" | "vern" | "themedata" | "colorschememapping" | "latentstyles" | "datastore" | "xmlnstbl" | "rsidtbl" | "generator" | "mmathPr" | "pgdsctbl" | "filetbl" | "listpicture" | "userprops" | "docvar" | "objdata" | "fontemb" | "fontfile" | "panose" | "falt" | "mhtmltag" | "htmltag" | "pnseclvl" | "background" | "sp" | "pn" | "pgptbl" => Some(Dest::Skip), - "creatim" if self.in_info() => { - self.in_creatim = true; - Some(Dest::Skip) - } _ => None, } } @@ -410,12 +404,7 @@ impl Reader { fn destination_word(&mut self, word: &str, param: Option, on: bool, value: i32) -> bool { match self.st.dest { - Dest::Skip => { - if self.in_creatim { - self.record_created_part(word, value); - } - true - } + Dest::Skip | Dest::InfoRoot | Dest::Created => true, Dest::FontTbl if !matches!(word, "u" | "uc") => { self.font_table_word(word, value); true @@ -483,7 +472,8 @@ impl Reader { } !matches!(word, "u" | "uc") } - Dest::Info(_) | Dest::FldInst | Dest::Bookmark if !matches!(word, "u" | "uc") => true, + Dest::Info(_) if !metadata_text_word(word) => true, + Dest::FldInst | Dest::Bookmark if !matches!(word, "u" | "uc") => true, Dest::Info(_) | Dest::FldInst | Dest::Bookmark => false, Dest::OldProps(false) if matches!(word, "crauth" | "crdate") => { if word == "crauth" { @@ -578,15 +568,42 @@ impl Reader { } } - fn skip_destination_word(&mut self, word: &str, value: i32) -> bool { - let kept_info = self.in_info() && matches!(word, "title" | "author" | "subject" | "keywords" | "doccomm" | "creatim"); - if self.st.dest != Dest::Skip || kept_info { - return false; + /// Metadata groups use the same stack as the body, but never dispatch document-level + /// destinations (font tables, pictures, bookmarks and revisions) from inside a property. + fn info_word(&mut self, word: &str, value: Option, starred: bool, first_in_group: bool) -> bool { + match self.st.dest { + Dest::InfoRoot => { + if first_in_group { + self.st.dest = match word { + "title" => Dest::Info(1), + "author" => Dest::Info(2), + "subject" => Dest::Info(3), + "keywords" => Dest::Info(4), + "doccomm" => Dest::Info(5), + "creatim" => Dest::Created, + _ => Dest::Skip, + }; + } + true + } + Dest::Info(_) | Dest::Created => { + let text = metadata_text_word(word); + let date = self.st.dest == Dest::Created && matches!(word, "yr" | "mo" | "dy" | "hr" | "min"); + if first_in_group && (starred || !(text || date || is_format_word(word))) { + self.st.dest = Dest::Skip; + } else if date && let Some(value) = value { + self.record_created_part(word, value); + } else if self.st.dest != Dest::Created { + if word == "plain" { + self.st.cp = self.font_cps.get(&self.deff).copied(); + } else if text { + return false; + } + } + true + } + _ => false, } - if self.in_creatim { - self.record_created_part(word, value); - } - true } fn record_created_part(&mut self, word: &str, value: i32) { @@ -608,10 +625,27 @@ impl Reader { self.st.field = Some(self.fields.len() - 1); } } +} - fn in_info(&self) -> bool { - self.info_depth.is_some_and(|d| self.depth() > d) - } +/// Words that only select a group's font, set its Unicode fallback or emit text. +fn metadata_text_word(word: &str) -> bool { + matches!( + word, + "f" | "u" + | "uc" + | "line" + | "softline" + | "tab" + | "emdash" + | "endash" + | "bullet" + | "lquote" + | "rquote" + | "ldblquote" + | "rdblquote" + | "emspace" + | "enspace" + ) } /// The target of a `HYPERLINK` field instruction; `%22` is a quote, as the writer stores one. From aa89df6814dd8c3481fed9ac0241e9e891064daa Mon Sep 17 00:00:00 2001 From: Rees Date: Thu, 19 Nov 2026 09:21:13 +0100 Subject: [PATCH 37/84] Preserve external DOCX mail-merge source relationships --- crates/docx/src/flat.rs | 7 +- crates/docx/src/lib.rs | 7 +- crates/docx/src/package.rs | 2 + crates/docx/src/read/meta.rs | 12 +- crates/docx/src/wordml2003_write.rs | 2 +- crates/docx/src/write.rs | 17 +- crates/docx/src/write/mail_merge.rs | 198 +++++++++++ crates/docx/src/write/parts.rs | 55 +-- crates/docx/src/write/settings.rs | 5 +- crates/docx/src/write/settings_merge.rs | 60 +++- crates/docx/tests/it/passthrough.rs | 4 +- crates/docx/tests/it/settings_merge.rs | 17 +- crates/docx/tests/mail_merge.rs | 445 ++++++++++++++++++++++++ 13 files changed, 794 insertions(+), 37 deletions(-) create mode 100644 crates/docx/src/write/mail_merge.rs create mode 100644 crates/docx/tests/mail_merge.rs diff --git a/crates/docx/src/flat.rs b/crates/docx/src/flat.rs index c257932cf..4cbe94ab1 100644 --- a/crates/docx/src/flat.rs +++ b/crates/docx/src/flat.rs @@ -387,7 +387,12 @@ fn root_tag_start(frag: &[u8]) -> Option { /// Write `doc` as a Word XML Document (Flat OPC). pub fn write(doc: &Document) -> Result, DocxError> { - let parts = crate::write::write_parts(doc, Flavor::Document)?; + write_with_options(doc, crate::WriteOptions::default()) +} + +/// Write Flat OPC using explicit save options. +pub fn write_with_options(doc: &Document, options: crate::WriteOptions) -> Result, DocxError> { + let parts = crate::write::write_parts(doc, Flavor::Document, options)?; let types = parts .iter() .find(|(n, _)| n == "[Content_Types].xml") diff --git a/crates/docx/src/lib.rs b/crates/docx/src/lib.rs index 68d41ab4d..19eb1f377 100644 --- a/crates/docx/src/lib.rs +++ b/crates/docx/src/lib.rs @@ -49,12 +49,12 @@ pub use crypt::{ DEFAULT_SPIN_COUNT, MAX_PASSWORD_CHARS, PasswordCheck, check_password, check_protection_password, decrypt, encrypt, encrypt_standard_for_tests, encrypt_with_spin_count, is_encrypted, protection_hash, }; -pub use flat::{XmlKind, sniff_xml, write as write_flat}; +pub use flat::{XmlKind, sniff_xml, write as write_flat, write_with_options as write_flat_with_options}; pub use fonts::{EmbeddedFont, embedded_fonts}; pub use read::{AltChunk, ChunkImporter, ReadOptions, read}; pub use smart_art::smart_art_items; pub use wordml2003_write::write as write_wordml2003; -pub use write::{write, write_as}; +pub use write::{WriteOptions, write, write_as, write_as_with_options}; /// Largest `.xml` file read as a Word XML document. pub const MAX_XML_FILE: usize = 1 << 30; @@ -196,4 +196,7 @@ pub enum DocxError { /// (or encrypting failed). #[error("encrypted document: {0}")] Encryption(String), + /// The retained mail-merge settings cannot be written with their original source. + #[error("mail merge: {0}")] + MailMerge(String), } diff --git a/crates/docx/src/package.rs b/crates/docx/src/package.rs index 67152ee83..0b44f2894 100644 --- a/crates/docx/src/package.rs +++ b/crates/docx/src/package.rs @@ -114,6 +114,8 @@ pub const CUSTOM_XML_ROOTS: &str = "wordcraft:customXml.roots"; /// The original `word/settings.xml` when it holds settings the model doesn't (merged into on /// save by `write::settings_merge`). Not a package part: WordCraft's own bookkeeping. pub const SETTINGS_ORIG: &str = "wordcraft:settings.orig"; +/// Retained relationship map for mail-merge sources referenced by the original settings. +pub const MAIL_MERGE_RELS: &str = "wordcraft:settings.mailMerge.rels"; /// The theme's East Asian, complex-script and per-script fonts (`a:ea`, `a:cs`, `a:font /// script="Hans"` in `a:majorFont` / `a:minorFont`), which the model doesn't hold: `major|minor /// \tface\tea|cs\ttypeface` and `major|minor\tscript\t