@bitmagic/asset-core 0.2.25-dev.0 → 0.2.25-dev.1

package/dist/trailer/music-beats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"music-beats.d.ts","sourceRoot":"","sources":["../../src/trailer/music-beats.ts"],"names":[],"mappings":"AAkBA,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AACtC,eAAO,MAAM,UAAU,OAAO,CAAC;AAC/B,eAAO,MAAM,QAAQ,MAAM,CAAC;AAC5B,eAAO,MAAM,aAAa,IAAI,CAAC;AAkC/B,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA6BD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,GAAG,IAAI,CAuCnE;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,YAAY,CAUpE;AAMD,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,QAAQ,EAAE,YAAY,CAAC;IACvB,qEAAqE;IACrE,GAAG,EAAE,YAAY,CAAC;IAClB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;CAChB;AA2BD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAmB,EAC9B,OAAO,GAAE,MAAiB,GACzB,aAAa,CAwCf;AAgBD,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;CAChB;AA+CD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,aAAa,CAiD7D;AA6BD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAmB9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,OAAO,GAClB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAczC;AAmED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAoB5E;AAqBD,+EAA+E;AAC/E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,YAAY,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,WAAgB,GACrB,YAAY,CA0Dd;AAMD;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAa7E;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiBhG;AAED,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAKnG;AAsBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBjG;AAMD,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BlG"}

package/dist/trailer/music-beats.js

