audio 2.0.0-0 → 2.0.0

package/fn/pad.js

@@ -0,0 +1,19 @@
+/**
+ * Pad — add silence to start and/or end of audio.
+ * pad(1) = 1s both sides. pad(1, 2) = 1s before, 2s after.
+ */
+
+import { seg } from '../plan.js'
+
+const padPlan = (segs, ctx) => {
+  let { total, sampleRate: sr, args } = ctx
+  let before = args[0] ?? 0, after = args.length > 1 ? args[1] : before
+  let bN = Math.round(before * sr), aN = Math.round(after * sr)
+  let r = segs.map(s => { let n = s.slice(); n[2] = s[2] + bN; return n })
+  if (bN > 0) r.unshift(seg(0, bN, 0, undefined, null))
+  if (aN > 0) r.push(seg(0, aN, total + bN, undefined, null))
+  return r
+}
+
+import audio from '../core.js'
+audio.op('pad', { plan: padPlan })

package/fn/pan.js

@@ -0,0 +1,35 @@
+/**
+ * Pan — stereo balance control. -1 = full left, 0 = center, 1 = full right.
+ * Linear attenuation — never boosts, only attenuates one channel.
+ */
+
+import { opRange } from '../plan.js'
+
+const pan = (chs, ctx) => {
+  let val = ctx.args[0] ?? 0 // -1..1 or t => value
+  if (chs.length < 2) return false // mono: no-op
+  let auto = typeof val === 'function'
+  let [s, end] = opRange(ctx, chs[0].length)
+  let off = (ctx.blockOffset || 0) * ctx.sampleRate
+  if (!auto) {
+    val = Math.max(-1, Math.min(1, val))
+    let gL = val <= 0 ? 1 : 1 - val, gR = val >= 0 ? 1 : 1 + val, gains = [gL, gR]
+    for (let c = 0; c < chs.length; c++) {
+      let g = gains[c] ?? 1
+      if (g === 1) continue
+      for (let i = Math.max(0, s); i < Math.min(end, chs[c].length); i++) chs[c][i] *= g
+    }
+    return chs
+  }
+  // Automation: per-sample evaluation
+  let L = chs[0], R = chs[1]
+  for (let i = Math.max(0, s); i < Math.min(end, L.length); i++) {
+    let p = Math.max(-1, Math.min(1, val((off + i) / ctx.sampleRate)))
+    L[i] *= p <= 0 ? 1 : 1 - p
+    R[i] *= p >= 0 ? 1 : 1 + p
+  }
+  return chs
+}
+
+import audio from '../core.js'
+audio.op('pan', { process: pan })

package/fn/play.js

