Files
hyperframes/packages/cli/src/audio/analysis/format.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

152 lines
5.7 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import type {
Beats,
Downbeats,
Envelope,
KindGuess,
Loudness,
Moments,
Onsets,
Sections,
SnapReport,
Span,
Tempo,
} from "@hyperframes/core/audio-analysis";
import type { AudioItem, AudioReport } from "./run.js";
import { filmTime } from "./targets.js";
const BARS = "▁▂▃▄▅▆▇█";
const SPARK_WIDTH = 48;
const ONSETS_SHOWN = 12;
const s = (t: number) => t.toFixed(3);
/** One character per slice of the envelope, from the floor of what it holds to its loudest. */
export function sparkline(envelope: Envelope, width = SPARK_WIDTH): string {
const { values } = envelope;
if (values.length === 0) return "";
const per = Math.max(1, Math.ceil(values.length / width));
const slices: number[] = [];
for (let i = 0; i < values.length; i += per) slices.push(Math.max(...values.slice(i, i + per)));
const top = Math.max(...slices);
const floor = Math.max(Math.min(...slices), top - 60);
if (top - floor < 1e-9) return BARS[0]!.repeat(slices.length);
return slices
.map(
(v) => BARS[Math.round(((Math.max(v, floor) - floor) / (top - floor)) * (BARS.length - 1))],
)
.join("");
}
type At = (t: number) => string;
function momentsLine(moments: Moments, at: At): string {
return ` onset ${at(moments.onset)} steepest ${at(moments.steepest)} peak ${at(moments.peak)} tail end ${at(moments.tailEnd)}`;
}
function hitsLine(onsets: Onsets, at: At): string | null {
if (!onsets.events.length) return null;
const shown = onsets.events
.slice(0, ONSETS_SHOWN)
.map((e) => `${at(e.t)}(${e.strength.toFixed(2)})`);
const more = onsets.events.length - shown.length;
return ` hits ${shown.join(" ")}${more > 0 ? ` +${more}` : ""}`;
}
function loudnessLine(loudness: Loudness, at: At): string {
const lufs = loudness.lufsIntegrated === null ? "below gate" : `${loudness.lufsIntegrated} LUFS`;
const { count, firstAt } = loudness.clipping;
const clip = count && firstAt !== null ? `, clips ${count}× from ${at(firstAt)}` : "";
return ` loudness ${lufs}, true peak ${loudness.truePeakDb} dBTP${clip}`;
}
function silenceLine(silence: Span[], at: At): string | null {
return silence.length
? ` silent ${silence.map((g) => `${at(g.start)}–${at(g.end)}`).join(" ")}`
: null;
}
function snapNote(snap: SnapReport | undefined): string {
if (!snap) return "";
const total = snap.snapped + snap.unsnapped.length;
const median = snap.medianShiftMs === null ? "" : `, median ${snap.medianShiftMs} ms`;
return `; ${snap.snapped}/${total} snapped to ${snap.reference}${median}`;
}
const listed = (times: number[], at: At) => {
const shown = times.slice(0, ONSETS_SHOWN).map(at).join(" ");
return times.length > ONSETS_SHOWN ? `${shown} +${times.length - ONSETS_SHOWN}` : shown;
};
function beatsLine(beats: Beats & { snap?: SnapReport }, at: At): string {
if (!beats.times.length) return ` beats none${beats.reason ? ` (${beats.reason})` : ""}`;
return ` beats ${beats.times.length}: ${listed(beats.times, at)}${snapNote(beats.snap)}`;
}
function downbeatsLine(downbeats: Downbeats & { snap?: SnapReport }, at: At): string | null {
if (!downbeats.times.length) return null;
const meter = downbeats.meter ? ` in ${downbeats.meter}` : "";
const low = downbeats.confidence === "low" ? ", a guess" : "";
return ` downbeats${meter}${low}: ${listed(downbeats.times, at)}${snapNote(downbeats.snap)}`;
}
function tempoLine(tempo: Tempo): string | null {
if (tempo.value === null) return null;
const bpms = tempo.curve.map((p) => p.bpm);
const spread =
bpms.length && Math.max(...bpms) - Math.min(...bpms) >= 2
? ` (${Math.min(...bpms)}–${Math.max(...bpms)})`
: "";
return ` tempo ${tempo.value} BPM${spread}`;
}
function sectionsLine(sections: Sections, at: At): string {
const spans = sections.spans.map((s) => `${s.label} ${at(s.start)}–${at(s.end)}`).join(" ");
return ` sections ${spans}${snapNote(sections.snap)}`;
}
function describeLine(description: { text?: string; tags: { label: string; score: number }[] }) {
const tags = description.tags.map((t) => `${t.label} ${t.score.toFixed(2)}`).join(", ");
return ` sounds like ${[description.text, tags].filter(Boolean).join(" — ")}`;
}
/** One line per measurement the item holds, in reading order. */
const LINES: [string, (value: never, at: At) => string | null][] = [
["moments", momentsLine],
["onsets", hitsLine],
["loudness", loudnessLine],
["silence", silenceLine],
["envelope", (envelope: Envelope) => ` ${sparkline(envelope)}`],
["describe", describeLine],
["bpm", tempoLine],
["beats", beatsLine],
["downbeats", downbeatsLine],
["sections", sectionsLine],
];
function headline(item: AudioItem, where: string): string {
const kind = item.kind as KindGuess | null | undefined;
const span = item.placement
? `film ${s(item.placement.start)}–${s(item.placement.end)}, file from ${s(item.placement.mediaStart)}`
: `${s(item.duration ?? 0)} s`;
return `${where} ${span}${kind ? ` ${kind.value} (${kind.confidence})` : ""}`;
}
function formatItem(item: AudioItem): string[] {
const where = item.ref ? `${item.file} ${item.ref}` : item.file;
if (item.error) return [`${where}: ${item.error}`];
const at: At = (t) => s(item.placement ? filmTime(item.placement, t) : t);
const lines = [headline(item, where)];
for (const [capability, line] of LINES) {
const value = item[capability];
const text = value ? line(value as never, at) : null;
if (text) lines.push(text);
}
for (const warning of item.warnings) lines.push(` ! ${warning}`);
return lines;
}
export function formatReport(report: AudioReport): string {
if (report.items.length === 0) return "No audio matched.";
return report.items.map((item) => formatItem(item).join("\n")).join("\n\n");
}