packages /

audio 0.1.0

Audio in pure Auk, covering the audio side of ffmpeg for uncompressed and lossless formats.

files / src/fx.auk 12.6 kB · 409 lines

/// Filters and effects on one channel at a time (module `audio.fx`): RBJ-cookbook biquads,
/// echo, dynamics (compressor, limiter, gate), fades and WSOLA time stretching. `audio` applies
/// them to every channel; the functions here take a channel's samples and the sample rate.

/// Normalized biquad coefficients: y = b0 x + b1 x1 + b2 x2 - a1 y1 - a2 y2.
pub struct Biquad { b0: float, b1: float, b2: float, a1: float, a2: float }

pub enum Kind { Lowpass, Highpass, Bandpass, Notch, Allpass, Peak, LowShelf, HighShelf }

/// The RBJ Audio EQ Cookbook filter of `kind` at `freq` Hz with quality `q` and (for peak and
/// shelf filters) `gain_db`.
pub fn design(kind: Kind, freq: float, q: float, gain_db: float, rate: int): Biquad {
  let w0 = 2.0 * float.pi * freq / float(rate)
  let cw = cos(w0)
  let alpha = sin(w0) / (2.0 * q)
  let a = 10.0 ** (gain_db / 40.0)
  let (b0, b1, b2, a0, a1, a2) = match kind {
    Lowpass => ((1.0 - cw) / 2.0, 1.0 - cw, (1.0 - cw) / 2.0, 1.0 + alpha, -2.0 * cw, 1.0 - alpha)
    Highpass =>
      ((1.0 + cw) / 2.0, -(1.0 + cw), (1.0 + cw) / 2.0, 1.0 + alpha, -2.0 * cw, 1.0 - alpha)
    Bandpass => (alpha, 0.0, -alpha, 1.0 + alpha, -2.0 * cw, 1.0 - alpha)
    Notch => (1.0, -2.0 * cw, 1.0, 1.0 + alpha, -2.0 * cw, 1.0 - alpha)
    Allpass => (1.0 - alpha, -2.0 * cw, 1.0 + alpha, 1.0 + alpha, -2.0 * cw, 1.0 - alpha)
    Peak =>
      (1.0 + alpha * a, -2.0 * cw, 1.0 - alpha * a, 1.0 + alpha / a, -2.0 * cw, 1.0 - alpha / a)
    LowShelf => {
      let s = 2.0 * sqrt(a) * alpha
      (
        a * ((a + 1.0) - (a - 1.0) * cw + s),
        2.0 * a * ((a - 1.0) - (a + 1.0) * cw),
        a * ((a + 1.0) - (a - 1.0) * cw - s),
        (a + 1.0) + (a - 1.0) * cw + s,
        -2.0 * ((a - 1.0) + (a + 1.0) * cw),
        (a + 1.0) + (a - 1.0) * cw - s,
      )
    }
    HighShelf => {
      let s = 2.0 * sqrt(a) * alpha
      (
        a * ((a + 1.0) + (a - 1.0) * cw + s),
        -2.0 * a * ((a - 1.0) + (a + 1.0) * cw),
        a * ((a + 1.0) + (a - 1.0) * cw - s),
        (a + 1.0) - (a - 1.0) * cw + s,
        2.0 * ((a - 1.0) - (a + 1.0) * cw),
        (a + 1.0) - (a - 1.0) * cw - s,
      )
    }
  }
  Biquad { b0: b0 / a0, b1: b1 / a0, b2: b2 / a0, a1: a1 / a0, a2: a2 / a0 }
}

/// Runs the filter over `xs` (transposed direct form II, starting from silence).
pub fn biquad(xs: [float], f: Biquad): [float] {
  var out = xs
  var z1 = 0.0
  var z2 = 0.0
  for i in 0..xs.len() {
    let x = xs[i]
    let y = f.b0 * x + z1
    z1 = f.b1 * x - f.a1 * y + z2
    z2 = f.b2 * x - f.a2 * y
    out[i] = y
  }
  out
}

