feat(weld): phase alignment for layered bass, release 0.1.0

Weld hears the other bass layer through the sidechain and fits polarity
plus up to four RBJ allpass sections to the measured cross-spectrum, so
the layers sum instead of cancelling. No latency; the layer on its own
keeps its sound.

- Worker thread: Welch cross-spectrum and coherence, Nelder-Mead fit with
  1/f weighting, a per-band loss penalty and model selection by share of
  the achievable gain; GCC-PHAT lag detection flags a late layer.
- Audio thread: allocation-free chain with a 40 ms warm-up and 40 ms
  crossfade per new fit; mono blocks go to the worker through a lock-free
  queue.
- Follow / Learn / Hold; the fit is persisted and restored without a
  crossfade.
- Editor: per-band loss and recovery against a perfect alignment, phase
  before and after, recovered dB, time offset and status.
- Tests for flat magnitude, crossfade, fit targets, Follow hysteresis,
  Learn, silence, realtime allocation and the persisted fit in the host.

plugins/weld/core/src/analyzer.rs

@@ -0,0 +1,429 @@
+//! The measuring half of Weld. Runs on the worker thread; deterministic, so tests drive
+//! it directly.
+//!
+//! A Welch estimate of the cross-spectrum S = F_A·conj(F_B) and both auto-spectra runs
+//! over Hann-windowed frames with 50 % overlap. Both layers share one complex FFT
+//! (A in the real part, B in the imaginary part).
+use crate::chain::Fit;
+use crate::fit::{search, Point, Problem};
+use crate::report::{band_of, curve_frequency, Report, Status, BANDS};
+use crate::settings::{Mode, Settings};
+use rustfft::{num_complex::Complex32, Fft, FftPlanner};
+use std::sync::Arc;
+
+/// Bins below this coherence do not steer the fit.
+const MIN_COHERENCE: f32 = 0.3;
+/// Below this mean coherence the layers count as unrelated.
+const LOOSE_COHERENCE: f32 = 0.3;
+/// Frames needed before the first fit.
+const MIN_FRAMES: u32 = 8;
+/// A new fit replaces the current one only when it gains this much (Follow mode).
+const FOLLOW_GAIN_DB: f32 = 0.3;
+const LEARN_GAIN_DB: f32 = 0.1;
+/// Lag search range and the smallest lag reported as "late".
+const LAG_RANGE_S: f32 = 0.005;
+const LATE_S: f32 = 0.0001;
+const LATE_STRENGTH: f32 = 0.3;
+/// Report and fit intervals in seconds of analysed audio.
+const REPORT_S: f32 = 0.25;
+const FIT_S: f32 = 0.5;
+/// −90 dBFS: anything quieter on the sidechain counts as no signal.
+const SILENCE: f32 = 3.2e-5;
+
+/// What a poll produced.
+#[derive(Debug, Clone, Copy)]
+pub struct Update {
+    /// Set when a new alignment was accepted.
+    pub fit: Option<Fit>,
+    pub report: Report,
+}
+
+pub struct Analyzer {
+    rate: f32,
+    n: usize,
+    hop: usize,
+    window: Vec<f32>,
+    ring_a: Vec<f32>,
+    ring_b: Vec<f32>,
+    write: usize,
+    filled: usize,
+    since_frame: usize,
+    fft: Arc<dyn Fft<f32>>,
+    ifft: Arc<dyn Fft<f32>>,
+    buf: Vec<Complex32>,
+    scratch: Vec<Complex32>,
+    sab: Vec<Complex32>,
+    saa: Vec<f32>,
+    sbb: Vec<f32>,
+    frames: u32,
+    settings: Settings,
+    current: Fit,
+    since_report: usize,
+    since_fit: usize,
+    finish_learn: bool,
+    side_level: f32,
+    gated: bool,
+}
+
+impl Analyzer {
+    pub fn new(rate: f32, fit: Fit) -> Self {
+        // About 11.7 Hz per bin at any rate.
+        let n = ((4096. * rate / 48000.) as usize)
+            .next_power_of_two()
+            .clamp(1024, 65536);
+        let mut planner = FftPlanner::new();
+        let fft = planner.plan_fft_forward(n);
+        let ifft = planner.plan_fft_inverse(n);
+        let scratch_len = fft
+            .get_inplace_scratch_len()
+            .max(ifft.get_inplace_scratch_len());
+        let window = (0..n)
+            .map(|i| 0.5 - 0.5 * (std::f32::consts::TAU * i as f32 / n as f32).cos())
+            .collect();
+        let bins = n / 2 + 1;
+        Self {
+            rate,
+            n,
+            hop: n / 2,
+            window,
+            ring_a: vec![0.; n],
+            ring_b: vec![0.; n],
+            write: 0,
+            filled: 0,
+            since_frame: 0,
+            fft,
+            ifft,
+            buf: vec![Complex32::default(); n],
+            scratch: vec![Complex32::default(); scratch_len],
+            sab: vec![Complex32::default(); bins],
+            saa: vec![0.; bins],
+            sbb: vec![0.; bins],
+            frames: 0,
+            settings: Settings::default(),
+            current: fit.sanitized(rate),
+            since_report: 0,
+            since_fit: 0,
+            finish_learn: false,
+            side_level: 0.,
+            gated: false,
+        }
+    }
+    pub fn fft_size(&self) -> usize {
+        self.n
+    }
+    pub fn current(&self) -> &Fit {
+        &self.current
+    }
+    pub fn frames(&self) -> u32 {
+        self.frames
+    }
+    pub fn set_settings(&mut self, settings: Settings) {
+        let old = self.settings.mode;
+        if settings.mode == Mode::Learn && old != Mode::Learn {
+            self.clear();
+        }
+        if old == Mode::Learn && settings.mode != Mode::Learn {
+            self.finish_learn = true;
+        }
+        self.settings = settings;
+    }
+    /// Forgets the measurement.
+    pub fn clear(&mut self) {
+        self.sab.fill(Complex32::default());
+        self.saa.fill(0.);
+        self.sbb.fill(0.);
+        self.frames = 0;
+    }
+    /// Feeds mono samples of the main layer `a` and the sidechain layer `b`.
+    pub fn push(&mut self, a: &[f32], b: &[f32]) {
+        for (&x, &y) in a.iter().zip(b) {
+            self.ring_a[self.write] = x;
+            self.ring_b[self.write] = y;
+            self.write = (self.write + 1) % self.n;
+            self.filled = (self.filled + 1).min(self.n);
+            self.since_frame += 1;
+            if self.filled == self.n && self.since_frame >= self.hop {
+                self.since_frame = 0;
+                self.frame();
+            }
+        }
+        self.since_report += a.len().min(b.len());
+        self.since_fit += a.len().min(b.len());
+    }
+    fn frame(&mut self) {
+        let n = self.n;
+        let (mut ea, mut eb) = (0f32, 0f32);
+        for i in 0..n {
+            let j = (self.write + i) % n;
+            let (a, b) = (self.ring_a[j], self.ring_b[j]);
+            ea += a * a;
+            eb += b * b;
+            self.buf[i] = Complex32::new(a * self.window[i], b * self.window[i]);
+        }
+        let (ra, rb) = ((ea / n as f32).sqrt(), (eb / n as f32).sqrt());
+        self.side_level = rb;
+        let gate = 10f32.powf(self.settings.gate / 20.);
+        self.gated = ra < gate || rb < gate;
+        if self.gated {
+            return;
+        }
+        self.fft
+            .process_with_scratch(&mut self.buf, &mut self.scratch);
+        self.frames = self.frames.saturating_add(1);
+        let count = 1. / self.frames as f32;
+        let alpha = match self.settings.mode {
+            Mode::Learn => count,
+            _ => {
+                let follow = 1. - (-(self.hop as f32) / (self.settings.response * self.rate)).exp();
+                count.max(follow)
+            }
+        };
+        for k in 0..=n / 2 {
+            let x = self.buf[k];
+            let xc = self.buf[(n - k) % n].conj();
+            let fa = (x + xc) * 0.5;
+            let fb = (x - xc) * Complex32::new(0., -0.5);
+            let old = self.sab[k];
+            self.sab[k] = old + (fa * fb.conj() - old) * alpha;
+            self.saa[k] += (fa.norm_sqr() - self.saa[k]) * alpha;
+            self.sbb[k] += (fb.norm_sqr() - self.sbb[k]) * alpha;
+        }
+    }
+    fn frequency(&self, k: usize) -> f32 {
+        k as f32 * self.rate / self.n as f32
+    }
+    fn coherence(&self, k: usize) -> f32 {
+        let d = self.saa[k] * self.sbb[k];
+        if d > 0. {
+            (self.sab[k].norm_sqr() / d).min(1.)
+        } else {
+            0.
+        }
+    }
+    fn range(&self) -> (f32, f32) {
+        let high = self.settings.high.min(0.45 * self.rate);
+        (self.settings.low.min(high * 0.5), high)
+    }
+    /// Fit points between Low and High: one per bin at the bottom, merged to 1/32 octave
+    /// higher up.
+    fn points(&self) -> Vec<Point> {
+        let (low, high) = self.range();
+        let mut points: Vec<Point> = Vec::new();
+        let mut last = usize::MAX;
+        for k in 1..=self.n / 2 {
+            let f = self.frequency(k);
+            if f < low || f > high {
+                continue;
+            }
+            let slot = (32. * (f / low).log2()) as usize;
+            if slot != last {
+                points.push(Point::new(f, self.rate));
+                last = slot;
+            }
+            let p = points.last_mut().expect("pushed above");
+            if self.coherence(k) >= MIN_COHERENCE {
+                p.fit += self.sab[k];
+            }
+            p.all += self.sab[k];
+            p.power += self.saa[k] + self.sbb[k];
+        }
+        points
+    }
+    /// Produces an update once enough audio has been analysed since the last one.
+    pub fn poll(&mut self) -> Option<Update> {
+        let report_due = self.since_report as f32 >= REPORT_S * self.rate;
+        if !report_due && !self.finish_learn {
+            return None;
+        }
+        self.since_report = 0;
+        let fit_due = self.since_fit as f32 >= FIT_S * self.rate;
+        let mode = self.settings.mode;
+        let threshold = if self.finish_learn {
+            Some(LEARN_GAIN_DB)
+        } else if fit_due && mode == Mode::Follow {
+            Some(FOLLOW_GAIN_DB)
+        } else if fit_due && mode == Mode::Learn {
+            Some(LEARN_GAIN_DB)
+        } else {
+            None
+        };
+        if fit_due {
+            self.since_fit = 0;
+        }
+        self.finish_learn = false;
+        Some(self.analyse(threshold))
+    }
+    /// Measures, fits when `threshold` is given (minimum predicted gain in dB over the
+    /// current fit), and reports.
+    pub fn analyse(&mut self, threshold: Option<f32>) -> Update {
+        let points = self.points();
+        let problem = Problem::new(points, self.rate);
+        let (weight, coherent) = problem.points.iter().fold((0., 0.), |(w, c), p| {
+            let x = p.all.norm();
+            (w + p.w * x, c + p.w * x * coherence_of(p))
+        });
+        let mean_coherence = if weight > 0. { coherent / weight } else { 0. };
+        let (lag_ms, lag_strength) = self.lag();
+        let late = lag_ms > LATE_S * 1000. && lag_strength > LATE_STRENGTH;
+        let status = if self.side_level < SILENCE && self.frames == 0 {
+            Status::NoSidechain
+        } else if self.frames < MIN_FRAMES {
+            if self.gated {
+                Status::Quiet
+            } else {
+                Status::Waiting
+            }
+        } else if mean_coherence < LOOSE_COHERENCE || problem.is_empty() {
+            Status::Loose
+        } else if late {
+            Status::Late
+        } else {
+            Status::Aligned
+        };
+        let mut changed = None;
+        if let Some(threshold) = threshold {
+            if matches!(status, Status::Aligned | Status::Late) {
+                let candidate = search(&problem, self.settings.sections, &self.current);
+                let gain = problem.mean_gain(
+                    &problem.bands(&self.current),
+                    &problem.bands(&candidate.fit),
+                );
+                if gain.is_finite() && gain >= threshold && candidate.fit != self.current {
+                    self.current = candidate.fit;
+                    changed = Some(candidate.fit);
+                }
+            }
+        }
+        let mut report = self.report(status, &problem);
+        report.lag_ms = lag_ms;
+        report.lag_strength = lag_strength;
+        report.changed = changed.is_some();
+        Update {
+            fit: changed,
+            report,
+        }
+    }
+    fn report(&self, status: Status, problem: &Problem) -> Report {
+        let fit = self.current;
+        let mut report = Report {
+            status,
+            fit,
+            frames: self.frames,
+            low: self.range().0,
+            high: self.range().1,
+            ..Report::default()
+        };
+        // Display bands over all bins.
+        // Sums per band: before, after, ideal, coherence·power, power.
+        let mut sums = [[0f32; 5]; BANDS];
+        for k in 1..=self.n / 2 {
+            let f = self.frequency(k);
+            if !(20. ..=0.45 * self.rate).contains(&f) {
+                continue;
+            }
+            let (hr, hi) = fit.response(f, self.rate);
+            let s = self.sab[k];
+            let p = self.saa[k] + self.sbb[k];
+            let b = &mut sums[band_of(f)];
+            b[0] += p + 2. * s.re;
+            b[1] += p + 2. * (s * Complex32::new(hr, hi)).re;
+            b[2] += p + 2. * s.norm();
+            b[3] += self.coherence(k) * p;
+            b[4] += p;
+        }
+        for (band, [before, after, ideal, coherent, power]) in report.bands.iter_mut().zip(sums) {
+            if ideal > 1e-12 && power > 0. {
+                band.before = db_ratio(before, ideal);
+                band.after = db_ratio(after, ideal);
+                band.coherence = (coherent / power).clamp(0., 1.);
+                band.valid = true;
+            }
+        }
+        // Phase curve: bins within ±1/24 octave of each point.
+        for (i, point) in report.curve.iter_mut().enumerate() {
+            let f = curve_frequency(i);
+            if f > 0.45 * self.rate {
+                continue;
+            }
+            let lo = ((f * 2f32.powf(-1. / 24.)) * self.n as f32 / self.rate).floor() as usize;
+            let hi = ((f * 2f32.powf(1. / 24.)) * self.n as f32 / self.rate).ceil() as usize;
+            let centre = (f * self.n as f32 / self.rate).round() as usize;
+            let (lo, hi) = (
+                lo.max(1).min(centre.max(1)),
+                hi.min(self.n / 2).max(centre.max(1)),
+            );
+            let (mut s, mut pa, mut pb) = (Complex32::default(), 0f32, 0f32);
+            for k in lo..=hi {
+                s += self.sab[k];
+                pa += self.saa[k];
+                pb += self.sbb[k];
+            }
+            if pa * pb <= 0. {
+                continue;
+            }
+            let (hr, hi) = fit.response(f, self.rate);
+            let h = Complex32::new(hr, hi);
+            point.before = s.arg().to_degrees();
+            point.after = (s * h).arg().to_degrees();
+            point.chain = h.arg().to_degrees();
+            point.coherence = (s.norm_sqr() / (pa * pb)).min(1.);
+            point.valid = true;
+        }
+        // Headline numbers over the fit range, every band weighted the same.
+        if !problem.is_empty() {
+            let before = problem.before_bands();
+            report.cost_db = problem.mean_gain(&before, &problem.ideal_bands());
+            report.recovered_db = problem.mean_gain(&before, &problem.bands(&fit));
+        }
+        report
+    }
+    /// Time offset from the phase transform of the cross-spectrum (GCC-PHAT) between
+    /// Low and High. Returns (ms, strength); positive means this layer is late.
+    fn lag(&mut self) -> (f32, f32) {
+        let n = self.n;
+        let (low, high) = self.range();
+        self.buf.fill(Complex32::default());
+        let mut used = 0usize;
+        for k in 1..n / 2 {
+            let f = self.frequency(k);
+            if f < low || f > high || self.coherence(k) < MIN_COHERENCE {
+                continue;
+            }
+            let s = self.sab[k];
+            let m = s.norm();
+            if m <= 0. {
+                continue;
+            }
+            let u = s / m;
+            self.buf[k] = u;
+            self.buf[n - k] = u.conj();
+            used += 1;
+        }
+        if used < 4 {
+            return (0., 0.);
+        }
+        self.ifft
+            .process_with_scratch(&mut self.buf, &mut self.scratch);
+        let range = (LAG_RANGE_S * self.rate) as isize;
+        let (mut best, mut at) = (0f32, 0isize);
+        for tau in -range..=range {
+            let v = self.buf[tau.rem_euclid(n as isize) as usize].re.abs();
+            if v > best {
+                best = v;
+                at = tau;
+            }
+        }
+        (at as f32 / self.rate * 1000., best / (2 * used) as f32)
+    }
+}
+
+fn coherence_of(p: &Point) -> f32 {
+    if p.all.norm() > 0. {
+        p.fit.norm() / p.all.norm()
+    } else {
+        0.
+    }
+}
+fn db_ratio(a: f32, b: f32) -> f32 {
+    (10. * (a.max(1e-20) / b.max(1e-20)).log10()).clamp(-40., 40.)
+}

