@hyperframes/core 0.8.158 → 0.8.160

package/dist/audioAnalysisLadder.js

@@ -0,0 +1,78 @@
+/**
+ * The provider ladder for audio analysis. Each capability lists providers best first; a call takes the first one
+ * that is available within the requested quality and answers, falling through on failure. The result says which
+ * provider answered and why the ones above it did not.
+ */
+/** The default order per capability: every registered provider that offers it, in registration order. */
+export function defaultLadder(capability, providers) {
+    return providers.filter((p) => p.capabilities.includes(capability)).map((p) => p.id);
+}
+/** Why a provider may not be used at this quality, or null when it may. */
+export function exclusion(provider, quality) {
+    if (quality === "fast" && !provider.signal)
+        return "quality fast allows signal processing only";
+    if (quality === "local" && !provider.local)
+        return "quality local keeps audio on this machine";
+    return null;
+}
+const message = (error) => (error instanceof Error ? error.message : String(error));
+async function availabilityOf(provider) {
+    try {
+        return provider.available ? await provider.available() : { ok: true };
+    }
+    catch (error) {
+        return { ok: false, reason: message(error) };
+    }
+}
+/** Why a provider cannot take this step, or null when it can. */
+async function blocked(id, candidate, capability, quality) {
+    if (!candidate?.capabilities.includes(capability))
+        return { provider: id, outcome: "unavailable", reason: `no provider ${id} for ${capability}` };
+    const excluded = exclusion(candidate, quality);
+    if (excluded)
+        return { provider: id, outcome: "excluded", reason: excluded };
+    const availability = await availabilityOf(candidate);
+    if (!availability.ok)
+        return { provider: id, outcome: "unavailable", reason: availability.reason };
+    return null;
+}
+/** One line naming the providers above `answered` that could not answer, and why; null when none was passed over. */
+function passedOver(capability, steps, answered) {
+    const skipped = steps.filter((s) => s.outcome === "unavailable" || s.outcome === "failed");
+    if (!skipped.length)
+        return null;
+    const why = skipped
+        .map((s) => `${s.provider} ${s.outcome}${s.reason ? ` (${s.reason})` : ""}`)
+        .join("; ");
+    return answered ? `${capability}: used ${answered}; ${why}` : `${capability}: ${why}`;
+}
+export async function runLadder(capability, input, providers, { quality = "best", ladder, provider, options = {} } = {}) {
+    const byId = new Map(providers.map((p) => [p.id, p]));
+    const order = provider ? [provider] : (ladder ?? defaultLadder(capability, providers));
+    const steps = [];
+    for (const id of order) {
+        const candidate = byId.get(id);
+        const skip = await blocked(id, candidate, capability, quality);
+        if (skip) {
+            steps.push(skip);
+            continue;
+        }
+        try {
+            const value = (await candidate.analyze(capability, input, options));
+            const warning = passedOver(capability, steps, id);
+            steps.push({ provider: id, outcome: "answered" });
+            return { value, provenance: id, steps, warnings: warning ? [warning] : [] };
+        }
+        catch (error) {
+            steps.push({ provider: id, outcome: "failed", reason: message(error) });
+        }
+    }
+    const none = order.length ? "" : " (none offers it)";
+    const why = passedOver(capability, steps, null)?.slice(capability.length + 2);
+    return {
+        value: null,
+        provenance: null,
+        steps,
+        warnings: [`${capability}: no provider answered${none}${why ? `; ${why}` : ""}`],
+    };
+}

package/dist/audioCarve.js

@@ -11,6 +11,7 @@
  * chain the studio generated rather than a separate rendering path.
  */
 import { defaultAudioFxParams, HF_AUDIO_FX_CHAIN_VERSION, } from "./audioFx.js";
+import { fft } from "./fft.js";
 export const HF_AUDIO_CARVE_ATTR = "data-fx-carve";
 /** Third-octave centres spanning the range speech actually occupies. */
 const CANDIDATE_CENTERS_HZ = [160, 250, 400, 630, 1000, 1600, 2500, 4000, 6000];
