packages /

audio 0.1.0

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

files / src/lib.auk 36.2 kB · 987 lines

/// Audio in pure Auk, at the level of ffmpeg's audio side: decode and encode WAV, AIFF/AIFC,
/// AU and FLAC (with PCM, float, G.711 and ADPCM codecs), probe files, resample, remix
/// channels, filter (biquads, EQ, echo, dynamics, fades, time stretch), measure (stats, EBU R128
/// loudness, true peak, spectra, silence) and generate signals. Filter graphs use ffmpeg's `-af`
/// syntax: `a.apply("highpass=f=80,loudnorm=I=-16")`.
///
/// Pure: no effects. Bytes are `[int]` (0–255) as in `fs.read_bytes`. Samples are planar floats,
/// nominally -1.0..1.0; integer formats clip outside that when encoded.

/// Decoded audio: `chans[c][i]` is frame `i` of channel `c`; every channel has the same length.
/// `tags` holds metadata with lowercase keys (`title`, `artist`, `album`, `comment`, ...).
pub struct Audio { rate: int, chans: [[float]], tags: {str: str} }

/// Why decoding, encoding or a filter graph failed.
pub enum AErr {
  Truncated(what: str),    // the input ended early
  Unsupported(what: str),  // a valid file in a format or codec this library doesn't handle
  Corrupt(why: str),       // malformed data
  BadArg(why: str),        // an invalid argument or filter graph
}

/// A one-line description, e.g. `unsupported: MP3`.
pub fn message(e: AErr): str
fn message(Truncated(what)): str = "truncated: {what}"
fn message(Unsupported(what)): str = "unsupported: {what}"
fn message(Corrupt(why)): str = "corrupt: {why}"
fn message(BadArg(why)): str = "bad argument: {why}"

/// Sample formats. `Ima` is 4-bit IMA ADPCM (WAV only).
pub enum Fmt { U8, S8, S16, S24, S32, F32, F64, Alaw, Ulaw, Ima }

/// File formats this library writes.
pub enum Container { Wav, Aiff, Au, Flac }

/// What `probe` finds without decoding the samples.
pub struct Info {
  container: str,  // "wav", "aiff", "aifc", "au" or "flac"
  codec: str,      // ffmpeg's codec name: "pcm_s16le", "pcm_f32be", "adpcm_ima_wav", "flac", ...
  rate: int,
  channels: int,
  frames: int,  // per channel (0 when a FLAC stream doesn't say)
  bits: int,    // bits per sample
  tags: {str: str},
}

pub fn duration(i: Info): float = if i.rate > 0 { float(i.frames) / float(i.rate) } else { 0.0 }

/// ffmpeg's name for a sample format's codec: `codec_name(S16, false) == "pcm_s16le"`.
pub fn codec_name(f: Fmt, big: bool): str {
  let e = if big { "be" } else { "le" }
  match f {
    U8 => "pcm_u8"
    S8 => "pcm_s8"
    S16 => "pcm_s16{e}"
    S24 => "pcm_s24{e}"
    S32 => "pcm_s32{e}"
    F32 => "pcm_f32{e}"
    F64 => "pcm_f64{e}"
    Alaw => "pcm_alaw"
    Ulaw => "pcm_mulaw"
    Ima => "adpcm_ima_wav"
  }
}

/// A sample format by ffmpeg's `-sample_fmt` or codec name: `u8 s16 s24 s32 flt dbl`, `f32`,
/// `pcm_s24le`, `alaw`, `mulaw`/`ulaw`, `ima`/`adpcm_ima_wav`.
pub fn fmt_named(s: str): Fmt? {
  let t = s.lower()
  let base = if t.starts_with("pcm_") { t[4..t.len()] } else { t }
  let core = if base.ends_with("le") || base.ends_with("be") {
    base[0..base.len() - 2]
  } else {
    base
  }
  match core {
    "u8" => some(U8)
    "s8" => some(S8)
    "s16" => some(S16)
    "s16p" => some(S16)
    "s24" => some(S24)
    "s32" => some(S32)
    "s32p" => some(S32)
    "flt" => some(F32)
    "fltp" => some(F32)
    "f32" => some(F32)
    "dbl" => some(F64)
    "dblp" => some(F64)
    "f64" => some(F64)
    "alaw" => some(Alaw)
    "mulaw" => some(Ulaw)
    "ulaw" => some(Ulaw)
    "ima" => some(Ima)
    "adpcm_ima_wav" => some(Ima)
    _ => none
  }
}

/// The container for a file name's extension: `.wav`, `.aif`/`.aiff`/`.aifc`, `.au`/`.snd`,
/// `.flac`.
pub fn container_for(path: str): Container? {
  let p = path.lower()
  if p.ends_with(".wav") || p.ends_with(".wave") {
    some(Wav)
  } else if p.ends_with(".aif") || p.ends_with(".aiff") || p.ends_with(".aifc") {
    some(Aiff)
  } else if p.ends_with(".au") || p.ends_with(".snd") {
    some(Au)
  } else if p.ends_with(".flac") {
    some(Flac)
  } else {
    none
  }
}

// ---- reading and writing ----

// What the first bytes say the file is.
fn sniff(d: [int]): str {
  let t = audio.pcm.tag(d, 0)
  if (t == "RIFF" || t == "RF64") && audio.pcm.tag(d, 8) == "WAVE" { return "wav" }
  if t == "FORM" && (audio.pcm.tag(d, 8) == "AIFF" || audio.pcm.tag(d, 8) == "AIFC") {
    return "aiff"
  }
  if t == ".snd" { return "au" }
  let skip = audio.flac.id3_offset(d)
  if audio.pcm.tag(d, skip) == "fLaC" { return "flac" }
  if t == "OggS" { return "Ogg" }
  if t.starts_with("ID3") || (d.len() >= 2 && d[0] == 0xff && (d[1] & 0xe0) == 0xe0) {
    return "MP3"
  }
  if d.len() >= 8 && audio.pcm.tag(d, 4) == "ftyp" { return "MP4/M4A" }
  if d.len() >= 4 && d[0] == 0x1a && d[1] == 0x45 && d[2] == 0xdf && d[3] == 0xa3 {
    return "Matroska/WebM"
  }
  ""
}