@@ -0,0 +1,112 @@
+import audio, { emit } from '../core.js'
+import Speaker from 'audio-speaker'
+
+/** Apply fade ramp to interleaved buffer. fadeIn=true ramps 0→1, fadeIn=false ramps 1→0 at end. */
+function ramp(buf, ch, len, fadeIn, RAMP) {
+  let n = Math.min(RAMP, len)
+  if (fadeIn) {
+    for (let i = 0; i < n; i++) { let t = i / n; for (let c = 0; c < ch; c++) buf[i * ch + c] *= t }
+  } else {
+    let s = len - n
+    for (let i = 0; i < n; i++) { let t = 1 - i / n; for (let c = 0; c < ch; c++) buf[(s + i) * ch + c] *= t }
+  }
+}
+
+/** Playback via audio-speaker (cross-platform: Node + browser). */
+audio.fn.play = function(opts) {
+  let offset = opts?.at ?? 0, duration = opts?.duration
+  let a = this, BLOCK = audio.BLOCK_SIZE
+  if (a.playing) { a.playing = false; a.paused = false; if (a._._wake) a._._wake() }
+  a.playing = false; a.paused = opts?.paused ?? false; a.currentTime = offset
+  a.volume = opts?.volume ?? 0; a.loop = opts?.loop ?? false
+  a.block = null; a._._wake = null; a._._seekTo = null
+
+  ;(async () => {
+    try {
+      let ch = a.channels, sr = a.sampleRate
+      a.playing = true
+      let wait = async () => { while (a.paused && a.playing && a._._seekTo == null) await new Promise(r => { a._._wake = r }); a._._wake = null }
+
+      let from = offset, RAMP = 256 // ~6ms anti-click ramp
+      while (a.playing) {
+        // If paused before playback starts (e.g. open without autoplay), wait silently
+        if (a.paused) {
+          await wait()
+          if (!a.playing) break
+          if (a._._seekTo != null) { from = a._._seekTo; a._._seekTo = null; a.currentTime = from }
+        }
+        let write = Speaker({ sampleRate: sr, channels: ch, bitDepth: 32 })
+        let seeked = false, played = 0, fadeIn = true
+        const flush = async () => {
+          let pad = new Uint8Array(BLOCK * ch * 4)
+          await new Promise(r => write(pad, r))
+          await new Promise(r => write(pad, r))
+        }
+        for await (let chunk of a.stream({at: from, duration})) {
+          if (!a.playing) break
+          let cLen = chunk[0].length
+          for (let bOff = 0; bOff < cLen; bOff += BLOCK) {
+            if (a._._seekTo != null) {
+              from = a._._seekTo; a._._seekTo = null
+              a.currentTime = from; seeked = true; break
+            }
+            let end = Math.min(bOff + BLOCK, cLen), len = end - bOff
+            a.block = chunk[0].subarray(bOff, end)
+
+            let g = 10 ** (a.volume / 20)
+            let buf = new Float32Array(len * ch)
+            for (let i = 0; i < len; i++) for (let c = 0; c < ch; c++)
+              buf[i * ch + c] = (chunk[c] || chunk[0])[bOff + i] * g
+            let send = () => new Promise(r => write(new Uint8Array(buf.buffer), r))
+            if (fadeIn) { ramp(buf, ch, len, true, RAMP); fadeIn = false }
+
+            if (a.paused) {
+              ramp(buf, ch, len, false, RAMP)
+              await send()
+              await flush()
+              played += len
+              a.currentTime = from + played / sr
+              await wait()
+              if (a._._seekTo != null) continue
+              if (!a.playing) break
+              fadeIn = true
+              continue
+            }
+
+            if (!a.playing) {
+              ramp(buf, ch, len, false, RAMP)
+              await send()
+              break
+            }
+
+            await send()
+            played += len
+            if (a._._seekTo == null) {
+              a.currentTime = from + played / sr
+              emit(a, 'timeupdate', a.currentTime)
+            }
+          }
+          if (seeked || !a.playing) break
+        }
+        if (!seeked && !a.playing) await flush()
+        if (seeked) { await flush(); fadeIn = true }
+        write(null)
+        if (seeked) continue
+        if (!a.playing) break
+        if (a.loop) { from = 0; a.currentTime = 0; emit(a, 'timeupdate', 0); continue }
+        a.playing = false
+        emit(a, 'timeupdate', a.currentTime)
+        break
+      }
+      a.playing = false; emit(a, 'ended')
+    } catch (err) {
+      console.error('Playback error:', err)
+      a.playing = false
+    }
+  })()
+  return this
+}
+
+let proto = audio.fn
+proto.pause = function() { this.paused = true }
+proto.resume = function() { this.paused = false; if (this._._wake) this._._wake() }

package/fn/remix.js

@@ -0,0 +1,25 @@
+const remix = (chs, ctx) => {
+  let arg = ctx.args[0], len = chs[0].length
+  // array map: [0, 1, null, ...] — number = source ch, null = silence
+  if (Array.isArray(arg)) {
+    return arg.map(src =>
+      src == null ? new Float32Array(len) : new Float32Array(chs[((src % chs.length) + chs.length) % chs.length])
+    )
+  }
+  let n = chs.length, m = arg
+  if (n === m) return false
+  if (m < n) {
+    let out = new Float32Array(len)
+    for (let c = 0; c < n; c++)
+      for (let i = 0; i < len; i++) out[i] += chs[c][i]
+    let inv = 1 / n
+    for (let i = 0; i < len; i++) out[i] *= inv
+    return Array.from({ length: m }, () => new Float32Array(out))
+  }
+  return Array.from({ length: m }, (_, c) => new Float32Array(chs[c % n]))
+}
+
+const remixCh = (_, args) => Array.isArray(args[0]) ? args[0].length : args[0]
+
+import audio from '../core.js'
+audio.op('remix', { process: remix, ch: remixCh })

package/fn/remove.js