plugins/weld/core/src/chain.rs

@@ -0,0 +1,163 @@
+//! Polarity plus a cascade of second-order allpass sections. Magnitude is flat by
+//! construction; only the phase of the main layer changes.
+use serde::{Deserialize, Serialize};
+
+pub const MAX_SECTIONS: usize = 4;
+pub const MIN_FC: f32 = 30.;
+pub const MIN_Q: f32 = 0.2;
+pub const MAX_Q: f32 = 4.;
+
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+pub struct Section {
+    /// Centre frequency in Hz, where the section's phase passes −180°.
+    pub fc: f32,
+    pub q: f32,
+}
+impl Default for Section {
+    fn default() -> Self {
+        Self { fc: 1000., q: 0.7 }
+    }
+}
+
+/// The result of a fit: what Weld applies to the main layer.
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Default)]
+pub struct Fit {
+    /// Invert the main layer.
+    pub flip: bool,
+    /// Number of active sections, 0..=MAX_SECTIONS.
+    pub count: usize,
+    pub sections: [Section; MAX_SECTIONS],
+}
+impl Fit {
+    /// The identity: no polarity change, no sections.
+    pub const NONE: Fit = Fit {
+        flip: false,
+        count: 0,
+        sections: [Section { fc: 1000., q: 0.7 }; MAX_SECTIONS],
+    };
+    pub fn active(&self) -> &[Section] {
+        &self.sections[..self.count.min(MAX_SECTIONS)]
+    }
+    /// Clamps every value into the range the filter supports; repairs restored state.
+    pub fn sanitized(mut self, rate: f32) -> Self {
+        self.count = self.count.min(MAX_SECTIONS);
+        let top = max_fc(rate);
+        for s in &mut self.sections {
+            s.fc = if s.fc.is_finite() {
+                s.fc.clamp(MIN_FC, top)
+            } else {
+                1000f32.min(top)
+            };
+            s.q = if s.q.is_finite() {
+                s.q.clamp(MIN_Q, MAX_Q)
+            } else {
+                0.7
+            };
+        }
+        self
+    }
+    /// Complex response at `f` Hz as (re, im).
+    pub fn response(&self, f: f32, rate: f32) -> (f32, f32) {
+        let w = std::f32::consts::TAU * f / rate;
+        let (mut re, mut im) = (if self.flip { -1. } else { 1. }, 0.);
+        for s in self.active() {
+            let c = Coefs::allpass(s.fc, s.q, rate);
+            let (hr, hi) = c.response(w.cos(), w.sin(), (2. * w).cos(), (2. * w).sin());
+            (re, im) = (re * hr - im * hi, re * hi + im * hr);
+        }
+        (re, im)
+    }
+}
+
+pub fn max_fc(rate: f32) -> f32 {
+    0.45 * rate
+}
+
+/// Normalised allpass coefficients: H(z) = (a2 + a1 z⁻¹ + z⁻²) / (1 + a1 z⁻¹ + a2 z⁻²).
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Coefs {
+    pub a1: f32,
+    pub a2: f32,
+}
+impl Coefs {
+    /// RBJ cookbook allpass.
+    pub fn allpass(fc: f32, q: f32, rate: f32) -> Self {
+        let fc = fc.clamp(MIN_FC, max_fc(rate));
+        let q = q.clamp(MIN_Q, MAX_Q);
+        let w = std::f32::consts::TAU * fc / rate;
+        let alpha = w.sin() / (2. * q);
+        let a0 = 1. + alpha;
+        Self {
+            a1: -2. * w.cos() / a0,
+            a2: (1. - alpha) / a0,
+        }
+    }
+    /// Response at z⁻¹ = e^{−jω}, given cos/sin of ω and 2ω.
+    /// For an allpass the numerator is z⁻²·conj(den), so H = z⁻²·conj(den)/den.
+    #[inline]
+    pub fn response(&self, c1: f32, s1: f32, c2: f32, s2: f32) -> (f32, f32) {
+        let x = 1. + self.a1 * c1 + self.a2 * c2;
+        let y = -(self.a1 * s1 + self.a2 * s2);
+        let m = x * x + y * y;
+        // conj(den)/den = conj(den)² / |den|²
+        let (qr, qi) = ((x * x - y * y) / m, -2. * x * y / m);
+        // times z⁻² = c2 − j s2
+        (qr * c2 + qi * s2, qi * c2 - qr * s2)
+    }
+}
+
+/// Transposed direct form II state, in f64 so sections near 30 Hz stay quiet.
+#[derive(Debug, Clone, Copy, Default)]
+struct State {
+    s1: f64,
+    s2: f64,
+}
+
+/// A running chain for up to two channels. Allocation-free.
+#[derive(Debug, Clone)]
+pub struct Chain {
+    fit: Fit,
+    sign: f32,
+    coefs: [(f64, f64); MAX_SECTIONS],
+    state: [[State; MAX_SECTIONS]; 2],
+}
+impl Chain {
+    pub fn new(fit: Fit, rate: f32) -> Self {
+        let mut chain = Self {
+            fit: Fit::NONE,
+            sign: 1.,
+            coefs: [(0., 0.); MAX_SECTIONS],
+            state: [[State::default(); MAX_SECTIONS]; 2],
+        };
+        chain.set(fit, rate);
+        chain
+    }
+    pub fn fit(&self) -> &Fit {
+        &self.fit
+    }
+    /// Replaces the coefficients and clears the state.
+    pub fn set(&mut self, fit: Fit, rate: f32) {
+        self.fit = fit.sanitized(rate);
+        self.sign = if self.fit.flip { -1. } else { 1. };
+        for (c, s) in self.coefs.iter_mut().zip(self.fit.active()) {
+            let k = Coefs::allpass(s.fc, s.q, rate);
+            *c = (k.a1 as f64, k.a2 as f64);
+        }
+        self.reset();
+    }
+    pub fn reset(&mut self) {
+        self.state = [[State::default(); MAX_SECTIONS]; 2];
+    }
+    #[inline]
+    pub fn process(&mut self, channel: usize, x: f32) -> f32 {
+        let mut y = (self.sign * x) as f64;
+        for (k, &(a1, a2)) in self.coefs[..self.fit.count].iter().enumerate() {
+            let st = &mut self.state[channel][k];
+            let out = a2 * y + st.s1;
+            st.s1 = a1 * y - a1 * out + st.s2;
+            st.s2 = y - a2 * out;
+            y = out;
+        }
+        y as f32
+    }
+}