/// The filter's gain in dB at `freq` Hz.
pub fn response_db(f: Biquad, freq: float, rate: int): float {
  let w = 2.0 * float.pi * freq / float(rate)
  // |B(e^jw)| / |A(e^jw)|
  let (c1, s1, c2, s2) = (cos(w), sin(w), cos(2.0 * w), sin(2.0 * w))
  let br = f.b0 + f.b1 * c1 + f.b2 * c2
  let bi = -(f.b1 * s1 + f.b2 * s2)
  let ar = 1.0 + f.a1 * c1 + f.a2 * c2
  let ai = -(f.a1 * s1 + f.a2 * s2)
  10.0 * log10((br * br + bi * bi) / (ar * ar + ai * ai))
}

// ---- delays ----

/// `secs` of silence before `xs`.
pub fn delay(xs: [float], secs: float, rate: int): [float] =
  audio.pcm.zeros(samples(secs, rate)) + xs

pub fn samples(secs: float, rate: int): int = if secs <= 0.0 {
  0
} else {
  int(round(secs * float(rate)))
}

/// ffmpeg's aecho: out = (x * in_gain + sum(x delayed by delays[i] * decays[i])) * out_gain,
/// lengthened so the last echo finishes.
pub fn echo(
  xs: [float],
  rate: int,
  in_gain: float,
  out_gain: float,
  delays: [float],
  decays: [float],
): [float] {
  let ds = delays.map(d => samples(d, rate))
  let tail = ds.max() else 0
  var out: [float] = []
  for i in 0..xs.len() + tail {
    var y = (xs.get(i) else 0.0) * in_gain
    for k in 0..ds.len() {
      let j = i - ds[k]
      if j >= 0 && j < xs.len() { y += xs[j] * decays[k] }
    }
    out.push(y * out_gain)
  }
  out
}

// ---- dynamics ----

pub fn db(x: float): float = if x <= 0.0 { -1000.0 } else { 20.0 * log10(x) }
pub fn undb(d: float): float = 10.0 ** (d / 20.0)

// The envelope step of ffmpeg's dynamics filters: 4 / (time * rate), at most 1.
fn step(secs: float, rate: int): float {
  let s = if secs <= 0.0 { 1.0 } else { 4.0 / (secs * float(rate)) }
  if s > 1.0 { 1.0 } else { s }
}

// A one-pole smoothing coefficient for a time constant in seconds.
fn coef(secs: float, rate: int): float = if secs <= 0.0 {
  0.0
} else {
  exp(-1.0 / (secs * float(rate)))
}

/// The gain (in dB, <= 0) a compressor applies to a level of `x` dB.
pub fn curve(x: float, threshold: float, ratio: float, knee: float): float {
  let over = x - threshold
  if knee > 0.0 && 2.0 * abs(over) <= knee {
    let t = over + knee / 2.0
    (1.0 / ratio - 1.0) * t * t / (2.0 * knee)
  } else if over > 0.0 {
    over * (1.0 / ratio - 1.0)
  } else {
    0.0
  }
}

/// The gain each sample gets from a feed-forward compressor driven by `detect` (one value per
/// sample: the loudest channel's absolute level, say), as ffmpeg's acompressor: an envelope
/// follows the level (or its square, for `rms`), rising with `attack` and falling with
/// `release` (seconds), and the gain comes from the envelope. Levels are in dB.
pub fn compress_gains(
  detect: [float],
  rate: int,
  threshold: float,
  ratio: float,
  knee: float,
  attack: float,
  release: float,
  makeup: float,
  rms: bool,
): [float] {
  let ca = step(attack, rate)
  let cr = step(release, rate)
  var env = 0.0
  var out: [float] = []
  for x in detect {
    let v = if rms { x * x } else { x }
    env += (v - env) * if v > env { ca } else { cr }
    let level = if rms { sqrt(env) } else { env }
    out.push(undb(curve(db(level), threshold, ratio, knee) + makeup))
  }
  out
}