@@ -0,0 +1,25 @@
+import { seg, planOffset } from '../plan.js'
+
+function removeSegs(segs, off, dur) {
+  let r = [], end = off + dur
+  for (let s of segs) {
+    let se = s[2] + s[1]
+    if (se <= off) r.push(s)
+    else if (s[2] >= end) { let n = s.slice(); n[2] = s[2] - dur; r.push(n) }
+    else {
+      let absR = Math.abs(s[3] || 1)
+      if (s[2] < off) r.push(seg(s[0], off - s[2], s[2], s[3], s[4]))
+      if (se > end) r.push(seg(s[0] + (end - s[2]) * absR, se - end, off, s[3], s[4]))
+    }
+  }
+  return r
+}
+
+const removePlan = (segs, ctx) => {
+  let { total } = ctx
+  let s = planOffset(ctx.offset, total)
+  return removeSegs(segs, s, Math.min(ctx.length ?? (total - s), total - s))
+}
+
+import audio from '../core.js'
+audio.op('remove', { plan: removePlan })

package/fn/repeat.js

@@ -0,0 +1,35 @@
+import { cropSegs } from './crop.js'
+import { seg, planOffset } from '../plan.js'
+
+function repeatSegs(segs, times, total, off, dur) {
+  if (off == null) {
+    let r = []
+    for (let t = 0; t <= times; t++)
+      for (let s of segs) { let n = s.slice(); n[2] = s[2] + total * t; r.push(n) }
+    return r
+  }
+  let segLen = dur ?? (total - off), clip = cropSegs(segs, off, segLen), r = []
+  for (let s of segs) {
+    let se = s[2] + s[1]
+    if (se <= off + segLen) r.push(s)
+    else if (s[2] >= off + segLen) { let n = s.slice(); n[2] = s[2] + segLen * times; r.push(n) }
+    else {
+      let absR = Math.abs(s[3] || 1), split = off + segLen - s[2]
+      r.push(seg(s[0], split, s[2], s[3], s[4]))
+      r.push(seg(s[0] + split * absR, se - off - segLen, off + segLen * (times + 1), s[3], s[4]))
+    }
+  }
+  for (let t = 1; t <= times; t++)
+    for (let c of clip) { let n = c.slice(); n[2] = off + segLen * t + c[2]; r.push(n) }
+  r.sort((a, b) => a[2] - b[2])
+  return r
+}
+
+const repeatPlan = (segs, ctx) => {
+  let { total, args, length } = ctx
+  let off = ctx.offset != null ? planOffset(ctx.offset, total) : null
+  return repeatSegs(segs, args[0] ?? 1, total, off, length)
+}
+
+import audio from '../core.js'
+audio.op('repeat', { plan: repeatPlan })

package/fn/reverse.js

@@ -0,0 +1,25 @@
+import { seg, planOffset } from '../plan.js'
+
+function reverseSegs(segs, off, end) {
+  let r = []
+  for (let s of segs) {
+    let se = s[2] + s[1]
+    if (se <= off || s[2] >= end) { r.push(s); continue }
+    let absR = Math.abs(s[3] || 1)
+    if (s[2] < off) r.push(seg(s[0], off - s[2], s[2], s[3], s[4]))
+    let iStart = Math.max(s[2], off), iEnd = Math.min(se, end)
+    r.push(seg(s[0] + (iStart - s[2]) * absR, iEnd - iStart, off + end - iEnd, -(s[3] || 1), s[4]))
+    if (se > end) r.push(seg(s[0] + (end - s[2]) * absR, se - end, end, s[3], s[4]))
+  }
+  r.sort((a, b) => a[2] - b[2])
+  return r
+}
+
+const reversePlan = (segs, ctx) => {
+  let { total, length } = ctx
+  let s = planOffset(ctx.offset, total)
+  return reverseSegs(segs, s, s + (length ?? total - s))
+}
+
+import audio from '../core.js'
+audio.op('reverse', { plan: reversePlan })

package/fn/save.js

