Skip to content

Write HTML. Render video. Built for agents.

feat(cli): beats tracks the music with the TypeScript beat tracker, without Chrome (#5634)

Xuanru Li1544b519a944
diff --git a/bun.lock b/bun.lock
index 2a34d5f276..69e180ee89 100644
--- a/bun.lock
+++ b/bun.lock
@@ -119,7 +119,6 @@
"@hyperframes/parsers": "workspace:*",
"@hyperframes/studio-server": "workspace:*",
"acorn": "^8.17.0",
- "bpm-detective": "^2.0.5",
"linkedom": "^0.18.12",
"postcss": "^8.5.8",
"wawoff2": "^2.0.1",
@@ -364,7 +363,6 @@
"@mcp-b/global": "^5.0.1",
"@phosphor-icons/react": "^2.1.10",
"@tanstack/react-virtual": "^3.14.13",
- "bpm-detective": "^2.0.5",
"cn": "0.2.4",
"dockview-react": "8.3.1",
"gsap": "^3.13.0",
@@ -1321,7 +1319,6 @@
"bowser": ["[email protected]", "", {}, "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg=="],
- "bpm-detective": ["[email protected]", "", {}, "sha512-FaHFT5WDCR5zwtjVTqxk01o2MDaf22ORHityX1lxMamBcVNX6NWXB6hw7nx4fmlEseRMv0xfuSybINZylljLfA=="],
"brace-expansion": ["[email protected]", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="],
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index 77290194e7..5078c9413c 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -483,8 +483,8 @@ npx hyperframes beats [dir] --json # { ok, file, count, bpm }
`beats` finds the music track — an `<audio>` element with
`data-timeline-role="music"`, or an id like `music`, `bgm`, or `soundtrack` —
-runs the same decode and BPM analysis Studio uses inside headless Chrome, and
-writes `beats/<audio-path>.json`:
+decodes it with ffmpeg, runs the same beat tracker Studio uses, and writes
+`beats/<audio-path>.json`:
```json
{
@@ -499,10 +499,10 @@ loads this file as-is and only generates one when none exists. `time` is seconds
into the audio; `strength` (0–1) is relative loudness. Beats you add, move, or
delete in Studio save back to the same file.
-Needs a local Chrome, the same one `render` uses. Run
-`npx hyperframes browser ensure` if it is missing. Results match Studio's to
-within a frame or two — a different headless-Chrome audio sample rate can shift
-a beat slightly.
+A track without a steady beat (ambient, rubato, too short) gets no beat file:
+the command fails and writes nothing rather than inventing a grid. Results
+match Studio's to within a frame or two — Studio decodes in the browser, often
+at a different sample rate, which can shift a beat slightly.
### `audio`
diff --git a/packages/cli/package.json b/packages/cli/package.json
index a15b2b8749..20e737a7b2 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -27,10 +27,9 @@
"scripts": {
"test": "vitest run",
"dev": "tsx src/cli.ts",
- "build": "bun run build:fonts && tsup && bun run build:runtime && bun run build:beat-analyzer && bun run build:copy",
+ "build": "bun run build:fonts && tsup && bun run build:runtime && bun run build:copy",
"build:fonts": "node scripts/build-fonts.mjs",
"build:runtime": "tsx scripts/build-runtime.ts",
- "build:beat-analyzer": "node scripts/build-beat-analyzer.mjs",
"build:copy": "node scripts/build-copy.mjs",
"typecheck": "tsc --noEmit",
"gen:skills-manifest": "tsx scripts/gen-skills-manifest.ts",
diff --git a/packages/cli/scripts/build-beat-analyzer.mjs b/packages/cli/scripts/build-beat-analyzer.mjs
deleted file mode 100644
index dacb6ad701..0000000000
--- a/packages/cli/scripts/build-beat-analyzer.mjs
+++ /dev/null
@@ -1,28 +0,0 @@
-// Prebuild the beat-detection browser bundle into dist so `hyperframes beats`
-// works in the published CLI (which ships only dist, not source). Mirrors how
-// the runtime IIFE is shipped. headlessAnalyzer.ts loads this at runtime and
-// injects it into a headless page.
-import { build } from "esbuild";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-
-const require = createRequire(import.meta.url);
-const coreRoot = dirname(require.resolve("@hyperframes/core/package.json"));
-const entry = join(coreRoot, "src/beats/beatDetection.ts");
-
-await build({
- stdin: {
- contents:
- `import { analyzeMusicFromBuffer } from ${JSON.stringify(entry)};\n` +
- `globalThis.__hfAnalyze = analyzeMusicFromBuffer;`,
- resolveDir: coreRoot,
- loader: "ts",
- },
- bundle: true,
- format: "iife",
- platform: "browser",
- target: "es2020",
- outfile: "dist/beat-analyzer.global.js",
-});
-
-console.log("built dist/beat-analyzer.global.js");
diff --git a/packages/cli/src/beats/headlessAnalyzer.ts b/packages/cli/src/beats/headlessAnalyzer.ts
deleted file mode 100644
index 5ae0f99166..0000000000
--- a/packages/cli/src/beats/headlessAnalyzer.ts
+++ /dev/null
@@ -1,153 +0,0 @@
-import { launchManagedBrowser } from "../browser/launch.js";
-// Run the shared beat detection (@hyperframes/core/beats) in a headless Chrome
-// so results match the Studio exactly — same Web Audio decode + same
-// bpm-detective. Used by the `beats` CLI command to write the beat file before
-// the Studio is ever opened.
-
-import { existsSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import type { Browser, Page } from "puppeteer-core";
-
-const require = createRequire(import.meta.url);
-
-// The detection is browser code. We need it as an IIFE that exposes
-// analyzeMusicFromBuffer on the page. Prefer the artifact prebuilt at CLI build
-// time (shipped in dist); fall back to bundling from core source at runtime
-// (dev/monorepo, where core's src is on disk).
-let bundlePromise: Promise<string> | null = null;
-
-function findPrebuiltBundle(): string | null {
- const here = dirname(fileURLToPath(import.meta.url));
- const candidates = [
- join(here, "beat-analyzer.global.js"), // dist root (tsup-bundled cli)
- join(here, "../beat-analyzer.global.js"), // dist/beats → dist
- join(here, "../dist/beat-analyzer.global.js"),
- ];
- for (const p of candidates) {
- if (existsSync(p)) return p;
- }
- return null;
-}
-
-async function buildFromCoreSource(): Promise<string> {
- const esbuild = await import("esbuild");
- const coreRoot = dirname(require.resolve("@hyperframes/core/package.json"));
- const entry = join(coreRoot, "src/beats/beatDetection.ts");
- const result = await esbuild.build({
- stdin: {
- contents:
- `import { analyzeMusicFromBuffer } from ${JSON.stringify(entry)};\n` +
- `globalThis.__hfAnalyze = analyzeMusicFromBuffer;`,
- resolveDir: coreRoot,
- loader: "ts",
- },
- bundle: true,
- format: "iife",
- platform: "browser",
- target: "es2020",
- write: false,
- });
- const out = result.outputFiles?.[0];
- if (!out) throw new Error("Failed to bundle beat analyzer");
- return out.text;
-}
-
-function buildAnalyzerBundle(): Promise<string> {
- if (bundlePromise) return bundlePromise;
- bundlePromise = (async () => {
- const prebuilt = findPrebuiltBundle();
- if (prebuilt) return readFileSync(prebuilt, "utf8");
- return buildFromCoreSource();
- })().catch((err) => {
- bundlePromise = null; // don't poison the process with a cached rejection
- throw err;
- });
- return bundlePromise;
-}
-
-export interface HeadlessBeatResult {
- beatTimes: number[];
- beatStrengths: number[];
- bpm: number | null;
- bpmConfidence: string;
-}
-
-// Guard against pathological inputs that would blow CDP message limits when
-// transferred to the page as base64 (≈ +33% over the raw bytes).
-const MAX_AUDIO_BYTES = 80 * 1024 * 1024;
-
-// Runs inside the headless page: decode the base64 audio and analyze it.
-function inPageAnalyze(data: string) {
- const bin = atob(data);
- const bytes = new Uint8Array(bin.length);
- for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
- const win = window as unknown as {
- AudioContext: typeof AudioContext;
- webkitAudioContext?: typeof AudioContext;
- __hfAnalyze?: (buffer: AudioBuffer) => Promise<HeadlessBeatResult>;
- };
- if (typeof win.__hfAnalyze !== "function") throw new Error("beat analyzer not loaded");
- const ctx = new (win.AudioContext || win.webkitAudioContext!)();
- return (
- ctx
- .decodeAudioData(bytes.buffer)
- .then((buf) => win.__hfAnalyze!(buf))
- // analyzeMusicFromBuffer also returns the decoded PCM (channelData) + sampleRate;
- // project to only the fields we need so page.evaluate doesn't serialize an
- // ~8-million-element Float32Array back across the CDP boundary.
- .then((r) => ({
- beatTimes: r.beatTimes,
- beatStrengths: r.beatStrengths,
- bpm: r.bpm,
- bpmConfidence: r.bpmConfidence,
- }))
- .finally(() => ctx.close())
- );
-}
-
-// Load the analyzer bundle into the page, run analysis, and surface in-page
-// errors (decode/codec failures, missing global) instead of an opaque rejection.
-async function detectOnPage(page: Page, bundle: string, b64: string): Promise<HeadlessBeatResult> {
- const pageErrors: string[] = [];
- page.on("pageerror", (e) => {
- pageErrors.push((e as Error).message);
- });
- page.on("console", (m) => {
- if (m.type() === "error") pageErrors.push(m.text());
- });
- await page.setContent("<!doctype html><html><body></body></html>");
- await page.addScriptTag({ content: bundle });
- try {
- return (await page.evaluate(inPageAnalyze, b64)) as HeadlessBeatResult;
- } catch (err) {
- const detail = pageErrors.length ? ` (${pageErrors.join("; ")})` : "";
- throw new Error(`${err instanceof Error ? err.message : String(err)}${detail}`);
- }
-}
-
-/** Decode + analyze the given audio bytes in headless Chrome. */
-export async function analyzeBeatsHeadless(audioBytes: Buffer): Promise<HeadlessBeatResult> {
- if (audioBytes.length > MAX_AUDIO_BYTES) {
- const mb = Math.round(audioBytes.length / 1e6);
- throw new Error(
- `Audio file too large for headless analysis (${mb}MB > ${MAX_AUDIO_BYTES / 1e6}MB).`,
- );
- }
- const bundle = await buildAnalyzerBundle();
- const { ensureBrowser } = await import("../browser/manager.js");
- const puppeteer = await import("puppeteer-core");
- const browser = await ensureBrowser();
- const chrome: Browser = await launchManagedBrowser(puppeteer.default, {
- headless: true,
- executablePath: browser.executablePath,
- args: ["--no-sandbox", "--disable-dev-shm-usage", "--autoplay-policy=no-user-gesture-required"],
- });
- try {
- const page = await chrome.newPage();
- return await detectOnPage(page, bundle, audioBytes.toString("base64"));
- } finally {
- await chrome.close();
- }
-}
diff --git a/packages/cli/src/commands/beats.test.ts b/packages/cli/src/commands/beats.test.ts
new file mode 100644
index 0000000000..a0f43eb7c2
--- /dev/null
+++ b/packages/cli/src/commands/beats.test.ts
@@ -0,0 +1,86 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
+import { encodeWav } from "../audio/analysis/providers/shared.js";
+
+const RATE = 22_050;
+const root = mkdtempSync(join(tmpdir(), "hf-beats-"));
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+/** A project whose music track is `seconds` of noise clicks at `bpm`, or silence when `bpm` is null. */
+function project(name: string, bpm: number | null, seconds = 12): string {
+ const dir = join(root, name);
+ const samples = new Float32Array(seconds * RATE);
+ let seed = 7;
+ const noise = () => (seed = (seed * 1_103_515_245 + 12_345) % 2_147_483_648) / 2 ** 30 - 1;
+ for (let t = 0.2; bpm && t < seconds - 0.1; t += 60 / bpm) {
+ const start = Math.round(t * RATE);
+ for (let i = 0; i < 0.05 * RATE; i++)
+ samples[start + i]! += 0.6 * noise() * Math.exp(-i / RATE / 0.015);
+ }
+ mkdirSync(join(dir, "assets"), { recursive: true });
+ writeFileSync(
+ join(dir, "assets", "song.wav"),
+ encodeWav({ sampleRate: RATE, channels: [samples] }),
+ );
+ writeFileSync(
+ join(dir, "index.html"),
+ `<div data-composition-id="main"><audio id="music" src="assets/song.wav"></audio></div>`,
+ );
+ return dir;
+}
+
+async function runBeats(dir: string): Promise<{ exitCode: number; out: string }> {
+ const command = (await import("./beats.js")).default as unknown as {
+ run: (context: { args: Record<string, unknown> }) => Promise<void>;
+ };
+ const lines: string[] = [];
+ const capture = (...parts: unknown[]) => void lines.push(parts.map(String).join(" "));
+ const log = vi.spyOn(console, "log").mockImplementation(capture);
+ const error = vi.spyOn(console, "error").mockImplementation(capture);
+ let exitCode = 0;
+ try {
+ await command.run({ args: { dir, json: true } });
+ } catch (thrown) {
+ exitCode = (thrown as { result?: { exitCode?: number } }).result?.exitCode ?? -1;
+ } finally {
+ log.mockRestore();
+ error.mockRestore();
+ }
+ return { exitCode, out: lines.join("\n") };
+}
+
+const ffmpeg = findFfBinary("ffmpeg") && findFfBinary("ffprobe");
+
+describe.skipIf(!ffmpeg)("hyperframes beats", () => {
+ it("writes beats/<audio>.json in the beat-file format the Studio reads", async () => {
+ const dir = project("steady", 120);
+ const { exitCode, out } = await runBeats(dir);
+ expect(exitCode).toBe(0);
+ const file = JSON.parse(readFileSync(join(dir, "beats", "assets", "song.wav.json"), "utf8"));
+ expect(Object.keys(file)).toEqual(["version", "audio", "beats"]);
+ expect(file).toMatchObject({ version: 1, audio: "assets/song.wav" });
+ for (const beat of file.beats) {
+ expect(Object.keys(beat)).toEqual(["time", "strength"]);
+ expect(beat.strength).toBeGreaterThanOrEqual(0);
+ expect(beat.strength).toBeLessThanOrEqual(1);
+ }
+ const times: number[] = file.beats.map((b: { time: number }) => b.time);
+ expect(times.length).toBeGreaterThan(18);
+ expect(times.every((t) => Math.abs(((t - 0.2 + 0.25) % 0.5) - 0.25) <= 0.07)).toBe(true);
+ const report = JSON.parse(out) as { ok: boolean; count: number; bpm: number };
+ expect(report).toMatchObject({ ok: true, file: "beats/assets/song.wav.json" });
+ expect(report.count).toBe(times.length);
+ expect(Math.abs(report.bpm - 120)).toBeLessThanOrEqual(1);
+ });
+
+ it("writes nothing for a track with no steady beat", async () => {
+ const dir = project("silent", null);
+ const { exitCode, out } = await runBeats(dir);
+ expect(exitCode).toBe(1);
+ expect(out).toMatch(/No beats detected in assets\/song\.wav/);
+ expect(existsSync(join(dir, "beats"))).toBe(false);
+ });
+});
diff --git a/packages/cli/src/commands/beats.ts b/packages/cli/src/commands/beats.ts
index 9ae8ff1d65..2381c1ecdd 100644
--- a/packages/cli/src/commands/beats.ts
+++ b/packages/cli/src/commands/beats.ts
@@ -2,10 +2,17 @@ import { failCommand } from "../utils/commandResult.js";
import { defineCommand } from "citty";
import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
import { resolve, join, dirname } from "node:path";
-import { findMusicAudioSrc, audioRelPathForSrc, serializeBeats } from "@hyperframes/core/beats";
+import {
+ analyzeMusicFromSignal,
+ audioRelPathForSrc,
+ findMusicAudioSrc,
+ serializeBeats,
+ type MusicBeatAnalysis,
+} from "@hyperframes/core/beats";
import type { Example } from "./_examples.js";
import { resolveProject, type ProjectDir } from "../utils/project.js";
-import { analyzeBeatsHeadless, type HeadlessBeatResult } from "../beats/headlessAnalyzer.js";
+import type { AudioSignal } from "@hyperframes/core/audio-analysis";
+import { decodeAudio } from "../audio/analysis/decode.js";
import { c } from "../ui/colors.js";
export const examples: Example[] = [
@@ -35,19 +42,17 @@ function resolveMusicTarget(project: ProjectDir): { rel: string; audioPath: stri
return { rel, audioPath };
}
-async function detect(audioPath: string): Promise<HeadlessBeatResult> {
+async function decode(audioPath: string): Promise<AudioSignal> {
try {
- return await analyzeBeatsHeadless(readFileSync(audioPath));
+ const decoded = await decodeAudio(audioPath);
+ if (decoded) return decoded.signal;
} catch (err) {
- const msg = err instanceof Error ? err.message : String(err);
- const hint = /chrome|executable|browser|ENOENT/i.test(msg)
- ? "\nRun: npx hyperframes browser ensure"
- : "";
- fail(`Beat detection failed: ${msg}${hint}`);
+ fail(`Beat detection failed: ${err instanceof Error ? err.message : String(err)}`);
}
+ fail(`Beat detection failed: ${audioPath} has no audio stream`);
}
-function report(file: string, result: HeadlessBeatResult, json: boolean): void {
+function report(file: string, result: MusicBeatAnalysis, json: boolean): void {
if (json) {
console.log(
JSON.stringify({ ok: true, file, count: result.beatTimes.length, bpm: result.bpm }, null, 2),
@@ -64,7 +69,7 @@ function report(file: string, result: HeadlessBeatResult, json: boolean): void {
export default defineCommand({
meta: {
name: "beats",
- description: "Detect beats in the music track (headless) and write beats/<audio>.json",
+ description: "Detect beats in the music track and write beats/<audio>.json",
},
args: {
dir: { type: "positional", description: "Project directory", required: false },
@@ -73,9 +78,9 @@ export default defineCommand({
async run({ args }) {
const project = resolveProject(args.dir);
const { rel, audioPath } = resolveMusicTarget(project);
- if (!args.json) console.log(c.dim(`Analyzing ${rel} in headless Chrome…`));
+ if (!args.json) console.log(c.dim(`Analyzing ${rel}…`));
- const result = await detect(audioPath);
+ const result = await analyzeMusicFromSignal(await decode(audioPath));
// The Studio ignores a 0-beat file (treats it as a stale seed), so don't write one.
if (result.beatTimes.length === 0) {
fail(`No beats detected in ${rel} — nothing written. (Track may be silent/ambient.)`);
diff --git a/packages/core/package.json b/packages/core/package.json
index 45d05dc8f0..a6a936b7f1 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -931,7 +931,6 @@
"@hyperframes/parsers": "workspace:*",
"@hyperframes/studio-server": "workspace:*",
"acorn": "^8.17.0",
- "bpm-detective": "^2.0.5",
"linkedom": "^0.18.12",
"postcss": "^8.5.8",
"wawoff2": "^2.0.1"
diff --git a/packages/core/src/audioAnalysis.ts b/packages/core/src/audioAnalysis.ts
index 7098a363cf..29d534ddb0 100644
--- a/packages/core/src/audioAnalysis.ts
+++ b/packages/core/src/audioAnalysis.ts
@@ -123,7 +123,7 @@ export const signalDuration = (signal: AudioSignal): number =>
(signal.channels[0]?.length ?? 0) / signal.sampleRate;
/** Per-sample energy. Channels are squared first, so a reversed channel stays audible. */
-function energyMix(signal: AudioSignal): Float32Array {
+export function energyMix(signal: AudioSignal): Float32Array {
const [first, ...rest] = signal.channels;
if (!first) return new Float32Array(0);
if (!rest.length) return first;
diff --git a/packages/core/src/audioRhythm.test.ts b/packages/core/src/audioRhythm.test.ts
index e176dbd7ad..2667d5d40c 100644
--- a/packages/core/src/audioRhythm.test.ts
+++ b/packages/core/src/audioRhythm.test.ts
@@ -84,6 +84,13 @@ describe("tempoOf", () => {
it("has no tempo without two beats", () => {
expect(tempoOf([1])).toEqual({ value: null, curve: [] });
});
+
+ it("reads 96 BPM off beats placed on 10 ms frames, though no interval between them is 625 ms", () => {
+ const beats = grid(0.4, 0.625, 20).map((t) => Math.round(t * 100) / 100);
+ const tempo = tempoOf(beats);
+ expect(tempo.value).toBeCloseTo(96, 0);
+ expect(tempo.curve.every((point) => Math.abs(point.bpm - 96) < 0.5)).toBe(true);
+ });
});
describe("sections", () => {
diff --git a/packages/core/src/audioRhythm.ts b/packages/core/src/audioRhythm.ts
index 9d1bd4f783..74fa42d36e 100644
--- a/packages/core/src/audioRhythm.ts
+++ b/packages/core/src/audioRhythm.ts
@@ -369,15 +369,25 @@ export function rhythmOf(frames: BandFrames, sampleRate: number): Rhythm {
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: readonly number[]): number | null {
+ 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: readonly number[]): Tempo {
- const interval = medianInterval(times);
+ const interval = steadyInterval(times);
if (!interval) return { value: null, curve: [] };
const bpm = (gap: number) => Math.round(600 / gap) / 10;
const curve: TempoPoint[] = [];
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) });
}
return { value: bpm(interval), curve };
diff --git a/packages/core/src/beats/beatDetection.test.ts b/packages/core/src/beats/beatDetection.test.ts
index f0a6ec72fc..d8e4244db2 100644
--- a/packages/core/src/beats/beatDetection.test.ts
+++ b/packages/core/src/beats/beatDetection.test.ts
@@ -1,59 +1,117 @@
import { describe, expect, it, vi } from "vitest";
-import { analyzeMusicFromBuffer, loadBpmDetective } from "./beatDetection";
+import type { AudioSignal } from "../audioAnalysis";
+import { analyzeMusicFromBuffer, analyzeMusicFromSignal } from "./beatDetection";
-describe("loadBpmDetective", () => {
- it("resolves to null when the import is unavailable", async () => {
- const detect = await loadBpmDetective(() => Promise.reject(new Error("missing")));
- expect(detect).toBeNull();
+const RATE = 22_050;
+
+function random(seed = 5) {
+ let state = seed;
+ return () => {
+ state = (state * 1_103_515_245 + 12_345) % 2_147_483_648;
+ return (state / 2_147_483_648) * 2 - 1;
+ };
+}
+
+const grid = (from: number, period: number, until: number) =>
+ Array.from({ length: Math.floor((until - from) / period) + 1 }, (_, k) => from + k * period);
+
+/** Add a decaying noise click at each time. */
+function clicks(samples: Float32Array, times: number[], level: number, seed = 5): void {
+ const noise = random(seed);
+ for (const t of times) {
+ const start = Math.round(t * RATE);
+ for (let i = 0; i < 0.06 * RATE && start + i < samples.length; i++)
+ samples[start + i]! += level * noise() * Math.exp(-i / RATE / 0.015);
+ }
+}
+
+/** Add a loud low chord that starts at each time and rings for `length` seconds. */
+function stabs(samples: Float32Array, times: number[], length: number): void {
+ for (const t of times) {
+ const start = Math.round(t * RATE);
+ for (let i = 0; i < length * RATE && start + i < samples.length; i++) {
+ const since = i / RATE;
+ const chord = [110, 138.6, 164.8].reduce(
+ (a, hz) => a + Math.sin(2 * Math.PI * hz * since),
+ 0,
+ );
+ samples[start + i]! += 0.3 * chord * Math.exp(-since / 0.25);
+ }
+ }
+}
+
+/** A chord that changes every four seconds, swelling in slowly each time: no pulse to follow. */
+function pad(seconds: number): Float32Array {
+ return Float32Array.from({ length: seconds * RATE }, (_, i) => {
+ const t = i / RATE;
+ const root = [110, 98, 123, 87][Math.floor(t / 4) % 4]!;
+ const swell = Math.min(1, (t % 4) / 1.5);
+ return (
+ 0.3 * swell * (Math.sin(2 * Math.PI * root * t) + 0.5 * Math.sin(3 * Math.PI * root * t))
+ );
});
+}
+
+const mono = (samples: Float32Array): AudioSignal => ({ sampleRate: RATE, channels: [samples] });
- it("retries a previously failed import instead of caching null forever", async () => {
- let shouldFail = true;
- const importFn = async () => {
- if (shouldFail) {
- throw new Error("transient");
- }
- return { default: () => 120 };
- };
+const nearBpm = (found: number | null, bpm: number) => Math.abs((found ?? 0) - bpm) <= 1;
- const first = await loadBpmDetective(importFn);
- expect(first).toBeNull();
+/** Share of `truth` with a found time within 70 ms. */
+function recall(found: number[], truth: number[]): number {
+ const heard = (t: number) => found.some((f) => Math.abs(f - t) <= 0.07);
+ return truth.filter(heard).length / truth.length;
+}
- shouldFail = false;
- const second = await loadBpmDetective(importFn);
- expect(second).not.toBeNull();
- expect(second?.({} as AudioBuffer)).toBe(120);
+describe("analyzeMusicFromSignal", () => {
+ // Loud stabs every 2 beats once averaged a ~52 BPM energy-peak tempo with 96 into 74 BPM;
+ // every 2.2 beats they phased a 96 BPM grid onto the off-beats.
+ it.each([2, 2.2])("keeps a 96 BPM pulse under loud stabs every %s beats", async (stabEvery) => {
+ const seconds = 30;
+ const beats = grid(0.4, 60 / 96, seconds - 0.5);
+ const samples = new Float32Array(seconds * RATE);
+ clicks(samples, beats, 0.25);
+ stabs(samples, grid(0.4, stabEvery * (60 / 96), seconds - 1), 0.9);
+ const analysis = await analyzeMusicFromSignal(mono(samples));
+ expect(nearBpm(analysis.bpm, 96)).toBe(true);
+ expect(recall(analysis.beatTimes, beats.slice(2, -2))).toBeGreaterThan(0.95);
+ expect(recall(beats, analysis.beatTimes)).toBeGreaterThan(0.95);
});
- it("uses the default export if present, otherwise the module object", async () => {
- const importFn = async () => ({ default: () => 90 });
- const detect = await loadBpmDetective(importFn);
- expect(detect?.({} as AudioBuffer)).toBe(90);
+ it.each([
+ { bpm: 120, offset: 0.31 },
+ { bpm: 90, offset: 0.12 },
+ { bpm: 140, offset: 0.2 },
+ ])("finds the tempo and the phase of a $bpm BPM grid", async ({ bpm, offset }) => {
+ const seconds = 20;
+ const beats = grid(offset, 60 / bpm, seconds - 0.3);
+ const samples = new Float32Array(seconds * RATE);
+ clicks(samples, beats, 0.6);
+ const analysis = await analyzeMusicFromSignal(mono(samples));
+ expect(nearBpm(analysis.bpm, bpm)).toBe(true);
+ expect(analysis.bpmConfidence).toBe("high");
+ expect(recall(analysis.beatTimes, beats.slice(1, -1))).toBeGreaterThan(0.95);
+ expect(recall(beats, analysis.beatTimes)).toBe(1);
+ expect(analysis.beatStrengths).toHaveLength(analysis.beatTimes.length);
+ expect(analysis.peak).toBeGreaterThan(0);
});
- it("falls back to the module object when there is no default export", async () => {
- const fn = (buffer: AudioBuffer) => buffer.duration;
- const importFn = async () => fn as unknown;
- const detect = await loadBpmDetective(importFn);
- expect(detect).toBe(fn);
+ it("reports no beats and no tempo for audio without a steady pulse", async () => {
+ const noise = random(9);
+ const hiss = Float32Array.from({ length: 12 * RATE }, () => 0.2 * noise());
+ for (const samples of [new Float32Array(12 * RATE), hiss, pad(30)]) {
+ const analysis = await analyzeMusicFromSignal(mono(samples));
+ expect(analysis).toMatchObject({ beatTimes: [], bpm: null, bpmConfidence: "uncertain" });
+ }
});
-});
-describe("analyzeMusicFromBuffer", () => {
it("waits on the caller's pause before each long stage", async () => {
- const sampleRate = 8000;
- const channel = new Float32Array(sampleRate * 2);
- for (let beat = 0; beat < 4; beat++) channel.fill(0.9, beat * 4000, beat * 4000 + 80);
- const audio = {
- getChannelData: () => channel,
- sampleRate,
- duration: 2,
- } as unknown as AudioBuffer;
+ const samples = new Float32Array(8 * RATE);
+ clicks(samples, grid(0.25, 0.5, 7.5), 0.6);
const held: (() => void)[] = [];
const pause = () => new Promise<void>((resolve) => held.push(resolve));
let done = false;
- const analysis = analyzeMusicFromBuffer(audio, { pause }).then((result) => {
+ const analysis = analyzeMusicFromSignal(mono(samples), { pause }).then((result) => {
done = true;
return result;
});
@@ -62,49 +120,25 @@ describe("analyzeMusicFromBuffer", () => {
expect(done).toBe(false);
held[stage - 1]!();
}
- await expect(analysis).resolves.toMatchObject({ sampleRate });
+ await expect(analysis).resolves.toMatchObject({ sampleRate: RATE });
});
+});
- it("rechecks pause after a slow tempo-detector import", async () => {
- let releaseImport!: () => void;
- const importGate = new Promise<void>((resolve) => (releaseImport = resolve));
- let importStarted = false;
- let moving = false;
- const movingAtDetect: boolean[] = [];
- const detect = vi.fn(() => {
- movingAtDetect.push(moving);
- return 120;
- });
- vi.resetModules();
- vi.doMock("bpm-detective", async () => {
- importStarted = true;
- await importGate;
- return { default: detect };
- });
- try {
- const { analyzeMusicFromBuffer: analyze } = await import("./beatDetection");
- const sampleRate = 8000;
- const audio = {
- getChannelData: () => new Float32Array(sampleRate * 2),
- sampleRate,
- duration: 2,
- } as unknown as AudioBuffer;
- const waiters: (() => void)[] = [];
- const pause = () =>
- moving ? new Promise<void>((resolve) => waiters.push(resolve)) : Promise.resolve();
- const analysis = analyze(audio, { pause });
- await vi.waitFor(() => expect(importStarted).toBe(true));
- moving = true;
- releaseImport();
- await vi.waitFor(() => expect(waiters).toHaveLength(1));
- expect(detect).not.toHaveBeenCalled();
- moving = false;
- waiters.shift()!();
- await analysis;
- expect(movingAtDetect).toEqual([false]);
- } finally {
- vi.doUnmock("bpm-detective");
- vi.resetModules();
- }
+describe("analyzeMusicFromBuffer", () => {
+ it("hears every channel, so a beat only on the right is found and has strength", async () => {
+ const beats = grid(0.25, 0.5, 9.5);
+ const right = new Float32Array(10 * RATE);
+ clicks(right, beats, 0.6);
+ const left = new Float32Array(right.length);
+ const audio = {
+ numberOfChannels: 2,
+ getChannelData: (c: number) => (c === 0 ? left : right),
+ sampleRate: RATE,
+ duration: 10,
+ } as unknown as AudioBuffer;
+ const analysis = await analyzeMusicFromBuffer(audio);
+ expect(nearBpm(analysis.bpm, 120)).toBe(true);
+ expect(recall(analysis.beatTimes, beats.slice(1, -1))).toBeGreaterThan(0.95);
+ expect(Math.min(...analysis.beatStrengths)).toBeGreaterThan(0.5);
});
});
diff --git a/packages/core/src/beats/beatDetection.ts b/packages/core/src/beats/beatDetection.ts
index db2eb2399a..f133bd8e14 100644
--- a/packages/core/src/beats/beatDetection.ts
+++ b/packages/core/src/beats/beatDetection.ts
@@ -1,39 +1,5 @@
-// bpm-detective touches `window` at module top-level, so it must NOT be a static
-// import (that would crash any non-browser import of this module graph, e.g.
-// vitest/SSR). It's loaded lazily inside analyzeMusicFromBuffer, which only runs
-// in the browser.
-type BpmDetect = (buffer: AudioBuffer) => number;
-let bpmDetectivePromise: Promise<BpmDetect | null> | null = null;
-
-const defaultBpmDetectiveImport = () =>
- // @ts-ignore -- no type declarations for bpm-detective
- import("bpm-detective");
-
-export function loadBpmDetective(
- importFn: () => Promise<unknown> = defaultBpmDetectiveImport,
-): Promise<BpmDetect | null> {
- const useCache = importFn === defaultBpmDetectiveImport;
- if (useCache && bpmDetectivePromise) {
- return bpmDetectivePromise;
- }
-
- const promise = importFn()
- .then((m) => ((m as { default?: BpmDetect }).default ?? (m as unknown as BpmDetect)) || null)
- .catch(() => {
- // Reset the cached promise so a transient import failure can be retried
- // on the next call instead of being cached as null for the session.
- if (useCache) bpmDetectivePromise = null;
- return null;
- });
-
- if (useCache) {
- bpmDetectivePromise = promise;
- }
- return promise;
-}
-
-const WINDOW_SIZE = 1024;
-const HOP_SIZE = 512;
+import { energyMix, type AudioSignal } from "../audioAnalysis";
+import { bandFrames, rhythmOf, tempoOf } from "../audioRhythm";
export interface MusicBeatAnalysis {
beatTimes: number[];
@@ -41,8 +7,8 @@ export interface MusicBeatAnalysis {
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. */
@@ -74,228 +40,56 @@ export function strengthAtTime(
return Math.min(1, computeRmsAt(analysis.channelData, analysis.sampleRate, time) / analysis.peak);
}
-// fallow-ignore-next-line complexity
-export async function detectBeats(audioBuffer: AudioBuffer): Promise<number[]> {
- const channelData = audioBuffer.getChannelData(0);
- const sampleRate = audioBuffer.sampleRate;
-
- const energies: number[] = [];
- for (let i = 0; i < channelData.length - WINDOW_SIZE; i += HOP_SIZE) {
- let sum = 0;
- for (let j = 0; j < WINDOW_SIZE; j++) {
- const sample = channelData[i + j]!;
- sum += sample * sample;
- }
- energies.push(sum / WINDOW_SIZE);
- }
-
- const beats: number[] = [];
- const localWindowSize = 20;
+/** Below this tracker confidence the grid is more likely the tracker's than the music's, so none is reported. */
+const MIN_CONFIDENCE = 0.2;
+/** At or above this the tempo is reported as "high" confidence. */
+const HIGH_CONFIDENCE = 0.35;
- for (let i = localWindowSize; i < energies.length - localWindowSize; i++) {
- let localMean = 0;
- for (let j = i - localWindowSize; j < i + localWindowSize; j++) {
- localMean += energies[j]!;
- }
- localMean /= localWindowSize * 2;
-
- const threshold = localMean * 1.5;
- const current = energies[i]!;
-
- if (
- current > threshold &&
- current > (energies[i - 1] ?? 0) &&
- current > (energies[i + 1] ?? 0)
- ) {
- const timeInSeconds = (i * HOP_SIZE) / sampleRate;
- if (beats.length === 0 || timeInSeconds - beats[beats.length - 1]! > 0.1) {
- beats.push(Math.round(timeInSeconds * 1000) / 1000);
- }
- }
- }
-
- return beats;
-}
-
-function computeBpmFromBeats(beatTimes: number[]): number | null {
- if (beatTimes.length < 4) return null;
- const iois: number[] = [];
- for (let i = 1; i < beatTimes.length; i++) {
- iois.push(beatTimes[i]! - beatTimes[i - 1]!);
- }
- const sorted = [...iois].sort((a, b) => a - b);
- const mid = Math.floor(sorted.length / 2);
- const medianIoi = sorted.length % 2 === 0 ? (sorted[mid - 1]! + sorted[mid]!) / 2 : sorted[mid]!;
- if (medianIoi <= 0) return null;
- return Math.round((60 / medianIoi) * 10) / 10;
-}
-
-// Fold into 60–120 for octave-safe BPM comparison
-function canonicalizeBpm(bpm: number): number {
- let b = bpm;
- while (b > 120) b /= 2;
- while (b < 60) b *= 2;
- return b;
-}
-
-// Pick the *2/÷2 octave of `bpm` whose beat interval is closest to the onset
-// pulse, so a half-time detective reading (e.g. 174 for an 87bpm song) doesn't
-// produce a double-density grid.
-function octaveAlignBpm(bpm: number, reference: number): number {
- const candidates = [bpm / 2, bpm, bpm * 2];
- let best = bpm;
- let bestDist = Number.POSITIVE_INFINITY;
- for (const c of candidates) {
- if (c <= 0) continue;
- const dist = Math.abs(c - reference);
- if (dist < bestDist) {
- bestDist = dist;
- best = c;
- }
- }
- return best;
-}
-
-// fallow-ignore-next-line complexity
-function regularizeBeats(rawBeats: number[], bpm: number, duration: number): number[] {
- if (rawBeats.length === 0 || bpm <= 0 || duration <= 0) return rawBeats;
- const beatInterval = 60 / bpm;
- // Guard against a pathological (octave-misread) tempo producing a millisecond
- // interval → tens of thousands of grid beats that freeze the timeline. 480 BPM
- // (0.125s) is well above any real music tempo; bail to the raw onsets instead.
- if (beatInterval < 0.125) return rawBeats;
- const threshold = beatInterval * 0.25;
-
- // Find phase offset that maximally aligns with raw onsets
- let bestOffset = 0;
- let bestScore = -1;
- for (const anchor of rawBeats.slice(0, 10)) {
- const offset = ((anchor % beatInterval) + beatInterval) % beatInterval;
- let score = 0;
- for (const rb of rawBeats) {
- const phase = ((rb % beatInterval) + beatInterval) % beatInterval;
- const dist = Math.min(Math.abs(phase - offset), beatInterval - Math.abs(phase - offset));
- if (dist < threshold) score++;
- }
- if (score > bestScore) {
- bestScore = score;
- bestOffset = offset;
- }
- }
-
- const beats: number[] = [];
- for (let t = bestOffset; t <= duration + 0.001; t += beatInterval) {
- beats.push(Math.round(t * 1000) / 1000);
- }
- return beats;
-}
-
-// Drop beats that fall in silent/near-silent regions (e.g. intro/outro) and
-// score each surviving beat's loudness (local RMS / peak) for brightness.
-function gateBeatsBySilence(
- beats: number[],
- channelData: Float32Array,
- sampleRate: number,
-): { times: number[]; strengths: number[]; peak: number } {
- if (beats.length === 0) return { times: beats, strengths: [], peak: 1e-6 };
- const energies = beats.map((t) => computeRmsAt(channelData, sampleRate, t));
+/** Each beat's local RMS against the loudest beat's, and that loudest RMS. */
+function beatStrengths(beats: number[], levels: Float32Array, sampleRate: number) {
+ const energies = beats.map((t) => computeRmsAt(levels, sampleRate, t));
const peak = Math.max(...energies, 1e-6);
- const threshold = peak * 0.12;
- const times: number[] = [];
- const strengths: number[] = [];
- for (let i = 0; i < beats.length; i++) {
- if (energies[i]! >= threshold) {
- times.push(beats[i]!);
- strengths.push(Math.min(1, energies[i]! / peak));
- }
- }
- return { times, strengths, peak };
+ return { strengths: energies.map((e) => Math.min(1, e / peak)), peak };
}
export interface MusicAnalysisOptions {
pause?: () => Promise<void>;
}
-// fallow-ignore-next-line complexity
-export async function analyzeMusicFromBuffer(
- audioBuffer: AudioBuffer,
+/** Beats, tempo and per-beat strength of decoded audio; no beats and a null bpm when it has no steady beat. */
+export async function analyzeMusicFromSignal(
+ signal: AudioSignal,
{ pause }: MusicAnalysisOptions = {},
): Promise<MusicBeatAnalysis> {
- const channelData = audioBuffer.getChannelData(0);
- const sampleRate = audioBuffer.sampleRate;
- const duration = audioBuffer.duration;
-
await pause?.();
- const rawBeats = await detectBeats(audioBuffer);
- const onsetBpm = computeBpmFromBeats(rawBeats);
-
- let detectiveBpm: number | null = null;
- const detect = await loadBpmDetective();
+ const frames = bandFrames(signal);
await pause?.();
- try {
- if (detect) detectiveBpm = detect(audioBuffer);
- } catch {
- // Not enough peaks or browser context unavailable
- }
-
- let bpm: number | null = onsetBpm;
- let confidence: MusicBeatAnalysis["bpmConfidence"] = "uncertain";
- let regularizeBpm: number | null = null;
-
- if (onsetBpm !== null && detectiveBpm !== null) {
- const pctDiff =
- Math.abs(canonicalizeBpm(onsetBpm) - canonicalizeBpm(detectiveBpm)) /
- canonicalizeBpm(detectiveBpm);
- if (pctDiff < 0.05) {
- // Detective folds tempo into 90–180; re-pick the octave nearest the onset
- // pulse so a half-time track isn't gridded at double density.
- bpm = octaveAlignBpm(detectiveBpm, onsetBpm);
- confidence = "high";
- regularizeBpm = bpm;
- } else if (pctDiff < 0.1) {
- bpm = Math.round((onsetBpm + detectiveBpm) / 2);
- confidence = "low";
- regularizeBpm = bpm;
- } else {
- bpm = onsetBpm;
- confidence = "uncertain";
- }
- } else if (onsetBpm !== null) {
- bpm = onsetBpm;
- confidence = "low";
- regularizeBpm = onsetBpm;
- } else if (detectiveBpm !== null) {
- bpm = detectiveBpm;
- confidence = "low";
- regularizeBpm = detectiveBpm;
- }
-
+ const { beats } = rhythmOf(frames, signal.sampleRate);
await pause?.();
- const gridBeats =
- regularizeBpm !== null ? regularizeBeats(rawBeats, regularizeBpm, duration) : rawBeats;
- const gated = gateBeatsBySilence(gridBeats, channelData, sampleRate);
-
+ const channelData = energyMix(signal);
+ const confidence = beats.confidence ?? 0;
+ const times = confidence >= MIN_CONFIDENCE ? beats.times : [];
+ const { strengths, peak } = beatStrengths(times, channelData, signal.sampleRate);
+ const bpm = tempoOf(times).value;
return {
- beatTimes: gated.times,
- beatStrengths: gated.strengths,
+ beatTimes: times,
+ beatStrengths: strengths,
bpm,
- bpmConfidence: confidence,
+ bpmConfidence: bpm === null ? "uncertain" : confidence >= HIGH_CONFIDENCE ? "high" : "low",
channelData,
- sampleRate,
- peak: gated.peak,
+ sampleRate: signal.sampleRate,
+ peak,
};
}
-export async function detectBeatsFromUrl(url: string): Promise<number[]> {
- const audioContext = new AudioContext();
- try {
- const response = await fetch(url);
- const arrayBuffer = await response.arrayBuffer();
- const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
- return detectBeats(audioBuffer);
- } finally {
- await audioContext.close();
- }
+export function analyzeMusicFromBuffer(
+ audioBuffer: AudioBuffer,
+ options: MusicAnalysisOptions = {},
+): Promise<MusicBeatAnalysis> {
+ const channels = Array.from({ length: audioBuffer.numberOfChannels }, (_, c) =>
+ audioBuffer.getChannelData(c),
+ );
+ return analyzeMusicFromSignal({ sampleRate: audioBuffer.sampleRate, channels }, options);
}
export async function analyzeMusicFromUrl(
diff --git a/packages/core/src/beats/beatFile.test.ts b/packages/core/src/beats/beatFile.test.ts
index 59f787a281..c99d054264 100644
--- a/packages/core/src/beats/beatFile.test.ts
+++ b/packages/core/src/beats/beatFile.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { findMusicAudioSrc } from "./beatFile";
+import { findMusicAudioSrc, parseBeats, serializeBeats } from "./beatFile";
describe("findMusicAudioSrc", () => {
it("finds a video with sound tagged as music", () => {
@@ -91,3 +91,24 @@ describe("findMusicAudioSrc", () => {
).toBe("right.wav");
});
});
+
+describe("serializeBeats", () => {
+ it("writes version 1 with the audio path and each beat's time and strength, rounded to the millisecond", () => {
+ const text = serializeBeats([0.31249, 0.9375], [0.87654, 1], "assets/song.mp3");
+ expect(text).toBe(
+ `${JSON.stringify(
+ {
+ version: 1,
+ audio: "assets/song.mp3",
+ beats: [
+ { time: 0.312, strength: 0.877 },
+ { time: 0.938, strength: 1 },
+ ],
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ expect(parseBeats(text)).toEqual({ times: [0.312, 0.938], strengths: [0.877, 1] });
+ });
+});
diff --git a/packages/studio/package.json b/packages/studio/package.json
index 38b758796a..b8322bec62 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -109,7 +109,6 @@
"@mcp-b/global": "^5.0.1",
"@phosphor-icons/react": "^2.1.10",
"@tanstack/react-virtual": "^3.14.13",
- "bpm-detective": "^2.0.5",
"cn": "0.2.4",
"dockview-react": "8.3.1",
"gsap": "^3.13.0",
diff --git a/packages/studio/tsup.config.ts b/packages/studio/tsup.config.ts
index ea45a7745d..e9d54eca40 100644
--- a/packages/studio/tsup.config.ts
+++ b/packages/studio/tsup.config.ts
@@ -28,7 +28,6 @@ export default defineConfig({
"@hyperframes/sdk",
"@lezer/highlight",
"@phosphor-icons/react",
- "bpm-detective",
"mediabunny",
"react",
"react-dom",
diff --git a/packages/studio/vite.config.ts b/packages/studio/vite.config.ts
index e8a0eca911..00af9240d5 100644
--- a/packages/studio/vite.config.ts
+++ b/packages/studio/vite.config.ts
@@ -336,9 +336,6 @@ export default defineConfig({
plugins: [stableStylesCssPlugin()],
},
},
- optimizeDeps: {
- include: ["bpm-detective"],
- },
server: {
port: 5190,
watch: {
diff --git a/scripts/check-no-main-deletions.mjs b/scripts/check-no-main-deletions.mjs
index b094ce9c52..4839fbc75b 100644
--- a/scripts/check-no-main-deletions.mjs
+++ b/scripts/check-no-main-deletions.mjs
@@ -52,6 +52,14 @@ const INSPECTOR_TOOLS_REASON =
"the inspector ships the capability, not agent tools; each harness defines its own tool names, descriptions and schemas";
export const ALLOWED_DELETIONS = new Map([
+ [
+ "packages/cli/src/beats/headlessAnalyzer.ts",
+ "the TypeScript beat tracker replaces the Chrome analyzer; the beats command decodes with ffmpeg directly",
+ ],
+ [
+ "packages/cli/scripts/build-beat-analyzer.mjs",
+ "the TypeScript beat tracker needs no browser bundle; its build step and only consumer are removed together",
+ ],
["packages/inspector/src/mcp.ts", INSPECTOR_TOOLS_REASON],
["packages/inspector/src/outputSchemas.ts", INSPECTOR_TOOLS_REASON],
["packages/inspector/src/tools.ts", INSPECTOR_TOOLS_REASON],
diff --git a/scripts/check-no-main-deletions.test.mjs b/scripts/check-no-main-deletions.test.mjs
index 6b9d738f28..7682b97cf2 100644
--- a/scripts/check-no-main-deletions.test.mjs
+++ b/scripts/check-no-main-deletions.test.mjs
@@ -59,3 +59,12 @@ test("the allowlist does not silence an unrelated deletion", () => {
assert.deepEqual(deleted, ["packages/cli/src/something-else.ts"]);
assert.equal(ALLOWED_DELETIONS.has("packages/cli/src/something-else.ts"), false);
});
+
+test("the Chrome beat analyzer removal is explicitly scoped", () => {
+ for (const path of [
+ "packages/cli/src/beats/headlessAnalyzer.ts",
+ "packages/cli/scripts/build-beat-analyzer.mjs",
+ ])
+ assert.match(ALLOWED_DELETIONS.get(path) ?? "", /TypeScript beat tracker/);
+ assert.equal(ALLOWED_DELETIONS.has("packages/core/src/beats/beatDetection.ts"), false);
+});
diff --git a/skills-manifest.json b/skills-manifest.json
index 25ae4ff291..3c12e2af1f 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -30,7 +30,7 @@
"files": 8
},
"hyperframes-cli": {
- "hash": "a2f100fa1e0c2db6",
+ "hash": "f08c429fb0f8b82c",
"files": 11
},
"hyperframes-core": {
diff --git a/skills/hyperframes-cli/references/beats.md b/skills/hyperframes-cli/references/beats.md
index da3c05f507..3465f72abf 100644
--- a/skills/hyperframes-cli/references/beats.md
+++ b/skills/hyperframes-cli/references/beats.md
@@ -8,12 +8,8 @@ npx hyperframes beats ./my-video
npx hyperframes beats ./my-video --json
```
-The project must contain a local music `<audio>` source. Mark it with `data-timeline-role="music"`; an id containing `music`, `bgm`, or `soundtrack` is also recognized. The command analyzes that file in headless Chrome and writes `beats/<audio-relative-path>.json`.
+The project must contain a local music `<audio>` source. Mark it with `data-timeline-role="music"`; an id containing `music`, `bgm`, or `soundtrack` is also recognized. The command decodes that file with ffmpeg, tracks its beats, and writes `beats/<audio-relative-path>.json`.
-If no beats are detected, the command fails and writes nothing. If Chrome is unavailable, run:
-
-```bash
-npx hyperframes browser ensure
-```
+If the track has no steady beat, the command fails and writes nothing. If ffmpeg is missing, run `npx hyperframes doctor`.
For a complete beat-synced video, route through `/music-to-video`. That workflow owns a different audio-driven pipeline and its `audiomap.json`; do not replace its analyzer with this Studio utility.