/// The gain each sample gets from a lookahead brickwall limiter: no sample of `detect` times
/// its gain goes over `limit`. The gain falls over `attack` seconds before a peak and recovers
/// over `release` seconds after it.
pub fn limit_gains(
  detect: [float],
  rate: int,
  limit: float,
  attack: float,
  release: float,
): [float] {
  let n = detect.len()
  let la = if samples(attack, rate) < 1 { 1 } else { samples(attack, rate) }
  let need = detect.map(x => if x > limit { limit / x } else { 1.0 })
  // the least gain needed anywhere in the next `la` samples (a sliding-window minimum)
  var held = audio.pcm.zeros(n)
  var dq: [int] = []
  var head = 0
  var j = 0
  for i in 0..n {
    while j < n && j <= i + la {
      while dq.len() > head && need[dq[dq.len() - 1]] >= need[j] { dq.pop() }
      dq.push(j)
      j += 1
    }
    while dq[head] < i { head += 1 }
    held[i] = need[dq[head]]
  }
  // recover slowly after a peak, never above what's held
  let cr = coef(release, rate)
  var r = 1.0
  for i in 0..n {
    r = cr * r + (1.0 - cr) * held[i]
    if r > held[i] { r = held[i] }
    held[i] = r
  }
  // a moving average over the lookahead ramps the gain down smoothly before each peak, and
  // stays at or below every sample's need (the window ending at a peak holds only values <= it)
  var out: [float] = []
  var sum = 0.0
  for i in 0..n {
    sum += held[i]
    if i > la { sum -= held[i - la - 1] }
    // before the window fills, pad with the first held value
    let pad = if i < la { float(la - i) * held[0] } else { 0.0 }
    out.push((sum + pad) / float(la + 1))
  }
  out
}

// Cubic Hermite interpolation between (x0, p0) and (x1, p1) with slopes m0 and m1.
fn hermite(x: float, x0: float, x1: float, p0: float, p1: float, m0: float, m1: float): float {
  let w = x1 - x0
  let t = (x - x0) / w
  let (a, b) = (m0 * w, m1 * w)
  let c2 = -3.0 * p0 - 2.0 * a + 3.0 * p1 - b
  let c3 = 2.0 * p0 + a - 2.0 * p1 + b
  c3 * t * t * t + c2 * t * t + a * t + p0
}

/// The gain a noise gate applies, as ffmpeg's agate (downward mode): an envelope of the level
/// (or of its square, for `rms`) with ffmpeg's attack and release; below the threshold the gain
/// falls along `ratio` in the envelope's log domain, through a Hermite knee spanning `threshold`
/// times or divided by sqrt(`knee`), never below `range`. Threshold, knee and range are linear.
pub fn gate_gains(
  detect: [float],
  rate: int,
  threshold: float,
  ratio: float,
  knee: float,
  range: float,
  attack: float,
  release: float,
  rms: bool,
): [float] {
  let ca = step(attack, rate)
  let cr = step(release, rate)
  let lt = if rms { threshold * threshold } else { threshold }
  let thres = ln(lt)
  let lin_stop = lt * sqrt(knee)
  let kstart = ln(lt / sqrt(knee))
  let kstop = ln(lin_stop)
  var env = 0.0
  var out: [float] = []
  for x in detect {
    let v = if rms { x * x } else { x }
    env += (v - env) * if v > env { ca } else { cr }
    var g = 1.0
    if env > 0.0 && env < lin_stop {
      let slope = ln(env)
      var gain = (slope - thres) * ratio + thres
      if knee > 1.0 && slope > kstart {
        gain = hermite(slope, kstart, kstop, (kstart - thres) * ratio + thres, kstop, ratio, 1.0)
      }
      g = exp(gain - slope)
      if g < range { g = range }
    }
    out.push(g)
  }
  out
}

// ---- fades ----

pub enum Curve { Linear, QuarterSine, HalfSine, Log, Exp, Square, Cube }

/// The gain at `t` (0..1) through a fade-in.
pub fn shape(c: Curve, t0: float): float {
  let t = if t0 < 0.0 { 0.0 } else if t0 > 1.0 { 1.0 } else { t0 }
  match c {
    Linear => t
    QuarterSine => sin(t * float.pi / 2.0)
    HalfSine => (1.0 - cos(t * float.pi)) / 2.0
    Log => if t <= 0.0 { 0.0 } else { max0(1.0 + log10(t) / 3.0) }
    Exp => if t <= 0.0 { 0.0 } else { 10.0 ** (3.0 * (t - 1.0)) }
    Square => t * t
    Cube => t * t * t
  }
}