/// Header information: format, codec, rate, channels, length and tags.
pub fn probe(d: [int]): Info!AErr = match sniff(d) {
  "wav" => audio.wav.probe(d)
  "aiff" => audio.aiff.probe(d)
  "au" => audio.aiff.au_probe(d)
  "flac" => audio.flac.probe(d)
  "" => fail(Unsupported("unknown file format"))
  other => fail(Unsupported(other))
}

/// Decodes a WAV, AIFF/AIFC, AU or FLAC file, recognized by its contents.
pub fn decode(d: [int]): Audio!AErr = match sniff(d) {
  "wav" => audio.wav.decode(d)
  "aiff" => audio.aiff.decode(d)
  "au" => audio.aiff.au_decode(d)
  "flac" => audio.flac.decode(d)
  "" => fail(Unsupported("unknown file format"))
  other => fail(Unsupported(other))
}

/// Encodes as a complete file. FLAC takes U8/S8 (stored as 8-bit), S16 or S24; WAV anything but
/// S8; AIFF the signed and float formats and G.711; AU the same.
pub fn encode(a: Audio, c: Container, f: Fmt): [int]!AErr {
  valid(a)?
  match c {
    Wav => audio.wav.encode(a, f)
    Aiff => audio.aiff.encode(a, f)
    Au => audio.aiff.au_encode(a, f)
    Flac => match f {
      U8 => audio.flac.encode(a, 8)
      S8 => audio.flac.encode(a, 8)
      S16 => audio.flac.encode(a, 16)
      S24 => audio.flac.encode(a, 24)
      _ => fail(Unsupported("FLAC with {codec_name(f, false)} samples; use S16 or S24"))
    }
  }
}

fn valid(a: Audio): ()!AErr {
  if a.chans.len() == 0 { fail(BadArg("audio has no channels")) }
  if a.rate < 1 { fail(BadArg("sample rate {a.rate}")) }
  let n = a.chans[0].len()
  if a.chans.any(ch => ch.len() != n) { fail(BadArg("channels have different lengths")) }
}

// ---- making audio ----

/// Audio from planar samples, with no tags.
pub fn new(rate: int, chans: [[float]]): Audio = Audio { rate, chans, tags: {} }

/// `secs` of silence.
pub fn silence(secs: float, rate: int, nch: int): Audio
  requires nch >= 1
{
  let n = audio.fx.samples(secs, rate)
  new(rate, (0..nch).map(_ => audio.pcm.zeros(n)))
}

/// A mono sine wave.
pub fn sine(freq: float, secs: float, rate: int): Audio =
  tone(audio.gen.Sine, freq, secs, rate, 1.0)

/// A mono periodic wave at amplitude `amp`.
pub fn tone(w: audio.gen.Wave, freq: float, secs: float, rate: int, amp: float): Audio =
  new(rate, [audio.gen.wave(w, freq, amp, audio.fx.samples(secs, rate), rate)])

/// A mono sine sweep from `f0` to `f1` Hz (exponential when `log`).
pub fn chirp(f0: float, f1: float, secs: float, rate: int, log: bool): Audio =
  new(rate, [audio.gen.chirp(f0, f1, 1.0, audio.fx.samples(secs, rate), rate, log)])

/// Mono noise; the same seed gives the same samples.
pub fn noise(c: audio.gen.Color, secs: float, rate: int, amp: float, seed: int): Audio =
  new(rate, [audio.gen.noise(c, amp, audio.fx.samples(secs, rate), seed)])

/// A source in ffmpeg's lavfi syntax: `sine=frequency=440:duration=2`,
/// `anoisesrc=color=pink:d=5:a=0.3:seed=7`, `anullsrc=r=48000:cl=stereo:d=1`, plus
/// `square`, `sawtooth`, `triangle` (like `sine`) and `chirp=f0=20:f1=20000:d=5`.
pub fn source(spec: str): Audio!AErr = audio.graph.source(spec)

// ---- basic facts ----

pub fn frames(a: Audio): int = if a.chans.len() == 0 { 0 } else { a.chans[0].len() }
pub fn nch(a: Audio): int = a.chans.len()
pub fn duration(a: Audio): float = float(a.frames()) / float(a.rate)

// Applies `f` to each channel.
fn each(a: Audio, f: ([float]) => [float]): Audio = Audio { chans: a.chans.map(f), ..a }

// ---- levels ----

pub fn db_to_gain(db: float): float = audio.fx.undb(db)
pub fn gain_to_db(g: float): float = audio.fx.db(g)

/// Every sample times `g`.
pub fn gain(a: Audio, g: float): Audio = a.each(ch => ch.map(x => x * g))

/// Louder or quieter by `db` decibels.
pub fn gain_db(a: Audio, db: float): Audio = a.gain(audio.fx.undb(db))

/// Scaled so the peak sample is at `peak_db` dBFS (silence stays silent).
pub fn normalize(a: Audio, peak_db: float): Audio {
  let p = a.chans.map(ch => audio.analyze.stats(ch).peak).max() else 0.0
  if p <= 0.0 { a } else { a.gain(audio.fx.undb(peak_db) / p) }
}

/// Scaled to `lufs` integrated loudness (EBU R128), then limited so the true peak stays under
/// `tp_db` dBTP: ffmpeg's `loudnorm` in linear mode.
pub fn loudnorm(a: Audio, lufs: float, tp_db: float): Audio {
  let l = a.loudness()
  if l.integrated <= -70.0 { return a }
  let g = a.gain_db(lufs - l.integrated)
  // the limiter works on samples; leave room for inter-sample peaks
  let tp = audio.analyze.true_peak(g.chans, g.rate)
  if audio.fx.db(tp) <= tp_db { g } else { g.limit(tp_db - 0.3, 0.005, 0.05) }
}

/// Clamps every sample to -1.0..1.0.
pub fn clip(a: Audio): Audio =
  a.each(ch => ch.map(x => if x > 1.0 { 1.0 } else if x < -1.0 { -1.0 } else { x }))