plugins/weld/core/src/fit.rs

@@ -0,0 +1,372 @@
+//! Fits polarity plus allpass sections to a measured cross-spectrum.
+//!
+//! With S = F_A·conj(F_B), the power of the sum after rotating A by H is
+//! |A|² + |B|² + 2·Re(S·H). The fit maximises Σ w(f)·Re(S·H) with w = 1/f, so every
+//! octave counts the same. Flipping polarity negates the sum, so the best polarity is
+//! the sign of the result and only the sections need searching.
+use crate::chain::{max_fc, Coefs, Fit, Section, MAX_Q, MAX_SECTIONS, MIN_FC, MIN_Q};
+use crate::report::{band_of, BANDS, DISPLAY_HIGH, DISPLAY_LOW};
+
+/// Bands for the loss penalty. Narrower bands make the penalty brittle next to the
+/// notches of a comb, which a delay between the layers always has.
+const FINE: usize = 10;
+fn fine_of(f: f32) -> usize {
+    let t = (f / DISPLAY_LOW).ln() / (DISPLAY_HIGH / DISPLAY_LOW).ln();
+    ((t * FINE as f32).max(0.) as usize).min(FINE - 1)
+}
+use rustfft::num_complex::Complex32;
+
+/// One fit point: bins merged over at most 1/32 octave.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct Point {
+    pub c1: f32,
+    pub s1: f32,
+    pub c2: f32,
+    pub s2: f32,
+    /// 1/f weight.
+    pub w: f32,
+    /// Cross-spectrum of the coherent bins only; drives the objective.
+    pub fit: Complex32,
+    /// Cross-spectrum and summed auto-spectra of all bins; drive the predicted levels.
+    pub all: Complex32,
+    pub power: f32,
+    pub band: usize,
+    pub fine: usize,
+}
+impl Point {
+    pub fn new(f: f32, rate: f32) -> Self {
+        let w = std::f32::consts::TAU * f / rate;
+        Self {
+            c1: w.cos(),
+            s1: w.sin(),
+            c2: (2. * w).cos(),
+            s2: (2. * w).sin(),
+            w: 1. / f,
+            fit: Complex32::default(),
+            all: Complex32::default(),
+            power: 0.,
+            band: band_of(f),
+            fine: fine_of(f),
+        }
+    }
+}
+
+pub(crate) struct Problem {
+    pub points: Vec<Point>,
+    pub rate: f32,
+    /// Σ w·|S| over the coherent bins: the objective of a perfect per-bin alignment.
+    norm: f32,
+    /// Per-band level of the unprocessed sum.
+    before: [f32; BANDS],
+    /// The same in third-octave bands, for the loss penalty.
+    before_fine: [f32; FINE],
+}
+
+/// Score of a perfectly aligned sum is 1. Losing more than 1 dB in any band against the
+/// unprocessed sum costs extra, so a fit cannot win the mids by giving away the top.
+const LOSS_FREE_DB: f32 = 1.0;
+const LOSS_WEIGHT: f32 = 0.05;
+/// The smallest model that reaches this share of the best model's improvement wins.
+const MODEL_SHARE: f32 = 0.95;
+/// Improvements below this score never justify another section.
+const MODEL_FLOOR: f32 = 0.001;
+
+#[derive(Debug, Clone, Copy)]
+pub struct Candidate {
+    pub fit: Fit,
+    pub score: f32,
+}
+
+impl Problem {
+    pub fn new(points: Vec<Point>, rate: f32) -> Self {
+        let norm = points.iter().map(|p| p.w * p.fit.norm()).sum::<f32>();
+        let mut before = [0f32; BANDS];
+        let mut before_fine = [0f32; FINE];
+        for p in &points {
+            before[p.band] += p.power + 2. * p.all.re;
+            before_fine[p.fine] += p.power + 2. * p.all.re;
+        }
+        Self {
+            points,
+            rate,
+            norm,
+            before,
+            before_fine,
+        }
+    }
+    pub fn is_empty(&self) -> bool {
+        self.norm <= 0.
+    }
+    fn coefs(&self, x: &[f32], out: &mut [Coefs; MAX_SECTIONS]) -> (usize, f32) {
+        let k = x.len() / 2;
+        let mut outside = 0.;
+        let (lo_f, hi_f) = (MIN_FC.ln(), max_fc(self.rate).ln());
+        let (lo_q, hi_q) = (MIN_Q.ln(), MAX_Q.ln());
+        for i in 0..k {
+            let (f, q) = (x[2 * i], x[2 * i + 1]);
+            outside +=
+                (lo_f - f).max(0.) + (f - hi_f).max(0.) + (lo_q - q).max(0.) + (q - hi_q).max(0.);
+            out[i] = Coefs::allpass(
+                f.clamp(lo_f, hi_f).exp(),
+                q.clamp(lo_q, hi_q).exp(),
+                self.rate,
+            );
+        }
+        (k, outside)
+    }
+    #[inline]
+    fn response(p: &Point, coefs: &[Coefs]) -> Complex32 {
+        let mut h = Complex32::new(1., 0.);
+        for c in coefs {
+            let (re, im) = c.response(p.c1, p.s1, p.c2, p.s2);
+            h *= Complex32::new(re, im);
+        }
+        h
+    }
+    /// Score and polarity for sections given as [ln fc, ln q, …].
+    fn score(&self, x: &[f32]) -> (f32, bool) {
+        let mut coefs = [Coefs { a1: 0., a2: 0. }; MAX_SECTIONS];
+        let (k, outside) = self.coefs(x, &mut coefs);
+        let coefs = &coefs[..k];
+        let mut j = 0f32;
+        let mut cross = [0f32; FINE];
+        let mut power = [0f32; FINE];
+        for p in &self.points {
+            let h = Self::response(p, coefs);
+            j += p.w * (p.fit * h).re;
+            cross[p.fine] += (p.all * h).re;
+            power[p.fine] += p.power;
+        }
+        let flip = j < 0.;
+        let sign = if flip { -1. } else { 1. };
+        let mut penalty = outside * outside;
+        for b in 0..FINE {
+            let before = self.before_fine[b];
+            if before <= 0. {
+                continue;
+            }
+            let after = (power[b] + 2. * sign * cross[b]).max(before * 1e-6);
+            let loss = 10. * (before / after).log10();
+            if loss > LOSS_FREE_DB {
+                penalty += LOSS_WEIGHT * (loss - LOSS_FREE_DB).powi(2);
+            }
+        }
+        (j.abs() / self.norm - penalty, flip)
+    }
+    fn candidate(&self, x: &[f32]) -> Candidate {
+        let (score, flip) = self.score(x);
+        let mut fit = Fit {
+            flip,
+            count: x.len() / 2,
+            ..Fit::NONE
+        };
+        for (i, s) in fit.sections[..fit.count].iter_mut().enumerate() {
+            *s = Section {
+                fc: x[2 * i].exp().clamp(MIN_FC, max_fc(self.rate)),
+                q: x[2 * i + 1].exp().clamp(MIN_Q, MAX_Q),
+            };
+        }
+        Candidate { fit, score }
+    }
+    /// Level of the sum per display band with `fit` applied (sign included).
+    pub fn bands(&self, fit: &Fit) -> [f32; BANDS] {
+        let mut coefs = [Coefs { a1: 0., a2: 0. }; MAX_SECTIONS];
+        for (c, s) in coefs.iter_mut().zip(fit.active()) {
+            *c = Coefs::allpass(s.fc, s.q, self.rate);
+        }
+        let coefs = &coefs[..fit.active().len()];
+        let sign = if fit.flip { -1. } else { 1. };
+        let mut out = [0f32; BANDS];
+        for p in &self.points {
+            out[p.band] += p.power + 2. * sign * (p.all * Self::response(p, coefs)).re;
+        }
+        out
+    }
+    /// Level per display band of a perfectly aligned sum.
+    pub fn ideal_bands(&self) -> [f32; BANDS] {
+        let mut out = [0f32; BANDS];
+        for p in &self.points {
+            out[p.band] += p.power + 2. * p.all.norm();
+        }
+        out
+    }
+    /// Mean change in dB over the bands that carry signal, from `from` to `to`. Every
+    /// band counts the same, so a hollow octave in the mids weighs as much as the sub.
+    pub fn mean_gain(&self, from: &[f32; BANDS], to: &[f32; BANDS]) -> f32 {
+        let total: f32 = self.before.iter().sum();
+        let (mut sum, mut count) = (0f32, 0);
+        for b in 0..BANDS {
+            if self.before[b] > total * 1e-4 && from[b] > 0. {
+                sum += 10. * (to[b].max(from[b] * 1e-6) / from[b]).log10();
+                count += 1;
+            }
+        }
+        if count > 0 {
+            sum / count as f32
+        } else {
+            0.
+        }
+    }
+    pub fn before_bands(&self) -> [f32; BANDS] {
+        self.before
+    }
+    /// The frequency where the current sections leave the most cross-energy unaligned,
+    /// smoothed over one third of an octave.
+    fn worst_frequency(&self, x: &[f32]) -> f32 {
+        let mut coefs = [Coefs { a1: 0., a2: 0. }; MAX_SECTIONS];
+        let (k, _) = self.coefs(x, &mut coefs);
+        let (_, flip) = self.score(x);
+        let sign = if flip { -1. } else { 1. };
+        let mut buckets = [0f32; 48];
+        let mut first = None;
+        for p in &self.points {
+            let h = Self::response(p, &coefs[..k]);
+            let residual = p.w * (p.fit.norm() - sign * (p.fit * h).re);
+            let f = 1. / p.w;
+            let low = *first.get_or_insert(f);
+            let i = ((3. * (f / low).log2()) as usize).min(47);
+            buckets[i] += residual;
+        }
+        let low = first.unwrap_or(100.);
+        let best = (0..48)
+            .max_by(|&a, &b| buckets[a].total_cmp(&buckets[b]))
+            .unwrap_or(0);
+        low * 2f32.powf((best as f32 + 0.5) / 3.)
+    }
+}
+
+/// Searches 0..=`max_sections` sections, warm-started from `warm`. Deterministic.
+pub(crate) fn search(problem: &Problem, max_sections: usize, warm: &Fit) -> Candidate {
+    let max_sections = max_sections.min(MAX_SECTIONS);
+    let mut best: Vec<Candidate> = Vec::with_capacity(max_sections + 1);
+    best.push(problem.candidate(&[]));
+    let mut previous: Vec<f32> = Vec::new();
+    for k in 1..=max_sections {
+        let mut seeds: Vec<Vec<f32>> = Vec::new();
+        let worst = problem.worst_frequency(&previous);
+        for f in [worst, worst * 0.4, worst * 2.5] {
+            let mut x = previous.clone();
+            x.extend([f.ln(), 0.7f32.ln()]);
+            seeds.push(x);
+        }
+        if k == 1 {
+            // Low-Q sections high up act like a short delay below their centre.
+            for (f, q) in [
+                (120f32, 0.7f32),
+                (400., 0.7),
+                (1500., 0.7),
+                (3000., 0.5),
+                (6000., 0.5),
+            ] {
+                seeds.push(vec![f.ln(), q.ln()]);
+            }
+        }
+        if warm.count == k {
+            seeds.push(
+                warm.active()
+                    .iter()
+                    .flat_map(|s| [s.fc.ln(), s.q.ln()])
+                    .collect(),
+            );
+        }
+        let mut top: Option<(Vec<f32>, f32)> = None;
+        for seed in seeds {
+            let (x, value) = nelder_mead(|x| -problem.score(x).0, &seed, 0.35, 120 * k * 2);
+            if top.as_ref().is_none_or(|(_, v)| value < *v) {
+                top = Some((x, value));
+            }
+        }
+        let (x, _) = top.expect("at least one seed");
+        let candidate = problem.candidate(&x);
+        let top = best.iter().map(|c| c.score).fold(f32::MIN, f32::max);
+        let gained = candidate.score - top;
+        let slack = MODEL_FLOOR.max((1. - MODEL_SHARE) * (top - best[0].score));
+        best.push(candidate);
+        previous = x;
+        // A section that adds next to nothing is not worth it; more of them rarely are.
+        if k >= 2 && gained < slack {
+            break;
+        }
+    }
+    let top = best.iter().map(|c| c.score).fold(f32::MIN, f32::max);
+    let slack = MODEL_FLOOR.max((1. - MODEL_SHARE) * (top - best[0].score));
+    *best
+        .iter()
+        .find(|c| c.score >= top - slack)
+        .expect("the best model qualifies")
+}
+
+/// Downhill simplex. Returns the best point and its value.
+fn nelder_mead(
+    mut f: impl FnMut(&[f32]) -> f32,
+    x0: &[f32],
+    step: f32,
+    max_evals: usize,
+) -> (Vec<f32>, f32) {
+    let n = x0.len();
+    let mut simplex: Vec<(Vec<f32>, f32)> = Vec::with_capacity(n + 1);
+    simplex.push((x0.to_vec(), f(x0)));
+    for i in 0..n {
+        let mut x = x0.to_vec();
+        x[i] += step;
+        let v = f(&x);
+        simplex.push((x, v));
+    }
+    let mut evals = n + 1;
+    let point = |a: &[f32], b: &[f32], t: f32| -> Vec<f32> {
+        a.iter().zip(b).map(|(a, b)| a + t * (b - a)).collect()
+    };
+    while evals < max_evals {
+        simplex.sort_by(|a, b| a.1.total_cmp(&b.1));
+        let spread = simplex[n].1 - simplex[0].1;
+        let size = simplex[1..]
+            .iter()
+            .flat_map(|(x, _)| x.iter().zip(&simplex[0].0).map(|(a, b)| (a - b).abs()))
+            .fold(0f32, f32::max);
+        if spread < 1e-7 && size < 1e-3 {
+            break;
+        }
+        let mut centroid = vec![0f32; n];
+        for (x, _) in &simplex[..n] {
+            for (c, v) in centroid.iter_mut().zip(x) {
+                *c += v / n as f32;
+            }
+        }
+        let worst = simplex[n].clone();
+        let reflected = point(&centroid, &worst.0, -1.);
+        let fr = f(&reflected);
+        evals += 1;
+        if fr < simplex[0].1 {
+            let expanded = point(&centroid, &worst.0, -2.);
+            let fe = f(&expanded);
+            evals += 1;
+            simplex[n] = if fe < fr {
+                (expanded, fe)
+            } else {
+                (reflected, fr)
+            };
+        } else if fr < simplex[n - 1].1 {
+            simplex[n] = (reflected, fr);
+        } else {
+            let contracted = if fr < worst.1 {
+                point(&centroid, &reflected, 0.5)
+            } else {
+                point(&centroid, &worst.0, 0.5)
+            };
+            let fc = f(&contracted);
+            evals += 1;
+            if fc < worst.1.min(fr) {
+                simplex[n] = (contracted, fc);
+            } else {
+                let best = simplex[0].0.clone();
+                for (x, v) in &mut simplex[1..] {
+                    *x = point(&best, x, 0.5);
+                    *v = f(x);
+                }
+                evals += n;
+            }
+        }
+    }
+    simplex.sort_by(|a, b| a.1.total_cmp(&b.1));
+    simplex.swap_remove(0)
+}