@@ -282,42 +283,6 @@ function powerSpectrum(mono, sampleRate) {
     }
     return { freqs, power };
 }
-/** In-place iterative radix-2 FFT. */
-function fft(re, im) {
-    const n = re.length;
-    for (let i = 1, j = 0; i < n; i++) {
-        let bit = n >> 1;
-        for (; j & bit; bit >>= 1)
-            j ^= bit;
-        j ^= bit;
-        if (i < j) {
-            [re[i], re[j]] = [re[j], re[i]];
-            [im[i], im[j]] = [im[j], im[i]];
-        }
-    }
-    for (let len = 2; len <= n; len <<= 1) {
-        const ang = (-2 * Math.PI) / len;
-        const wr = Math.cos(ang);
-        const wi = Math.sin(ang);
-        for (let i = 0; i < n; i += len) {
-            let cr = 1;
-            let ci = 0;
-            for (let k = 0; k < len / 2; k++) {
-                const ur = re[i + k];
-                const ui = im[i + k];
-                const vr = re[i + k + len / 2] * cr - im[i + k + len / 2] * ci;
-                const vi = re[i + k + len / 2] * ci + im[i + k + len / 2] * cr;
-                re[i + k] = ur + vr;
-                im[i + k] = ui + vi;
-                re[i + k + len / 2] = ur - vr;
-                im[i + k + len / 2] = ui - vi;
-                const ncr = cr * wr - ci * wi;
-                ci = cr * wi + ci * wr;
-                cr = ncr;
-            }
-        }
-    }
-}
 function bandPower(freqs, power, center) {
     const lo = center / Math.pow(2, 1 / 6);
     const hi = center * Math.pow(2, 1 / 6);

package/dist/audioRhythm.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Beats, downbeats and tempo from signal processing alone: a log-band spectral-flux onset curve, an autocorrelation
+ * tempo with a log-normal prior, and dynamic-programming beat placement (Ellis 2007). Times are seconds into the signal.
+ */
+import type { AudioSignal } from "./audioAnalysis";
+export interface Beats {
+    /** Empty when there is no steady beat, with `reason` saying so. */
+    times: number[];
+    /** 0–1: how strongly the onsets repeat at the beat period, scaled by how much stronger they are on the beats. */
+    confidence?: number;
+    reason?: string;
+}
+export interface Downbeats {
+    times: number[];
+    /** Beats per bar, 3 or 4; null when there are too few beats to tell. */
+    meter: number | null;
+    /** "low" for a guess from where the low end hits hardest. */
+    confidence?: "low";
+}
+export interface TempoPoint {
+    t: number;
+    bpm: number;
+}
+export interface Tempo {
+    /** Beats per minute from the median beat interval; null without at least two beats. */
+    value: number | null;
+    /** The tempo over the beats around each point, every few seconds, for music that speeds up or slows down. */
+    curve: TempoPoint[];
+}
+export interface Rhythm {
+    beats: Beats;
+    downbeats: Downbeats;
+}
+/** Log energy per frame in log-spaced bands, the frames `fps` per second. */
+export interface BandFrames {
+    fps: number;
+    bands: Float64Array[];
+}
+/** Per-band log power, summed over channels so a polarity-flipped channel cannot cancel. */
+export declare function bandFrames(signal: AudioSignal): BandFrames;
+export declare function medianInterval(times: readonly number[]): number | null;
+/** Below this the beats are more likely the tracker's own grid than the music's. */
+export declare const STEADY_BEAT_CONFIDENCE = 0.05;
+/** Beats and downbeats of `frames`, the band energies of a signal at `sampleRate`. */
+export declare function rhythmOf(frames: BandFrames, sampleRate: number): Rhythm;
+/** Tempo from beat times, by whichever provider placed them: the median interval, and a curve over ±4 s windows. */
+export declare function tempoOf(times: readonly number[]): Tempo;
+/** Band energies of `signal`, computed once per signal for every capability that reads them. */
+export declare function bandFramesOf(signal: AudioSignal): BandFrames;
+export declare function rhythm(signal: AudioSignal): Rhythm;

package/dist/audioRhythm.js

@@ -0,0 +1,311 @@
+/**
+ * Beats, downbeats and tempo from signal processing alone: a log-band spectral-flux onset curve, an autocorrelation
+ * tempo with a log-normal prior, and dynamic-programming beat placement (Ellis 2007). Times are seconds into the signal.
+ */
+import { fft } from "./fft.js";
+const FRAMES_PER_SECOND = 100;
+const LOW_BAND_HZ = 150;
+const SLOWEST_BPM = 40;
+const FASTEST_BPM = 240;
+const TIGHTNESS = 100;
+const round = (t) => Math.round(t * 1000) / 1000;
+function bandEdges(sampleRate, size) {
+    const binHz = sampleRate / size;
+    const edges = [];
+    for (let hz = 30; hz < Math.min(9000, sampleRate / 2); hz *= 2 ** (1 / 5))
+        edges.push(Math.max(1, Math.round(hz / binHz)));
+    return edges;
+}
+/** Add each band's power in the Hann-windowed frame centred on `center` into `into`. */
+function addFramePower(samples, center, window, edges, into) {
+    const size = window.length;
+    const re = new Float64Array(size);
+    const im = new Float64Array(size);
+    const first = center - size / 2;
+    for (let i = 0; i < size; i++) {
+        const at = first + i;
+        re[i] = at >= 0 && at < samples.length ? samples[at] * window[i] : 0;
+    }
+    fft(re, im);
+    for (let b = 0; b + 1 < edges.length; b++) {
+        const end = Math.max(edges[b] + 1, edges[b + 1]);
+        let power = 0;
+        for (let k = edges[b]; k < end; k++)
+            power += re[k] * re[k] + im[k] * im[k];
+        into[b] += power / (size * size * (end - edges[b]));
+    }
+}
+/** Per-band log power, summed over channels so a polarity-flipped channel cannot cancel. */
+export function bandFrames(signal) {
+    const { sampleRate, channels } = signal;
+    const hop = Math.max(1, Math.round(sampleRate / FRAMES_PER_SECOND));
+    const size = 2 ** Math.round(Math.log2(sampleRate * 0.046));
+    const window = Float64Array.from({ length: size }, (_, i) => 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / size));
+    const edges = bandEdges(sampleRate, size);
+    const length = channels[0]?.length ?? 0;
+    const bands = [];
+    for (let center = 0; center < length; center += hop) {
+        const power = new Float64Array(Math.max(0, edges.length - 1));
+        for (const channel of channels)
+            addFramePower(channel, center, window, edges, power);
+        bands.push(power.map((p) => Math.log1p(1e9 * p)));
+    }
+    return { fps: sampleRate / hop, bands };
+}
+/** Subtract the mean of the surrounding ±`radius` frames and keep what rises above it. */
+function aboveLocalMean(curve, radius) {
+    const sums = new Float64Array(curve.length + 1);
+    for (let i = 0; i < curve.length; i++)
+        sums[i + 1] = sums[i] + curve[i];
+    return curve.map((value, i) => {
+        const from = Math.max(0, i - radius);
+        const to = Math.min(curve.length, i + radius + 1);
+        return Math.max(0, value - (sums[to] - sums[from]) / (to - from));
+    });
+}
+function standardized(curve) {
+    const mean = curve.reduce((a, b) => a + b, 0) / (curve.length || 1);
+    const spread = Math.sqrt(curve.reduce((a, v) => a + (v - mean) ** 2, 0) / (curve.length || 1));
+    return spread > 0 ? curve.map((v) => v / spread) : curve.map(() => 0);
+}
+function onsetCurves({ fps, bands }, sampleRate) {
+    const size = 2 ** Math.round(Math.log2(sampleRate * 0.046));
+    const lowBands = bandEdges(sampleRate, size).filter((bin) => (bin * sampleRate) / size < LOW_BAND_HZ).length;
+    const broad = new Float64Array(bands.length);
+    const low = new Float64Array(bands.length);
+    for (let f = 1; f < bands.length; f++) {
+        const frame = bands[f];
+        const previous = bands[f - 1];
+        for (let b = 0; b < frame.length; b++) {
+            const rise = Math.max(0, frame[b] - previous[b]);
+            broad[f] += rise;
+            if (b < lowBands)
+                low[f] += rise;
+        }
+    }
+    const radius = Math.round(0.4 * fps);
+    return {
+        fps,
+        broad: standardized(aboveLocalMean(broad, radius)),
+        low: standardized(aboveLocalMean(low, radius)),
+    };
+}
+/** Autocorrelation of `curve` at lags 0…`maxLag`, normalized by lag 0. */
+function autocorrelation(curve, maxLag) {
+    const mean = curve.reduce((a, b) => a + b, 0) / (curve.length || 1);
+    const centred = curve.map((v) => v - mean);
+    const ac = new Float64Array(maxLag + 1);
+    for (let lag = 0; lag <= maxLag && lag < centred.length; lag++) {
+        let sum = 0;
+        for (let i = lag; i < centred.length; i++)
+            sum += centred[i] * centred[i - lag];
+        ac[lag] = sum;
+    }
+    const zero = ac[0] || 1;
+    return ac.map((v) => v / zero);
+}
+const tempoPrior = (lag, fps) => Math.exp(-0.5 * Math.log2(60 / (lag / fps) / 120) ** 2);
+const fullRange = (fps) => ({
+    shortest: Math.max(1, Math.floor((60 / FASTEST_BPM) * fps)),
+    longest: Math.ceil((60 / SLOWEST_BPM) * fps),
+});
+/** The beat period in frames: prior-weighted autocorrelation plus half its value at twice the lag. */
+function beatPeriod(curve, fps, { shortest, longest } = fullRange(fps)) {
+    const ac = autocorrelation(curve, 2 * longest + 1);
+    const at = (lag) => ac[Math.min(ac.length - 1, Math.max(0, lag))];
+    const score = (lag) => tempoPrior(lag, fps) *
+        (at(lag) + 0.5 * at(2 * lag) + 0.25 * (at(2 * lag - 1) + at(2 * lag + 1)));
+    let best = shortest;
+    for (let lag = shortest; lag <= longest; lag++)
+        if (score(lag) > score(best))
+            best = lag;
+    const [a, b, c] = [score(best - 1), score(best), score(best + 1)];
+    const curvature = a - 2 * b + c;
+    const shift = curvature ? Math.max(-0.5, Math.min(0.5, (0.5 * (a - c)) / curvature)) : 0;
+    return { period: best + shift, clarity: Math.max(0, Math.min(1, at(best))) };
+}
+/** The onset curve smoothed by a Gaussian a thirty-second of a beat wide. */
+function smoothed(curve, period) {
+    const half = Math.max(1, Math.round(period / 8));
+    const kernel = Array.from({ length: 2 * half + 1 }, (_, i) => Math.exp(-0.5 * (((i - half) * 32) / period) ** 2));
+    return curve.map((_, i) => {
+        let sum = 0;
+        for (let j = 0; j < kernel.length; j++)
+            sum += kernel[j] * (curve[i + j - half] ?? 0);
+        return sum;
+    });
+}
+/** Ellis's recursion: each frame's best score from a predecessor about one period back, penalized by log deviation. */
+function cumulativeScore(local, periodAt) {
+    const score = new Float64Array(local.length);
+    const back = new Int32Array(local.length).fill(-1);
+    for (let i = 0; i < local.length; i++) {
+        const period = periodAt(i);
+        let best = -Infinity;
+        let from = -1;
+        for (let j = Math.max(0, Math.round(i - 2 * period)); j <= i - Math.round(period / 2); j++) {
+            const candidate = score[j] - TIGHTNESS * Math.log((i - j) / period) ** 2;
+            if (candidate > best)
+                [best, from] = [candidate, j];
+        }
+        score[i] = local[i] + Math.max(0, best);
+        back[i] = best > 0 ? from : -1;
+    }
+    return { score, back };
+}
+/** The last local maximum of the cumulative score that reaches half the median of all of them. */
+function lastBeat(score) {
+    const maxima = [];
+    for (let i = 1; i + 1 < score.length; i++)
+        if (score[i] > score[i - 1] && score[i] >= score[i + 1])
+            maxima.push(i);
+    if (!maxima.length)
+        return score.length - 1;
+    const median = maxima.map((i) => score[i]).sort((a, b) => a - b)[maxima.length >> 1];
+    for (let k = maxima.length - 1; k >= 0; k--)
+        if (score[maxima[k]] >= 0.5 * median)
+            return maxima[k];
+    return maxima[maxima.length - 1];
+}
+/** Drop beats at either end whose onset strength is under half the RMS of the beats' strengths. */
+function trimmed(beats, local) {
+    const rms = Math.sqrt(beats.reduce((a, b) => a + local[b] ** 2, 0) / (beats.length || 1));
+    let first = 0;
+    let end = beats.length;
+    while (first < end && local[beats[first]] < 0.5 * rms)
+        first++;
+    while (end > first && local[beats[end - 1]] < 0.5 * rms)
+        end--;
+    return beats.slice(first, end);
+}
+const LOCAL_WINDOW_SECONDS = 8;
+/** The period through the piece: eight-second windows a second apart, held near the global period, median-smoothed. */
+function localPeriods(curve, fps, period) {
+    const window = Math.round(LOCAL_WINDOW_SECONDS * fps);
+    const hop = Math.round(fps);
+    const range = {
+        shortest: Math.max(fullRange(fps).shortest, Math.floor(period * 0.7)),
+        longest: Math.min(fullRange(fps).longest, Math.ceil(period * 1.4)),
+    };
+    const centres = [];
+    const periods = [];
+    for (let start = 0; start === 0 || start + window <= curve.length; start += hop) {
+        const end = Math.min(curve.length, start + window);
+        periods.push(beatPeriod(curve.subarray(start, end), fps, range).period);
+        centres.push((start + end) / 2);
+    }
+    const median = periods.map((_, i) => {
+        const near = periods.slice(Math.max(0, i - 2), i + 3).sort((a, b) => a - b);
+        return near[near.length >> 1];
+    });
+    return (frame) => interpolate(centres, median, frame);
+}
+function interpolate(xs, ys, x) {
+    if (x <= xs[0])
+        return ys[0];
+    for (let i = 1; i < xs.length; i++)
+        if (x <= xs[i]) {
+            const t = (x - xs[i - 1]) / (xs[i] - xs[i - 1]);
+            return ys[i - 1] * (1 - t) + ys[i] * t;
+        }
+    return ys[ys.length - 1];
+}
+function beatFrames(curve, fps, period) {
+    const local = smoothed(curve, period);
+    const { score, back } = cumulativeScore(local, localPeriods(curve, fps, period));
+    const beats = [];
+    for (let i = lastBeat(score); i >= 0; i = back[i])
+        beats.push(i);
+    return { frames: trimmed(beats.reverse(), local), local };
+}
+/** How much stronger the smoothed onsets are on the beats than on average, as a share: 0 is no stronger. */
+function onsetLift(frames, local) {
+    const overall = local.reduce((a, b) => a + b, 0) / (local.length || 1);
+    const onBeats = frames.reduce((a, f) => a + local[f], 0) / (frames.length || 1);
+    return overall > 0 ? onBeats / overall - 1 : 0;
+}
+/** The meter and bar phase whose beats carry the most low-band onset energy against the others. */
+function barPhase(beats, curves) {
+    const strength = (f) => Math.max(...[-1, 0, 1, 2].map((d) => (curves.low[f + d] ?? 0) + 0.3 * (curves.broad[f + d] ?? 0)));
+    const levels = beats.map(strength);
+    let best = { meter: 4, phase: 0, contrast: -Infinity };
+    for (const meter of [4, 3])
+        for (let phase = 0; phase < meter; phase++) {
+            const on = levels.filter((_, k) => (k - phase) % meter === 0);
+            const off = levels.filter((_, k) => (k - phase) % meter !== 0);
+            const mean = (v) => v.reduce((a, b) => a + b, 0) / (v.length || 1);
+            const contrast = (mean(on) - mean(off)) * (meter === 3 ? 0.85 : 1);
+            if (contrast > best.contrast)
+                best = { meter, phase, contrast };
+        }
+    return best;
+}
+export function medianInterval(times) {
+    const gaps = times
+        .slice(1)
+        .map((t, i) => t - times[i])
+        .sort((a, b) => a - b);
+    return gaps.length ? gaps[gaps.length >> 1] : null;
+}
+const noRhythm = (confidence, reason = "no steady beat") => ({
+    beats: { times: [], confidence, reason },
+    downbeats: { times: [], meter: null, confidence: "low" },
+});
+/** Two bars of 4/4 at 80 BPM: anything shorter has too few beats to call steady. */
+const SHORTEST_SECONDS = 6;
+/** Below this the beats are more likely the tracker's own grid than the music's. */
+export const STEADY_BEAT_CONFIDENCE = 0.05;
+/** Clarity of the period, scaled down when the beats are under three times as strong as the onsets around them. */
+const beatConfidence = (clarity, lift) => round(Math.max(0, Math.min(1, clarity)) * Math.max(0, Math.min(1, lift / 3)));
+/** Beats and downbeats of `frames`, the band energies of a signal at `sampleRate`. */
+export function rhythmOf(frames, sampleRate) {
+    const curves = onsetCurves(frames, sampleRate);
+    const { period, clarity } = beatPeriod(curves.broad, curves.fps);
+    if (curves.broad.length < SHORTEST_SECONDS * curves.fps)
+        return noRhythm(0, "too short for a steady beat");
+    if (!curves.broad.some((v) => v > 0) || curves.broad.length < 2 * period)
+        return noRhythm(0);
+    const { frames: beatList, local } = beatFrames(curves.broad, curves.fps, period);
+    const confidence = beatConfidence(clarity, onsetLift(beatList, local));
+    if (beatList.length < 4 || confidence < STEADY_BEAT_CONFIDENCE)
+        return noRhythm(confidence);
+    const times = beatList.map((f) => round(f / curves.fps));
+    const bar = beatList.length >= 6 ? barPhase(beatList, curves) : null;
+    return {
+        beats: { times, confidence },
+        downbeats: {
+            times: bar ? times.filter((_, k) => (k - bar.phase) % bar.meter === 0) : [],
+            meter: bar?.meter ?? null,
+            confidence: "low",
+        },
+    };
+}
+const TEMPO_STEP_SECONDS = 4;
+/** Tempo from beat times, by whichever provider placed them: the median interval, and a curve over ±4 s windows. */
+export function tempoOf(times) {
+    const interval = medianInterval(times);
+    if (!interval)
+        return { value: null, curve: [] };
+    const bpm = (gap) => Math.round(600 / gap) / 10;
+    const curve = [];
+    const last = times[times.length - 1];
+    for (let t = times[0]; t <= last; t += TEMPO_STEP_SECONDS) {
+        const gap = medianInterval(times.filter((b) => Math.abs(b - t) <= TEMPO_STEP_SECONDS));
+        if (gap)
+            curve.push({ t: round(t), bpm: bpm(gap) });
+    }
+    return { value: bpm(interval), curve };
+}
+const measured = new WeakMap();
+/** Band energies of `signal`, computed once per signal for every capability that reads them. */
+export function bandFramesOf(signal) {
+    let entry = measured.get(signal);
+    if (!entry)
+        measured.set(signal, (entry = { frames: bandFrames(signal) }));
+    return entry.frames;
+}
+export function rhythm(signal) {
+    const frames = bandFramesOf(signal);
+    const entry = measured.get(signal);
+    return (entry.rhythm ??= rhythmOf(frames, signal.sampleRate));
+}