@@ -0,0 +1,55 @@
+import audio, { emit, parseTime } from '../core.js'
+import encode from 'encode-audio'
+
+const FMT_ALIAS = { aif: 'aiff', oga: 'ogg' }
+
+function resolveFormat(fmt) { return FMT_ALIAS[fmt] || fmt || 'wav' }
+
+/** Stream-encode audio: calls sink(buf) per chunk, returns sink(null) at end. */
+async function encodeStream(inst, fmt, opts, sink) {
+  let enc = await encode[fmt]({ sampleRate: inst.sampleRate, channels: inst.channels, ...opts.meta })
+  let written = 0, tick = 0
+  for await (let chunk of inst.stream({ at: opts.at, duration: opts.duration })) {
+    let buf = await enc(chunk)
+    if (buf.length) await sink(buf)
+    written += chunk[0].length
+    if (++tick % 2 === 0) await new Promise(r => setTimeout(r, 0))
+    emit(inst, 'progress', { offset: written / inst.sampleRate, total: (opts.duration != null ? parseTime(opts.duration) : null) ?? inst.duration })
+  }
+  let final = await enc()
+  if (final.length) await sink(final)
+  return sink(null)
+}
+
+/** Encode audio to bytes. */
+audio.fn.encode = async function(fmt, opts = {}) {
+  if (typeof fmt === 'object') { opts = fmt; fmt = undefined }
+  fmt = resolveFormat(fmt)
+  if (!encode[fmt]) throw new Error('Unknown format: ' + fmt)
+  let parts = []
+  await encodeStream(this, fmt, opts, buf => { if (buf) parts.push(buf) })
+  let total = parts.reduce((n, p) => n + p.length, 0)
+  let out = new Uint8Array(total), pos = 0
+  for (let p of parts) { out.set(p, pos); pos += p.length }
+  return out
+}
+
+/** Save audio to file path (Node) or writable handle (browser). */
+audio.fn.save = async function(target, opts = {}) {
+  let fmt = opts.format ?? (typeof target === 'string' ? target.split('.').pop() : 'wav')
+  fmt = resolveFormat(fmt)
+  if (!encode[fmt]) throw new Error('Unknown format: ' + fmt)
+
+  let write, finish
+  if (typeof target === 'string') {
+    let { createWriteStream } = await import('fs')
+    let ws = createWriteStream(target)
+    write = buf => { if (!ws.write(Buffer.from(buf))) return new Promise(r => ws.once('drain', r)) }
+    finish = () => new Promise((res, rej) => { ws.on('finish', res); ws.on('error', rej); ws.end() })
+  } else if (target?.write) {
+    write = buf => target.write(buf)
+    finish = () => target.close?.()
+  } else throw new Error('Invalid save target')
+
+  await encodeStream(this, fmt, opts, buf => buf ? write(buf) : finish?.())
+}

package/fn/silence.js

@@ -0,0 +1,34 @@
+/**
+ * Silence detection stat — finds silent regions from block stats.
+ * a.stat('silence', { threshold?, minDuration? }) → [{ at, duration }, ...]
+ */
+
+import audio from '../core.js'
+import { queryRange } from '../stats.js'
+import { resolveThreshold, isLoud } from './trim.js'
+
+audio.fn.silence = async function(opts) {
+  let { stats, ch, sr, from, to } = await queryRange(this, opts)
+  let bs = stats.blockSize
+  let minDur = opts?.minDuration ?? 0.1
+  let thresh = resolveThreshold(stats, ch, from, to, opts?.threshold)
+
+  // Scan blocks for silence
+  let segs = [], start = null
+  for (let i = from; i < to; i++) {
+    if (!isLoud(stats, i, ch, thresh)) {
+      if (start == null) start = i
+    } else if (start != null) {
+      let segAt = start * bs / sr, segEnd = i * bs / sr
+      if (segEnd - segAt >= minDur) segs.push({ at: segAt, duration: segEnd - segAt })
+      start = null
+    }
+  }
+  // Trailing silence
+  if (start != null) {
+    let segAt = start * bs / sr, segEnd = Math.min(to * bs / sr, this.duration)
+    if (segEnd - segAt >= minDur) segs.push({ at: segAt, duration: segEnd - segAt })
+  }
+
+  return segs
+}

package/fn/spectrum.js