/// Adds `d` to every sample.
pub fn dc_shift(a: Audio, d: float): Audio = a.each(ch => ch.map(x => x + d))

// ---- time ----

fn at(a: Audio, secs: float): int {
  let i = audio.fx.samples(secs, a.rate)
  if i > a.frames() { a.frames() } else { i }
}

/// The part from `start` to `end` seconds (`end` < 0: to the end).
pub fn trim(a: Audio, start: float, end: float): Audio {
  let s = a.at(start)
  let e = if end < 0.0 { a.frames() } else { a.at(end) }
  if e <= s { a.each(_ => []) } else { a.each(ch => ch[s..e]) }
}

/// `secs` of silence added at the end.
pub fn pad(a: Audio, secs: float): Audio {
  let z = audio.pcm.zeros(audio.fx.samples(secs, a.rate))
  a.each(ch => ch + z)
}

/// `secs` of silence added at the start.
pub fn delay(a: Audio, secs: float): Audio = a.each(ch => audio.fx.delay(ch, secs, a.rate))

/// Each channel delayed by its own amount (ffmpeg's adelay); missing entries are 0.
pub fn delay_each(a: Audio, secs: [float]): Audio {
  let ds = (0..a.nch()).map(c => audio.fx.samples(secs.get(c) else 0.0, a.rate))
  let longest = ds.max() else 0
  Audio {
    chans: (0..a.nch()).map(
      c => audio.pcm.zeros(ds[c]) + a.chans[c] + audio.pcm.zeros(longest - ds[c]),
    ),
    ..a,
  }
}

pub fn reverse(a: Audio): Audio = a.each(ch => ch.reverse())

/// Fades in over the first `secs`.
pub fn fade_in(a: Audio, secs: float): Audio = a.fade(true, 0.0, secs, audio.fx.Linear)

/// Fades out over the last `secs`.
pub fn fade_out(a: Audio, secs: float): Audio =
  a.fade(false, a.duration() - secs, secs, audio.fx.Linear)

/// A fade (in or out) starting at `start` seconds and lasting `secs`, with curve `c`
/// (ffmpeg's afade).
pub fn fade(a: Audio, fade_in: bool, start: float, secs: float, c: audio.fx.Curve): Audio {
  let s = audio.fx.samples(start, a.rate)
  let n = audio.fx.samples(secs, a.rate)
  a.each(ch => audio.fx.fade(ch, fade_in, s, n, c))
}

/// Joins clips end to end. They must share a rate and channel count.
pub fn concat(xs: [Audio]): Audio!AErr {
  let [first, ..rest] = xs else fail(BadArg("concat of nothing"))
  var chans = first.chans
  for x in rest {
    if x.rate != first.rate || x.nch() != first.nch() {
      fail(
        BadArg("concat needs the same rate and channels: {first.rate} Hz x{first.nch()} vs {x.rate} Hz x{x.nch()}"),
      )
    }
    for c in 0..chans.len() {
      for v in x.chans[c] { chans[c].push(v) }
    }
  }
  Audio { chans, ..first }
}

/// `b` added onto `a` starting at `at` seconds; the result is as long as both need. They must
/// share a rate and channel count.
pub fn overlay(a: Audio, b: Audio, at: float): Audio!AErr {
  if a.rate != b.rate || a.nch() != b.nch() {
    fail(
      BadArg("overlay needs the same rate and channels: {a.rate} Hz x{a.nch()} vs {b.rate} Hz x{b.nch()}"),
    )
  }
  let off = audio.fx.samples(at, a.rate)
  let n = if off + b.frames() > a.frames() { off + b.frames() } else { a.frames() }
  var chans = a.chans.map(ch => ch + audio.pcm.zeros(n - ch.len()))
  for c in 0..chans.len() {
    for i in 0..b.frames() { chans[c][off + i] = chans[c][off + i] + b.chans[c][i] }
  }
  Audio { chans, ..a }
}

/// The sum of several clips, each scaled by 1/n so it can't clip more than the loudest input
/// (ffmpeg's amix); converts rates and channel counts to the first clip's.
pub fn mix(xs: [Audio]): Audio!AErr {
  let [first, ..] = xs else fail(BadArg("mix of nothing"))
  var out = first.gain(1.0 / float(xs.len()))
  for x in xs.skip(1) {
    let y = x.resample(first.rate).remix(first.nch()).gain(1.0 / float(xs.len()))
    out = out.overlay(y, 0.0)?
  }
  out
}

/// Plays faster (`factor` > 1) or slower without changing pitch (ffmpeg's atempo), by WSOLA
/// with 40 ms frames.
pub fn tempo(a: Audio, factor: float): Audio
  requires factor > 0.0
{
  if factor == 1.0 || a.frames() == 0 { return a }
  // 40 ms frames (an even number of samples), aligned within +-12 ms
  let win = 2 * (audio.fx.samples(0.02, a.rate) + 1)
  let guide = a.mono().chans[0]
  let starts = audio.fx.wsola_plan(guide, factor, win, audio.fx.samples(0.012, a.rate))
  let len = int(round(float(a.frames()) / factor))
  a.each(ch => audio.fx.wsola_apply(ch, starts, win, len))
}

/// Shifts the pitch by `semitones` keeping the duration: resample, then stretch back.
pub fn pitch(a: Audio, semitones: float): Audio {
  if semitones == 0.0 { return a }
  let ratio = 2.0 ** (semitones / 12.0)
  // play `ratio` times faster (higher), then stretch back to the original length
  let fast = Audio { rate: int(round(float(a.rate) * ratio)), ..a }.resample(a.rate)
  fast.tempo(1.0 / ratio)
}

/// The same samples labelled with a new rate: faster and higher, or slower and lower
/// (ffmpeg's asetrate).
pub fn set_rate(a: Audio, rate: int): Audio
  requires rate > 0
{ Audio { rate, ..a } }

/// Converts to `rate` Hz (band-limited sinc interpolation).
pub fn resample(a: Audio, rate: int): Audio
  requires rate > 0
{
  if rate == a.rate { return a }
  Audio { rate, chans: a.chans.map(ch => audio.resample.resample(ch, a.rate, rate)), ..a }
}

