@hyperframes/core 0.8.160 → 0.8.162

package/dist/adapters/gsap.d.ts

@@ -1,4 +1,4 @@
-import type { FrameAdapter } from "./types";
+import type { FrameAdapter } from "./types.js";
 export interface GSAPTimelineLike {
     duration: () => number;
     totalDuration?: () => number;

package/dist/adapters/index.d.ts

@@ -1,3 +1,3 @@
-export type { FrameAdapter, FrameAdapterContext } from "./types";
-export type { GSAPTimelineLike, CreateGSAPFrameAdapterOptions } from "./gsap";
-export { createGSAPFrameAdapter } from "./gsap";
+export type { FrameAdapter, FrameAdapterContext } from "./types.js";
+export type { GSAPTimelineLike, CreateGSAPFrameAdapterOptions } from "./gsap.js";
+export { createGSAPFrameAdapter } from "./gsap.js";

package/dist/audioAnalysis.d.ts

@@ -2,7 +2,7 @@
  * 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";
+import type { AudioAnalysisProvider } from "./audioAnalysisLadder.js";
 /** Decoded audio: one Float32Array per channel, all the same length. */
 export interface AudioSignal {
     sampleRate: number;
@@ -100,6 +100,8 @@ export interface KindFeatures {
     sustain: number;
 }
 export declare const signalDuration: (signal: AudioSignal) => number;
+/** Per-sample energy. Channels are squared first, so a reversed channel stays audible. */
+export declare function energyMix(signal: AudioSignal): Float32Array;
 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;
@@ -111,9 +113,9 @@ export declare function kindFeatures(signal: AudioSignal): KindFeatures;
  * 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";
+export * from "./audioAnalysisLadder.js";
+export * from "./audioRhythm.js";
+export * from "./audioSections.js";
+export * from "./audioSnap.js";
 /** 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

@@ -8,7 +8,7 @@ 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) {
+export function energyMix(signal) {
     const [first, ...rest] = signal.channels;
     if (!first)
         return new Float32Array(0);

package/dist/audioResample.d.ts

@@ -0,0 +1,2 @@
+/** Band-limited resampling by windowed-sinc interpolation, so analysis reads the same at any decode rate. */
+export declare function resample(samples: Float32Array, from: number, to: number): Float32Array;

package/dist/audioResample.js

@@ -0,0 +1,37 @@
+/** Band-limited resampling by windowed-sinc interpolation, so analysis reads the same at any decode rate. */
+const ZERO_CROSSINGS = 8;
+const STEPS_PER_CROSSING = 256;
+/** Cutoff as a share of the lower Nyquist, leaving the window's transition band below it. */
+const CUTOFF = 0.95;
+const KERNEL = Float64Array.from({ length: ZERO_CROSSINGS * STEPS_PER_CROSSING + 2 }, (_, i) => {
+    const x = i / STEPS_PER_CROSSING;
+    if (x >= ZERO_CROSSINGS)
+        return 0;
+    const sinc = x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x);
+    return sinc * (0.5 + 0.5 * Math.cos((Math.PI * x) / ZERO_CROSSINGS));
+});
+function kernelAt(x) {
+    const at = Math.abs(x) * STEPS_PER_CROSSING;
+    const i = Math.floor(at);
+    if (i + 1 >= KERNEL.length)
+        return 0;
+    const frac = at - i;
+    return KERNEL[i] * (1 - frac) + KERNEL[i + 1] * frac;
+}
+export function resample(samples, from, to) {
+    if (from === to)
+        return samples;
+    const ratio = to / from;
+    const scale = Math.min(1, ratio) * CUTOFF;
+    const reach = ZERO_CROSSINGS / scale;
+    const out = new Float32Array(Math.floor(samples.length * ratio));
+    for (let n = 0; n < out.length; n++) {
+        const t = n / ratio;
+        const last = Math.min(samples.length - 1, Math.floor(t + reach));
+        let sum = 0;
+        for (let k = Math.max(0, Math.ceil(t - reach)); k <= last; k++)
+            sum += samples[k] * kernelAt((t - k) * scale);
+        out[n] = sum * scale;
+    }
+    return out;
+}

package/dist/audioRhythm.d.ts

@@ -2,7 +2,7 @@
  * 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";
+import type { AudioSignal } from "./audioAnalysis.js";
 export interface Beats {
     /** Empty when there is no steady beat, with `reason` saying so. */
     times: number[];
@@ -14,7 +14,7 @@ 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. */
+    /** "low": a guess from where the harmony changes and the low end hits. */
     confidence?: "low";
 }
 export interface TempoPoint {
@@ -31,19 +31,17 @@ export interface Rhythm {
     beats: Beats;
     downbeats: Downbeats;
 }
-/** Log energy per frame in log-spaced bands, the frames `fps` per second. */
+/** Log energy per frame in log-spaced bands, `fps` frames per second, and a slower pitch-class profile. */
 export interface BandFrames {
     fps: number;
     bands: Float64Array[];
+    chroma: Float64Array[];
+    chromaFps: number;
 }
-/** 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 const STEADY_BEAT_CONFIDENCE = 0.15;
+/** Tempo from beat times, by whichever provider placed them: the steady 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;

package/dist/audioRhythm.js

@@ -2,20 +2,29 @@
  * 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 { resample } from "./audioResample.js";
 import { fft } from "./fft.js";
+/** Every signal is analyzed at this rate and as the mean of its channels' power, so decode rate and layout cannot change a result. */
+const ANALYSIS_RATE = 22050;
+const FRAME_SIZE = 1024;
+const CHROMA_SIZE = 4096;
+const CHROMA_FPS = 10;
 const FRAMES_PER_SECOND = 100;
 const LOW_BAND_HZ = 150;
 const SLOWEST_BPM = 40;
 const FASTEST_BPM = 240;
 const TIGHTNESS = 100;
+/** The onset curve peaks this much ahead of where listeners place the beat, so beats move this much later. */
+const ONSET_LAG_SECONDS = 0.015;
 const round = (t) => Math.round(t * 1000) / 1000;
-function bandEdges(sampleRate, size) {
-    const binHz = sampleRate / size;
+function bandEdges() {
+    const binHz = ANALYSIS_RATE / FRAME_SIZE;
     const edges = [];
-    for (let hz = 30; hz < Math.min(9000, sampleRate / 2); hz *= 2 ** (1 / 5))
+    for (let hz = 30; hz < 9000; hz *= 2 ** (1 / 5))
         edges.push(Math.max(1, Math.round(hz / binHz)));
     return edges;
 }
+const hann = (size) => Float64Array.from({ length: size }, (_, i) => 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / size));
 /** 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;
@@ -35,22 +44,60 @@ function addFramePower(samples, center, window, edges, into) {
         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;
+/** Per-band log power of every frame, averaged over channels so a polarity-flipped channel cannot cancel. */
+function bandPower(channels) {
+    const window = hann(FRAME_SIZE);
+    const edges = bandEdges();
+    const hop = ANALYSIS_RATE / FRAMES_PER_SECOND;
     const bands = [];
-    for (let center = 0; center < length; center += hop) {
-        const power = new Float64Array(Math.max(0, edges.length - 1));
+    for (let f = 0; Math.round(f * hop) < (channels[0]?.length ?? 0); f++) {
+        const power = new Float64Array(edges.length - 1);
         for (const channel of channels)
-            addFramePower(channel, center, window, edges, power);
-        bands.push(power.map((p) => Math.log1p(1e9 * p)));
+            addFramePower(channel, Math.round(f * hop), window, edges, power);
+        bands.push(power.map((p) => Math.log1p((1e9 * p) / channels.length)));
     }
-    return { fps: sampleRate / hop, bands };
+    return bands;
+}
+/** Index of the pitch class, A = 9, of each FFT bin from 55 Hz to 2 kHz; -1 outside that range. */
+const PITCH_CLASS = Array.from({ length: CHROMA_SIZE / 2 }, (_, bin) => {
+    const hz = (bin * ANALYSIS_RATE) / CHROMA_SIZE;
+    if (hz < 55 || hz > 2000)
+        return -1;
+    return (((Math.round(12 * Math.log2(hz / 440)) + 9) % 12) + 12) % 12;
+});
+function chromaFrames(channels) {
+    const window = hann(CHROMA_SIZE);
+    const hop = ANALYSIS_RATE / CHROMA_FPS;
+    const re = new Float64Array(CHROMA_SIZE);
+    const im = new Float64Array(CHROMA_SIZE);
+    const frames = [];
+    for (let f = 0; Math.round(f * hop) < (channels[0]?.length ?? 0); f++) {
+        const chroma = new Float64Array(12);
+        const first = Math.round(f * hop) - CHROMA_SIZE / 2;
+        for (const channel of channels) {
+            for (let i = 0; i < CHROMA_SIZE; i++) {
+                const at = first + i;
+                re[i] = at >= 0 && at < channel.length ? channel[at] * window[i] : 0;
+                im[i] = 0;
+            }
+            fft(re, im);
+            PITCH_CLASS.forEach((pc, bin) => {
+                if (pc >= 0)
+                    chroma[pc] += Math.hypot(re[bin], im[bin]);
+            });
+        }
+        frames.push(chroma);
+    }
+    return frames;
+}
+function bandFrames(signal) {
+    const channels = signal.channels.map((c) => resample(c, signal.sampleRate, ANALYSIS_RATE));
+    return {
+        fps: FRAMES_PER_SECOND,
+        bands: bandPower(channels),
+        chroma: chromaFrames(channels),
+        chromaFps: CHROMA_FPS,
+    };
 }
 /** Subtract the mean of the surrounding ±`radius` frames and keep what rises above it. */
 function aboveLocalMean(curve, radius) {
@@ -68,9 +115,8 @@ function standardized(curve) {
     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;
+function onsetCurves({ fps, bands }) {
+    const lowBands = bandEdges().filter((bin) => (bin * ANALYSIS_RATE) / FRAME_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++) {
@@ -104,7 +150,7 @@ function autocorrelation(curve, maxLag) {
     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 tempoPrior = (lag, fps) => Math.exp(-0.5 * (Math.log2(60 / (lag / fps) / 120) / 0.8) ** 2);
 const fullRange = (fps) => ({
     shortest: Math.max(1, Math.floor((60 / FASTEST_BPM) * fps)),
     longest: Math.ceil((60 / SLOWEST_BPM) * fps),
@@ -179,13 +225,13 @@ function trimmed(beats, local) {
     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. */
+/** The period through the piece: eight-second windows a second apart, held within 10% of 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)),
+        shortest: Math.max(fullRange(fps).shortest, Math.floor(period * 0.9)),
+        longest: Math.min(fullRange(fps).longest, Math.ceil(period * 1.1)),
     };
     const centres = [];
     const periods = [];
@@ -224,22 +270,70 @@ function onsetLift(frames, local) {
     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);
+const mean = (values) => values.reduce((a, b) => a + b, 0) / (values.length || 1);
+function zScored(values) {
+    const centre = mean(values);
+    const spread = Math.sqrt(mean(values.map((v) => (v - centre) ** 2))) || 1;
+    return values.map((v) => (v - centre) / spread);
+}
+const CHROMA_REACH_SECONDS = CHROMA_SIZE / 2 / ANALYSIS_RATE;
+/** The unit-length mean chroma from one time to another, in seconds, leaving out frames that already hear the next onset. */
+function chromaBetween({ chroma, chromaFps }, from, to) {
+    const middle = Math.round(((from + to) / 2) * chromaFps);
+    let first = Math.ceil(from * chromaFps);
+    let end = Math.floor((to - CHROMA_REACH_SECONDS) * chromaFps) + 1;
+    if (end <= first)
+        [first, end] = [middle, middle + 1];
+    const sum = new Array(12).fill(0);
+    for (let f = first; f < end; f++)
+        for (let c = 0; c < 12; c++)
+            sum[c] += chroma[f]?.[c] ?? 0;
+    const length = Math.hypot(...sum) || 1;
+    return sum.map((v) => v / length);
+}
+const cosine = (a, b) => a.reduce((sum, v, i) => sum + v * b[i], 0);
+/** How much the harmony changes at each beat: the chroma `span` beats before it against the `span` after. */
+function harmonicChange(beats, fps, frames, span) {
+    return beats.map((f, k) => {
+        if (k < span || k + span >= beats.length)
+            return 0;
+        const before = chromaBetween(frames, beats[k - span] / fps, f / fps);
+        return 1 - cosine(before, chromaBetween(frames, f / fps, beats[k + span] / fps));
+    });
+}
+/** Each beat's evidence of starting a bar: a low-end hit, a chord change, and a chord change over half a bar. */
+function barStartEvidence(beats, curves, frames) {
+    const lowHit = (f) => Math.max(...[-1, 0, 1, 2].map((d) => curves.low[f + d] ?? 0));
+    const cues = [
+        zScored(beats.map(lowHit)),
+        zScored(harmonicChange(beats, curves.fps, frames, 1)),
+        zScored(harmonicChange(beats, curves.fps, frames, 2)),
+    ];
+    return beats.map((_, k) => cues.reduce((sum, cue) => sum + cue[k], 0));
+}
+/** Most music is in four, so three must win by a clear margin. */
+const TRIPLE_METER_HANDICAP = 0.7;
+function barPhase(beats, curves, frames) {
+    const evidence = barStartEvidence(beats, curves, frames);
     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);
+            const on = evidence.filter((_, k) => (k - phase) % meter === 0);
+            const off = evidence.filter((_, k) => (k - phase) % meter !== 0);
+            const contrast = (mean(on) - mean(off)) * (meter === 3 ? TRIPLE_METER_HANDICAP : 1);
             if (contrast > best.contrast)
                 best = { meter, phase, contrast };
         }
     return best;
 }
+function downbeatsOf(beatList, times, curves, frames) {
+    const bar = beatList.length >= 6 ? barPhase(beatList, curves, frames) : null;
+    return {
+        times: bar ? times.filter((_, k) => (k - bar.phase) % bar.meter === 0) : [],
+        meter: bar?.meter ?? null,
+        confidence: "low",
+    };
+}
 export function medianInterval(times) {
     const gaps = times
         .slice(1)
@@ -254,12 +348,12 @@ const noRhythm = (confidence, reason = "no steady beat") => ({
 /** 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;
+export const STEADY_BEAT_CONFIDENCE = 0.15;
 /** 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);
+/** Beats and downbeats of `frames`, a signal's band energies and chroma. */
+function rhythmOf(frames) {
+    const curves = onsetCurves(frames);
     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");
@@ -269,28 +363,30 @@ export function rhythmOf(frames, sampleRate) {
     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 times = beatList.map((f) => round(f / curves.fps + ONSET_LAG_SECONDS));
+    return { beats: { times, confidence }, downbeats: downbeatsOf(beatList, times, curves, frames) };
 }
 const TEMPO_STEP_SECONDS = 4;
-/** Tempo from beat times, by whichever provider placed them: the median interval, and a curve over ±4 s windows. */
+function steadyInterval(times) {
+    const median = medianInterval(times);
+    if (!median)
+        return null;
+    const near = times
+        .slice(1)
+        .map((t, i) => t - times[i])
+        .filter((gap) => Math.abs(gap - median) <= 0.1 * median);
+    return near.reduce((a, b) => a + b, 0) / near.length;
+}
+/** Tempo from beat times, by whichever provider placed them: the steady interval, and a curve over ±4 s windows. */
 export function tempoOf(times) {
-    const interval = medianInterval(times);
+    const interval = steadyInterval(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));
+        const gap = steadyInterval(times.filter((b) => Math.abs(b - t) <= TEMPO_STEP_SECONDS));
         if (gap)
             curve.push({ t: round(t), bpm: bpm(gap) });
     }
@@ -307,5 +403,5 @@ export function bandFramesOf(signal) {
 export function rhythm(signal) {
     const frames = bandFramesOf(signal);
     const entry = measured.get(signal);
-    return (entry.rhythm ??= rhythmOf(frames, signal.sampleRate));
+    return (entry.rhythm ??= rhythmOf(frames));
 }

package/dist/audioSections.d.ts

@@ -1,9 +1,9 @@
 /**
- * Sections from signal processing: band energies averaged into half-second blocks, a self-similarity matrix, and
+ * Sections from signal processing: band energies and chroma 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";
+import type { AudioSignal } from "./audioAnalysis.js";
+import { type SnapReport } from "./audioSnap.js";
 export interface Section {
     start: number;
     end: number;

package/dist/audioSections.js

@@ -1,5 +1,5 @@
 /**
- * Sections from signal processing: band energies averaged into half-second blocks, a self-similarity matrix, and
+ * Sections from signal processing: band energies and chroma 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";
@@ -26,14 +26,22 @@ function standardizeBands(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 }) {
+/** Block means of the band energies and of the log chroma, each part unit length within a block. */
+function blockParts({ fps, bands, chroma, chromaFps }) {
     const per = Math.max(1, Math.round(BLOCK_SECONDS * fps));
+    const chromaPer = Math.max(1, Math.round(BLOCK_SECONDS * chromaFps));
     const blocks = [];
-    for (let start = 0; start + per <= bands.length; start += per)
-        blocks.push(meanOf(bands.slice(start, start + per)));
+    for (let start = 0, b = 0; start + per <= bands.length; start += per, b++) {
+        const pitch = meanOf(chroma.slice(b * chromaPer, (b + 1) * chromaPer)).map(Math.log1p);
+        blocks.push([...meanOf(bands.slice(start, start + per)), ...unit(pitch)]);
+    }
+    return blocks;
+}
+function blockFeatures(frames) {
+    const blocks = blockParts(frames);
     standardizeBands(blocks);
-    return blocks.map(unit);
+    const split = frames.bands[0]?.length ?? 0;
+    return blocks.map((block) => [...unit(block.slice(0, split)), ...unit(block.slice(split))].map((v) => v * Math.SQRT1_2));
 }
 function unit(vector) {
     const length = Math.hypot(...vector) || 1;

package/dist/beats/beatDetection.d.ts

@@ -1,13 +1,12 @@
-type BpmDetect = (buffer: AudioBuffer) => number;
-export declare function loadBpmDetective(importFn?: () => Promise<unknown>): Promise<BpmDetect | null>;
+import { type AudioSignal } from "../audioAnalysis.js";
 export interface MusicBeatAnalysis {
     beatTimes: number[];
     /** Per-beat loudness 0–1 (local RMS / peak), aligned by index with beatTimes. */
     beatStrengths: number[];
     bpm: number | null;
     bpmConfidence: "high" | "low" | "uncertain";
-    /** Decoded mono samples — retained so strength can be measured at user-added
-     *  beats. Audio-file coordinates. May be null if decode data was dropped. */
+    /** Per-sample level across channels — retained so strength can be measured at
+     *  user-added beats. Audio-file coordinates. May be null if decode data was dropped. */
     channelData: Float32Array | null;
     sampleRate: number;
     /** Reference peak RMS used to normalize beat strengths. */
@@ -17,11 +16,10 @@ export interface MusicBeatAnalysis {
 export declare function computeRmsAt(channelData: Float32Array, sampleRate: number, time: number): number;
 /** Normalized beat strength (0–1) at an audio-file time, using a track peak. */
 export declare function strengthAtTime(analysis: Pick<MusicBeatAnalysis, "channelData" | "sampleRate" | "peak">, time: number): number;
-export declare function detectBeats(audioBuffer: AudioBuffer): Promise<number[]>;
 export interface MusicAnalysisOptions {
     pause?: () => Promise<void>;
 }
-export declare function analyzeMusicFromBuffer(audioBuffer: AudioBuffer, { pause }?: MusicAnalysisOptions): Promise<MusicBeatAnalysis>;
-export declare function detectBeatsFromUrl(url: string): Promise<number[]>;
+/** Beats, tempo and per-beat strength of decoded audio; no beats and a null bpm when it has no steady beat. */
+export declare function analyzeMusicFromSignal(signal: AudioSignal, { pause }?: MusicAnalysisOptions): Promise<MusicBeatAnalysis>;
+export declare function analyzeMusicFromBuffer(audioBuffer: AudioBuffer, options?: MusicAnalysisOptions): Promise<MusicBeatAnalysis>;
 export declare function analyzeMusicFromUrl(url: string, options?: MusicAnalysisOptions): Promise<MusicBeatAnalysis>;
-export {};