@hyperframes/core 0.8.158 → 0.8.160

package/dist/audioAnalysis.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Measurements of decoded audio over time: an energy envelope, onsets, the moments a sound lands, loudness and silence.
+ * Pure functions of PCM samples, so they run the same in Node, Bun and the browser. Times are seconds into the signal.
+ */
+import type { AudioAnalysisProvider } from "./audioAnalysisLadder";
+/** Decoded audio: one Float32Array per channel, all the same length. */
+export interface AudioSignal {
+    sampleRate: number;
+    channels: Float32Array[];
+}
+export type EnvelopeScale = "db" | "linear";
+export interface EnvelopeOptions {
+    hopMs?: number;
+    /** RMS window; twice the hop when left out. */
+    windowMs?: number;
+    scale?: EnvelopeScale;
+    /** Measure only this frequency band, in Hz. */
+    band?: [number, number];
+}
+export interface Envelope {
+    hopMs: number;
+    scale: EnvelopeScale;
+    /** One value per hop, the first centred on time 0. */
+    values: number[];
+}
+export type OnsetMethod = "spectral-flux" | "energy";
+export interface OnsetOptions {
+    method?: OnsetMethod;
+    band?: [number, number];
+    /** Smallest normalized strength, 0–1, that counts as an onset. */
+    threshold?: number;
+    /** Onsets closer than this keep only the stronger. */
+    minGapMs?: number;
+    hopMs?: number;
+}
+export interface Onset {
+    t: number;
+    /** Relative to the strongest onset in the signal, 0–1. */
+    strength: number;
+}
+export interface Onsets {
+    method: OnsetMethod;
+    events: Onset[];
+}
+export interface MomentOptions {
+    /** The onset is where RMS first reaches this fraction of its peak. */
+    onsetRatio?: number;
+    /** The tail ends where RMS last stays above the peak plus this many dB. */
+    tailDb?: number;
+    hopMs?: number;
+}
+/** Where a sound lands. Null for a silent signal. */
+export interface Moments {
+    /** RMS first reaches `onsetRatio` of its peak. */
+    onset: number;
+    /** The largest rise in RMS between neighbouring hops. */
+    steepest: number;
+    /** The loudest hop. */
+    peak: number;
+    /** The last hop within `tailDb` of the peak. */
+    tailEnd: number;
+}
+export interface Loudness {
+    /** ITU-R BS.1770 gated integrated loudness; null when every block is below the absolute gate. */
+    lufsIntegrated: number | null;
+    /** The loudest 3 s window. */
+    lufsShortTermMax: number | null;
+    samplePeakDb: number;
+    /** A 4× oversampled estimate of the true peak, in dBTP. */
+    truePeakDb: number;
+    clipping: {
+        count: number;
+        firstAt: number | null;
+    };
+}
+export interface SilenceOptions {
+    thresholdDb?: number;
+    minMs?: number;
+    hopMs?: number;
+}
+export interface Span {
+    start: number;
+    end: number;
+}
+export type AudioKind = "sfx" | "music" | "voice" | "mixed";
+export interface KindGuess {
+    value: AudioKind;
+    /** 0–1. Signal heuristics only: treat below 0.6 as a guess. */
+    confidence: number;
+    /** What the guess was made from. */
+    features: KindFeatures;
+}
+export interface KindFeatures {
+    duration: number;
+    /** Strongest autocorrelation of the onset curve at beat-like lags (0.3–1.5 s), 0–1. */
+    regularity: number;
+    /** Share of envelope modulation at syllable rate (3–8 Hz), 0–1. */
+    syllables: number;
+    /** Share of 50 ms frames within 20 dB of the loud end (95th percentile), 0–1: high for beds and speech, low for hits. */
+    sustain: number;
+}
+export declare const signalDuration: (signal: AudioSignal) => number;
+export declare function envelope(signal: AudioSignal, options?: EnvelopeOptions): Envelope;
+export declare function onsets(signal: AudioSignal, options?: OnsetOptions): Onsets;
+export declare function moments(signal: AudioSignal, options?: MomentOptions): Moments | null;
+export declare function loudness(signal: AudioSignal): Loudness;
+export declare function silence(signal: AudioSignal, options?: SilenceOptions): Span[];
+export declare function kindFeatures(signal: AudioSignal): KindFeatures;
+/**
+ * A first guess at what the audio is. Length decides most of it: beds run long, effects short. Long audio is voice
+ * when its envelope moves at syllable rate without a beat; short audio is voice when it also holds its level.
+ */
+export declare function classify(signal: AudioSignal): KindGuess;
+export * from "./audioAnalysisLadder";
+export * from "./audioRhythm";
+export * from "./audioSections";
+export * from "./audioSnap";
+/** Signal processing as a ladder provider: always available, the measured ground every other provider snaps to. */
+export declare const signalProvider: AudioAnalysisProvider<AudioSignal>;