// ---- channels ----

/// The mean of all channels, as one.
pub fn mono(a: Audio): Audio {
  if a.nch() == 1 { return a }
  a.pan([(0..a.nch()).map(_ => 1.0 / float(a.nch()))])
}

/// Mixes channels by a matrix: output channel `o` is the sum of `m[o][i] * input i` (ffmpeg's
/// pan filter).
pub fn pan(a: Audio, m: [[float]]): Audio {
  let n = a.frames()
  let chans = m.map(row => {
    var out = audio.pcm.zeros(n)
    for i in 0..row.len() {
      let g = row[i]
      if g != 0.0 && i < a.nch() {
        let ch = a.chans[i]
        for k in 0..n { out[k] = out[k] + g * ch[k] }
      }
    }
    out
  })
  Audio { chans, ..a }
}

/// Converts to `n` channels: mono is copied to the front left and right, stereo to mono is the
/// mean (ffmpeg uses 0.707 per channel, which can clip), 5.1 and quad fold down to stereo with
/// -3 dB centre and surrounds (normalized so no output can clip); otherwise channels are dropped
/// or silent ones added.
pub fn remix(a: Audio, n: int): Audio
  requires n >= 1
{
  let k = a.nch()
  if n == k { return a }
  let h = 0.7071067811865476
  if k == 1 { return a.pan((0..n).map(o => if o < 2 || n == 1 { [1.0] } else { [0.0] })) }
  if n == 1 && k == 2 { return a.mono() }
  if n == 2 && (k == 6 || k == 5) {
    // L R C LFE Ls Rs (or L R C Ls Rs)
    let s = if k == 6 { 4 } else { 3 }
    var l = audio.pcm.zeros(k)
    var r = audio.pcm.zeros(k)
    l[0] = 1.0
    l[2] = h
    l[s] = h
    r[1] = 1.0
    r[2] = h
    r[s + 1] = h
    let norm = 1.0 / (1.0 + 2.0 * h)
    return a.pan([l.map(g => g * norm), r.map(g => g * norm)])
  }
  if n == 2 && k == 4 {
    let norm = 1.0 / (1.0 + h)
    return a.pan([[norm, 0.0, h * norm, 0.0], [0.0, norm, 0.0, h * norm]])
  }
  if n == 1 { return a.remix(2).mono() }
  a.pan((0..n).map(o => (0..k).map(i => if i == o { 1.0 } else { 0.0 })))
}

/// Channel `c` alone, as mono.
pub fn channel(a: Audio, c: int): Audio
  requires c >= 0 && c < a.nch()
{ Audio { chans: [a.chans[c]], ..a } }

/// Widens (`m` > 1) or narrows (`m` < 1) a stereo image around its mid (ffmpeg's extrastereo).
pub fn widen(a: Audio, m: float): Audio {
  if a.nch() != 2 { return a }
  let n = a.frames()
  var l = a.chans[0]
  var r = a.chans[1]
  for i in 0..n {
    let mid = (a.chans[0][i] + a.chans[1][i]) / 2.0
    l[i] = mid + m * (a.chans[0][i] - mid)
    r[i] = mid + m * (a.chans[1][i] - mid)
  }
  Audio { chans: [l, r], ..a }
}

// ---- filters ----

/// Any RBJ biquad on every channel.
pub fn biquad(a: Audio, kind: audio.fx.Kind, freq: float, q: float, gain_db: float): Audio {
  let f = audio.fx.design(kind, freq, q, gain_db, a.rate)
  a.each(ch => audio.fx.biquad(ch, f))
}

/// Two-pole low-pass at `freq` Hz (Butterworth, Q 0.707).
pub fn lowpass(a: Audio, freq: float): Audio =
  a.biquad(audio.fx.Lowpass, freq, 0.7071067811865476, 0.0)

/// Two-pole high-pass at `freq` Hz (Butterworth, Q 0.707).
pub fn highpass(a: Audio, freq: float): Audio =
  a.biquad(audio.fx.Highpass, freq, 0.7071067811865476, 0.0)

/// Band-pass around `freq` Hz (constant 0 dB peak gain).
pub fn bandpass(a: Audio, freq: float, q: float): Audio = a.biquad(audio.fx.Bandpass, freq, q, 0.0)

/// Removes a narrow band around `freq` Hz (mains hum: `notch(50.0, 10.0)`).
pub fn notch(a: Audio, freq: float, q: float): Audio = a.biquad(audio.fx.Notch, freq, q, 0.0)

/// A peaking EQ band: `gain_db` at `freq` Hz, width set by `q`.
pub fn eq(a: Audio, freq: float, q: float, gain_db: float): Audio =
  a.biquad(audio.fx.Peak, freq, q, gain_db)

/// Boosts or cuts below `freq` Hz (ffmpeg's bass/lowshelf).
pub fn bass(a: Audio, gain_db: float, freq: float): Audio =
  a.biquad(audio.fx.LowShelf, freq, 0.7071067811865476, gain_db)

/// Boosts or cuts above `freq` Hz (ffmpeg's treble/highshelf).
pub fn treble(a: Audio, gain_db: float, freq: float): Audio =
  a.biquad(audio.fx.HighShelf, freq, 0.7071067811865476, gain_db)

/// ffmpeg's aecho: delays in seconds, each with its decay; `in_gain` and `out_gain` scale the
/// dry signal and the sum. The result is longer by the longest delay.
pub fn echo(a: Audio, in_gain: float, out_gain: float, delays: [float], decays: [float]): Audio
  requires delays.len() == decays.len()
{ a.each(ch => audio.fx.echo(ch, a.rate, in_gain, out_gain, delays, decays)) }

/// Amplitude modulation at `freq` Hz; `depth` 0..1 (ffmpeg's tremolo).
pub fn tremolo(a: Audio, freq: float, depth: float): Audio {
  let n = a.frames()
  let g = (0..n).map(
    i => 1.0 - depth / 2.0 + depth / 2.0 * cos(2.0 * float.pi * freq * float(i) / float(a.rate)),
  )
  a.each(ch => (0..ch.len()).map(i => ch[i] * g[i]))
}