@@ -0,0 +1,104 @@
+/**
+ * Mel-frequency spectrum — FFT → mel-binned magnitudes.
+ * Core analysis primitive for spectrum display, spectrogram, feature extraction.
+ * Used by stat system (`a.stat('spectrum')`) and CLI playback visualization.
+ */
+
+import fft from 'fourier-transform'
+import hann from 'window-function/hann'
+import { a as aWeight } from 'a-weighting'
+
+// ── Mel scale ───────────────────────────────────────────────────
+
+export let toMel = f => 2595 * Math.log10(1 + f / 700)
+export let fromMel = m => 700 * (10 ** (m / 2595) - 1)
+
+// ── Window cache ────────────────────────────────────────────────
+
+let windows = {}
+function hannWin(n) {
+  if (windows[n]) return windows[n]
+  let w = new Float32Array(n)
+  for (let i = 0; i < n; i++) w[i] = hann(i, n)
+  return (windows[n] = w)
+}
+
+// ── Core ────────────────────────────────────────────────────────
+
+/**
+ * Compute mel-binned magnitude spectrum from a block of samples.
+ * @param {Float32Array} samples — mono PCM block (length should be power of 2)
+ * @param {number} sr — sample rate
+ * @param {object} [opts]
+ * @param {number} [opts.bins=128] — number of mel frequency bins
+ * @param {number} [opts.fMin=30] — minimum frequency Hz
+ * @param {number} [opts.fMax] — maximum frequency Hz (default: min(sr/2, 20000))
+ * @param {boolean} [opts.weight=true] — apply A-weighting (perceptual loudness)
+ * @returns {Float32Array} magnitude per mel bin (linear scale)
+ */
+export function melSpectrum(samples, sr, opts = {}) {
+  let { bins = 128, fMin = 30, fMax = Math.min(sr / 2, 20000), weight = true } = opts
+  let N = samples.length, win = hannWin(N)
+  let buf = new Float32Array(N)
+  for (let i = 0; i < N; i++) buf[i] = samples[i] * win[i]
+  let mag = fft(buf)
+
+  let mMin = toMel(fMin), mMax = toMel(fMax), binHz = sr / N
+  let out = new Float32Array(bins)
+
+  for (let b = 0; b < bins; b++) {
+    let f0 = fromMel(mMin + (mMax - mMin) * b / bins)
+    let f1 = fromMel(mMin + (mMax - mMin) * (b + 1) / bins)
+    let k0 = Math.max(1, Math.floor(f0 / binHz))
+    let k1 = Math.min(mag.length - 1, Math.ceil(f1 / binHz))
+    let sum = 0, cnt = 0
+    for (let k = k0; k <= k1; k++) { sum += mag[k] ** 2; cnt++ }
+    let rms = cnt > 0 ? Math.sqrt(sum / cnt) : 0
+    if (weight) rms *= aWeight((f0 + f1) / 2, sr)
+    out[b] = rms
+  }
+  return out
+}
+
+
+// ── Block analysis helper ───────────────────────────────────────
+
+/** Stream ch0, buffer remainder, call fn(block, acc) per N-sample block. Returns {acc, cnt}. */
+export async function analyzeBlocks(inst, opts, N, bins, fn) {
+  let acc = new Float64Array(bins), cnt = 0, rem = new Float32Array(0)
+  for await (let pcm of inst.stream({ at: opts?.at, duration: opts?.duration })) {
+    let ch0 = pcm[0]
+    if (!ch0 || !ch0.length) continue
+    let input = ch0
+    if (rem.length) {
+      input = new Float32Array(rem.length + ch0.length)
+      input.set(rem, 0)
+      input.set(ch0, rem.length)
+    }
+    let limit = input.length - (input.length % N)
+    for (let off = 0; off < limit; off += N) { fn(input.subarray(off, off + N), acc); cnt++ }
+    rem = limit < input.length ? input.slice(limit) : new Float32Array(0)
+  }
+  return { acc, cnt }
+}
+
+// ── Stat registration ───────────────────────────────────────────
+
+import audio from '../core.js'
+
+/** a.stat('spectrum', {bins}) → average mel spectrum in dB over range */
+audio.fn.spectrum = async function(opts) {
+  let bins = opts?.bins ?? 128
+  let spectOpts = { bins, fMin: opts?.fMin, fMax: opts?.fMax, weight: opts?.weight }
+  let sr = this.sampleRate
+
+  let { acc, cnt } = await analyzeBlocks(this, opts, 1024, bins, (block, acc) => {
+    let mag = melSpectrum(block, sr, spectOpts)
+    for (let b = 0; b < bins; b++) acc[b] += mag[b] ** 2
+  })
+
+  if (cnt === 0) return new Float32Array(bins)
+  let out = new Float32Array(bins)
+  for (let b = 0; b < bins; b++) out[b] = 20 * Math.log10(Math.sqrt(acc[b] / cnt) + 1e-10)
+  return out
+}

