Files
hyperframes/packages/core/src/audioSnap.ts
T
Xuanru Li 8e340d220e feat(cli): audio answers beats, downbeats, bpm, sections and describe through a provider ladder (#5632)
* feat(cli): audio answers beats, downbeats, bpm, sections and describe through a provider ladder

Beats and downbeats try api, apple-mu, beat-this, then signal; sections try api, apple-mu,
then signal; describe tries api, then apple-sound. bpm is read off whichever provider placed
the beats. Each provider says whether it can run here and why not, and the ladder warns
when it passes one over.

The signal rung is a TypeScript tracker: log-band spectral flux, autocorrelation tempo with
a log-normal prior, Ellis dynamic-programming beats with a windowed local tempo, a low-band
bar phase, and Foote novelty sections snapped to beats. It reports no steady beat when the
onsets do not repeat.

The api rung posts the audio to HYPERFRAMES_AUDIO_API_URL with HYPERFRAMES_AUDIO_API_KEY and
moves each answered time onto the nearest signal beat within a quarter beat, reporting what
moved and what did not. beat-this runs Beat This! from a configured Python and local weights
and never downloads. apple-sound runs macOS's sound classifier through a Swift helper.
apple-mu reports that Music Understanding needs macOS 27.

words are no longer accepted: they come from hyperframes transcribe.

* docs(cli): audio's beats, downbeats, bpm, sections, describe and their provider ladder

* fix(cli): remove redundant audio context comment

* fix(core): keep flat audio novelty in one section

* fix(cli): honor BPM provider pins before analysis
2026-10-15 05:16:55 +00:00

63 lines
2.0 KiB
TypeScript

/** 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;
}
/** Index of the value in ascending `sorted` nearest `t`. */
function nearestIndex(sorted: readonly number[], t: number): number {
let low = 0;
let high = sorted.length - 1;
while (low < high) {
const mid = (low + high) >> 1;
if (sorted[mid]! < t) low = mid + 1;
else high = mid;
}
return low > 0 && t - sorted[low - 1]! <= sorted[low]! - t ? low - 1 : low;
}
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 function snapper(
measured: readonly number[],
toleranceSeconds: number,
reference: string,
): Snapper {
const shifts: number[] = [];
const unsnapped: number[] = [];
return {
snap(t) {
const nearest = measured.length ? measured[nearestIndex(measured, t)]! : null;
if (nearest === null || Math.abs(nearest - t) > toleranceSeconds) {
unsnapped.push(t);
return t;
}
shifts.push(Math.abs(nearest - t));
return nearest;
},
report() {
const sorted = [...shifts].sort((a, b) => a - b);
const median = sorted.length ? sorted[sorted.length >> 1]! : null;
return {
reference,
toleranceMs: Math.round(toleranceSeconds * 1000),
snapped: shifts.length,
unsnapped: [...unsnapped],
medianShiftMs: median === null ? null : Math.round(median * 1000),
};
},
};
}