// ---- dynamics ----

// The mean |sample| over channels at each frame, as ffmpeg's link=average (channels share one
// gain, so the stereo image holds).
fn detector_avg(a: Audio): [float] {
  let n = a.frames()
  var d = audio.pcm.zeros(n)
  for ch in a.chans {
    for i in 0..n { d[i] = d[i] + abs(ch[i]) / float(a.nch()) }
  }
  d
}

// The loudest channel's |sample| at each frame.
fn detector(a: Audio): [float] {
  let n = a.frames()
  var d = audio.pcm.zeros(n)
  for ch in a.chans {
    for i in 0..n { if abs(ch[i]) > d[i] { d[i] = abs(ch[i]) } }
  }
  d
}

fn apply_gains(a: Audio, g: [float]): Audio = a.each(ch => (0..ch.len()).map(i => ch[i] * g[i]))

/// Settings for `compress`: levels in dB, times in seconds.
pub struct Comp {
  threshold: float,  // where reduction starts
  ratio: float,      // 4.0 = 4 dB over the threshold comes out as 1 dB over
  knee: float,       // soft knee width
  attack: float,
  release: float,
  makeup: float,  // gain added after
  rms: bool,      // detect RMS level (true) or peaks
}

/// ffmpeg's acompressor defaults: threshold -18 dB, ratio 2, knee 9 dB, attack 20 ms,
/// release 250 ms, no makeup, RMS detection.
pub let COMP = Comp {
  threshold: -18.0,
  ratio: 2.0,
  knee: 9.0,
  attack: 0.02,
  release: 0.25,
  makeup: 0.0,
  rms: true,
}

/// A feed-forward compressor, with one gain for all channels.
pub fn compress(a: Audio, c: Comp): Audio
  requires c.ratio >= 1.0
{
  a.apply_gains(
    audio.fx.compress_gains(
      a.detector_avg(),
      a.rate,
      c.threshold,
      c.ratio,
      c.knee,
      c.attack,
      c.release,
      c.makeup,
      c.rms,
    ),
  )
}

/// A lookahead brickwall limiter: no sample exceeds `ceiling_db` dBFS. The gain ramps down over
/// `attack` seconds before a peak and recovers over `release` after.
pub fn limit(a: Audio, ceiling_db: float, attack: float, release: float): Audio = a.apply_gains(
  audio.fx.limit_gains(a.detector(), a.rate, audio.fx.undb(ceiling_db), attack, release),
)

/// A noise gate (ffmpeg's agate with its defaults: RMS detection, a 9 dB soft knee): below
/// `threshold_db` the level is pushed down by `ratio`, by at most `range_db` dB.
pub fn gate(
  a: Audio,
  threshold_db: float,
  ratio: float,
  range_db: float,
  attack: float,
  release: float,
): Audio
  requires ratio >= 1.0
{
  let g = audio.fx.gate_gains(
    a.detector_avg(),
    a.rate,
    audio.fx.undb(threshold_db),
    ratio,
    2.828427125,
    audio.fx.undb(-abs(range_db)),
    attack,
    release,
    true,
  )
  a.apply_gains(g)
}

// ---- measuring ----

/// Per-channel statistics (ffmpeg's astats and volumedetect).
pub fn stats(a: Audio): [audio.analyze.Stats] = a.chans.map(ch => audio.analyze.stats(ch))

/// The largest |sample| over all channels.
pub fn peak(a: Audio): float = a.chans.map(ch => audio.analyze.stats(ch).peak).max() else 0.0

/// EBU R128 loudness (integrated, range, maxima, true peak), as ffmpeg's ebur128 filter.
pub fn loudness(a: Audio): audio.analyze.Loudness = audio.analyze.loudness(a.chans, a.rate)

/// The magnitude spectrum of the mono mix, in dBFS, `size / 2 + 1` bins up to Nyquist.
pub fn spectrum(a: Audio, size: int): [float] = audio.analyze.spectrum(a.mono().chans[0], size)

/// The strongest frequency (Hz) in the mono mix.
pub fn dominant(a: Audio): float = audio.analyze.dominant(a.mono().chans[0], a.rate)

/// Silent spans, (start, end) in seconds: every channel below `threshold_db` for at least
/// `min_secs` (ffmpeg's silencedetect).
pub fn silences(a: Audio, threshold_db: float, min_secs: float): [(float, float)] =
  audio.analyze.silences(a.chans, a.rate, threshold_db, min_secs)

/// Leading and trailing silence (below `threshold_db` on every channel) removed.
pub fn trim_silence(a: Audio, threshold_db: float): Audio = match audio.analyze.sound_bounds(
  a.chans,
  threshold_db,
) {
  some((s, e)) => a.each(ch => ch[s..e])
  none => a.each(_ => [])
}

// ---- filter graphs ----

/// Runs a filter chain written as ffmpeg's `-af`: `volume=-3dB,highpass=f=80,aresample=48000`.
/// See the README for the filters and options supported.
pub fn apply(a: Audio, graph: str): Audio!AErr = audio.graph.apply(a, graph)

// ---- tests ----

fn unhex(h: str): [int] = h.chars().chunks(2).map(p => hexdigit(p[0]) * 16 + hexdigit(p[1]))

fn hexdigit(c: char): int = if c.is_digit() { int(c) - 48 } else { int(c) - 87 }

fn tohex(bs: [int]): str = bs.map(b => {
  let d = "0123456789abcdef"
  str([d[b >> 4], d[b & 15]])
}).join("")

// A stereo test signal: a sine and a sawtooth, 1000 frames at 8 kHz.
fn sig(): Audio = new(8000, [
  audio.gen.wave(audio.gen.Sine, 440.0, 0.5, 1000, 8000),
  audio.gen.wave(audio.gen.Sawtooth, 300.0, 0.4, 1000, 8000),
])

fn max_err(a: Audio, b: Audio): float {
  var m = 0.0
  for c in 0..a.nch() {
    for i in 0..a.frames() {
      m = if abs(a.chans[c][i] - b.chans[c][i]) > m {
        abs(a.chans[c][i] - b.chans[c][i])
      } else {
        m
      }
    }
  }
  m
}