plugins/weld/core/src/lib.rs

@@ -1,9 +1,79 @@
 //! Weld engine: aligns the phase of the main layer to a sidechain layer so the two sum
-//! instead of cancel. Allocation-free after `new`; zero latency.
+//! instead of cancelling. The audio thread runs polarity plus an allpass chain and hands
+//! mono blocks to a worker thread, which measures the cross-spectrum and fits the chain.
+//! Allocation-free on the audio thread after `new`; zero latency.
+mod analyzer;
+mod chain;
+mod fit;
+mod report;
 mod settings;
-pub use settings::{Listen, Settings};
+mod worker;
+pub use analyzer::{Analyzer, Update};
+pub use chain::{Chain, Fit, Section, MAX_SECTIONS};
+pub use report::{
+    band_edge, curve_frequency, Band, CurvePoint, Report, Status, BANDS, CURVE, DISPLAY_HIGH,
+    DISPLAY_LOW,
+};
+pub use settings::{Listen, Mode, Settings};
+pub use worker::Worker;
 
-/// Levels for the editor, published a few times per second.
+use crossbeam_queue::ArrayQueue;
+use std::sync::{
+    atomic::{AtomicUsize, Ordering},
+    Arc,
+};
+
+/// Samples per block handed to the worker.
+pub const BLOCK: usize = 256;
+/// Blocks the queue holds: about 340 ms at 48 kHz.
+const QUEUE_BLOCKS: usize = 64;
+/// A new fit runs silently this long before it is faded in, so its filters settle.
+const WARM_S: f32 = 0.04;
+/// Crossfade time from the old fit to the new one.
+const FADE_S: f32 = 0.04;
+
+/// Mono blocks of both layers, before Weld's processing.
+#[derive(Clone, Copy)]
+pub struct Block {
+    pub a: [f32; BLOCK],
+    pub b: [f32; BLOCK],
+}
+
+/// Lock-free queues between one engine and its worker.
+pub struct Link {
+    pub(crate) blocks: ArrayQueue<Block>,
+    pub(crate) fits: ArrayQueue<Fit>,
+    pub(crate) settings: ArrayQueue<Settings>,
+    dropped: AtomicUsize,
+}
+impl Link {
+    fn new() -> Self {
+        Self {
+            blocks: ArrayQueue::new(QUEUE_BLOCKS),
+            fits: ArrayQueue::new(4),
+            settings: ArrayQueue::new(1),
+            dropped: AtomicUsize::new(0),
+        }
+    }
+    /// Blocks dropped because the worker fell behind.
+    pub fn dropped(&self) -> usize {
+        self.dropped.load(Ordering::Relaxed)
+    }
+    /// Takes the next block, as the worker does. For tests and offline tools.
+    pub fn pop_block(&self) -> Option<Block> {
+        self.blocks.pop()
+    }
+    /// Takes the latest settings, as the worker does. For tests and offline tools.
+    pub fn pop_settings(&self) -> Option<Settings> {
+        self.settings.pop()
+    }
+    /// Hands a fit to the engine, as the worker does. For tests and offline tools.
+    pub fn push_fit(&self, fit: Fit) {
+        self.fits.force_push(fit);
+    }
+}
+
+/// Levels for the editor, published a few times per second by the audio thread.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct AnalyzerFrame {
     /// RMS of the main input in dBFS since the last frame.
