Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(cli): beats tracks the music with the TypeScript beat tracker, without Chrome (#5634)
Xuanru Li1544b519a944
diff --git a/bun.lock b/bun.lockindex 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.mdxindex 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 secondsinto the audio; `strength` (0–1) is relative loudness. Beats you add, move, ordelete 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.jsonindex 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.mjsdeleted file mode 100644index 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.tsdeleted file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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: strireturn { 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.tsindex 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.tsindex 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.mjsindex 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.mjsindex 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.jsonindex 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.mdindex 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-videonpx 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.