// The signal as it reads back from `bits`-bit integers.
fn quantized(a: Audio, bits: int): Audio =
  a.each(ch => ch.map(x => float(audio.pcm.quant(x, bits)) / float(1 << (bits - 1))))

test "WAV round trips every format" {
  let a = sig()
  for (f, codec, tol) in [
    (U8, "pcm_u8", 0.004),
    (S16, "pcm_s16le", 0.00002),
    (S24, "pcm_s24le", 0.0000001),
    (S32, "pcm_s32le", 0.000000001),
    (F32, "pcm_f32le", 0.0000001),
    (F64, "pcm_f64le", 0.0),
    (Alaw, "pcm_alaw", 0.02),
    (Ulaw, "pcm_mulaw", 0.02),
    (Ima, "adpcm_ima_wav", 1.0),
  ] {
    let bs = encode(a, Wav, f)?
    let i = probe(bs)?
    assert (i.container, i.codec, i.rate, i.channels, i.frames) == ("wav", codec, 8000, 2, 1000)
    let b = decode(bs)?
    assert b.frames() == 1000
    assert max_err(a, b) <= tol
  }
  // ADPCM tracks a sine closely (it can't follow the sawtooth's jumps)
  let s = sine(440.0, 0.2, 8000).gain(0.5)
  assert max_err(s.trim(0.01, -1.0), (decode(encode(s, Wav, Ima)?)?).trim(0.01, -1.0)) < 0.03
}

test "AIFF and AU round trips" {
  let a = Audio { tags: {"title": "Raft", "artist": "Auk"}, ..sig() }
  for (c, f, name) in [
    (Aiff, S16, "pcm_s16be"),
    (Aiff, S8, "pcm_s8"),
    (Aiff, S24, "pcm_s24be"),
    (Aiff, F32, "pcm_f32be"),
    (Aiff, Ulaw, "pcm_mulaw"),
    (Au, S16, "pcm_s16be"),
    (Au, F64, "pcm_f64be"),
    (Au, Alaw, "pcm_alaw"),
  ] {
    let bs = encode(a, c, f)?
    assert (probe(bs)?).codec == name
    let b = decode(bs)?
    assert b.frames() == 1000 && b.rate == 8000
    assert max_err(a, b) < 0.02
  }
  assert (decode(encode(a, Aiff, S16)?)?).tags == {"title": "Raft", "artist": "Auk"}
  assert (decode(encode(a, Wav, S16)?)?).tags == {"title": "Raft", "artist": "Auk"}
  assert (probe(encode(a, Aiff, F64)?)?).container == "aifc"
}

test "FLAC round trips are lossless" {
  let a = sig()
  for bits in [8, 16, 24] {
    let q = quantized(a, bits)
    let fmt = if bits == 8 { S8 } else if bits == 16 { S16 } else { S24 }
    let b = decode(encode(q, Flac, fmt)?)?
    assert max_err(q, b) == 0.0
    assert (probe(encode(q, Flac, fmt)?)?).bits == bits
  }
  // edge cases: lengths around the block size, 1 to 8 channels, silence, noise, full scale
  let q = quantized(a, 16)
  for n in [0, 1, 15, 4095, 4097] {
    let x = new(8000, [(0..n).map(i => q.chans[0][i % 1000])])
    let y = decode(encode(x, Flac, S16)?)?
    assert y.frames() == n && max_err(x, y) == 0.0
  }
  for nch in [1, 3, 6, 8] {
    let x = new(48000, (0..nch).map(c => q.chans[c % 2].map(v => v * float(c + 1) / 8.0)))
    let x16 = quantized(x, 16)
    assert max_err(x16, decode(encode(x16, Flac, S16)?)?) == 0.0
  }
  let silent = silence(0.1, 8000, 2)
  assert max_err(silent, decode(encode(silent, Flac, S16)?)?) == 0.0
  assert (encode(silent, Flac, S16)?).len() < 200
  let hiss = quantized(noise(audio.gen.White, 0.5, 8000, 1.0, 7), 16)
  assert max_err(hiss, decode(encode(hiss, Flac, S16)?)?) == 0.0
  let loud = tone(audio.gen.Square, 100.0, 0.2, 8000, 1.5)
  let lq = quantized(loud, 16)
  assert max_err(lq, decode(encode(loud, Flac, S16)?)?) == 0.0
  // 8-bit samples in 16 bits: wasted bits
  let coarse = quantized(a, 8)
  assert (encode(coarse, Flac, S16)?).len() < (encode(q, Flac, S16)?).len() / 2 + 100
}

test "FLAC from libFLAC" {
  // `flac --blocksize=32` of 48 stereo frames: a sine and a ramp, at 8 kHz
  let f = unhex(
    "664c6143000000220020002000003700004201f402f00000003089597962fd24657f210a268c4fcc9cdb840000" +
      "28200000007265666572656e6365206c6962464c414320312e352e3020323032353032313100000000fff8641800" +
      "1f1c180000093c11a5187a0193179f9e9f9c141120c1feb2d2fefee2ce877e1ec466c7021101a16053f063f1e43" +
      "0c3c3c3c3ea000f3e3d04000f0f0689fff86418010f7918fa8ef1b4ea22e48301945cdedfdd5752e9c7dc94d424" +
      "00d00bb0984c26130984c29b0ac2016ed856158561584043a3",
  )
  let a = decode(f)?
  assert (a.rate, a.nch(), a.frames()) == (8000, 2, 48)
  let left = a.chans[0].map(x => int(round(x * 32768.0)))
  let right = a.chans[1].map(x => int(round(x * 32768.0)))
  assert left.take(6) == [0, 2364, 4517, 6266, 7456, 7979]
  assert left == (0..48).map(i => int(8000.0 * sin(float(i) * 0.3)))
  assert right == (0..48).map(i => (i * 97) % 2000 - 1000)
  assert (probe(f)?).tags == {}
  // a flipped bit fails a CRC
  var bad = f
  bad[150] = bad[150] ^ 4
  assert decode(bad) is err(Corrupt(_))
  assert decode(f.take(180)) is err(Truncated(_))
}