@@ -14,6 +84,8 @@ pub struct AnalyzerFrame {
     pub side_peak_db: f32,
     /// True once any sidechain sample above −90 dBFS arrived since activation.
     pub side_seen: bool,
+    /// Blocks the worker could not take in time, since activation.
+    pub dropped: usize,
     pub sample_rate: f32,
 }
 impl Default for AnalyzerFrame {
@@ -23,6 +95,7 @@ impl Default for AnalyzerFrame {
             side_db: -120.,
             side_peak_db: -120.,
             side_seen: false,
+            dropped: 0,
             sample_rate: 48000.,
         }
     }
@@ -46,16 +119,34 @@ struct Levels {
     count: usize,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq)]
+enum Phase {
+    Steady,
+    /// The next chain runs unheard for this many more samples.
+    Warm(usize),
+    /// The next chain fades in over this many more samples.
+    Fade(usize),
+}
+
 pub struct Engine {
     rate: f32,
     channels: usize,
     settings: Settings,
+    sent: Option<Settings>,
     gain: f32,
     target_gain: f32,
     gain_coef: f32,
     fresh: bool,
     levels: Levels,
     side_seen: bool,
+    current: Chain,
+    next: Chain,
+    phase: Phase,
+    warm: usize,
+    fade: usize,
+    link: Arc<Link>,
+    block: Block,
+    fill: usize,
 }
 impl Engine {
     pub fn new(rate: f32, channels: usize) -> Result<Self, &'static str> {
@@ -69,12 +160,24 @@ impl Engine {
             rate,
             channels,
             settings: Settings::default(),
+            sent: None,
             gain: 1.,
             target_gain: 1.,
             gain_coef: 1. - (-1. / (0.02 * rate)).exp(),
             fresh: true,
             levels: Levels::default(),
             side_seen: false,
+            current: Chain::new(Fit::NONE, rate),
+            next: Chain::new(Fit::NONE, rate),
+            phase: Phase::Steady,
+            warm: ((WARM_S * rate) as usize).max(1),
+            fade: ((FADE_S * rate) as usize).max(1),
+            link: Arc::new(Link::new()),
+            block: Block {
+                a: [0.; BLOCK],
+                b: [0.; BLOCK],
+            },
+            fill: 0,
         })
     }
     pub const fn latency_samples(&self) -> u32 {
@@ -83,9 +186,28 @@ impl Engine {
     pub fn channels(&self) -> usize {
         self.channels
     }
+    pub fn sample_rate(&self) -> f32 {
+        self.rate
+    }
     pub fn settings(&self) -> &Settings {
         &self.settings
     }
+    /// The queues for this engine's worker.
+    pub fn link(&self) -> Arc<Link> {
+        self.link.clone()
+    }
+    /// The alignment heard now (the target one during a crossfade).
+    pub fn fit(&self) -> Fit {
+        match self.phase {
+            Phase::Steady => *self.current.fit(),
+            _ => *self.next.fit(),
+        }
+    }
+    /// Applies `fit` at once, without a crossfade. For restoring saved state.
+    pub fn set_fit(&mut self, fit: Fit) {
+        self.current.set(fit, self.rate);
+        self.phase = Phase::Steady;
+    }
     pub fn set_settings(&mut self, settings: Settings) -> Result<(), &'static str> {
         settings.validate()?;
         self.settings = settings;
@@ -94,11 +216,22 @@ impl Engine {
             self.gain = self.target_gain;
             self.fresh = false;
         }
+        if self.sent != Some(settings) {
+            self.link.settings.force_push(settings);
+            self.sent = Some(settings);
+        }
         Ok(())
     }
     pub fn reset(&mut self) {
         self.gain = self.target_gain;
         self.levels = Levels::default();
+        self.current.reset();
+        if self.phase != Phase::Steady {
+            std::mem::swap(&mut self.current, &mut self.next);
+            self.current.reset();
+            self.phase = Phase::Steady;
+        }
+        self.fill = 0;
     }
     /// One frame of main input `x` and sidechain input `side`. Mono uses index 0 only.
     #[inline]
@@ -118,22 +251,66 @@ impl Engine {
         if s.abs() > 3e-5 {
             self.side_seen = true;
         }
+        self.feed(m, s);
+        if self.phase == Phase::Steady {
+            if let Some(fit) = self.link.fits.pop() {
+                self.next.set(fit, self.rate);
+                self.phase = Phase::Warm(self.warm);
+            }
+        }
+        let mut aligned = [0f32; 2];
+        let mix = match self.phase {
+            Phase::Steady => None,
+            Phase::Warm(_) => Some(0.),
+            Phase::Fade(left) => Some(1. - left as f32 / self.fade as f32),
+        };
+        for c in 0..n {
+            let a = self.current.process(c, x[c]);
+            aligned[c] = match mix {
+                None => a,
+                Some(t) => {
+                    let b = self.next.process(c, x[c]);
+                    a + t * (b - a)
+                }
+            };
+        }
+        self.phase = match self.phase {
+            Phase::Steady => Phase::Steady,
+            Phase::Warm(1) => Phase::Fade(self.fade),
+            Phase::Warm(left) => Phase::Warm(left - 1),
+            Phase::Fade(1) => {
+                std::mem::swap(&mut self.current, &mut self.next);
+                Phase::Steady
+            }
+            Phase::Fade(left) => Phase::Fade(left - 1),
+        };
         self.gain += (self.target_gain - self.gain) * self.gain_coef;
         if self.settings.bypass {
             return x;
         }
         let mut out = [0.; 2];
         for c in 0..n {
-            let layer = x[c];
             out[c] = self.gain
                 * match self.settings.listen {
-                    Listen::Layer => layer,
-                    Listen::Sum => layer + side[c],
+                    Listen::Layer => aligned[c],
+                    Listen::Sum => aligned[c] + side[c],
                     Listen::SumDry => x[c] + side[c],
                 };
         }
         out
     }
+    #[inline]
+    fn feed(&mut self, a: f32, b: f32) {
+        self.block.a[self.fill] = a;
+        self.block.b[self.fill] = b;
+        self.fill += 1;
+        if self.fill == BLOCK {
+            self.fill = 0;
+            if self.link.blocks.push(self.block).is_err() {
+                self.link.dropped.fetch_add(1, Ordering::Relaxed);
+            }
+        }
+    }
     /// Levels since the previous call.
     pub fn take_analyzer(&mut self) -> AnalyzerFrame {
         let n = self.levels.count.max(1) as f64;
@@ -142,6 +319,7 @@ impl Engine {
             side_db: db((self.levels.side / n) as f32, true),
             side_peak_db: db(self.levels.peak, false),
             side_seen: self.side_seen,
+            dropped: self.link.dropped(),
             sample_rate: self.rate,
         };
         self.levels = Levels::default();

plugins/weld/core/src/report.rs

@@ -0,0 +1,108 @@
+//! What the analysis tells the editor. Plain `Copy` data, so it crosses threads through
+//! a lock-free queue without allocating.
+use crate::chain::Fit;
+
+/// Display bands, equally wide on a log axis from `DISPLAY_LOW` to `DISPLAY_HIGH`.
+pub const BANDS: usize = 10;
+/// Points of the phase curve.
+pub const CURVE: usize = 96;
+pub const DISPLAY_LOW: f32 = 30.;
+pub const DISPLAY_HIGH: f32 = 12000.;
+
+/// Index of the display band that contains `f` (clamped to the outer bands).
+pub fn band_of(f: f32) -> usize {
+    let t = (f / DISPLAY_LOW).ln() / (DISPLAY_HIGH / DISPLAY_LOW).ln();
+    ((t * BANDS as f32).max(0.) as usize).min(BANDS - 1)
+}
+/// Lower edge of display band `i`; `band_edge(BANDS)` is the top edge.
+pub fn band_edge(i: usize) -> f32 {
+    DISPLAY_LOW * (DISPLAY_HIGH / DISPLAY_LOW).powf(i as f32 / BANDS as f32)
+}
+/// Frequency of curve point `i`.
+pub fn curve_frequency(i: usize) -> f32 {
+    DISPLAY_LOW * (DISPLAY_HIGH / DISPLAY_LOW).powf(i as f32 / (CURVE - 1) as f32)
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Status {
+    /// Not enough measured audio yet.
+    #[default]
+    Waiting,
+    /// The sidechain carries no signal.
+    NoSidechain,
+    /// Both layers play, but one of them is under the gate.
+    Quiet,
+    /// The layers are not related closely enough to align (free-running oscillators,
+    /// different notes, noise).
+    Loose,
+    /// This layer is later than the sidechain layer. An allpass cannot move it earlier.
+    Late,
+    /// Measuring and aligning.
+    Aligned,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Default)]
+pub struct Band {
+    /// Level of the unprocessed sum relative to a perfectly aligned sum, in dB (≤ 0).
+    pub before: f32,
+    /// Level of the sum with Weld's alignment, relative to a perfect one, in dB (≤ 0).
+    pub after: f32,
+    /// Power-weighted coherence of the two layers, 0..1.
+    pub coherence: f32,
+    /// False when the band carries no measured signal.
+    pub valid: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Default)]
+pub struct CurvePoint {
+    /// Phase of the main layer relative to the sidechain layer, degrees, ±180.
+    pub before: f32,
+    /// The same with Weld's alignment applied.
+    pub after: f32,
+    /// Phase of Weld's chain, degrees, ±180.
+    pub chain: f32,
+    pub coherence: f32,
+    pub valid: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Report {
+    pub status: Status,
+    /// The alignment currently applied (or about to be).
+    pub fit: Fit,
+    /// True when this report comes with a newly accepted fit.
+    pub changed: bool,
+    pub bands: [Band; BANDS],
+    pub curve: [CurvePoint; CURVE],
+    /// What the cancellation costs between Low and High: aligned sum over unprocessed sum.
+    pub cost_db: f32,
+    /// What Weld wins back between Low and High: aligned-by-Weld sum over unprocessed sum.
+    pub recovered_db: f32,
+    /// Time offset of this layer against the sidechain layer, ms. Positive: this layer
+    /// is late.
+    pub lag_ms: f32,
+    /// How clear the time offset is, 0..1.
+    pub lag_strength: f32,
+    /// Measured frames in the current average.
+    pub frames: u32,
+    pub low: f32,
+    pub high: f32,
+}
+impl Default for Report {
+    fn default() -> Self {
+        Self {
+            status: Status::Waiting,
+            fit: Fit::NONE,
+            changed: false,
+            bands: [Band::default(); BANDS],
+            curve: [CurvePoint::default(); CURVE],
+            cost_db: 0.,
+            recovered_db: 0.,
+            lag_ms: 0.,
+            lag_strength: 0.,
+            frames: 0,
+            low: 60.,
+            high: 6000.,
+        }
+    }
+}

plugins/weld/core/src/settings.rs

@@ -1,4 +1,4 @@
-//! Host-independent controls. Gains in dB.
+//! Host-independent controls. Gains in dB, frequencies in Hz, times in seconds.
 use serde::{Deserialize, Serialize};
 
 /// What the plugin outputs.
@@ -13,9 +13,33 @@ pub enum Listen {
     SumDry,
 }
 
+/// How the alignment is found.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub enum Mode {
+    /// Keep measuring and refit when a clearly better alignment shows up.
+    #[default]
+    Follow,
+    /// Measure from the moment Learn starts, with equal weight; the result is applied
+    /// when Learn ends.
+    Learn,
+    /// Keep the current alignment. The display keeps measuring.
+    Hold,
+}
+
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
 #[serde(deny_unknown_fields)]
 pub struct Settings {
+    pub mode: Mode,
+    /// Averaging time of the measurement in Follow mode.
+    pub response: f32,
+    /// Lowest frequency the fit listens to.
+    pub low: f32,
+    /// Highest frequency the fit listens to.
+    pub high: f32,
+    /// Largest number of allpass sections the fit may use.
+    pub sections: usize,
+    /// Frames quieter than this (dBFS RMS) on either layer are not measured.
+    pub gate: f32,
     pub listen: Listen,
     pub output: f32,
     pub bypass: bool,
@@ -23,6 +47,12 @@ pub struct Settings {
 impl Default for Settings {
     fn default() -> Self {
         Self {
+            mode: Mode::Follow,
+            response: 1.5,
+            low: 60.,
+            high: 6000.,
+            sections: 4,
+            gate: -50.,
             listen: Listen::Layer,
             output: 0.,
             bypass: false,
@@ -31,10 +61,17 @@ impl Default for Settings {
 }
 impl Settings {
     pub fn validate(&self) -> Result<(), &'static str> {
-        if !self.output.is_finite() {
+        let values = [self.response, self.low, self.high, self.gate, self.output];
+        if values.iter().any(|v| !v.is_finite()) {
             return Err("non-finite setting");
         }
-        if (-12.0..=12.).contains(&self.output) {
+        if (0.3..=5.).contains(&self.response)
+            && (30.0..=400.).contains(&self.low)
+            && (1000.0..=12000.).contains(&self.high)
+            && (1..=crate::chain::MAX_SECTIONS).contains(&self.sections)
+            && (-70.0..=-30.).contains(&self.gate)
+            && (-12.0..=12.).contains(&self.output)
+        {
             Ok(())
         } else {
             Err("setting out of range")

plugins/weld/core/src/worker.rs

@@ -0,0 +1,77 @@
+//! The worker thread: takes blocks from the audio thread, runs the analyzer and sends
+//! accepted fits back. Started and stopped outside the audio thread.
+use crate::analyzer::Analyzer;
+use crate::chain::Fit;
+use crate::report::Report;
+use crate::Link;
+use crossbeam_queue::ArrayQueue;
+use std::{
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    },
+    thread::JoinHandle,
+    time::Duration,
+};
+
+pub struct Worker {
+    stop: Arc<AtomicBool>,
+    thread: Option<JoinHandle<()>>,
+}
+impl Worker {
+    /// Starts the worker for one engine. `on_fit` runs on the worker thread for every
+    /// accepted fit, for example to store it in the plugin state.
+    pub fn spawn(
+        link: Arc<Link>,
+        rate: f32,
+        fit: Fit,
+        reports: Arc<ArrayQueue<Report>>,
+        mut on_fit: impl FnMut(Fit) + Send + 'static,
+    ) -> std::io::Result<Self> {
+        let stop = Arc::new(AtomicBool::new(false));
+        let flag = stop.clone();
+        let thread = std::thread::Builder::new()
+            .name("weld-analysis".into())
+            .spawn(move || {
+                let mut analyzer = Analyzer::new(rate, fit);
+                while !flag.load(Ordering::Relaxed) {
+                    let mut idle = true;
+                    while let Some(settings) = link.settings.pop() {
+                        analyzer.set_settings(settings);
+                    }
+                    while let Some(block) = link.blocks.pop() {
+                        idle = false;
+                        analyzer.push(&block.a, &block.b);
+                        if let Some(update) = analyzer.poll() {
+                            if let Some(fit) = update.fit {
+                                link.fits.force_push(fit);
+                                on_fit(fit);
+                            }
+                            reports.force_push(update.report);
+                        }
+                        if flag.load(Ordering::Relaxed) {
+                            break;
+                        }
+                    }
+                    if idle {
+                        std::thread::sleep(Duration::from_millis(5));
+                    }
+                }
+            })?;
+        Ok(Self {
+            stop,
+            thread: Some(thread),
+        })
+    }
+    pub fn stop(&mut self) {
+        self.stop.store(true, Ordering::Relaxed);
+        if let Some(thread) = self.thread.take() {
+            let _ = thread.join();
+        }
+    }
+}
+impl Drop for Worker {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}