@@ -0,0 +1,672 @@
+/**
+ * Beat detection for trailer music — hand-rolled DSP, no audio libraries.
+ *
+ * ffmpeg decodes the track to mono 16-bit PCM on stdout; everything after that
+ * (Hann window, radix-2 FFT, spectral flux, autocorrelation, phase search) is
+ * plain TypeScript, the same way synth.ts hand-writes WAV encoding.
+ *
+ * The pure half — analyzeBeatsFromSamples and everything below it — takes raw
+ * samples, so the whole pipeline unit-tests on synthetic PCM without ffmpeg.
+ */
+import { TrailerError } from './errors.js';
+import { captureFfmpegTool } from './ffmpeg.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { SYNTH_SAMPLE_RATE, samplesToWav, synthesizeSamples } from './synth.js';
+import { out } from './io.js';
+/** Analysis decode rate: covers kick through hat, and keeps the FFTs cheap. */
+export const BEAT_SAMPLE_RATE = 22050;
+export const FRAME_SIZE = 1024;
+export const HOP_SIZE = 512;
+export const BEATS_PER_BAR = 4;
+const MIN_BPM = 60;
+const MAX_BPM = 200;
+/** Under this, the autocorrelation peak is more likely half-time than tempo. */
+const OCTAVE_UP_BELOW_BPM = 90;
+/** Over this, the peak is more likely double-time than tempo. */
+const OCTAVE_DOWN_ABOVE_BPM = 180;
+/** Take the doubled tempo when it still scores this fraction of the peak. */
+const OCTAVE_UP_TOLERANCE = 0.85;
+/** Onset-spike blur (in frames) applied before autocorrelation. */
+const TEMPO_SMOOTH_FRAMES = 2;
+/** Width of the moving average subtracted from the raw flux. */
+const BASELINE_SEC = 0.5;
+/** Kick band for downbeat picking. */
+const LOW_BAND_HZ = 150;
+/** Below this relative spread the four low-band phase scores are a coin flip. */
+const LOW_BAND_FLAT_SPREAD = 0.05;
+const SILENCE_DBFS = -120;
+/**
+ * confidence maps the ratio (mean onset strength on the grid) / (mean onset
+ * strength everywhere) onto 0..1: ratio 1 is chance — a grid that hits nothing
+ * special — and maps to 0; a grid landing on onsets this many times stronger
+ * than the track average maps to 1. Measured on real tracks, a wrong tempo
+ * sits at 0.8-1.5 and a locked-on grid at 3-4, so the scale is set at 4.
+ */
+const CONFIDENCE_FULL_RATIO = 4;
+/** Half-width, in beats, of the window a grid refinement pulls onsets from. */
+const REFINE_WINDOW_BEATS = 0.25;
+/** Beats in the first grid-refinement pass, before the horizon doubles. */
+const REFINE_FIRST_HORIZON_BEATS = 8;
+/** A refit that moves the period further than this is rejected as a bad fit. */
+const REFINE_MAX_PERIOD_DRIFT = 0.05;
+const twiddleCache = new Map();
+/** cos/sin of -2*pi*k/n for k < n/2, cached per transform size. */
+function twiddles(n) {
+    const cached = twiddleCache.get(n);
+    if (cached !== undefined)
+        return cached;
+    const cos = new Float64Array(n / 2);
+    const sin = new Float64Array(n / 2);
+    for (let k = 0; k < n / 2; k++) {
+        const angle = (-2 * Math.PI * k) / n;
+        cos[k] = Math.cos(angle);
+        sin[k] = Math.sin(angle);
+    }
+    const table = { cos, sin };
+    twiddleCache.set(n, table);
+    return table;
+}
+/**
+ * Iterative in-place radix-2 Cooley-Tukey FFT. Power-of-two lengths only —
+ * the frame size is ours to choose, so there is no mixed-radix fallback.
+ */
+export function fftInPlace(re, im) {
+    const n = re.length;
+    if (im.length !== n)
+        throw new Error(`FFT real/imag length mismatch: ${n} vs ${im.length}`);
+    if (n < 2 || (n & (n - 1)) !== 0)
+        throw new Error(`FFT size must be a power of two >= 2, got ${n}`);
+    // Bit-reversal permutation.
+    for (let i = 1, j = 0; i < n; i++) {
+        let bit = n >> 1;
+        for (; (j & bit) !== 0; bit >>= 1)
+            j ^= bit;
+        j ^= bit;
+        if (i < j) {
+            const tr = re[i];
+            re[i] = re[j];
+            re[j] = tr;
+            const ti = im[i];
+            im[i] = im[j];
+            im[j] = ti;
+        }
+    }
+    const { cos, sin } = twiddles(n);
+    for (let len = 2; len <= n; len <<= 1) {
+        const half = len >> 1;
+        const stride = n / len;
+        for (let start = 0; start < n; start += len) {
+            for (let k = 0; k < half; k++) {
+                const wr = cos[k * stride];
+                const wi = sin[k * stride];
+                const a = start + k;
+                const b = a + half;
+                const vr = re[b] * wr - im[b] * wi;
+                const vi = re[b] * wi + im[b] * wr;
+                re[b] = re[a] - vr;
+                im[b] = im[a] - vi;
+                re[a] += vr;
+                im[a] += vi;
+            }
+        }
+    }
+}
+/** Magnitude spectrum of a real frame: bins 0..n/2 inclusive. */
+export function fftMagnitudes(frame) {
+    const n = frame.length;
+    const re = new Float64Array(n);
+    const im = new Float64Array(n);
+    for (let i = 0; i < n; i++)
+        re[i] = frame[i];
+    fftInPlace(re, im);
+    const bins = n / 2 + 1;
+    const mags = new Float64Array(bins);
+    for (let b = 0; b < bins; b++)
+        mags[b] = Math.hypot(re[b], im[b]);
+    return mags;
+}
+function hannWindow(size) {
+    const w = new Float64Array(size);
+    for (let i = 0; i < size; i++)
+        w[i] = 0.5 * (1 - Math.cos((2 * Math.PI * i) / size));
+    return w;
+}
+/**
+ * Subtract a centred moving average and half-wave rectify, so a loud steady
+ * section reads as no onset at all while a transient still spikes.
+ */
+function subtractBaseline(flux, hopSec) {
+    const n = flux.length;
+    const half = Math.max(1, Math.round(BASELINE_SEC / 2 / hopSec));
+    const prefix = new Float64Array(n + 1);
+    for (let i = 0; i < n; i++)
+        prefix[i + 1] = prefix[i] + flux[i];
+    const result = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        const from = Math.max(0, i - half);
+        const to = Math.min(n, i + half + 1);
+        const mean = (prefix[to] - prefix[from]) / (to - from);
+        result[i] = Math.max(0, flux[i] - mean);
+    }
+    return result;
+}
+/**
+ * Spectral-flux onset envelope. Frames are centred (the signal is treated as
+ * zero-padded by frameSize/2 on the left) so frame t sits exactly on
+ * t * hopSec — the beat grid is built in that time base.
+ */
+export function computeOnsetEnvelope(samples, sampleRate, frameSize = FRAME_SIZE, hopSize = HOP_SIZE) {
+    const hopSec = hopSize / sampleRate;
+    const frameCount = Math.max(1, Math.floor(samples.length / hopSize) + 1);
+    const window = hannWindow(frameSize);
+    const bins = frameSize / 2 + 1;
+    const lowBins = Math.max(1, Math.min(bins, Math.round((LOW_BAND_HZ * frameSize) / sampleRate) + 1));
+    const flux = new Float64Array(frameCount);
+    const lowFlux = new Float64Array(frameCount);
+    const frame = new Float64Array(frameSize);
+    let prev = null;
+    for (let t = 0; t < frameCount; t++) {
+        const start = t * hopSize - frameSize / 2;
+        for (let i = 0; i < frameSize; i++) {
+            const index = start + i;
+            frame[i] = index >= 0 && index < samples.length ? samples[index] * window[i] : 0;
+        }
+        const mags = fftMagnitudes(frame);
+        if (prev !== null) {
+            let total = 0;
+            let low = 0;
+            for (let b = 0; b < bins; b++) {
+                const rise = mags[b] - prev[b];
+                if (rise > 0) {
+                    total += rise;
+                    if (b < lowBins)
+                        low += rise;
+                }
+            }
+            flux[t] = total;
+            lowFlux[t] = low;
+        }
+        prev = mags;
+    }
+    return {
+        strength: subtractBaseline(flux, hopSec),
+        low: subtractBaseline(lowFlux, hopSec),
+        hopSec
+    };
+}
+/** Linear-interpolated envelope value at an arbitrary time. */
+function sampleEnvelope(values, hopSec, timeSec) {
+    const position = timeSec / hopSec;
+    if (position <= 0)
+        return values.length > 0 ? values[0] : 0;
+    const i = Math.floor(position);
+    if (i >= values.length - 1)
+        return values.length > 0 ? values[values.length - 1] : 0;
+    const frac = position - i;
+    return values[i] * (1 - frac) + values[i + 1] * frac;
+}
+/**
+ * Small Gaussian blur of the envelope, for tempo estimation only.
+ *
+ * A hard one-frame onset spike makes the autocorrelation prefer whole-frame
+ * lags: at a true period of 21.53 frames the beat lag lands between samples
+ * and scores low, while the two-beat lag (43.06) lands almost on a frame and
+ * scores high — the estimator picks half tempo for a purely numeric reason.
+ * Widening each spike to ~3 frames makes the correlation continuous in lag.
+ */
+function smoothForTempo(values, sigmaFrames) {
+    const radius = Math.max(1, Math.ceil(sigmaFrames * 3));
+    const kernel = [];
+    let sum = 0;
+    for (let d = -radius; d <= radius; d++) {
+        const w = Math.exp(-(d * d) / (2 * sigmaFrames * sigmaFrames));
+        kernel.push(w);
+        sum += w;
+    }
+    const smoothed = new Float64Array(values.length);
+    for (let i = 0; i < values.length; i++) {
+        let acc = 0;
+        for (let d = -radius; d <= radius; d++) {
+            const j = i + d;
+            if (j >= 0 && j < values.length)
+                acc += values[j] * kernel[d + radius];
+        }
+        smoothed[i] = acc / sum;
+    }
+    return smoothed;
+}
+/**
+ * Autocorrelation of the mean-removed envelope at a (possibly fractional) lag
+ * in frames, normalized by the overlap length so long lags are not penalized.
+ */
+function autocorrelation(centred, hopSec, lagFrames) {
+    const n = centred.length;
+    const span = n - Math.ceil(lagFrames);
+    if (span <= 0)
+        return 0;
+    let sum = 0;
+    for (let t = 0; t < span; t++) {
+        sum += centred[t] * sampleEnvelope(centred, hopSec, (t + lagFrames) * hopSec);
+    }
+    return sum / span;
+}
+/**
+ * Tempo from the onset envelope: autocorrelation peak over 60-200 BPM, refined
+ * to a fractional lag, then octave-corrected. The refinement matters — at a
+ * 23ms hop the integer lags around 120 BPM are 117.4 and 123.0 BPM, so an
+ * integer-lag answer alone cannot be within 1 BPM of the truth.
+ */
+export function detectTempo(env) {
+    const { hopSec } = env;
+    // sqrt-compress first: tempo is about WHERE the onsets are, not how loud.
+    // Uncompressed, a run of alternating loud/quiet onsets correlates better at
+    // two beats (loud-to-loud) than at one (loud-to-quiet), and the estimator
+    // reports half tempo for what is really a dynamics artefact.
+    const compressed = new Float64Array(env.strength.length);
+    for (let i = 0; i < compressed.length; i++)
+        compressed[i] = Math.sqrt(env.strength[i]);
+    const strength = smoothForTempo(compressed, TEMPO_SMOOTH_FRAMES);
+    const n = strength.length;
+    let mean = 0;
+    for (let i = 0; i < n; i++)
+        mean += strength[i];
+    mean /= Math.max(1, n);
+    const centred = new Float64Array(n);
+    for (let i = 0; i < n; i++)
+        centred[i] = strength[i] - mean;
+    const minLag = Math.max(2, Math.floor(60 / MAX_BPM / hopSec));
+    const maxLag = Math.min(n - 2, Math.ceil(60 / MIN_BPM / hopSec));
+    if (maxLag <= minLag)
+        return { bpm: MIN_BPM, score: 0, rawBpm: MIN_BPM };
+    let bestLag = minLag;
+    let bestScore = -Infinity;
+    for (let lag = minLag; lag <= maxLag; lag++) {
+        const score = autocorrelation(centred, hopSec, lag);
+        if (score > bestScore) {
+            bestScore = score;
+            bestLag = lag;
+        }
+    }
+    const refined = refineLag(centred, hopSec, bestLag, minLag, maxLag);
+    const rawBpm = 60 / (refined.lag * hopSec);
+    // Octave correction. Halving is unconditional (60-200 BPM halves into a
+    // plausible 90-100); doubling has to earn it against the peak's own score.
+    let bpm = rawBpm;
+    let score = refined.score;
+    if (rawBpm > OCTAVE_DOWN_ABOVE_BPM) {
+        const halved = refineLag(centred, hopSec, refined.lag * 2, minLag, maxLag);
+        bpm = 60 / (halved.lag * hopSec);
+        score = halved.score;
+    }
+    else if (rawBpm < OCTAVE_UP_BELOW_BPM) {
+        const doubled = refineLag(centred, hopSec, refined.lag / 2, minLag, maxLag);
+        if (doubled.score >= refined.score * OCTAVE_UP_TOLERANCE) {
+            bpm = 60 / (doubled.lag * hopSec);
+            score = doubled.score;
+        }
+    }
+    return { bpm, score, rawBpm };
+}
+/** Fine scan of the autocorrelation around a lag, at 1/20th of a frame. */
+function refineLag(centred, hopSec, lagFrames, minLag, maxLag) {
+    const step = 0.05;
+    let bestLag = Math.min(maxLag, Math.max(minLag, lagFrames));
+    let bestScore = autocorrelation(centred, hopSec, bestLag);
+    for (let delta = -1; delta <= 1 + 1e-9; delta += step) {
+        const lag = lagFrames + delta;
+        if (lag < minLag || lag > maxLag)
+            continue;
+        const score = autocorrelation(centred, hopSec, lag);
+        if (score > bestScore) {
+            bestScore = score;
+            bestLag = lag;
+        }
+    }
+    return { lag: bestLag, score: bestScore };
+}
+// ---------------------------------------------------------------------------
+// Phase and grid
+// ---------------------------------------------------------------------------
+/**
+ * With the period fixed, the offset within one period whose grid collects the
+ * most onset strength. Offsets are hop-sized; refineGrid takes it from there.
+ */
+export function detectPhase(env, periodSec, durationSec) {
+    const steps = Math.max(1, Math.round(periodSec / env.hopSec));
+    const beatCount = Math.max(1, Math.floor(durationSec / periodSec) + 1);
+    let bestOffset = 0;
+    let bestScore = -Infinity;
+    for (let k = 0; k < steps; k++) {
+        const offset = (k * periodSec) / steps;
+        let score = 0;
+        for (let j = 0; j < beatCount; j++) {
+            const t = offset + j * periodSec;
+            if (t > durationSec)
+                break;
+            score += sampleEnvelope(env.strength, env.hopSec, t);
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            bestOffset = offset;
+        }
+    }
+    return bestOffset;
+}
+/**
+ * Pull the grid onto the onsets it found. Each beat contributes the
+ * strength-weighted centroid of the envelope within a quarter beat of it, and
+ * a weighted least-squares line through those centroids gives period+phase at
+ * sub-hop resolution.
+ *
+ * This is not a nicety. The autocorrelation peak around the beat lag is a
+ * near-flat trapezoid — one beat of a 120 BPM track is 21.53 frames, and both
+ * lag 21 (123.0 BPM) and lag 22 (117.4 BPM) score about the same — so the
+ * tempo alone is only good to a couple of percent, and no hop-sized phase can
+ * be better than +-12ms.
+ *
+ * `lockPeriod` keeps a forced --bpm exactly as given and refines only the phase.
+ */
+export function refineGrid(env, periodSec, phaseSec, durationSec, lockPeriod) {
+    // A period that is a couple of percent off walks the grid clean off the
+    // onsets by the end of a long track, and the fit then averages whatever
+    // happens to be nearby. So the horizon starts short — where the drift is
+    // still well under a quarter beat — and doubles once the period is sharper.
+    let period = periodSec;
+    let phase = phaseSec;
+    for (let horizon = periodSec * REFINE_FIRST_HORIZON_BEATS;; horizon *= 2) {
+        const span = Math.min(horizon, durationSec);
+        const fit = fitGrid(env, period, phase, span, lockPeriod);
+        period = fit.periodSec;
+        phase = fit.phaseSec;
+        if (span >= durationSec)
+            return { periodSec: period, phaseSec: phase };
+    }
+}
+/** One weighted least-squares pass over the beats up to `durationSec`. */
+function fitGrid(env, periodSec, phaseSec, durationSec, lockPeriod) {
+    const window = periodSec * REFINE_WINDOW_BEATS;
+    const halfFrames = Math.max(1, Math.round(window / env.hopSec));
+    const indices = [];
+    const times = [];
+    const weights = [];
+    for (let j = 0;; j++) {
+        const t = phaseSec + j * periodSec;
+        if (t > durationSec)
+            break;
+        const centre = Math.round(t / env.hopSec);
+        let weight = 0;
+        let moment = 0;
+        for (let f = centre - halfFrames; f <= centre + halfFrames; f++) {
+            if (f < 0 || f >= env.strength.length)
+                continue;
+            const offset = f * env.hopSec - t;
+            // Taper to zero at the window edge. Untapered, onsets sitting exactly at
+            // +-a quarter beat (eighth notes, when the grid is on quarters) pull the
+            // centroid as hard as the beat itself and the phase can walk off.
+            const w = env.strength[f] * (1 - Math.abs(offset) / window);
+            if (w <= 0)
+                continue;
+            weight += w;
+            moment += w * offset;
+        }
+        if (weight <= 0)
+            continue;
+        indices.push(j);
+        times.push(t + moment / weight);
+        weights.push(weight);
+    }
+    if (indices.length < 4)
+        return { periodSec, phaseSec };
+    let sumW = 0;
+    let sumJ = 0;
+    let sumT = 0;
+    let sumJJ = 0;
+    let sumJT = 0;
+    for (let i = 0; i < indices.length; i++) {
+        const w = weights[i];
+        sumW += w;
+        sumJ += w * indices[i];
+        sumT += w * times[i];
+        sumJJ += w * indices[i] * indices[i];
+        sumJT += w * indices[i] * times[i];
+    }
+    if (lockPeriod)
+        return { periodSec, phaseSec: (sumT - periodSec * sumJ) / sumW };
+    const denominator = sumW * sumJJ - sumJ * sumJ;
+    if (Math.abs(denominator) < 1e-12)
+        return { periodSec, phaseSec };
+    const slope = (sumW * sumJT - sumJ * sumT) / denominator;
+    const intercept = (sumT - slope * sumJ) / sumW;
+    // A refit that wanders this far found a different pulse, not a better fit.
+    if (!Number.isFinite(slope) || Math.abs(slope - periodSec) > periodSec * REFINE_MAX_PERIOD_DRIFT) {
+        return { periodSec, phaseSec };
+    }
+    return { periodSec: slope, phaseSec: intercept };
+}
+/**
+ * Of the four candidate downbeat phases, the one whose beats carry the most
+ * kick-band onset energy. When the low band is flat (no drums, or a mix with
+ * nothing under 150Hz) the four scores are meaningless, so it falls back to
+ * total onset strength.
+ */
+export function pickDownbeat(env, beatTimes) {
+    const scoreFor = (values) => Array.from({ length: BEATS_PER_BAR }, (_, phase) => {
+        let sum = 0;
+        for (let i = phase; i < beatTimes.length; i += BEATS_PER_BAR) {
+            sum += sampleEnvelope(values, env.hopSec, beatTimes[i]);
+        }
+        return sum;
+    });
+    const lowScores = scoreFor(env.low);
+    const maxLow = Math.max(...lowScores);
+    const minLow = Math.min(...lowScores);
+    const scores = maxLow > 0 && (maxLow - minLow) / maxLow >= LOW_BAND_FLAT_SPREAD ? lowScores : scoreFor(env.strength);
+    let best = 0;
+    for (let phase = 1; phase < BEATS_PER_BAR; phase++) {
+        if (scores[phase] > scores[best])
+            best = phase;
+    }
+    return best;
+}
+// ---------------------------------------------------------------------------
+// Analysis
+// ---------------------------------------------------------------------------
+function round(value, digits) {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+}
+function rmsDbfs(samples, fromSec, toSec, sampleRate) {
+    const start = Math.max(0, Math.floor(fromSec * sampleRate));
+    const end = Math.min(samples.length, Math.ceil(toSec * sampleRate));
+    if (end <= start)
+        return SILENCE_DBFS;
+    let sum = 0;
+    for (let i = start; i < end; i++)
+        sum += samples[i] * samples[i];
+    const rms = Math.sqrt(sum / (end - start));
+    return rms > 0 ? Math.max(SILENCE_DBFS, 20 * Math.log10(rms)) : SILENCE_DBFS;
+}
+/** The whole pipeline over decoded mono samples — no ffmpeg, no filesystem. */
+export function analyzeBeatsFromSamples(samples, sampleRate, opts = {}) {
+    if (samples.length === 0)
+        throw new Error('cannot analyze an empty sample buffer');
+    if (opts.bpm !== undefined && (!Number.isFinite(opts.bpm) || opts.bpm <= 0)) {
+        throw new Error(`invalid forced bpm: ${opts.bpm}`);
+    }
+    const durationSec = samples.length / sampleRate;
+    const env = computeOnsetEnvelope(samples, sampleRate);
+    const forced = opts.bpm !== undefined;
+    const initialPeriod = forced ? 60 / opts.bpm : 60 / detectTempo(env).bpm;
+    // Two passes. A phase found against a tempo that is a couple of percent off
+    // drifts a whole beat over a long track and can settle on the offbeat, so
+    // the first pass exists to sharpen the period; the phase is then searched
+    // again against that period, and refined once more.
+    const coarse = refineGrid(env, initialPeriod, detectPhase(env, initialPeriod, durationSec), durationSec, forced);
+    const phase = detectPhase(env, coarse.periodSec, durationSec);
+    const grid = refineGrid(env, coarse.periodSec, phase, durationSec, forced);
+    const periodSec = grid.periodSec;
+    // Keep the first beat inside the first period; a refit can drag it negative.
+    let phaseSec = grid.phaseSec;
+    while (phaseSec < 0)
+        phaseSec += periodSec;
+    while (phaseSec >= periodSec)
+        phaseSec -= periodSec;
+    const beatTimes = [];
+    for (let j = 0;; j++) {
+        const t = phaseSec + j * periodSec;
+        if (t > durationSec)
+            break;
+        beatTimes.push(round(t, 6));
+    }
+    const downbeatIndex = beatTimes.length > 0 ? pickDownbeat(env, beatTimes) : 0;
+    const barTimes = [];
+    for (let i = downbeatIndex; i < beatTimes.length; i += BEATS_PER_BAR)
+        barTimes.push(beatTimes[i]);
+    const barSec = periodSec * BEATS_PER_BAR;
+    const energyPerBar = barTimes.map((start) => round(rmsDbfs(samples, start, Math.min(durationSec, start + barSec), sampleRate), 2));
+    let beatSum = 0;
+    for (const t of beatTimes)
+        beatSum += sampleEnvelope(env.strength, env.hopSec, t);
+    let overallSum = 0;
+    for (const value of env.strength)
+        overallSum += value;
+    const meanAtBeats = beatTimes.length > 0 ? beatSum / beatTimes.length : 0;
+    const meanOverall = env.strength.length > 0 ? overallSum / env.strength.length : 0;
+    const ratio = meanOverall > 0 ? meanAtBeats / meanOverall : 0;
+    const confidence = Math.max(0, Math.min(1, (ratio - 1) / (CONFIDENCE_FULL_RATIO - 1)));
+    return {
+        bpm: forced ? opts.bpm : round(60 / periodSec, 2),
+        confidence: round(confidence, 3),
+        beatTimes,
+        barTimes,
+        downbeatIndex,
+        durationSec: round(durationSec, 3),
+        energyPerBar
+    };
+}
+// ---------------------------------------------------------------------------
+// ffmpeg decode
+// ---------------------------------------------------------------------------
+/**
+ * Playable seconds in an audio file. Asks for the audio stream's own duration
+ * first and falls back to the container's; throws if neither is a number.
+ */
+export async function probeAudioDurationSec(filePath) {
+    const stdout = await captureFfmpegTool('ffprobe', [
+        '-v', 'error',
+        '-select_streams', 'a:0',
+        '-show_entries', 'stream=duration:format=duration',
+        '-of', 'default=noprint_wrappers=1:nokey=1',
+        filePath
+    ]);
+    for (const line of stdout.toString('utf-8').split('\n')) {
+        const value = Number(line.trim());
+        if (Number.isFinite(value) && value > 0)
+            return value;
+    }
+    throw new Error(`ffprobe reported no usable duration for ${filePath}`);
+}
+/**
+ * Decode any audio file to mono float samples at `sampleRate`.
+ *
+ * `-vn` plus an explicit `-map 0:a:0` matter: music files routinely carry
+ * embedded cover art as a video stream, and without both, ffmpeg tries to push
+ * that image into a PCM stream and fails.
+ */
+export async function decodeMonoPcm(audioPath, sampleRate) {
+    const raw = await captureFfmpegTool('ffmpeg', [
+        '-v', 'error',
+        '-nostdin',
+        '-i', audioPath,
+        '-vn',
+        '-map', '0:a:0',
+        '-ac', '1',
+        '-ar', String(sampleRate),
+        '-acodec', 'pcm_s16le',
+        '-f', 's16le',
+        'pipe:1'
+    ]);
+    const count = Math.floor(raw.length / 2);
+    const samples = new Float32Array(count);
+    for (let i = 0; i < count; i++)
+        samples[i] = raw.readInt16LE(i * 2) / 32768;
+    return samples;
+}
+export async function analyzeBeats(audioPath, opts = {}) {
+    const sampleRate = opts.sampleRate ?? BEAT_SAMPLE_RATE;
+    const samples = await decodeMonoPcm(audioPath, sampleRate);
+    if (samples.length === 0)
+        throw new Error(`decoded no audio from ${audioPath}`);
+    return analyzeBeatsFromSamples(samples, sampleRate, opts);
+}
+// ---------------------------------------------------------------------------
+// Click track — the human verification path
+// ---------------------------------------------------------------------------
+const CLICK_SEC = 0.025;
+const DOWNBEAT_HZ = 1500;
+const BEAT_HZ = 900;
+/** Music is ducked under the clicks so the grid is audible against the track. */
+const CLICK_MUSIC_GAIN = 0.6;
+function clickRecipe(freq) {
+    return {
+        dur: CLICK_SEC,
+        layers: [
+            { wave: 'sine', freq, gain: [0.9, 0] },
+            { wave: 'noise', gain: [0.25, 0] }
+        ]
+    };
+}
+/**
+ * The music with a click burst on every beat (downbeats an octave-ish up), as
+ * a 48kHz mono WAV. The grid is only verifiable by ear, so this file is the
+ * point of the whole `beats` command.
+ */
+export async function renderClickTrack(audioPath, analysis) {
+    const music = await decodeMonoPcm(audioPath, SYNTH_SAMPLE_RATE);
+    const mix = new Float32Array(music.length);
+    for (let i = 0; i < music.length; i++)
+        mix[i] = music[i] * CLICK_MUSIC_GAIN;
+    const downbeatClick = synthesizeSamples(clickRecipe(DOWNBEAT_HZ));
+    const beatClick = synthesizeSamples(clickRecipe(BEAT_HZ));
+    analysis.beatTimes.forEach((time, index) => {
+        const isDownbeat = index >= analysis.downbeatIndex && (index - analysis.downbeatIndex) % BEATS_PER_BAR === 0;
+        const click = isDownbeat ? downbeatClick : beatClick;
+        const start = Math.round(time * SYNTH_SAMPLE_RATE);
+        for (let i = 0; i < click.length; i++) {
+            const target = start + i;
+            if (target >= mix.length)
+                break;
+            mix[target] = Math.max(-1, Math.min(1, mix[target] + click[i]));
+        }
+    });
+    return samplesToWav(mix);
+}
+const PRINTED_BARS = 8;
+export async function runBeats(audioPath, options = {}) {
+    const resolved = path.resolve(audioPath);
+    if (!fs.existsSync(resolved))
+        throw new TrailerError(`Audio file not found: ${resolved}`);
+    const analysis = await analyzeBeats(resolved, options.bpm !== undefined ? { bpm: options.bpm } : {});
+    const barSpacing = (BEATS_PER_BAR * 60) / analysis.bpm;
+    out(`bpm: ${analysis.bpm}${options.bpm !== undefined ? ' (forced)' : ''}`);
+    out(`confidence: ${analysis.confidence.toFixed(3)}`);
+    out(`duration: ${analysis.durationSec.toFixed(2)}s | beats: ${analysis.beatTimes.length} | bars: ${analysis.barTimes.length}`);
+    out(`downbeatIndex: ${analysis.downbeatIndex} | bar spacing: ${barSpacing.toFixed(3)}s (4 x 60/bpm)`);
+    const bars = analysis.barTimes.slice(0, PRINTED_BARS);
+    out(`first ${bars.length} bar times: ${bars.map((t) => t.toFixed(3)).join(', ')}`);
+    out(`first ${bars.length} bar energies (dBFS): ${analysis.energyPerBar.slice(0, PRINTED_BARS).map((e) => e.toFixed(1)).join(', ')}`);
+    if (options.jsonPath !== undefined) {
+        const jsonPath = path.resolve(options.jsonPath);
+        fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+        fs.writeFileSync(jsonPath, `${JSON.stringify(analysis, null, 2)}\n`);
+        out(`wrote ${jsonPath}`);
+    }
+    if (options.clickPath !== undefined) {
+        const clickPath = path.resolve(options.clickPath);
+        fs.mkdirSync(path.dirname(clickPath), { recursive: true });
+        fs.writeFileSync(clickPath, await renderClickTrack(resolved, analysis));
+        out(`wrote ${clickPath}`);
+    }
+}
+//# sourceMappingURL=music-beats.js.map