@miadi/ava8-measure 0.1.0

package/dist/audio.js

@@ -0,0 +1,821 @@
+/**
+ * Spectral share and pitch, read back off a rendered artefact.
+ *
+ * A port of the atelier's `atelier_audio.py` (numpy + the standard library
+ * `wave` module) onto typed arrays, so the same measurement can run where
+ * numpy cannot. The numbers are the point: this file agrees with that program
+ * on synthetic signals to better than 1e-6 relative, and four details are the
+ * reason it does. Each one silently changes every number if it is written the
+ * way a DSP tutorial writes it.
+ *
+ *  1. `hann(n)` is `np.hanning(n)` — the SYMMETRIC window, denominator `n - 1`,
+ *     not the periodic `n`. The difference is a fraction of a percent of a band
+ *     share, measured against a reject line that sits at 13.12 %.
+ *  2. `bandShare` sums MAGNITUDE by default, not power. Summing |X|² instead
+ *     puts every real piece under 1 % and makes the reject line unreachable by
+ *     any sound, which cannot be what the threshold was calibrated against.
+ *  3. A median over an even-length window is the mean of the two middle values,
+ *     and `medianSmooth` drops NaNs BEFORE taking the median.
+ *  4. The band mask is half-open — `freqs >= lo && freqs < hi`. The `<` decides
+ *     a whole bin at a band edge. (`octaveErrorCheck` uses a CLOSED interval
+ *     around each partial; that difference is in the original and is kept.)
+ *
+ * ## NaN is load-bearing
+ *
+ * `f0Track` returns a `Float64Array` carrying `NaN` for every unvoiced frame,
+ * and `isNaN` guards nearly every loop downstream. Silence with a pitch
+ * attached is an invention, and an unvoiced frame that reads as a number is
+ * how one gets invented. Do not reach for `number | null` here.
+ *
+ * ## Bytes in, never a path
+ *
+ * `decodeWav` takes a `Uint8Array`. This module opens no file, imports no
+ * `node:fs`, and touches no `Buffer` — a measurement library that reads the
+ * disk decides where a recording lives, and that decision belongs to whoever
+ * consented to the recording.
+ */
+import { STRIDENCE, stridenceVerdict } from "@miadi/ava8-atelier";
+import { irfft, rfft, rfftfreq } from "./fft.js";
+export { STRIDENCE, stridenceVerdict };
+/** Thrown for a WAV this module will not guess at. */
+export class UnsupportedWav extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedWav";
+    }
+}
+const WAVE_FORMAT_PCM = 0x0001;
+const WAVE_FORMAT_IEEE_FLOAT = 0x0003;
+const WAVE_FORMAT_EXTENSIBLE = 0xfffe;
+function fourcc(view, at) {
+    return String.fromCharCode(view.getUint8(at), view.getUint8(at + 1), view.getUint8(at + 2), view.getUint8(at + 3));
+}
+/**
+ * Decode a PCM WAV from bytes and mix it down to mono.
+ *
+ * Mono on purpose: every measure here is about spectral content and pitch, and
+ * a stereo pair measured separately would answer twice without deciding
+ * anything. Refuses a compressed or float WAV rather than guessing — a silent
+ * wrong answer is worse than a stop, and it is the same refusal the numpy
+ * original inherits from Python's `wave` module.
+ *
+ * 8-bit is unsigned, 16/24/32-bit are signed little-endian, matching the
+ * original byte for byte — including its `float32` intermediate, which is why
+ * a 32-bit source rounds identically here and there.
+ */
+export function decodeWav(bytes) {
+    if (bytes.byteLength < 12) {
+        throw new UnsupportedWav(`not a WAV: ${bytes.byteLength} bytes is too short for a RIFF header`);
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (fourcc(view, 0) !== "RIFF" || fourcc(view, 8) !== "WAVE") {
+        throw new UnsupportedWav("not a WAV: missing the RIFF/WAVE signature");
+    }
+    let format = -1;
+    let effective = -1;
+    let channels = 0;
+    let rate = 0;
+    let bits = 0;
+    let dataAt = -1;
+    let dataLen = 0;
+    let pos = 12;
+    while (pos + 8 <= bytes.byteLength) {
+        const id = fourcc(view, pos);
+        const size = view.getUint32(pos + 4, true);
+        const body = pos + 8;
+        if (id === "fmt " && size >= 16) {
+            format = view.getUint16(body, true);
+            channels = view.getUint16(body + 2, true);
+            rate = view.getUint32(body + 4, true);
+            bits = view.getUint16(body + 14, true);
+            effective = format;
+            // WAVE_FORMAT_EXTENSIBLE hides the real code in the first two bytes of
+            // its SubFormat GUID.
+            if (format === WAVE_FORMAT_EXTENSIBLE && size >= 40) {
+                effective = view.getUint16(body + 24, true);
+            }
+        }
+        else if (id === "data") {
+            dataAt = body;
+            dataLen = Math.min(size, bytes.byteLength - body);
+        }
+        pos = body + size + (size & 1);
+    }
+    if (format < 0)
+        throw new UnsupportedWav("WAV has no fmt chunk");
+    if (dataAt < 0)
+        throw new UnsupportedWav("WAV has no data chunk");
+    if (effective !== WAVE_FORMAT_PCM) {
+        const named = effective === WAVE_FORMAT_IEEE_FLOAT
+            ? "IEEE float"
+            : `format 0x${effective.toString(16)}`;
+        throw new UnsupportedWav(`WAV is ${named}, not linear PCM. This decoder does not decompress or ` +
+            "convert; re-render the file as 8, 16, 24 or 32-bit PCM rather than " +
+            "measuring a guess.");
+    }
+    if (channels < 1)
+        throw new UnsupportedWav(`WAV declares ${channels} channels`);
+    if (rate < 1)
+        throw new UnsupportedWav(`WAV declares a sample rate of ${rate}`);
+    const width = Math.ceil(bits / 8);
+    if (width < 1 || width > 4) {
+        throw new UnsupportedWav(`unsupported sample width ${width} bytes (${bits} bits)`);
+    }
+    const block = width * channels;
+    const frames = Math.floor(dataLen / block);
+    const total = frames * channels;
+    // float32 first, exactly as the numpy original does, so a 32-bit source
+    // rounds the same way in both programs.
+    const flat = new Float32Array(total);
+    for (let i = 0; i < total; i += 1) {
+        const at = dataAt + i * width;
+        if (width === 1) {
+            flat[i] = (view.getUint8(at) - 128.0) / 128.0;
+        }
+        else if (width === 2) {
+            flat[i] = view.getInt16(at, true) / 32768.0;
+        }
+        else if (width === 3) {
+            const raw = view.getUint8(at) | (view.getUint8(at + 1) << 8) | (view.getUint8(at + 2) << 16);
+            const signed = raw & 0x800000 ? raw - 0x1000000 : raw;
+            flat[i] = signed / 8388608.0;
+        }
+        else {
+            flat[i] = view.getInt32(at, true) / 2147483648.0;
+        }
+    }
+    const samples = new Float64Array(frames);
+    if (channels > 1) {
+        for (let i = 0; i < frames; i += 1) {
+            let acc = 0;
+            for (let c = 0; c < channels; c += 1)
+                acc = Math.fround(acc + flat[i * channels + c]);
+            samples[i] = Math.fround(acc / channels);
+        }
+    }
+    else {
+        samples.set(flat);
+    }
+    return { samples, rate, channels };
+}
+// --------------------------------------------------------------------------
+// spectrum
+// --------------------------------------------------------------------------
+/** Default analysis frame, so the same file measured on two hosts agrees. */
+export const N_FFT = 2048;
+/** Default hop: 50 % overlap. */
+export const HOP = 1024;
+/**
+ * `np.hanning(n)` — the SYMMETRIC Hann window, denominator `n - 1`.
+ *
+ * Not the periodic window (`denominator n`) that most DSP writing means by
+ * "Hann". The two differ by about 1e-1 at the shoulders of a short window and
+ * shift a band share by a fraction of a percent, which is the whole margin
+ * between one verdict and another.
+ *
+ * Written as numpy writes it — `0.5 + 0.5·cos(π·n/(M-1))` over
+ * `n = 1-M, 3-M, … M-1` — rather than the algebraically equal
+ * `0.5 - 0.5·cos(2πi/(M-1))`, because the two forms differ in the last bit and
+ * only this one reproduces `np.hanning` exactly.
+ */
+export function hann(n) {
+    if (n < 1)
+        return new Float64Array(0);
+    const out = new Float64Array(n);
+    if (n === 1) {
+        out[0] = 1;
+        return out;
+    }
+    for (let i = 0; i < n; i += 1) {
+        out[i] = 0.5 + 0.5 * Math.cos((Math.PI * (2 * i - n + 1)) / (n - 1));
+    }
+    return out;
+}
+/**
+ * Mean power spectrum over the whole file, Hann-windowed.
+ *
+ * Fixed 2048-point frames with 50 % overlap, so the same file measured twice
+ * returns the same number. A band edge is given in Hz, never in bins.
+ */
+export function spectrum(audio, opts = {}) {
+    const nFft = opts.nFft ?? N_FFT;
+    const hop = opts.hop ?? HOP;
+    const x = audio.samples;
+    const win = hann(nFft);
+    const bins = (nFft >> 1) + 1;
+    const acc = new Float64Array(bins);
+    const frame = new Float64Array(nFft);
+    const spec = { re: new Float64Array(bins), im: new Float64Array(bins) };
+    // the original zero-pads a file shorter than one frame, then frames it
+    const len = Math.max(x.length, nFft);
+    let frames = 0;
+    for (let s = 0; s + nFft <= len; s += hop) {
+        for (let i = 0; i < nFft; i += 1) {
+            const j = s + i;
+            frame[i] = (j < x.length ? x[j] : 0) * win[i];
+        }
+        rfft(frame, nFft, spec);
+        for (let k = 0; k < bins; k += 1) {
+            // np.abs(X)**2 — hypot then square, as the original writes it
+            const m = Math.hypot(spec.re[k], spec.im[k]);
+            acc[k] += m * m;
+        }
+        frames += 1;
+    }
+    if (frames) {
+        for (let k = 0; k < bins; k += 1)
+            acc[k] /= frames;
+    }
+    return { freqs: rfftfreq(nFft, 1.0 / audio.rate), power: acc };
+}
+/**
+ * Share of total spectral weight inside an arbitrary Hz band, whole file.
+ *
+ * Decides which instrument a piece gets, and whether an arrangement will mask
+ * a singer. Two bands are read for every candidate timbre: 2-5 kHz (does it
+ * scratch) and the singer's own band in Hz (does it sit on top of them). The
+ * winner is the best of the two numbers, not the prettiest sound.
+ *
+ * `weight: "magnitude"` sums |X| — the default, and the only scale on which
+ * the thresholds in `@miadi/ava8-atelier` mean anything. Summing |X|² instead
+ * puts every real piece under 1 % and makes a 13.12 % reject line unreachable
+ * by any sound, which cannot be what those thresholds were calibrated against.
+ *
+ * The mask is half-open: `freqs >= lo && freqs < hi`.
+ */
+export function bandShare(audio, loHz, hiHz, opts = {}) {
+    const { freqs, power } = spectrum(audio, opts);
+    const usePower = opts.weight === "power";
+    let total = 0;
+    let inside = 0;
+    for (let k = 0; k < power.length; k += 1) {
+        const v = usePower ? power[k] : Math.sqrt(power[k]);
+        total += v;
+        if (freqs[k] >= loHz && freqs[k] < hiHz)
+            inside += v;
+    }
+    if (total <= 0)
+        return 0.0;
+    return inside / total;
+}
+/**
+ * Share of spectral magnitude in 2000-5000 Hz over the whole file.
+ *
+ * THE timbre decision. See `STRIDENCE` and `stridenceVerdict` in
+ * `@miadi/ava8-atelier` for the thresholds; they belong to a musician and are
+ * not redefined here. Whole file on purpose: a bright section measured alone
+ * answers a different question than "does the piece scratch".
+ *
+ * UNVERIFIED against the session's own figures. The atelier's stridence code
+ * was never written down in a generator, and the candidate renders it read
+ * are gone, so this implementation could not be checked number for number.
+ * Measured here on the surviving renders of 2026-08-16: op019 2.09 %,
+ * op018 4.42 %, ava2v2 6.50 %, op023 8.44 % — the same ordering and the same
+ * 4-8 % range the session reported for that day, running 15-25 % low against
+ * the two figures it named (ava2v2 7.60 %, op023 11.30 %). Treat a number
+ * from this function as comparable to another number from this function, and
+ * re-measure every candidate rather than quoting a figure from the day.
+ */
+export function stridence(audio, opts = {}) {
+    return bandShare(audio, STRIDENCE.bandHz[0], STRIDENCE.bandHz[1], opts);
+}
+function nextPow2(v) {
+    let p = 1;
+    while (p < v)
+        p *= 2;
+    return p;
+}
+/**
+ * Autocorrelation f0 per 40 ms window, 5-frame median smoothing.
+ *
+ * Decides what is actually sung, as opposed to what a listener reports. Two
+ * guards, both earned:
+ *   · frames below `confFloor` or `rmsFloor` are UNVOICED (NaN), not forced to
+ *     a pitch — silence with a pitch attached is an invention;
+ *   · the median smoother removes single-frame octave flips, which are the
+ *     cheap half of the octave problem. The expensive half needs
+ *     `octaveErrorCheck`, and skipping it once invented a note nobody sang.
+ */
+export function f0Track(audio, opts = {}) {
+    const windowS = opts.windowS ?? 0.04;
+    const hopS = opts.hopS ?? 0.02;
+    const fmin = opts.fmin ?? 60.0;
+    const fmax = opts.fmax ?? 1000.0;
+    const confFloor = opts.confFloor ?? 0.3;
+    const rmsFloor = opts.rmsFloor ?? 1e-4;
+    const smooth = opts.smooth ?? 5;
+    const x = audio.samples;
+    const rate = audio.rate;
+    const n = Math.max(64, Math.trunc(windowS * rate));
+    const hop = Math.max(1, Math.trunc(hopS * rate));
+    const lagLo = Math.max(2, Math.trunc(rate / fmax));
+    const lagHi = Math.min(n - 1, Math.trunc(rate / fmin));
+    const nfft = nextPow2(2 * n);
+    const bins = (nfft >> 1) + 1;
+    const times = [];
+    const hz = [];
+    const rmsList = [];
+    const confList = [];
+    const seg = new Float64Array(n);
+    const spec = { re: new Float64Array(bins), im: new Float64Array(bins) };
+    const powerSpec = { re: new Float64Array(bins), im: new Float64Array(bins) };
+    const ac = new Float64Array(nfft);
+    const stop = Math.max(1, x.length - n + 1);
+    for (let s = 0; s < stop; s += hop) {
+        if (s + n > x.length)
+            break;
+        let mean = 0;
+        for (let i = 0; i < n; i += 1)
+            mean += x[s + i];
+        mean /= n;
+        let r0 = 0;
+        for (let i = 0; i < n; i += 1) {
+            const v = x[s + i] - mean;
+            seg[i] = v;
+            r0 += v * v;
+        }
+        const rms = Math.sqrt(r0 / n);
+        times.push((s + n / 2.0) / rate);
+        rmsList.push(rms);
+        if (r0 <= 0 || rms < rmsFloor || lagHi <= lagLo) {
+            hz.push(Number.NaN);
+            confList.push(0.0);
+            continue;
+        }
+        rfft(seg, nfft, spec);
+        for (let k = 0; k < bins; k += 1) {
+            const m = Math.hypot(spec.re[k], spec.im[k]);
+            powerSpec.re[k] = m * m;
+            powerSpec.im[k] = 0;
+        }
+        irfft(powerSpec, nfft, ac);
+        const zero = ac[0];
+        let best = lagLo;
+        let bestVal = ac[lagLo] / zero;
+        for (let k = lagLo + 1; k <= lagHi; k += 1) {
+            const v = ac[k] / zero;
+            if (v > bestVal) {
+                bestVal = v;
+                best = k;
+            }
+        }
+        const c = bestVal;
+        if (c < confFloor) {
+            hz.push(Number.NaN);
+            confList.push(c);
+            continue;
+        }
+        let kRef = best;
+        if (best > 0 && best < n - 1) {
+            const y0 = ac[best - 1] / zero;
+            const y1 = ac[best] / zero;
+            const y2 = ac[best + 1] / zero;
+            const denom = y0 - 2 * y1 + y2;
+            kRef = denom ? best + 0.5 * (y0 - y2) / denom : best;
+        }
+        hz.push(kRef > 0 ? rate / kRef : Number.NaN);
+        confList.push(c);
+    }
+    let midi = new Float64Array(hz.length);
+    for (let i = 0; i < hz.length; i += 1) {
+        midi[i] = Number.isNaN(hz[i])
+            ? Number.NaN
+            : 69.0 + 12.0 * Math.log2(Math.max(hz[i], 1e-9) / 440.0);
+    }
+    const hzArr = Float64Array.from(hz);
+    if (smooth && smooth > 1) {
+        midi = medianSmooth(midi, smooth);
+        for (let i = 0; i < midi.length; i += 1) {
+            hzArr[i] = Number.isNaN(midi[i]) ? Number.NaN : 440.0 * 2.0 ** ((midi[i] - 69.0) / 12.0);
+        }
+    }
+    return {
+        times: Float64Array.from(times),
+        midi,
+        hz: hzArr,
+        rms: Float64Array.from(rmsList),
+        confidence: Float64Array.from(confList),
+        rate,
+        windowS,
+        hopS,
+    };
+}
+/** `np.median` — an even-length window is the MEAN of the two middle values. */
+function medianOf(values) {
+    const s = values.slice().sort((a, b) => a - b);
+    const len = s.length;
+    if (len === 0)
+        return Number.NaN;
+    const mid = len >> 1;
+    return len % 2 === 1 ? s[mid] : 0.5 * (s[mid - 1] + s[mid]);
+}
+/**
+ * Median over `k` frames, NaN-aware. A single wild frame must not become a note.
+ *
+ * NaNs are dropped BEFORE the median, not treated as values and not
+ * propagated: a window that is half unvoiced still has a real median, and a
+ * window that is entirely unvoiced stays NaN.
+ */
+export function medianSmooth(series, k) {
+    const len = series.length;
+    const out = new Float64Array(len);
+    const half = Math.floor(k / 2);
+    for (let i = 0; i < len; i += 1) {
+        const lo = Math.max(0, i - half);
+        const hi = Math.min(len, i + half + 1);
+        const w = [];
+        for (let j = lo; j < hi; j += 1) {
+            if (!Number.isNaN(series[j]))
+                w.push(series[j]);
+        }
+        out[i] = w.length ? medianOf(w) : Number.NaN;
+    }
+    return out;
+}
+/**
+ * Fold every MIDI value down by octaves until it sits at or under `ceiling`.
+ *
+ * Decides where a voice really is. A tracker that reports B4 for a man droning
+ * B2 is reporting its own error, and folding is the first half of the fix —
+ * the second half is `octaveErrorCheck`, which says whether the fold was
+ * warranted or whether the note up there was genuinely sung.
+ */
+export function foldOctaves(midiSeries, ceiling, floor) {
+    const m = Float64Array.from(midiSeries);
+    for (let i = 0; i < m.length; i += 1) {
+        while (m[i] > ceiling)
+            m[i] -= 12.0;
+    }
+    if (floor !== undefined) {
+        for (let i = 0; i < m.length; i += 1) {
+            while (m[i] < floor)
+                m[i] += 12.0;
+        }
+    }
+    return m;
+}
+/**
+ * Energy at f/4 against energy at f, frame by frame. This caught an invented note.
+ *
+ * Decides whether a reported high pitch is real. When `shareBelow` is high and
+ * `medianRatio` > 1, the tracker is octave-doubling and the series must be
+ * folded before a note is claimed.
+ *
+ * The analysis window here is longer than the tracker's (4× by default): f/4
+ * of 494 Hz is 123 Hz, which a 40 ms window cannot resolve. Measuring the
+ * correction at the resolution that produced the error would reproduce it.
+ *
+ * The ratio is a POWER ratio, so a component at four times the amplitude reads
+ * 16 and not 4. Verified against a synthesised case: f/4 built at 5× amplitude
+ * reads 24.82. Say which ratio you mean when you quote it.
+ *
+ * Note the band here is CLOSED — `>= lo && <= hi` — unlike the half-open mask
+ * in `bandShare`. That asymmetry is in the original and is preserved.
+ */
+export function octaveErrorCheck(audio, f0, opts = {}) {
+    const ratioHz = opts.ratioHz ?? 4.0;
+    const bandFrac = opts.bandFrac ?? 0.06;
+    const minHz = opts.minHz ?? 40.0;
+    const longWindowFactor = opts.longWindowFactor ?? 4;
+    const rate = audio.rate;
+    const x = audio.samples;
+    const n = Math.max(256, Math.trunc(f0.windowS * rate) * longWindowFactor);
+    const nfft = nextPow2(n);
+    const bins = (nfft >> 1) + 1;
+    const win = hann(n);
+    const freqs = rfftfreq(nfft, 1.0 / rate);
+    const frame = new Float64Array(n);
+    const spec = { re: new Float64Array(bins), im: new Float64Array(bins) };
+    const powerBins = new Float64Array(bins);
+    const ratios = [];
+    const count = Math.min(f0.times.length, f0.hz.length);
+    for (let idx = 0; idx < count; idx += 1) {
+        const t = f0.times[idx];
+        const f = f0.hz[idx];
+        if (Number.isNaN(f) || f / ratioHz < minHz)
+            continue;
+        const c = Math.trunc(t * rate);
+        const s = Math.max(0, c - Math.floor(n / 2));
+        if (s + n > x.length)
+            continue;
+        let mean = 0;
+        for (let i = 0; i < n; i += 1)
+            mean += x[s + i];
+        mean /= n;
+        for (let i = 0; i < n; i += 1)
+            frame[i] = (x[s + i] - mean) * win[i];
+        rfft(frame, nfft, spec);
+        for (let k = 0; k < bins; k += 1) {
+            const m = Math.hypot(spec.re[k], spec.im[k]);
+            powerBins[k] = m * m;
+        }
+        const lo = f * (1 - bandFrac);
+        const hi = f * (1 + bandFrac);
+        const fl = f / ratioHz;
+        const subLo = fl * (1 - bandFrac);
+        const subHi = fl * (1 + bandFrac);
+        let ef = 0;
+        let eSub = 0;
+        for (let k = 0; k < bins; k += 1) {
+            const fr = freqs[k];
+            if (fr >= lo && fr <= hi)
+                ef += powerBins[k];
+            if (fr >= subLo && fr <= subHi)
+                eSub += powerBins[k];
+        }
+        if (ef > 0)
+            ratios.push(eSub / ef);
+    }
+    if (ratios.length === 0) {
+        return {
+            frames: 0,
+            medianRatio: null,
+            meanRatio: null,
+            shareBelow: null,
+            verdict: "no voiced frame could be checked",
+        };
+    }
+    let above = 0;
+    let sum = 0;
+    for (const r of ratios) {
+        if (r > 1.0)
+            above += 1;
+        sum += r;
+    }
+    const share = above / ratios.length;
+    const med = medianOf(ratios);
+    const verdict = med > 1.0 && share > 0.5
+        ? `octave error: energy at f/${fmtG(ratioHz)} is ${fmtFixed(med, 2)}× stronger in ` +
+            `${fmtFixed(100 * share, 0)} % of frames — fold before claiming a note`
+        : `no octave error detected (median ratio ${fmtFixed(med, 2)}, ` +
+            `${fmtFixed(100 * share, 0)} % of frames)`;
+    return {
+        frames: ratios.length,
+        medianRatio: med,
+        meanRatio: sum / ratios.length,
+        shareBelow: share,
+        verdict,
+    };
+}
+/**
+ * Frames that stay within ±1 semitone for at least 200 ms become one note.
+ *
+ * Decides what is singing and what is speech. Speech never holds a pitch for
+ * 200 ms; a drone holds it for seconds. Everything downstream — the
+ * pitch-class profile, the motif database, the interval cells — is built on
+ * these notes and not on frames, because a frame count is a property of the
+ * tracker's hop and a held note is a property of the singer.
+ */
+export function heldNotes(f0, opts = {}) {
+    const minMs = opts.minMs ?? 200.0;
+    const tol = opts.tolSemitones ?? 1.0;
+    const minS = minMs / 1000.0;
+    const out = [];
+    let run = [];
+    const close = () => {
+        if (run.length === 0)
+            return;
+        const first = f0.times[run[0]];
+        const last = f0.times[run[run.length - 1]];
+        const dur = last - first + f0.hopS;
+        if (dur >= minS) {
+            const ms = [];
+            let rmsSum = 0;
+            for (const i of run) {
+                ms.push(f0.midi[i]);
+                rmsSum += f0.rms[i];
+            }
+            const start = pyRound(first, 4);
+            const end = pyRound(first + dur, 4);
+            out.push({
+                start,
+                end,
+                midi: medianOf(ms),
+                rms: rmsSum / run.length,
+                duration: end - start,
+            });
+        }
+    };
+    for (let i = 0; i < f0.midi.length; i += 1) {
+        const m = f0.midi[i];
+        if (Number.isNaN(m)) {
+            close();
+            run = [];
+            continue;
+        }
+        if (run.length === 0) {
+            run = [i];
+            continue;
+        }
+        const ref = medianOf(run.map((j) => f0.midi[j]));
+        if (Math.abs(m - ref) <= tol && f0.times[i] - f0.times[run[run.length - 1]] <= 2.5 * f0.hopS) {
+            run.push(i);
+        }
+        else {
+            close();
+            run = [i];
+        }
+    }
+    close();
+    return out;
+}
+export const MOTIF_MIN_NOTES = 3;
+export const MOTIF_MIN_DISTINCT = 3;
+export const MOTIF_MIN_SPAN = 3.0;
+/**
+ * Split held notes into gestures at every silence, then classify each one.
+ *
+ * The rule, and it is a rule and not an impression: a gesture is a MOTIF when
+ * it has ≥3 notes, ≥3 distinct pitches and a span of ≥3 semitones. Anything
+ * else is a DRONE. Without it, someone who drones reads as a melodist — which
+ * is exactly the mistake that would have had them handed a tune to sing
+ * instead of a world to stand inside.
+ */
+export function motifs(notes, opts = {}) {
+    const gapS = opts.gapS ?? 0.5;
+    const gestures = [];
+    let cur = [];
+    for (const n of notes) {
+        if (cur.length > 0 && n.start - cur[cur.length - 1].end > gapS) {
+            gestures.push(cur);
+            cur = [];
+        }
+        cur.push(n);
+    }
+    if (cur.length > 0)
+        gestures.push(cur);
+    return gestures.map((g) => {
+        const pitches = g.map((n) => pyRound(n.midi, 0));
+        const distinct = new Set(pitches).size;
+        const span = pitches.length ? Math.max(...pitches) - Math.min(...pitches) : 0;
+        const isMotif = g.length >= MOTIF_MIN_NOTES && distinct >= MOTIF_MIN_DISTINCT && span >= MOTIF_MIN_SPAN;
+        const intervals = [];
+        for (let i = 0; i + 1 < pitches.length; i += 1)
+            intervals.push(pitches[i + 1] - pitches[i]);
+        return {
+            kind: isMotif ? "motif" : "drone",
+            start: g[0].start,
+            end: g[g.length - 1].end,
+            duration: pyRound(g[g.length - 1].end - g[0].start, 3),
+            nNotes: g.length,
+            distinct,
+            span,
+            pitches,
+            intervals,
+            notes: g,
+        };
+    });
+}
+/**
+ * Recurring interval sequences across gestures, with the time of every hit.
+ *
+ * Intervals and not pitches on purpose: a cell sung twice at different heights
+ * is the same cell, and counting pitches would miss it.
+ *
+ * Returns cells sorted by count then length, each with its timestamps. A cell
+ * that appears once is still returned; the timestamps are what let a human
+ * listen and disagree.
+ */
+export function intervalCells(gestures, opts = {}) {
+    const lengths = opts.lengths ?? [2, 3, 4];
+    const motifsOnly = opts.motifsOnly ?? true;
+    const hits = new Map();
+    for (let gi = 0; gi < gestures.length; gi += 1) {
+        const g = gestures[gi];
+        if (motifsOnly && g.kind !== "motif")
+            continue;
+        const iv = g.intervals;
+        for (const L of lengths) {
+            for (let i = 0; i + L <= iv.length; i += 1) {
+                const cell = iv.slice(i, i + L);
+                const key = `${L}|${cell.join(",")}`;
+                let rec = hits.get(key);
+                if (!rec) {
+                    rec = { cell, length: L, count: 0, times: [], gestures: [] };
+                    hits.set(key, rec);
+                }
+                rec.count += 1;
+                rec.times.push(pyRound(g.notes[i].start, 3));
+                rec.gestures.push(gi);
+            }
+        }
+    }
+    return [...hits.values()].sort((a, b) => b.count - a.count || b.length - a.length || a.times[0] - b.times[0]);
+}
+/**
+ * RMS before, during and after every crossfade point.
+ *
+ * Decides whether an assembled piece is listenable. A seam that dips to
+ * silence is a hole; a seam that jumps is a click. Both are audible and both
+ * are invisible in the source score, because the score does not know the
+ * pieces were glued. Reported as levels and as a difference: dB differences
+ * are what an ear notices, and `jumpDb` is the number to argue about.
+ */
+export function seams(audio, times, opts = {}) {
+    const windowS = opts.windowS ?? 0.25;
+    const x = audio.samples;
+    const rms = (t0, t1) => {
+        const i0 = Math.max(0, Math.trunc(t0 * audio.rate));
+        const i1 = Math.min(x.length, Math.trunc(t1 * audio.rate));
+        if (i1 <= i0)
+            return 0.0;
+        let acc = 0;
+        for (let i = i0; i < i1; i += 1)
+            acc += x[i] * x[i];
+        return Math.sqrt(acc / (i1 - i0));
+    };
+    const db = (v) => (v > 0 ? 20.0 * Math.log10(v) : Number.NEGATIVE_INFINITY);
+    return times.map((t) => {
+        const before = rms(t - windowS, t);
+        const during = rms(t - windowS / 2.0, t + windowS / 2.0);
+        const after = rms(t, t + windowS);
+        const lo = Math.min(before, during, after);
+        const hi = Math.max(before, during, after);
+        // a seam that runs into silence is a hole; a seam that halves is a dip.
+        // Both are audible, and the silence case must not be excused by a missing
+        // ratio — that is exactly the seam a listener notices first.
+        const silent = lo <= 0.0 && 0.0 < hi;
+        return {
+            at: t,
+            windowS,
+            rmsBefore: before,
+            rmsDuring: during,
+            rmsAfter: after,
+            dbBefore: db(before),
+            dbDuring: db(during),
+            dbAfter: db(after),
+            jumpDb: before > 0 && after > 0 ? db(after) - db(before) : null,
+            silent,
+            dip: (before > 0 && after > 0 && during < 0.5 * Math.min(before, after)) || silent,
+        };
+    });
+}
+// --------------------------------------------------------------------------
+// small numeric helpers, matching Python where it differs from JavaScript
+// --------------------------------------------------------------------------
+/**
+ * Python's `round(x, d)` — half to EVEN, where JavaScript rounds half away
+ * from zero. `round(2.5)` is 2 in Python and 3 in JavaScript, and the pitches
+ * a motif is classified on are rounded MIDI floats.
+ */
+export function pyRound(x, digits) {
+    if (!Number.isFinite(x))
+        return x;
+    const halfEven = (scaled) => {
+        const floor = Math.floor(scaled);
+        const frac = scaled - floor;
+        if (frac > 0.5)
+            return floor + 1;
+        if (frac < 0.5)
+            return floor;
+        return floor % 2 === 0 ? floor : floor + 1;
+    };
+    if (digits === 0)
+        return halfEven(x);
+    // `x * 10**digits` is NOT safe to round from: 2.675 is really
+    // 2.67499999999999982, so Python answers 2.67 while the scaled product
+    // answers 2.68. `toFixed` rounds from the exact value of the double, which
+    // is what Python does — it differs only on an exact tie, which it breaks
+    // away from zero where Python breaks it to even.
+    //
+    // A tie is exact only when the double is a dyadic rational with denominator
+    // 2^(digits+1) — 0.03125 at 4 digits, never 2.675 at 2 — and in that case
+    // the scaled product IS exact, so scaling is safe there and only there.
+    const p = 10 ** digits;
+    const scaled = x * p;
+    if (Number.isInteger(x * 2 ** (digits + 1)) &&
+        Math.abs(scaled) < Number.MAX_SAFE_INTEGER &&
+        Math.abs(scaled - Math.floor(scaled)) === 0.5) {
+        return halfEven(scaled) / p;
+    }
+    return Number(x.toFixed(digits));
+}
+/** Python's `f"{v:.Nf}"` — correctly rounded, ties to even. */
+function fmtFixed(v, digits) {
+    if (!Number.isFinite(v))
+        return String(v);
+    const probe = v.toFixed(digits + 1);
+    if (probe.endsWith("5") && Number(probe) === v) {
+        return pyRound(v, digits).toFixed(digits);
+    }
+    return v.toFixed(digits);
+}
+/** Python's `f"{v:g}"` — six significant digits, trailing zeros stripped. */
+function fmtG(v) {
+    if (!Number.isFinite(v))
+        return String(v);
+    if (v === 0)
+        return "0";
+    const exp = Math.floor(Math.log10(Math.abs(v)));
+    if (exp < -4 || exp >= 6) {
+        return v
+            .toExponential(5)
+            .replace(/\.?0+e/, "e")
+            .replace(/e([+-])(\d)$/, "e$10$2");
+    }
+    let s = v.toPrecision(6);
+    if (s.includes("."))
+        s = s.replace(/\.?0+$/, "");
+    return s;
+}
+//# sourceMappingURL=audio.js.map