fn max0(x: float): float = if x < 0.0 { 0.0 } else { x }

pub fn curve_named(s: str): Curve? = match s {
  "tri" => some(Linear)
  "linear" => some(Linear)
  "qsin" => some(QuarterSine)
  "hsin" => some(HalfSine)
  "log" => some(Log)
  "exp" => some(Exp)
  "squ" => some(Square)
  "cub" => some(Cube)
  _ => none
}

/// Fades `xs` in (or out) over `len` samples starting at sample `start`: before a fade-in is
/// silence, after a fade-out too.
pub fn fade(xs: [float], fade_in: bool, start: int, len: int, c: Curve): [float] {
  var out = xs
  for i in 0..xs.len() {
    let t = if len <= 0 {
      if i >= start { 1.0 } else { 0.0 }
    } else {
      float(i - start) / float(len)
    }
    let g = if fade_in { shape(c, t) } else { shape(c, 1.0 - t) }
    if g != 1.0 { out[i] = xs[i] * g }
  }
  out
}

// ---- time stretching (WSOLA) ----

/// Positions in the input where each output frame of a WSOLA stretch starts: frames of `win`
/// samples, written every `win / 2`, read every `win / 2 * tempo` and nudged by up to `search`
/// samples to line up with the previous frame. `guide` is a mono mix used to line frames up.
pub fn wsola_plan(guide: [float], tempo: float, win: int, search: int): [int] {
  let hop = win / 2
  let n = guide.len()
  var starts: [int] = [0]
  var k = 1
  loop {
    let nominal = int(round(float(k) * float(hop) * tempo))
    if nominal >= n { break }
    // the natural continuation of the previous frame
    let target = starts[k - 1] + hop
    var best = nominal
    if target + hop <= n {
      // coarse search every 4 samples, then refine around the best
      best = align(guide, target, hop, nominal - search, nominal + search, 4, 8, nominal)
      best = align(guide, target, hop, best - 3, best + 3, 1, 2, best)
    }
    starts.push(best)
    k += 1
  }
  starts
}

// The start in lo..=hi (every `step`) whose `hop` samples best match those at `target`, by
// normalized cross-correlation over every `stride`-th sample.
fn align(
  g: [float],
  target: int,
  hop: int,
  lo: int,
  hi: int,
  step: int,
  stride: int,
  dflt: int,
): int {
  let n = g.len()
  var best = dflt
  var best_score = -1.0e300
  var p = lo
  while p <= hi {
    if p >= 0 && p + hop <= n {
      var s = 0.0
      var e = 0.0
      var i = 0
      while i < hop {
        let x = g[p + i]
        s += x * g[target + i]
        e += x * x
        i += stride
      }
      let score = if e > 0.0 { s / sqrt(e) } else { 0.0 }
      if score > best_score {
        best_score = score
        best = p
      }
    }
    p += step
  }
  best
}

/// Overlap-adds Hann-windowed frames of `xs` from `starts`, one every `win / 2` samples.
pub fn wsola_apply(xs: [float], starts: [int], win: int, len: int): [float] {
  let hop = win / 2
  var out = audio.pcm.zeros(starts.len() * hop + win)
  var norm = audio.pcm.zeros(starts.len() * hop + win)
  let w = (0..win).map(i => 0.5 - 0.5 * cos(2.0 * float.pi * float(i) / float(win)))
  for k in 0..starts.len() {
    let p = starts[k]
    let o = k * hop
    for i in 0..win {
      let x = xs.get(p + i) else 0.0
      out[o + i] = out[o + i] + x * w[i]
      norm[o + i] = norm[o + i] + w[i]
    }
  }
  var res: [float] = []
  for i in 0..len {
    let nv = norm.get(i) else 0.0
    res.push(if nv > 1.0e-6 { out[i] / nv } else { 0.0 })
  }
  res
}