test "MD5 and G.711" {
  assert tohex(audio.flac.md5([])) == "d41d8cd98f00b204e9800998ecf8427e"
  assert tohex(audio.flac.md5("abc".bytes())) == "900150983cd24fb0d6963f7d28e17f72"
  let long =
    "The quick brown fox jumps over the lazy dog. The quick brown fox jumps over the lazy dog."
  assert tohex(audio.flac.md5(long.bytes())) == "f168d89e05b664041ee6745f050caa4b"
  assert (audio.pcm.alaw(0), audio.pcm.ulaw(0), audio.pcm.alaw(32767), audio.pcm.ulaw(32767)) ==
    (0xd5, 0xff, 0xaa, 0x80)
  assert (audio.pcm.alaw(-32768), audio.pcm.ulaw(-32768)) == (0x2a, 0x00)
}

test "unknown and broken input" {
  assert decode([]) is err(Unsupported(_))
  assert decode("ID3\u{3}".bytes() + [0, 0, 0, 0, 0, 0]) is err(Unsupported("MP3"))
  assert decode("OggS".bytes() + [0, 0, 0, 0]) is err(Unsupported("Ogg"))
  let w = encode(sig(), Wav, S16)?
  assert decode(w.take(10)) is err(Unsupported(_))
  assert decode(w.take(20)) is err(Truncated(_))
  assert decode(w.take(40)) is err(Truncated(_))  // no data chunk
  assert decode(
    [0x52, 0x49, 0x46, 0x46, 0, 0, 0, 0] + "WAVEdata".bytes() + [0, 0, 0, 0],
  ) is err(Truncated(_))
  // a cut-off data chunk reads what's there
  assert (decode(w.take(w.len() - 400))?).frames() == 900
  assert encode(sig(), Flac, F32) is err(Unsupported(_))
  assert encode(new(8000, []), Wav, S16) is err(BadArg(_))
  assert message(Unsupported("MP3")) == "unsupported: MP3"
}

test "names" {
  assert fmt_named("s16") == some(S16) &&
    fmt_named("pcm_s24le") == some(S24) &&
    fmt_named("flt") == some(F32)
  assert fmt_named("mulaw") == some(Ulaw) && fmt_named("opus") == none
  assert container_for("a/b.FLAC") == some(Flac) &&
    container_for("x.aif") == some(Aiff) &&
    container_for("x.mp3") == none
  assert codec_name(F64, true) == "pcm_f64be"
}

test "resampling keeps a sine clean" {
  for (from, to) in [(44100, 48000), (48000, 44100), (8000, 22050)] {
    let a = sine(1000.0, 0.2, from).resample(to)
    let ideal = sine(1000.0, 0.2, to)
    assert a.frames() == ideal.frames()
    let mid = a.trim(0.05, 0.15)
    let ref = ideal.trim(0.05, 0.15)
    assert max_err(mid, ref) < 0.0001
  }
}

test "filters" {
  let lp = audio.fx.design(audio.fx.Lowpass, 1000.0, 0.7071067811865476, 0.0, 48000)
  assert abs(audio.fx.response_db(lp, 1000.0, 48000) + 3.01) < 0.01
  assert audio.fx.response_db(lp, 10000.0, 48000) < -38.0
  let pk = audio.fx.design(audio.fx.Peak, 2000.0, 1.0, 6.0, 48000)
  assert abs(audio.fx.response_db(pk, 2000.0, 48000) - 6.0) < 0.001
  // a 5 kHz tone through a 500 Hz low-pass loses about 40 dB
  let t = sine(5000.0, 0.5, 48000)
  let drop = gain_to_db(t.lowpass(500.0).trim(0.1, -1.0).peak() / t.peak())
  assert drop < -38.0 && drop > -42.0
  // hum removal
  let hum = sine(50.0, 1.0, 8000)
  assert hum.notch(50.0, 5.0).trim(0.5, -1.0).peak() < 0.01
}

test "levels and loudness" {
  // EBU Tech 3341: a stereo 1 kHz sine at -23 dBFS reads -23 LUFS
  let s = sine(1000.0, 3.0, 48000).remix(2).gain_db(-23.0)
  let l = s.loudness()
  assert abs(l.integrated + 23.0) < 0.1
  assert abs(l.true_peak_db + 23.0) < 0.1
  assert abs(s.loudnorm(-16.0, -1.0).loudness().integrated + 16.0) < 0.1
  assert abs(gain_to_db(s.normalize(-1.0).peak()) + 1.0) < 0.0001
  let st = sine(100.0, 1.0, 8000).gain(0.5).stats()[0]
  assert abs(st.rms - 0.35355) < 0.001 && abs(st.crest - 1.4142) < 0.001 && st.clipped == 0
  assert silence(0.1, 8000, 1).loudness().integrated == -70.0
}

test "dynamics" {
  let a = sine(200.0, 1.0, 8000).gain(3.0)
  let lim = a.limit(-1.0, 0.005, 0.05)
  assert lim.peak() <= db_to_gain(-1.0) + 0.000001
  assert lim.peak() > db_to_gain(-1.5)
  // 2:1 above -18 dB with no knee: a 0 dB tone comes out near -9 dB
  let c = sine(200.0, 1.0, 8000).compress(Comp { knee: 0.0, rms: false, ..COMP })
  assert abs(gain_to_db(c.trim(0.5, -1.0).peak()) + 9.0) < 1.0
  // a quiet tone is gated down, a loud one passes
  let quiet = sine(200.0, 1.0, 8000).gain_db(-50.0)
  assert quiet.gate(-30.0, 4.0, 40.0, 0.01, 0.1).trim(0.5, -1.0).peak() < quiet.peak() / 10.0
  let loud = sine(200.0, 1.0, 8000).gain_db(-10.0)
  assert abs(loud.gate(-30.0, 4.0, 40.0, 0.01, 0.1).trim(0.5, -1.0).peak() - loud.peak()) < 0.01
}