package/fn/speed.js

@@ -0,0 +1,23 @@
+/**
+ * Speed — change playback rate. speed(2) = double speed (half duration),
+ * speed(0.5) = half speed (double duration), speed(-1) = reverse.
+ */
+
+import { seg } from '../plan.js'
+
+const speedPlan = (segs, ctx) => {
+  let rate = ctx.args[0]
+  if (rate === 0) throw new RangeError('speed: rate cannot be 0')
+  if (!rate || rate === 1) return segs
+  let absR = Math.abs(rate)
+  let r = [], dst = 0
+  for (let s of segs) {
+    let count = Math.round(s[1] / absR)
+    r.push(seg(s[0], count, dst, s[4] === null ? s[3] : (s[3] || 1) * rate, s[4]))
+    dst += count
+  }
+  return r
+}
+
+import audio from '../core.js'
+audio.op('speed', { plan: speedPlan })

package/fn/split.js

@@ -0,0 +1,9 @@
+import audio, { parseTime } from '../core.js'
+
+/** Split at offsets, returning views. No copies. */
+audio.fn.split = function(...args) {
+  let offsets = (Array.isArray(args[0]) ? args[0] : args).map(parseTime)
+  let dur = this.duration
+  let cuts = [0, ...offsets.sort((a, b) => a - b).filter(t => t > 0 && t < dur), dur]
+  return cuts.slice(0, -1).map((start, i) => this.clip({at: start, duration: cuts[i + 1] - start}))
+}

package/fn/stat.js

@@ -0,0 +1,77 @@
+import audio from '../core.js'
+
+let rMin = (src, from, to) => { let v = Infinity; for (let i = from; i < to; i++) if (src[i] < v) v = src[i]; return v === Infinity ? 0 : v }
+let rMax = (src, from, to) => { let v = -Infinity; for (let i = from; i < to; i++) if (src[i] > v) v = src[i]; return v === -Infinity ? 0 : v }
+let rSum = (src, from, to) => { let v = 0; for (let i = from; i < to; i++) v += src[i]; return v }
+let rMean = (src, from, to) => { let n = to - from; if (!n) return 0; let v = 0; for (let i = from; i < to; i++) v += src[i]; return v / n }
+let rRms = (src, from, to) => { let n = to - from; if (!n) return 0; let v = 0; for (let i = from; i < to; i++) v += src[i]; return Math.sqrt(v / n) }
+
+audio.stat('min', {
+  block: (chs) => chs.map(ch => {
+    let mn = Infinity
+    for (let i = 0; i < ch.length; i++) if (ch[i] < mn) mn = ch[i]
+    return mn
+  }),
+  reduce: rMin,
+  query: (stats, chs, from, to) => {
+    let v = Infinity
+    for (let c of chs) for (let i = from; i < Math.min(to, stats.min[c].length); i++) if (stats.min[c][i] < v) v = stats.min[c][i]
+    return v === Infinity ? 0 : v
+  }
+})
+
+audio.stat('max', {
+  block: (chs) => chs.map(ch => {
+    let mx = -Infinity
+    for (let i = 0; i < ch.length; i++) if (ch[i] > mx) mx = ch[i]
+    return mx
+  }),
+  reduce: rMax,
+  query: (stats, chs, from, to) => {
+    let v = -Infinity
+    for (let c of chs) for (let i = from; i < Math.min(to, stats.max[c].length); i++) if (stats.max[c][i] > v) v = stats.max[c][i]
+    return v === -Infinity ? 0 : v
+  }
+})
+
+audio.stat('dc', {
+  block: (chs) => chs.map(ch => {
+    let sum = 0
+    for (let i = 0; i < ch.length; i++) sum += ch[i]
+    return sum / ch.length
+  }),
+  reduce: rMean
+})
+
+audio.stat('clipping', {
+  block: (chs) => chs.map(ch => {
+    let n = 0
+    for (let i = 0; i < ch.length; i++) if (ch[i] >= 1 || ch[i] <= -1) n++
+    return n
+  }),
+  reduce: rSum,
+  query: (stats, chs, from, to, sr) => {
+    let bs = stats.blockSize, times = []
+    for (let i = from; i < to; i++) {
+      let n = 0
+      for (let c of chs) n += stats.clipping[c][i] || 0
+      if (n > 0) times.push(i * bs / sr)
+    }
+    return new Float32Array(times)
+  }
+})
+
+audio.stat('rms', {
+  block: (chs) => chs.map(ch => {
+    let sum = 0
+    for (let i = 0; i < ch.length; i++) sum += ch[i] * ch[i]
+    return sum / ch.length
+  }),
+  reduce: rRms,
+  query: (stats, chs, from, to) => {
+    let sum = 0, n = 0
+    for (let c of chs)
+      for (let i = from; i < Math.min(to, stats.rms[c].length); i++) { sum += stats.rms[c][i]; n++ }
+    return n ? Math.sqrt(sum / n) : 0
+  }
+})