package/dist/audioAnalysis.js

@@ -0,0 +1,466 @@
+/**
+ * Measurements of decoded audio over time: an energy envelope, onsets, the moments a sound lands, loudness and silence.
+ * Pure functions of PCM samples, so they run the same in Node, Bun and the browser. Times are seconds into the signal.
+ */
+import { fft } from "./fft.js";
+import { rhythm } from "./audioRhythm.js";
+import { sections } from "./audioSections.js";
+const DB_FLOOR = -120;
+export const signalDuration = (signal) => (signal.channels[0]?.length ?? 0) / signal.sampleRate;
+/** Per-sample energy. Channels are squared first, so a reversed channel stays audible. */
+function energyMix(signal) {
+    const [first, ...rest] = signal.channels;
+    if (!first)
+        return new Float32Array(0);
+    if (!rest.length)
+        return first;
+    const mixed = new Float32Array(first.length);
+    for (const channel of signal.channels)
+        for (let i = 0; i < mixed.length; i++)
+            mixed[i] += channel[i] * channel[i];
+    const scale = 1 / signal.channels.length;
+    for (let i = 0; i < mixed.length; i++)
+        mixed[i] = Math.sqrt(mixed[i] * scale);
+    return mixed;
+}
+const toDb = (amplitude) => amplitude > 0 ? Math.max(DB_FLOOR, 20 * Math.log10(amplitude)) : DB_FLOOR;
+const hopSamples = (sampleRate, hopMs) => Math.max(1, Math.round((sampleRate * hopMs) / 1000));
+const round = (t) => Math.round(t * 1e4) / 1e4;
+function rmsFrames(samples, sampleRate, hopMs, windowMs) {
+    const hop = hopSamples(sampleRate, hopMs);
+    const half = Math.max(1, Math.round((sampleRate * windowMs) / 2000));
+    const frames = [];
+    for (let center = 0; center < samples.length; center += hop) {
+        const from = Math.max(0, center - half);
+        const to = Math.min(samples.length, center + half);
+        let sum = 0;
+        for (let i = from; i < to; i++)
+            sum += samples[i] * samples[i];
+        frames.push(to > from ? Math.sqrt(sum / (to - from)) : 0);
+    }
+    return frames;
+}
+const fftSizeFor = (sampleRate) => 2 ** Math.round(Math.log2(sampleRate * 0.023));
+/** Magnitude spectra of Hann-windowed frames centred on each hop, limited to `band`. */
+/** The FFT bins inside `band`, as [first, end). */
+function bandBins(sampleRate, size, band) {
+    const binHz = sampleRate / size;
+    const low = Math.max(1, Math.floor((band?.[0] ?? 0) / binHz));
+    return [low, Math.max(low, Math.min(size / 2, Math.ceil((band?.[1] ?? sampleRate / 2) / binHz)))];
+}
+/** Load the Hann-windowed frame centred on `center` into `re`, zero outside the signal. */
+function loadFrame(samples, center, window, re, im) {
+    const first = center - window.length / 2;
+    for (let i = 0; i < window.length; i++) {
+        const at = first + i;
+        re[i] = at >= 0 && at < samples.length ? samples[at] * window[i] : 0;
+        im[i] = 0;
+    }
+}
+function spectra(samples, sampleRate, hopMs, band) {
+    const size = fftSizeFor(sampleRate);
+    const hop = hopSamples(sampleRate, hopMs);
+    const window = Float64Array.from({ length: size }, (_, i) => 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / size));
+    const [low, high] = bandBins(sampleRate, size, band);
+    const frames = [];
+    const re = new Float64Array(size);
+    const im = new Float64Array(size);
+    for (let center = 0; center < samples.length; center += hop) {
+        loadFrame(samples, center, window, re, im);
+        fft(re, im);
+        const magnitudes = new Float64Array(high - low);
+        for (let k = low; k < high; k++)
+            magnitudes[k - low] = Math.hypot(re[k], im[k]);
+        frames.push(magnitudes);
+    }
+    return frames;
+}
+function averageMagnitudes(frames) {
+    const mixed = new Float64Array(frames[0]?.length ?? 0);
+    for (const frame of frames)
+        for (let bin = 0; bin < mixed.length; bin++)
+            mixed[bin] += frame[bin];
+    const scale = frames.length || 1;
+    for (let bin = 0; bin < mixed.length; bin++)
+        mixed[bin] /= scale;
+    return mixed;
+}
+/** Mean magnitude spectrum across channels, so opposite polarity cannot cancel a bin. */
+function meanSpectra(signal, hopMs, band) {
+    const stacked = signal.channels.map((channel) => spectra(channel, signal.sampleRate, hopMs, band));
+    const count = stacked[0]?.length ?? 0;
+    const mixed = [];
+    for (let frame = 0; frame < count; frame++)
+        mixed.push(averageMagnitudes(stacked.map((channel) => channel[frame])));
+    return mixed;
+}
+export function envelope(signal, options = {}) {
+    const { hopMs = 5, scale = "db", band } = options;
+    const windowMs = options.windowMs ?? hopMs * 2;
+    const size = fftSizeFor(signal.sampleRate);
+    // Parseval over the band's bins; a Hann window keeps 0.375 of a frame's power.
+    const amplitudes = band
+        ? meanSpectra(signal, hopMs, band).map((frame) => {
+            let sum = 0;
+            for (const magnitude of frame)
+                sum += magnitude * magnitude;
+            return Math.sqrt((2 * sum) / (size * size * 0.375));
+        })
+        : rmsFrames(energyMix(signal), signal.sampleRate, hopMs, windowMs);
+    return { hopMs, scale, values: amplitudes.map((a) => (scale === "db" ? toDb(a) : a)) };
+}
+/** Positive change between neighbouring frames: spectral flux of log magnitudes, or the rise in RMS. */
+function noveltyCurve(signal, method, hopMs, band) {
+    const samples = energyMix(signal);
+    if (method === "energy") {
+        const rms = rmsFrames(samples, signal.sampleRate, hopMs, hopMs * 2);
+        return rms.map((value, i) => Math.max(0, value - (rms[i - 1] ?? 0)));
+    }
+    const frames = meanSpectra(signal, hopMs, band).map((frame) => frame.map((m) => Math.log1p(100 * m)));
+    // A frame cut off by the end of the signal splatters across the spectrum; that is the edge, not a hit.
+    const lastWhole = Math.floor((samples.length - fftSizeFor(signal.sampleRate) / 2) / hopSamples(signal.sampleRate, hopMs));
+    return frames.map((frame, i) => {
+        const previous = frames[i - 1];
+        if (!previous || i > lastWhole)
+            return 0;
+        let flux = 0;
+        for (let k = 0; k < frame.length; k++)
+            flux += Math.max(0, frame[k] - previous[k]);
+        return flux;
+    });
+}
+/** Peaks of the novelty curve that stand out from their neighbourhood. */
+/** A local maximum within `gap` frames that clears the mean of its ±`context` neighbourhood by 5% of the top. */
+function isOnsetPeak(curve, i, gap, context, top) {
+    const value = curve[i];
+    let sum = 0;
+    let count = 0;
+    for (let j = Math.max(0, i - context); j <= Math.min(curve.length - 1, i + context); j++) {
+        if (Math.abs(j - i) <= gap && curve[j] > value)
+            return false;
+        sum += curve[j];
+        count++;
+    }
+    return value >= sum / count + 0.05 * top;
+}
+export function onsets(signal, options = {}) {
+    const { method = "spectral-flux", band, threshold = 0.1, minGapMs = 30, hopMs = 5 } = options;
+    const curve = noveltyCurve(signal, method, hopMs, band);
+    const top = Math.max(0, ...curve);
+    if (top <= 0)
+        return { method, events: [] };
+    const gap = Math.max(1, Math.round(minGapMs / hopMs));
+    const context = Math.max(gap, Math.round(100 / hopMs));
+    const hopSeconds = hopSamples(signal.sampleRate, hopMs) / signal.sampleRate;
+    const events = [];
+    for (let i = 0; i < curve.length; i++) {
+        const strength = curve[i] / top;
+        if (strength < threshold || !isOnsetPeak(curve, i, gap, context, top))
+            continue;
+        const onset = { t: round(i * hopSeconds), strength: round(strength) };
+        const last = events[events.length - 1];
+        if (!last || onset.t - last.t >= minGapMs / 1000)
+            events.push(onset);
+        else if (onset.strength > last.strength)
+            events[events.length - 1] = onset;
+    }
+    return { method, events };
+}
+export function moments(signal, options = {}) {
+    const { onsetRatio = 0.2, tailDb = -40, hopMs = 1 } = options;
+    const rms = rmsFrames(energyMix(signal), signal.sampleRate, hopMs, Math.max(4, hopMs * 4));
+    const hopSeconds = hopSamples(signal.sampleRate, hopMs) / signal.sampleRate;
+    let peakIndex = 0;
+    for (let i = 1; i < rms.length; i++)
+        if (rms[i] > rms[peakIndex])
+            peakIndex = i;
+    const peak = rms[peakIndex] ?? 0;
+    if (peak <= 0)
+        return null;
+    let onsetIndex = rms.findIndex((value) => value >= peak * onsetRatio);
+    if (onsetIndex < 0)
+        onsetIndex = peakIndex;
+    let steepestIndex = onsetIndex;
+    let steepestRise = -Infinity;
+    for (let i = 1; i <= peakIndex; i++) {
+        const rise = rms[i] - rms[i - 1];
+        if (rise > steepestRise)
+            [steepestRise, steepestIndex] = [rise, i];
+    }
+    const floor = peak * 10 ** (tailDb / 20);
+    let tailIndex = peakIndex;
+    for (let i = rms.length - 1; i > peakIndex; i--)
+        if (rms[i] >= floor) {
+            tailIndex = i;
+            break;
+        }
+    return {
+        onset: round(onsetIndex * hopSeconds),
+        steepest: round(steepestIndex * hopSeconds),
+        peak: round(peakIndex * hopSeconds),
+        tailEnd: round(tailIndex * hopSeconds),
+    };
+}
+/** BS.1770 K-weighting at any sample rate: a high-shelf pre-filter, then the RLB high-pass. */
+function kWeighting(sampleRate) {
+    let k = Math.tan((Math.PI * 1681.974450955533) / sampleRate);
+    const q = 0.7071752369554196;
+    const vh = 10 ** (3.999843853973347 / 20);
+    const vb = vh ** 0.4996667741545416;
+    let a0 = 1 + k / q + k * k;
+    const shelf = [
+        (vh + (vb * k) / q + k * k) / a0,
+        (2 * (k * k - vh)) / a0,
+        (vh - (vb * k) / q + k * k) / a0,
+        (2 * (k * k - 1)) / a0,
+        (1 - k / q + k * k) / a0,
+    ];
+    k = Math.tan((Math.PI * 38.13547087602444) / sampleRate);
+    const q2 = 0.5003270373238773;
+    a0 = 1 + k / q2 + k * k;
+    const highPass = [1, -2, 1, (2 * (k * k - 1)) / a0, (1 - k / q2 + k * k) / a0];
+    return [shelf, highPass];
+}
+function filtered(samples, [b0, b1, b2, a1, a2]) {
+    const out = new Float64Array(samples.length);
+    let x1 = 0, x2 = 0, y1 = 0, y2 = 0;
+    for (let i = 0; i < samples.length; i++) {
+        const x = samples[i];
+        const y = b0 * x + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
+        x2 = x1;
+        x1 = x;
+        y2 = y1;
+        y1 = y;
+        out[i] = y;
+    }
+    return out;
+}
+const blockLoudness = (meanSquare) => meanSquare > 0 ? -0.691 + 10 * Math.log10(meanSquare) : -Infinity;
+/** Running sum of squares, so any block's power is one subtraction. */
+function squareSums(channel) {
+    const sums = new Float64Array(channel.length + 1);
+    for (let i = 0; i < channel.length; i++)
+        sums[i + 1] = sums[i] + channel[i] * channel[i];
+    return sums;
+}
+/** Summed channel power of each block of `blockSeconds`, stepped by `stepSeconds`. */
+function blockPowers(sums, sampleRate, blockSeconds, stepSeconds) {
+    const length = (sums[0]?.length ?? 1) - 1;
+    if (!length)
+        return [];
+    const block = Math.min(length, Math.round(blockSeconds * sampleRate));
+    const step = Math.round(stepSeconds * sampleRate);
+    const powers = [];
+    for (let start = 0; start + block <= length; start += step)
+        powers.push(sums.reduce((power, sum) => power + (sum[start + block] - sum[start]) / block, 0));
+    return powers;
+}
+const TRUE_PEAK_OVERSAMPLE = 4;
+const TRUE_PEAK_TAPS = 12;
+const TRUE_PEAK_KERNELS = Array.from({ length: TRUE_PEAK_OVERSAMPLE - 1 }, (_, phase) => {
+    const offset = (phase + 1) / TRUE_PEAK_OVERSAMPLE;
+    return Float64Array.from({ length: 2 * TRUE_PEAK_TAPS }, (_, tap) => {
+        const x = tap - TRUE_PEAK_TAPS + 1 - offset;
+        const sinc = x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x);
+        return sinc * (0.5 + 0.5 * Math.cos((Math.PI * x) / TRUE_PEAK_TAPS));
+    });
+});
+/**
+ * The 4× oversampled peak, interpolated only between samples at least half the sample peak: overshooting both
+ * neighbours by 6 dB takes energy near Nyquist that real program material does not carry.
+ */
+function truePeak(channel) {
+    let samplePeak = 0;
+    for (let i = 0; i < channel.length; i++)
+        samplePeak = Math.max(samplePeak, Math.abs(channel[i]));
+    const floor = samplePeak / 2;
+    const taps = 2 * TRUE_PEAK_TAPS;
+    let peak = samplePeak;
+    for (let n = 0; n + taps <= channel.length; n++) {
+        if (Math.abs(channel[n + TRUE_PEAK_TAPS - 1]) < floor &&
+            Math.abs(channel[n + TRUE_PEAK_TAPS]) < floor)
+            continue;
+        for (const kernel of TRUE_PEAK_KERNELS) {
+            let y = 0;
+            for (let tap = 0; tap < taps; tap++)
+                y += channel[n + tap] * kernel[tap];
+            if (y > peak)
+                peak = y;
+            else if (-y > peak)
+                peak = -y;
+        }
+    }
+    return peak;
+}
+export function loudness(signal) {
+    const [shelf, highPass] = kWeighting(signal.sampleRate);
+    const sums = signal.channels.map((channel) => squareSums(filtered(filtered(channel, shelf), highPass)));
+    const momentary = blockPowers(sums, signal.sampleRate, 0.4, 0.1);
+    const audible = momentary.filter((power) => blockLoudness(power) > -70);
+    let lufsIntegrated = null;
+    if (audible.length) {
+        const relative = blockLoudness(audible.reduce((a, b) => a + b, 0) / audible.length) - 10;
+        const gated = audible.filter((power) => blockLoudness(power) > relative);
+        if (gated.length)
+            lufsIntegrated =
+                Math.round(blockLoudness(gated.reduce((a, b) => a + b, 0) / gated.length) * 10) / 10;
+    }
+    const shortTerm = blockPowers(sums, signal.sampleRate, 3, 0.1)
+        .map(blockLoudness)
+        .filter(Number.isFinite);
+    let samplePeak = 0;
+    let count = 0;
+    let firstAt = null;
+    for (const channel of signal.channels)
+        for (let i = 0; i < channel.length; i++) {
+            const magnitude = Math.abs(channel[i]);
+            samplePeak = Math.max(samplePeak, magnitude);
+            if (magnitude >= 0.999) {
+                count++;
+                const t = i / signal.sampleRate;
+                if (firstAt === null || t < firstAt)
+                    firstAt = round(t);
+            }
+        }
+    return {
+        lufsIntegrated,
+        lufsShortTermMax: shortTerm.length ? Math.round(Math.max(...shortTerm) * 10) / 10 : null,
+        samplePeakDb: Math.round(toDb(samplePeak) * 10) / 10,
+        truePeakDb: Math.round(toDb(Math.max(0, ...signal.channels.map(truePeak))) * 10) / 10,
+        clipping: { count, firstAt },
+    };
+}
+export function silence(signal, options = {}) {
+    const { thresholdDb = -50, minMs = 200, hopMs = 5 } = options;
+    const db = rmsFrames(energyMix(signal), signal.sampleRate, hopMs, hopMs * 2).map(toDb);
+    const hopSeconds = hopSamples(signal.sampleRate, hopMs) / signal.sampleRate;
+    const spans = [];
+    let from = null;
+    for (let i = 0; i <= db.length; i++) {
+        const quiet = i < db.length && db[i] < thresholdDb;
+        if (quiet && from === null)
+            from = i;
+        if (!quiet && from !== null) {
+            if ((i - from) * hopSeconds * 1000 >= minMs)
+                spans.push({
+                    start: round(from * hopSeconds),
+                    end: round(Math.min(i * hopSeconds, signalDuration(signal))),
+                });
+            from = null;
+        }
+    }
+    return spans;
+}
+/** How regular the onsets are: the strongest normalized autocorrelation of the novelty curve at beat-like lags. */
+function periodicity(curve, hopMs) {
+    const mean = curve.reduce((a, b) => a + b, 0) / (curve.length || 1);
+    const centred = curve.map((v) => v - mean);
+    const energy = centred.reduce((a, v) => a + v * v, 0);
+    if (!energy)
+        return 0;
+    let best = 0;
+    for (let lag = Math.round(300 / hopMs); lag <= Math.round(1500 / hopMs) && lag < centred.length; lag++) {
+        let sum = 0;
+        for (let i = lag; i < centred.length; i++)
+            sum += centred[i] * centred[i - lag];
+        best = Math.max(best, sum / energy);
+    }
+    return best;
+}
+/** How much of the envelope's modulation sits at syllable rate (3–8 Hz). */
+function syllableModulation(signal) {
+    const hopMs = 10;
+    const rms = rmsFrames(energyMix(signal), signal.sampleRate, hopMs, 25);
+    const size = 2 ** Math.floor(Math.log2(Math.min(rms.length, 1024)));
+    if (size < 64)
+        return 0;
+    const re = Float64Array.from(rms.slice(0, size));
+    const mean = re.reduce((a, b) => a + b, 0) / size;
+    for (let i = 0; i < size; i++)
+        re[i] = re[i] - mean;
+    const im = new Float64Array(size);
+    fft(re, im);
+    const rate = 1000 / hopMs;
+    let inBand = 0;
+    let total = 0;
+    for (let k = 1; k < size / 2; k++) {
+        const power = re[k] * re[k] + im[k] * im[k];
+        const hz = (k * rate) / size;
+        total += power;
+        if (hz >= 3 && hz <= 8)
+            inBand += power;
+    }
+    return total ? inBand / total : 0;
+}
+function sustainShare(signal) {
+    const levels = rmsFrames(energyMix(signal), signal.sampleRate, 50, 100).map(toDb);
+    if (!levels.length)
+        return 0;
+    const loud = [...levels].sort((a, b) => a - b)[Math.floor((levels.length - 1) * 0.95)];
+    return levels.filter((level) => level > loud - 20).length / levels.length;
+}
+export function kindFeatures(signal) {
+    return {
+        duration: round(signalDuration(signal)),
+        regularity: round(periodicity(noveltyCurve(signal, "spectral-flux", 10), 10)),
+        syllables: round(syllableModulation(signal)),
+        sustain: round(sustainShare(signal)),
+    };
+}
+/**
+ * A first guess at what the audio is. Length decides most of it: beds run long, effects short. Long audio is voice
+ * when its envelope moves at syllable rate without a beat; short audio is voice when it also holds its level.
+ */
+export function classify(signal) {
+    const features = kindFeatures(signal);
+    const { duration, regularity, syllables, sustain } = features;
+    const speechLike = syllables >= 0.35 && regularity < 0.35;
+    if (duration >= 8) {
+        if (sustain < 0.4)
+            return { value: "sfx", confidence: 0.6, features };
+        if (speechLike)
+            return { value: "voice", confidence: round(Math.min(0.9, 0.4 + syllables)), features };
+        return { value: "music", confidence: round(Math.min(0.9, 0.5 + regularity)), features };
+    }
+    if (duration >= 1.5 && syllables >= 0.17 && regularity < 0.3 && sustain >= 0.7)
+        return { value: "voice", confidence: speechLike ? 0.8 : 0.6, features };
+    return { value: "sfx", confidence: duration <= 2 ? 0.85 : 0.65, features };
+}
+export * from "./audioAnalysisLadder.js";
+export * from "./audioRhythm.js";
+export * from "./audioSections.js";
+export * from "./audioSnap.js";
+const SIGNAL_MEASURES = {
+    beats: (input) => rhythm(input).beats,
+    downbeats: (input) => rhythm(input).downbeats,
+    sections: (input, options) => sections(input, options),
+    envelope: (input, options) => envelope(input, options),
+    onsets: (input, options) => onsets(input, options),
+    moments: (input, options) => moments(input, options),
+    loudness: (input) => loudness(input),
+    silence: (input, options) => silence(input, options),
+    kind: (input) => classify(input),
+};
+/** Signal processing as a ladder provider: always available, the measured ground every other provider snaps to. */
+export const signalProvider = {
+    id: "signal",
+    local: true,
+    signal: true,
+    capabilities: [
+        "envelope",
+        "onsets",
+        "moments",
+        "loudness",
+        "silence",
+        "kind",
+        "beats",
+        "downbeats",
+        "sections",
+    ],
+    async analyze(capability, input, options) {
+        const measure = SIGNAL_MEASURES[capability];
+        if (!measure)
+            throw new Error(`signal processing does not measure ${capability}`);
+        return measure(input, options);
+    },
+};