package/dist/audioSections.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sections from signal processing: band energies averaged into half-second blocks, a self-similarity matrix, and
+ * Foote's checkerboard novelty, whose peaks are where the music changes. Boundaries snap to the nearest beat.
+ */
+import type { AudioSignal } from "./audioAnalysis";
+import { type SnapReport } from "./audioSnap";
+export interface Section {
+    start: number;
+    end: number;
+    /** Sections that sound alike share a letter. */
+    label: string;
+}
+export interface Sections {
+    spans: Section[];
+    snap?: SnapReport;
+}
+export interface SectionOptions {
+    /** Shortest section, in seconds. */
+    minSeconds?: number;
+}
+export declare function sections(signal: AudioSignal, options?: SectionOptions): Sections;

package/dist/audioSections.js

@@ -0,0 +1,109 @@
+/**
+ * Sections from signal processing: band energies averaged into half-second blocks, a self-similarity matrix, and
+ * Foote's checkerboard novelty, whose peaks are where the music changes. Boundaries snap to the nearest beat.
+ */
+import { bandFramesOf, medianInterval, rhythm } from "./audioRhythm.js";
+import { snapper } from "./audioSnap.js";
+const BLOCK_SECONDS = 0.5;
+/** Checkerboard half-width: eight seconds of music either side of a candidate boundary. */
+const KERNEL_BLOCKS = 16;
+const SAME_SECTION = 0.9;
+const round = (t) => Math.round(t * 1000) / 1000;
+function meanOf(frames) {
+    const sum = new Array(frames[0]?.length ?? 0).fill(0);
+    for (const frame of frames)
+        for (let b = 0; b < sum.length; b++)
+            sum[b] += frame[b];
+    return sum.map((v) => v / (frames.length || 1));
+}
+/** Each band moved to zero mean and unit spread over time, in place. */
+function standardizeBands(blocks) {
+    for (let b = 0; b < (blocks[0]?.length ?? 0); b++) {
+        const column = blocks.map((block) => block[b]);
+        const mean = column.reduce((a, v) => a + v, 0) / column.length;
+        const spread = Math.sqrt(column.reduce((a, v) => a + (v - mean) ** 2, 0) / column.length);
+        for (const block of blocks)
+            block[b] = (block[b] - mean) / (spread || 1);
+    }
+}
+/** Band energies averaged over blocks, each band standardized over time and each block scaled to unit length. */
+function blockFeatures({ fps, bands }) {
+    const per = Math.max(1, Math.round(BLOCK_SECONDS * fps));
+    const blocks = [];
+    for (let start = 0; start + per <= bands.length; start += per)
+        blocks.push(meanOf(bands.slice(start, start + per)));
+    standardizeBands(blocks);
+    return blocks.map(unit);
+}
+function unit(vector) {
+    const length = Math.hypot(...vector) || 1;
+    return vector.map((v) => v / length);
+}
+const dot = (a, b) => a.reduce((sum, v, i) => sum + v * b[i], 0);
+/** The checkerboard kernel, offsets -KERNEL_BLOCKS…KERNEL_BLOCKS-1 each way: + within a side, − across, tapered. */
+const CHECKERBOARD = (() => {
+    const offsets = Array.from({ length: 2 * KERNEL_BLOCKS }, (_, k) => k - KERNEL_BLOCKS);
+    const taper = (k) => Math.exp(-0.5 * (((k < 0 ? -k - 1 : k) + 0.5) / (KERNEL_BLOCKS / 2)) ** 2);
+    return offsets.map((a) => offsets.map((b) => (a < 0 === b < 0 ? 1 : -1) * taper(a) * taper(b)));
+})();
+/** Foote novelty at block `i`: similarity within each side of it minus similarity across it. */
+function noveltyAt(blocks, i) {
+    let sum = 0;
+    CHECKERBOARD.forEach((row, a) => {
+        const x = blocks[i + a - KERNEL_BLOCKS];
+        if (!x)
+            return;
+        row.forEach((weight, b) => {
+            const y = blocks[i + b - KERNEL_BLOCKS];
+            if (y)
+                sum += weight * dot(x, y);
+        });
+    });
+    return sum;
+}
+const novelty = (blocks) => blocks.map((_, i) => noveltyAt(blocks, i));
+/** Blocks where novelty peaks over its neighbourhood and clears the mean by a standard deviation. */
+function boundaryBlocks(curve, minBlocks) {
+    const mean = curve.reduce((a, b) => a + b, 0) / (curve.length || 1);
+    const spread = Math.sqrt(curve.reduce((a, v) => a + (v - mean) ** 2, 0) / (curve.length || 1));
+    const peaks = [];
+    for (let i = minBlocks; i <= curve.length - minBlocks; i++) {
+        const neighbourhood = curve.slice(Math.max(0, i - minBlocks), i + minBlocks + 1);
+        if (curve[i] < Math.max(...neighbourhood) || curve[i] <= mean + spread)
+            continue;
+        if (!peaks.length || i - peaks[peaks.length - 1] >= minBlocks)
+            peaks.push(i);
+    }
+    return peaks;
+}
+/** A letter per span: the letter of the first earlier span whose mean features are this alike, else a new one. */
+function labels(blocks, edges) {
+    const means = [];
+    const letters = [];
+    for (let s = 0; s + 1 < edges.length; s++) {
+        const part = blocks.slice(edges[s], edges[s + 1]);
+        const mean = unit(part[0].map((_, b) => part.reduce((a, block) => a + block[b], 0)));
+        const match = means.findIndex((other) => dot(other, mean) >= SAME_SECTION);
+        letters.push(match >= 0 ? letters[match] : String.fromCharCode(65 + (new Set(letters).size % 26)));
+        means.push(mean);
+    }
+    return letters;
+}
+/** Half the median beat interval: a boundary moves to a beat, never past one. */
+const beatTolerance = (beats) => (medianInterval(beats) ?? 0) / 2;
+export function sections(signal, options = {}) {
+    const duration = round((signal.channels[0]?.length ?? 0) / signal.sampleRate);
+    const blocks = blockFeatures(bandFramesOf(signal));
+    const minBlocks = Math.max(1, Math.round((options.minSeconds ?? 4) / BLOCK_SECONDS));
+    if (blocks.length < 2 * minBlocks)
+        return { spans: [{ start: 0, end: duration, label: "A" }] };
+    const edges = [0, ...boundaryBlocks(novelty(blocks), minBlocks), blocks.length];
+    const letters = labels(blocks, edges);
+    const beats = rhythm(signal).beats.times;
+    const onBeat = snapper(beats, beatTolerance(beats), "signal beats");
+    const times = edges.map((e, i) => i === 0 ? 0 : i === edges.length - 1 ? duration : round(onBeat.snap(e * BLOCK_SECONDS)));
+    return {
+        spans: letters.map((label, s) => ({ start: times[s], end: times[s + 1], label })),
+        snap: onBeat.report(),
+    };
+}

package/dist/audioSnap.d.ts

@@ -0,0 +1,18 @@
+/** Moving reported times onto measured ones, one at a time, and saying how far they moved. */
+export interface SnapReport {
+    /** What the times were moved onto. */
+    reference: string;
+    toleranceMs: number;
+    /** Times moved onto a measured one. */
+    snapped: number;
+    /** Times with nothing measured within the tolerance, kept as reported. */
+    unsnapped: number[];
+    /** Median distance between a reported time and the measured one it moved to, in ms: low means they agreed. */
+    medianShiftMs: number | null;
+}
+export interface Snapper {
+    snap: (t: number) => number;
+    report: () => SnapReport;
+}
+/** Snaps each time to the nearest of `measured` (ascending) when one is within `toleranceSeconds`, else keeps it. */
+export declare function snapper(measured: readonly number[], toleranceSeconds: number, reference: string): Snapper;