package/fn/transform.js

@@ -0,0 +1,6 @@
+import audio from '../core.js'
+
+audio.op('transform', {
+  process: (chs, ctx) => ctx.args[0](chs, ctx),
+  call(std, f) { return this.run({ type: 'transform', args: [f] }) }
+})

package/fn/trim.js

@@ -0,0 +1,68 @@
+import audio from '../core.js'
+
+export function autoThreshold(energies) {
+  let vals = energies.filter(e => e > 0)
+  if (!vals.length) return -40
+  vals.sort((a, b) => a - b)
+  let floor = vals[Math.floor(vals.length * 0.1)]
+  return Math.max(-80, Math.min(-20, 10 * Math.log10(floor) + 12))
+}
+
+/** Resolve dB threshold to linear. Auto-detects from energy stats when db is null. */
+export function resolveThreshold(stats, ch, from, to, db) {
+  if (db == null) {
+    let energies = []
+    for (let c = 0; c < ch; c++) for (let i = from; i < to; i++) energies.push(stats.energy[c][i])
+    db = autoThreshold(energies)
+  }
+  return 10 ** (db / 20)
+}
+
+/** Check if block i is loud (any channel exceeds thresh). */
+export let isLoud = (stats, i, ch, thresh) => {
+  for (let c = 0; c < ch; c++)
+    if (Math.max(Math.abs(stats.min[c][i]), Math.abs(stats.max[c][i])) > thresh) return true
+  return false
+}
+
+const trim = (chs, ctx) => {
+  let threshold = ctx.args[0]
+  if (threshold == null) {
+    let energies = []
+    for (let c = 0; c < chs.length; c++)
+      for (let off = 0; off < chs[c].length; off += audio.BLOCK_SIZE) {
+        let end = Math.min(off + audio.BLOCK_SIZE, chs[c].length), sum = 0
+        for (let i = off; i < end; i++) sum += chs[c][i] * chs[c][i]
+        energies.push(sum / (end - off))
+      }
+    threshold = autoThreshold(energies)
+  }
+  let thresh = 10 ** (threshold / 20)
+
+  let len = chs[0].length, s = 0, e = len - 1
+  for (; s < len; s++) { let loud = false; for (let c = 0; c < chs.length; c++) if (Math.abs(chs[c][s]) > thresh) { loud = true; break }; if (loud) break }
+  for (; e >= s; e--) { let loud = false; for (let c = 0; c < chs.length; c++) if (Math.abs(chs[c][e]) > thresh) { loud = true; break }; if (loud) break }
+  e++
+
+  return s === 0 && e === len ? false : chs.map(ch => ch.slice(s, e))
+}
+
+const trimResolve = (args, { stats, sampleRate, totalDuration }) => {
+  if (!stats?.min || !stats?.energy) return null
+  let ch = stats.min.length, blocks = stats.min[0].length
+  let total = Math.round(totalDuration * sampleRate)
+  let thresh = resolveThreshold(stats, ch, 0, stats.energy[0].length, args[0])
+
+  let s = 0, e = blocks - 1
+  for (; s < blocks; s++) if (isLoud(stats, s, ch, thresh)) break
+  for (; e >= s; e--) if (isLoud(stats, e, ch, thresh)) break
+  e++
+
+  if (s === 0 && e === blocks) return false
+  if (s >= e) return { type: 'crop', args: [], at: 0, duration: 0 }
+  let startSample = s * audio.BLOCK_SIZE
+  let endSample = Math.min(e * audio.BLOCK_SIZE, total)
+  return { type: 'crop', args: [], at: startSample / sampleRate, duration: (endSample - startSample) / sampleRate }
+}
+
+audio.op('trim', { process: trim, resolve: trimResolve })