package/dist/audioAnalysisLadder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+export type AudioCapability = "envelope" | "onsets" | "moments" | "loudness" | "silence" | "kind" | "beats" | "downbeats" | "bpm" | "sections" | "describe";
+/** `best` may use any provider; `local` none that sends audio off the machine; `fast` only signal processing. */
+export type AnalysisQuality = "best" | "local" | "fast";
+/** Whether a provider can run here now, and if not, what is missing. */
+export type Availability = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface AudioAnalysisProvider<Input = unknown> {
+    id: string;
+    /** Runs on this machine; a provider that is not local sends the audio to a service. */
+    local: boolean;
+    /** Pure signal processing: no model, no download. */
+    signal?: boolean;
+    capabilities: readonly AudioCapability[];
+    /** Whether it can run here now: a key, a platform, a model on disk. Missing means always. */
+    available?: () => Availability | Promise<Availability>;
+    analyze: (capability: AudioCapability, input: Input, options: Record<string, unknown>) => Promise<unknown>;
+}
+export type LadderOutcome = "answered" | "unavailable" | "excluded" | "failed";
+export interface LadderStep {
+    provider: string;
+    outcome: LadderOutcome;
+    reason?: string;
+}
+export interface LadderResult<Value = unknown> {
+    value: Value | null;
+    /** The provider that answered; null when none could. */
+    provenance: string | null;
+    steps: LadderStep[];
+    warnings: string[];
+}
+export interface LadderOptions {
+    quality?: AnalysisQuality;
+    /** This capability's ladder, best first, in place of the default. */
+    ladder?: readonly string[];
+    /** Use only this provider. */
+    provider?: string;
+    options?: Record<string, unknown>;
+}
+/** The default order per capability: every registered provider that offers it, in registration order. */
+export declare function defaultLadder<Input>(capability: AudioCapability, providers: readonly AudioAnalysisProvider<Input>[]): string[];
+/** Why a provider may not be used at this quality, or null when it may. */
+export declare function exclusion<Input>(provider: AudioAnalysisProvider<Input>, quality: AnalysisQuality): string | null;
+export declare function runLadder<Input, Value = unknown>(capability: AudioCapability, input: Input, providers: readonly AudioAnalysisProvider<Input>[], { quality, ladder, provider, options }?: LadderOptions): Promise<LadderResult<Value>>;