test "editing" {
  let a = sig()
  assert a.trim(0.025, 0.1).frames() == 600
  assert a.trim(0.1, 0.05).frames() == 0
  assert a.pad(0.5).frames() == 5000 && a.delay(0.5).chans[0][4000] == a.chans[0][0]
  assert a.reverse().chans[1][0] == a.chans[1][999]
  let f = a.fade_in(0.05)
  assert f.chans[0][0] == 0.0 && f.chans[0][500] == a.chans[0][500]
  assert (concat([a, a, a])?).frames() == 3000
  assert concat([a, sine(1.0, 1.0, 8000)]) is err(BadArg(_))
  let o = a.overlay(a, 0.1)?
  assert o.frames() == 1800 && o.chans[0][900] == a.chans[0][900] + a.chans[0][100]
  assert (mix([a, a])?).chans[0][7] == a.chans[0][7]
  let e = a.echo(1.0, 1.0, [0.01], [0.5])
  assert e.frames() == 1080 && e.chans[0][100] == a.chans[0][100] + 0.5 * a.chans[0][20]
  assert abs(a.delay_each([0.0, 0.01]).chans[1][80] - a.chans[1][0]) == 0.0
}

test "channels" {
  let m = sine(100.0, 0.1, 8000)
  let st = m.remix(2)
  assert st.nch() == 2 && st.chans[1] == m.chans[0]
  assert st.mono().chans[0] == m.chans[0]
  let six = new(8000, (0..6).map(_ => m.chans[0]))
  let down = six.remix(2)
  assert down.nch() == 2 && down.peak() <= 1.000000001 && down.peak() > 0.99
  assert m.remix(6).chans[2] == audio.pcm.zeros(800)
  assert sig().channel(1).chans[0] == sig().chans[1]
  assert max_err(sig().widen(1.0), sig()) < 0.000000000001
}

test "time and pitch" {
  let a = concat([sine(500.0, 0.5, 8000), sine(1000.0, 0.5, 8000)])?
  let fast = a.tempo(2.0)
  assert fast.frames() == 4000
  assert abs(fast.trim(0.05, 0.2).dominant() - 500.0) < 5.0
  assert abs(fast.trim(0.3, 0.45).dominant() - 1000.0) < 5.0
  let up = sine(440.0, 1.0, 8000).pitch(12.0)
  assert up.frames() == 8000 && abs(up.trim(0.2, 0.8).dominant() - 880.0) < 5.0
  assert sine(440.0, 1.0, 8000).set_rate(16000).duration() == 0.5
}

test "analysis" {
  assert abs(sine(1234.0, 0.5, 44100).dominant() - 1234.0) < 1.0
  let sp = sine(1000.0, 1.0, 8000).spectrum(1024)
  assert sp.len() == 513 && abs(sp[128]) < 0.1 && sp[300] < -100.0
  var re = [1.0, 2.0, 3.0, 4.0, 0.0, -1.0, 0.5, 2.0]
  var im = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
  let orig = re
  audio.analyze.fft(&re, &im, false)
  assert abs(re[0] - 11.5) < 0.0000001
  audio.analyze.fft(&re, &im, true)
  assert (0..8).all(i => abs(re[i] - orig[i]) < 0.0000001)
  let gap = concat([sine(300.0, 0.5, 8000), silence(1.0, 8000, 1), sine(300.0, 0.5, 8000)])?
  let sil = gap.silences(-60.0, 0.5)
  assert sil.len() == 1 && abs(sil[0].0 - 0.5) < 0.01 && abs(sil[0].1 - 1.5) < 0.01
  assert silence(0.2, 8000, 1).delay(0.0).silences(-60.0, 0.1).len() == 1
  let padded = concat([silence(0.25, 8000, 1), sine(300.0, 0.5, 8000), silence(0.25, 8000, 1)])?
  assert abs(padded.trim_silence(-60.0).duration() - 0.5) < 0.001
}

test "filter graphs" {
  let a = sig()
  assert (a.apply("volume=0.5")?).chans[0][3] == a.chans[0][3] * 0.5
  assert abs((a.apply("volume=-6.0206dB")?).peak() - a.peak() / 2.0) < 0.0001
  let b = a.apply("highpass=f=100, lowpass=f=3000:p=1 ,aresample=16000,atrim=start=0.01:duration=0.05,afade=t=out:d=0.01")?
  assert b.rate == 16000 && b.frames() == 800
  assert (a.apply("pan=mono|c0=0.5*c0+0.5*c1")?).chans[0][9] ==
    (a.chans[0][9] + a.chans[1][9]) * 0.5
  assert (a.apply("pan=stereo|c0=c1|c1=-c0")?).chans[1][9] == -a.chans[0][9]
  assert (a.apply("aformat=sample_rates=4000:channel_layouts=mono")?).rate == 4000
  assert (a.apply("aecho=0.8:0.9:10|20:0.3|0.2")?).frames() == 1160
  assert (a.apply("adelay=10|20")?).frames() == 1160
  assert (a.apply("atempo=2")?).frames() == 500
  assert (a.apply("anull,areverse,areverse")?).chans == a.chans
  assert a.apply("bogus=1") is err(BadArg(_))
  assert a.apply("volume=loud") is err(BadArg(_))
  assert a.apply("lowpass=f=9000") is err(BadArg(_))
  assert audio.graph.duration("1:02.5") == some(62.5) && audio.graph.duration("250ms") == some(0.25)
}

test "sources" {
  let s = source("sine=frequency=1000:duration=0.5:sample_rate=8000")?
  assert s.frames() == 4000 && abs(s.peak() - 0.125) < 0.001 && abs(s.dominant() - 1000.0) < 2.0
  let n = source("anoisesrc=color=pink:d=0.2:a=0.5:seed=3:r=8000")?
  assert n.frames() == 1600 &&
    n.peak() <= 1.0 &&
    n == source("anoisesrc=color=pink:d=0.2:a=0.5:seed=3:r=8000")?
  assert (source("anullsrc=r=48000:cl=5.1:d=0.1")?).nch() == 6
  assert (source("square=f=100:d=0.1:r=8000")?).peak() == 0.5
  assert (source("chirp=f0=100:f1=1000:d=1:r=8000")?).frames() == 8000
  assert source("wobble") is err(BadArg(_))
}