@homie-rocks/studio 0.48.4 → 0.50.0

package/guides/music/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: music
+description: Make songs, themes and game scores for a Homie studio with ElevenLabs Music, through the creator's OWN ElevenLabs account — a composition plan for anything sung, a transcription check that every line is actually sung, mastering to a loudness target, seamless loops and stems for games — then a song page on the studio's site. It tells the person the plan, the rights and the credit cost before anything is rendered, and never spends past the budget they set. Use when someone in a studio asks for a song, a theme song, a jingle, background music, a game score, loops or stems.
+compatibility: Node 22 and ffmpeg. ElevenLabs' own CLI (elevenlabs, signed in with elevenlabs auth login) or ELEVENLABS_API_KEY, on the creator's own ElevenLabs account.
+metadata:
+  providers: elevenlabs
+---
+
+# Music for a studio
+
+A studio is the folder with `studio.json` (the `studio-setup` skill makes one). Songs live in
+`music/<slug>/`, listed in `music/manifest.json`; a published entry is a page at
+`/music/<slug>/` on the studio's own site. Everything below runs through one script in this
+skill's folder: `scripts/music.mjs` (in Claude Code:
+`node "${CLAUDE_PLUGIN_ROOT}/skills/music/scripts/music.mjs" <command>`; elsewhere, the path next
+to this file). Run it from inside the studio. It needs Node 22 and ffmpeg. Every command takes
+`--json`.
+
+Finish in this turn: a render is one call that usually returns in a minute or two. Only stop early to
+ask the person something (the go-ahead on the cost, a budget, an install).
+
+## 1. The provider, only now
+
+A studio that never makes music is never asked about ElevenLabs. **Free first:** sound effects, a
+chiptune or synth theme, a game score from chords and patterns, loops and stems that cost nothing and
+need no account are the `sound` skill (synthesized on this computer). Use this skill for sung songs and
+produced music from a model, when the person wants that and has (or will make) an ElevenLabs account.
+Check when this skill starts:
+
+```sh
+node <music.mjs> check
+```
+
+It reports the road (the `elevenlabs` CLI signed in, or `ELEVENLABS_API_KEY` in the
+environment), the plan, the credits left and when they reset, whether the account can go over,
+the rights that plan gives, ffmpeg, and whether the studio's site has song pages.
+
+Not connected? Offer ElevenLabs' own tools, never a copy of anyone's key or code:
+
+- **The official CLI** (what this skill uses for music): `brew install elevenlabs/tap/elevenlabs`
+  (or `npm install -g @elevenlabs/cli`), then `elevenlabs auth login`. It opens ElevenLabs in the
+  browser; the person signs in once and the sign-in stays in the OS keychain. Nobody pastes a key.
+  Install the CLI yourself as part of the requested music work. An older CLI works; `brew upgrade elevenlabs` keeps it current
+  (1.4.0 on 2026-09-25).
+- An existing API key in the environment still works, but never send a new person to find or set one.
+  Use the browser sign-in above.
+- **ElevenLabs' plugin** for Claude Code (`/plugin marketplace add elevenlabs/plugin`, then
+  `/plugin install elevenlabs@elevenlabs`; in Codex `codex plugin marketplace add elevenlabs/plugin`)
+  brings their own skills and their hosted MCP (`https://api.elevenlabs.io/v1/mcp`, signed in on
+  ElevenLabs' page: speech, voices, transcription, agents). Their skills alone: `npx skills add
+  elevenlabs/skills`. It is optional here, and their MCP has no music tools: songs, stems and the
+  lyric check go through this skill's script, which keeps the budget, the receipts and the rights.
+  Their speech and sound-effect tools spend the same credits: tell the person the cost first, and the
+  Homie mod (Claude Code) and Homie's hooks (Codex) hold a generating tool (an `estimate_only` call is free).
+
+Prefer the CLI to a raw API call or a pasted key; never call ElevenLabs' API with `curl` for a song
+(the same request twice is twice the bill, and nothing records it).
+
+No ffmpeg: offer `brew install ffmpeg` (macOS) or the system package; the person approves.
+
+## 2. Say the plan and the rights, plainly, before anything is made
+
+From `check`, tell the person in two or three lines: the plan (tier), the credits left, and what
+the plan allows. ElevenLabs' terms: **the free plan has no commercial licence** (no ads, sales or
+monetised channels, and published copies credit "Eleven Music"); **paid plans include a
+commercial licence** (not for Beta features) under their Terms and Prohibited Use Policy. The plan
+**at render time** is what counts, and every render records it. Details:
+`references/RIGHTS.md`.
+
+## 3. Write the song
+
+Write `music/<slug>/spec.json` (shape and a full example: `references/COMPOSITION.md`): tempo,
+key, global styles and what to avoid, and sections in whole bars, each either instrumental or
+with its sung lines. Then:
+
+```sh
+node <music.mjs> plan <slug> --spec music/<slug>/spec.json
+```
+
+It builds the composition plan (every section a whole number of bars, so section starts are bar
+lines that loops and video cuts can land on), checks ElevenLabs' limits (each section 3 s to
+120 s, lines up to 200 characters) and quotes the cost.
+
+- **Anything sung goes through the plan's sections.** A prompt with lyrics beside it has come
+  back with nothing sung; `render --prompt` refuses words for that reason.
+- A theme or a song: the hook inside the first 10 seconds, one or two sung lines per bar at
+  most, simple words that sing clearly.
+- A game score: instrumental, a steady tempo, sections of 4, 8 or 16 bars that can each loop.
+- Describe sound, not artists: no "in the style of" a real singer or band, no real person's name
+  or voice (ElevenLabs refuses them, and they are not ours to use).
+
+## 4. Price it, get the go-ahead, render once
+
+```sh
+node <music.mjs> quote --seconds <s> [--vocals] [--budget <credits>]
+```
+
+About **27.5 credits per second** of `music_v2` (measured on a paid account; every render then
+records what it really cost, read off the account before and after). Tell the person the cost and
+ask for the go-ahead and a cap. Then:
+
+```sh
+node <music.mjs> budget <slug> --cap <credits they agreed to>
+node <music.mjs> render <slug> --dry-run      # free: the CLI validates the request and sends nothing
+node <music.mjs> render <slug> --yes          # the one paid render
+```
+
+- `render` refuses with no budget, refuses anything that would pass the cap, and asks again
+  without `--yes`. If the ask costs more than the cap, say so and offer what fits: the longest
+  length within it (`quote --budget` works it out), or a shorter section that loops honestly to
+  length (a loop, called a loop). Never raise a cap yourself.
+- ElevenLabs' balance can take a minute to show a render (measured: unchanged right after,
+  +445 a minute later). `render` waits up to 40 s for it; if it has not moved, the quote is
+  counted against the cap and the receipt is marked pending. `node <music.mjs> reconcile <slug>`
+  a minute later writes the real number. Never report a pending cost as zero.
+- Never re-send a failed render on your own: the same request twice is twice the bill. A render
+  that was sent and never answered leaves `work/render-<n>.pending`; the script refuses to send
+  again until the person has looked at their ElevenLabs history and agrees (`--again`).
+- Never buy credits, never change the plan, never turn on usage-based billing.
+
+## 5. Check that every line is sung
+
+```sh
+node <music.mjs> lyrics <slug>
+```
+
+ElevenLabs' own speech-to-text (Scribe) listens to the render, and every planned line is
+matched against what it heard, in order. A line passes at 75 % of its words (sung contractions
+drift: "I'll" comes back "I"). A **MISS** is a line the model did not sing, or sang as something
+else. Tell the person; the fix is a simpler line (the key word on a strong beat, fewer syllables)
+and another paid render, which needs their go-ahead. Update the lyrics shown on the page to what
+is actually sung.
+
+## 6. Master it
+
+```sh
+node <music.mjs> master <slug>                       # -14 LUFS integrated, -1 dBTP: the web and streaming
+node <music.mjs> master <slug> --lufs -18 --tp -1.5   # a bed under game sound effects
+node <music.mjs> analyze music/<slug>/<slug>.mp3      # duration, loudness, tempo, first beat
+```
+
+Two-pass loudness, then a limiter, measured after on both the WAV master (kept off the site) and
+the mp3 the page plays. Listen-worthy numbers go in your report, not adjectives.
+
+## 7. Loops and stems for games
+
+```sh
+node <music.mjs> loop <slug> --bars 8 --from-bar 4    # a seamless loop cut on bar lines, WAV + OGG
+node <music.mjs> stems <slug> --yes                   # paid, priced by measurement; ask first
+```
+
+The loop is cut at the song's measured bar lines, the tail crossfaded into the head, and checked:
+the jump at the wrap against the music's own sample steps, and the beat grid of the loop played
+three times. Never ship a loop as mp3 (encoders pad the ends with silence). Using loops in a
+game: `references/GAME-AUDIO.md`.
+
+## 8. The page
+
+```sh
+node <music.mjs> add <slug> --title "<Title>" --blurb "<one line>" [--for-game <game id>] --publish
+node <music.mjs> publish <slug>
+```
+
+`add` writes the manifest entry from what is in `music/<slug>/` (the mp3 the page plays, the
+master kept off the site, loops and stems offered for download, the lyrics, the plan and rights
+at render time, the credits line). `publish` rebuilds and redeploys the site and checks the
+page answers 200 and the audio answers a byte range. Without storage the site serves the song
+itself (a song is a few MB; the limit is 25 MiB a file). A studio that has storage (`storage add`)
+keeps its big media in its own R2: the deploy uploads the song (over 1 MiB, or left out of git),
+reads it back, checks it by SHA-256 and serves it from R2 at the same address. If the studio is
+not online yet, use the `publish` skill first. If `check` says the studio's `@homie-rocks/studio`
+predates song pages, say so and update it.
+
+## 9. Tell the person
+
+Four or five lines: the page link, the length, the credits it cost (measured) and what is left,
+the plan and whether it may be used commercially, the lyric check result, the loudness. Commit
+`music/` in the studio (the big audio files stay out of git by the studio's `.gitignore`; the
+manifest, spec, plan and receipts go in).
+
+## Never
+
+- Never print, paste or store a key; never ask for one in chat.
+- Never render without the person's go-ahead on the cost, and never past their cap.
+- Never claim rights the plan did not give, and never drop the "Eleven Music" credit on a
+  free-plan render.
+- Never imitate a real artist, voice or person.
+
+### Existing provider credentials
+
+The tools read `FAL_KEY` or `ELEVENLABS_API_KEY` first, then the plain single-line
+key in `~/.homie/keys/fal-key` or `~/.homie/keys/elevenlabs-key`. They also accept
+`~/.homie/workspace/fal-key` and `~/.homie/workspace/elevenlabs-key` from earlier
+installs. Checks name the source, never the key. Keep these files private (mode
+0600); never copy them into a studio. ElevenLabs also accepts its CLI browser
+sign-in and the existing Stripe Projects connection. Run the tool’s `check`
+before declaring a provider disconnected.

package/guides/music/references/COMPOSITION.md

@@ -0,0 +1,59 @@
+# Composition plans
+
+ElevenLabs Music (`music_v2`) takes either a short prompt or a **composition plan**: a list of
+chunks, each with its own length, text, and styles. Anything with words goes through a plan.
+
+## The spec `plan` reads
+
+```json
+{
+  "title": "Paper Lanterns",
+  "bpm": 118,
+  "key": "D minor",
+  "beatsPerBar": 4,
+  "styles": ["bright indie synth-pop", "punchy live drums", "warm female lead vocal, clear diction, close to the mic", "big hook"],
+  "avoid": ["rap", "heavy autotune", "spoken word"],
+  "sections": [
+    { "name": "Intro", "bars": 4, "instrumental": true, "styles": ["filtered arpeggio, no drums yet"] },
+    { "name": "Hook", "bars": 8, "lines": ["We light the paper lanterns", "and let the whole night see"], "styles": ["full drums", "stacked harmonies"] },
+    { "name": "Verse", "bars": 8, "lines": ["Ten more minutes on the rooftop", "the city humming under me", "every window is a story", "and none of them are asleep"] },
+    { "name": "Outro", "bars": 4, "instrumental": true, "styles": ["drums fall away", "ends on a held chord"] }
+  ]
+}
+```
+
+What `plan` does with it:
+
+- **Whole bars.** A section of `bars` bars at `bpm` lasts `bars × beatsPerBar × 60 / bpm`
+  seconds; the boundaries are rounded to the millisecond so the total is exact. For `music_v2`
+  ElevenLabs holds every section to its length, so section starts are bar lines in the render.
+- **Limits.** Each section 3 s to 120 s (at 120 BPM a bar is 2 s, so the shortest section is 2
+  bars); the whole song 3 s to 10 min; a line up to 200 characters.
+- **Styles.** The first chunk carries the global styles, the tempo and the key (they set the whole
+  song); every later chunk repeats the tempo and adds its own. `avoid` becomes each chunk's
+  negative styles; an instrumental section also avoids vocals and says `{instrumental, no vocals}`
+  in its text (text in curly braces is a direction, not a lyric).
+- **Lines.** A sung section's text is `[Name]` and its lines. About one line a bar at pop tempos,
+  two at most; more comes back rushed or skipped.
+
+## Traps, measured
+
+- **A prompt with `lyrics_text` has come back with nothing sung.** Words go in the plan's
+  sections. `render --prompt` refuses words for this reason.
+- **`output_format` is a query option, not a body field.** Put in the JSON body it is rejected
+  before anything is sent. The script passes `--output-format mp3_48000_192`.
+- **Short hooks drift.** In one render a three-word hook came back as a different three words;
+  making the key word unambiguous (and on a strong beat) fixed it in the next render. The lyric
+  check (Scribe) is what catches this, not listening once.
+- **Contractions drift.** "I'll wake up" came back "I wake up": the check passes lines at 75 % of
+  their words, and the page should show what is actually sung.
+- **The cost is about 27.5 credits per second** of `music_v2` on a paid plan (1,015 credits for
+  37 s and 5,204 for 189 s, measured). The quote uses this; the render records the real number off
+  the account.
+
+## What a render leaves
+
+`music/<slug>/work/render-<n>.mp3` (the audio as rendered), `render-<n>.json` (the plan
+ElevenLabs used, song metadata, and word timestamps: the model's own times for every sung
+word, which the `video` skill uses for lyric type), `music/<slug>/render.json` (the latest),
+`budget.json` (the cap and every call), and a line in `music/receipts.jsonl`.

package/guides/music/references/GAME-AUDIO.md

@@ -0,0 +1,50 @@
+# Music in a game
+
+## Loops
+
+`music.mjs loop <slug> --bars <n> --from-bar <k>` cuts `n` bars starting at bar `k` of the
+mastered song, on the song's measured bar lines, and makes the wrap seamless: the music that
+would follow the loop's last sample is crossfaded (30 ms, equal power) into its first. It writes a
+16-bit WAV (exact length everywhere) and an Ogg (Vorbis, or Opus where ffmpeg has no Vorbis
+encoder; smaller). Both decode to exactly `bars × beats × 60 / bpm` seconds.
+
+Play it in WebAudio, never with an `<audio loop>` element (it gaps on the wrap):
+
+```js
+const ctx = new AudioContext();
+const buf = await ctx.decodeAudioData(await (await fetch('/music/theme/theme-loop-8bars.wav')).arrayBuffer());
+const src = ctx.createBufferSource();
+src.buffer = buf;
+src.loop = true;           // loopStart 0 and loopEnd 0 mean the whole buffer
+const gain = ctx.createGain();
+gain.gain.value = 0.6;     // under the game's own sound effects
+src.connect(gain).connect(ctx.destination);
+src.start();               // after the player's first tap or key: browsers need a gesture
+```
+
+- **Never an mp3 for a loop.** mp3 encoders add silence at both ends; the wrap clicks or gaps.
+- Test the Ogg on an iPhone before relying on it; the WAV plays everywhere.
+- To change intensity with the game (calm, chase, final seconds), make the song in sections of
+  the same tempo and key, loop each, and crossfade between loops on a bar line: the next bar
+  starts at `start + ceil((ctx.currentTime - start) / bar) * bar`.
+
+## Levels
+
+- A menu or title theme: master to -14 LUFS.
+- A bed under gameplay sound effects: -18 to -20 LUFS (`master --lufs -18 --tp -1.5`), so hits
+  and pickups stay on top without the game turning its own sounds up.
+- Stingers (a win, a round starting): a separate short instrumental render (3 to 5 s) at the
+  same tempo and key as the bed.
+
+## Stems
+
+`music.mjs stems <slug> --yes` asks ElevenLabs to split the master into stems (vocals, drums,
+bass, other). It is paid and its price is measured off the account, so it needs the person's
+go-ahead and fits inside the song's budget. Stems let a game drop the vocals under dialogue or
+bring the drums in when the action starts.
+
+## The page
+
+A song entry with `--for-game <id>` is a score: its page links the game, and its loops and stems
+are listed for download so another studio's game can use them (under the song's licence: say
+what it is in `credits`).

package/guides/music/references/RIGHTS.md

@@ -0,0 +1,43 @@
+# Plans, rights and receipts
+
+## What ElevenLabs allows (read 2026-09-29)
+
+From ElevenLabs' help centre, "Can I publish the content I generate on the platform?":
+
+- **Free plan:** no commercial licence. Nothing made on it may be used commercially (ads, sales,
+  monetised channels, a paid game). If it is published at all, it credits ElevenLabs by naming
+  "Eleven Music".
+- **Paid plans (Starter and up):** a commercial licence is included, except for Beta services,
+  provided the person has the rights to what they put in (their lyrics, their references) and
+  follows the Terms of Service and the Prohibited Use Policy.
+
+Terms change: when a person is about to publish commercially, read the current page
+(https://help.elevenlabs.io/hc/en-us/articles/13313564601361) and say what it says today.
+
+## The plan at render time is what counts
+
+`render` reads the plan before it sends anything and writes it into the render's receipt and
+into the manifest entry (`rights.plan`, `rights.commercial`, `rights.attribution`). The song page
+shows it in plain words. A render made on the free plan stays under free-plan terms after an
+upgrade: to use it commercially, render it again on the paid plan.
+
+## What never goes in
+
+- A real person's name, voice or likeness, or "in the style of" a real artist.
+- Lyrics the person does not have the rights to (someone else's song).
+- A key, token or password, anywhere in the studio.
+
+## Receipts
+
+Every paid call leaves three records:
+
+- `music/<slug>/budget.json`: the cap the person agreed to, who agreed, and every call with its
+  cost;
+- `music/receipts.jsonl`: one line per call (provider, model, the song id, credits quoted and
+  measured, the plan and rights, the file it made);
+- optionally a team ledger: set `HOMIE_SPEND_LEDGER=<file>` (and `HOMIE_SPEND_ATTRIBUTION`) and
+  each call is also appended there.
+
+Credits are measured off the account (used before and after the call). Another job spending on
+the same account at the same moment shows up in that number; the receipt keeps the quote beside
+it.

package/guides/music/scripts/lib/audio.mjs

@@ -0,0 +1,258 @@
+/**
+ * Audio facts measured off the file, with ffmpeg doing the decoding and plain
+ * JavaScript doing the arithmetic (no Python, no native add-ons): loudness, an
+ * onset envelope, a beat grid, the lag between two recordings.
+ */
+import { spawnSync } from 'node:child_process';
+
+export function run(cmd, args, { input, maxBuffer = 1024 * 1024 * 1024, timeout = 10 * 60_000 } = {}) {
+  const r = spawnSync(cmd, args, { input: typeof input === 'string' ? Buffer.from(input) : input, maxBuffer, timeout });
+  if (r.error) throw new Error(`${cmd} could not run: ${r.error.message}`);
+  return { code: r.status ?? 1, stdout: r.stdout ?? Buffer.alloc(0), stderr: (r.stderr ?? Buffer.alloc(0)).toString('utf8') };
+}
+
+export function need(cmd) {
+  const r = spawnSync(cmd, ['-version'], { encoding: 'utf8' });
+  return !r.error && r.status === 0;
+}
+
+/** Container and stream facts: duration (s), audio rate/channels, video size/fps/frames. */
+export function probe(file) {
+  const r = run('ffprobe', ['-v', 'error', '-show_entries', 'format=duration:stream=codec_type,codec_name,sample_rate,channels,width,height,r_frame_rate,nb_frames', '-of', 'json', file]);
+  if (r.code !== 0) throw new Error(`ffprobe could not read ${file}: ${r.stderr.trim().split('\n').pop()}`);
+  const j = JSON.parse(r.stdout.toString('utf8'));
+  const a = (j.streams ?? []).find((s) => s.codec_type === 'audio');
+  const v = (j.streams ?? []).find((s) => s.codec_type === 'video');
+  const [fn, fd] = String(v?.r_frame_rate ?? '0/1').split('/').map(Number);
+  return {
+    duration: Number(j.format?.duration ?? NaN),
+    audio: a ? { codec: a.codec_name, rate: Number(a.sample_rate), channels: Number(a.channels) } : null,
+    video: v ? { codec: v.codec_name, width: v.width, height: v.height, fps: fd ? fn / fd : null, frames: v.nb_frames ? Number(v.nb_frames) : null } : null,
+  };
+}
+
+/** Mono float samples at `rate` (optionally a window and a filter chain). */
+export function decodeMono(file, { rate = 22050, start = null, duration = null, filter = null } = {}) {
+  const args = ['-hide_banner', '-loglevel', 'error'];
+  if (start !== null) args.push('-ss', String(start));
+  if (duration !== null) args.push('-t', String(duration));
+  args.push('-i', file, '-vn', '-ac', '1', '-ar', String(rate));
+  if (filter) args.push('-af', filter);
+  args.push('-f', 'f32le', '-');
+  const r = run('ffmpeg', args);
+  if (r.code !== 0) throw new Error(`ffmpeg could not decode ${file}: ${r.stderr.trim().split('\n').pop()}`);
+  const b = r.stdout;
+  return new Float32Array(b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength - (b.byteLength % 4)));
+}
+
+/** EBU R128: integrated loudness (LUFS), loudness range (LU) and true peak (dBTP). */
+export function loudness(file) {
+  const r = run('ffmpeg', ['-hide_banner', '-nostats', '-i', file, '-af', 'ebur128=peak=true', '-f', 'null', '-']);
+  const text = r.stderr;
+  const sum = text.slice(text.lastIndexOf('Summary:'));
+  const num = (re) => { const m = re.exec(sum); return m ? Number(m[1]) : null; };
+  return { lufs: num(/I:\s+(-?[\d.]+|-inf) LUFS/), lra: num(/LRA:\s+(-?[\d.]+) LU/), truePeak: num(/Peak:\s+(-?[\d.]+|-inf) dBFS/) };
+}
+
+/* ---------------------------------------------------------------- FFT */
+
+/** In-place radix-2 FFT (re, im of a power-of-two length). */
+export function fft(re, im, inverse = false) {
+  const n = re.length;
+  for (let i = 1, j = 0; i < n; i++) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    if (i < j) { [re[i], re[j]] = [re[j], re[i]]; [im[i], im[j]] = [im[j], im[i]]; }
+  }
+  for (let len = 2; len <= n; len <<= 1) {
+    const ang = (2 * Math.PI / len) * (inverse ? 1 : -1);
+    const wr = Math.cos(ang); const wi = Math.sin(ang);
+    for (let i = 0; i < n; i += len) {
+      let cr = 1; let ci = 0;
+      for (let k = 0; k < len / 2; k++) {
+        const ar = re[i + k]; const ai = im[i + k];
+        const br = re[i + k + len / 2] * cr - im[i + k + len / 2] * ci;
+        const bi = re[i + k + len / 2] * ci + im[i + k + len / 2] * cr;
+        re[i + k] = ar + br; im[i + k] = ai + bi;
+        re[i + k + len / 2] = ar - br; im[i + k + len / 2] = ai - bi;
+        const t = cr * wr - ci * wi; ci = cr * wi + ci * wr; cr = t;
+      }
+    }
+  }
+  if (inverse) for (let i = 0; i < n; i++) { re[i] /= n; im[i] /= n; }
+}
+
+const pow2 = (n) => 1 << Math.ceil(Math.log2(Math.max(2, n)));
+
+/**
+ * Spectral-flux onset envelope: log-magnitude rises summed over a band, the
+ * slow trend removed. Returns { env, rate } (envelope values per second).
+ */
+export function onsetEnvelope(x, sr, { hop = 256, nfft = 1024, lo = 30, hi = 8000 } = {}) {
+  const frames = Math.max(0, 1 + Math.floor((x.length - nfft) / hop));
+  const win = new Float32Array(nfft).map((_, i) => 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / nfft));
+  const kLo = Math.max(1, Math.floor((lo * nfft) / sr)); const kHi = Math.min(nfft / 2, Math.ceil((hi * nfft) / sr));
+  const env = new Float32Array(frames);
+  let prev = new Float32Array(kHi - kLo + 1);
+  const re = new Float64Array(nfft); const im = new Float64Array(nfft);
+  for (let f = 0; f < frames; f++) {
+    for (let i = 0; i < nfft; i++) { re[i] = x[f * hop + i] * win[i]; im[i] = 0; }
+    fft(re, im);
+    const cur = new Float32Array(kHi - kLo + 1);
+    let flux = 0;
+    for (let k = kLo; k <= kHi; k++) {
+      const m = Math.log1p(20 * Math.hypot(re[k], im[k]));
+      cur[k - kLo] = m;
+      if (f > 0) flux += Math.max(0, m - prev[k - kLo]);
+    }
+    env[f] = flux; prev = cur;
+  }
+  // Frame f describes the window centred at (f * hop + nfft / 2) samples.
+  // Remove a half-second moving average so sustained loud passages don't read as onsets.
+  const rate = sr / hop; const w = Math.max(1, Math.round(rate / 2));
+  const out = new Float32Array(frames);
+  let acc = 0;
+  for (let i = 0; i < frames; i++) {
+    acc += env[i]; if (i >= w) acc -= env[i - w];
+    const mean = acc / Math.min(i + 1, w);
+    out[i] = Math.max(0, env[i] - mean);
+  }
+  return { env: out, rate, offset: nfft / 2 / sr };
+}
+
+/**
+ * A sharper onset envelope for WHERE the hits are (spectral flux is steadier for
+ * HOW FAST they come): the rise of log energy in short windows, centred.
+ */
+export function energyOnsets(x, sr, { win = 0.012, hop = 0.004 } = {}) {
+  const w = Math.max(8, Math.round(win * sr)); const h = Math.max(1, Math.round(hop * sr));
+  const frames = Math.max(0, 1 + Math.floor((x.length - w) / h));
+  const e = new Float32Array(frames);
+  for (let f = 0; f < frames; f++) {
+    let s = 0; for (let i = f * h; i < f * h + w; i++) s += x[i] * x[i];
+    e[f] = Math.log10(s / w + 1e-10);
+  }
+  const env = new Float32Array(frames);
+  for (let f = 1; f < frames; f++) env[f] = Math.max(0, e[f] - e[f - 1]);
+  // Credit the rise to the window it completes in: the hit sits near the newer window's centre.
+  return { env, rate: sr / h, offset: w / 2 / sr };
+}
+
+/**
+ * A beat grid off an onset envelope: tempo by autocorrelation (or a given
+ * `bpm`), phase by summing the envelope on a comb. Confidence is how far the
+ * best comb stands above the average one (1 = no preference, 2+ = clear).
+ */
+export function beatGrid(env, rate, { bpm = null, lo = 70, hi = 180, from = 0, to = null, offset = 0 } = {}) {
+  const n = env.length;
+  const end = to === null ? n / rate + offset : to;
+  const at = (t) => Math.round((t - offset) * rate);
+  const comb = (period, ph) => {
+    let sum = 0; let count = 0;
+    for (let t = from + ph; t < end; t += period) {
+      const i = at(t);
+      if (i >= 0 && i < n) { sum += env[i] + 0.5 * ((env[i - 1] ?? 0) + (env[i + 1] ?? 0)); count++; }
+    }
+    return count ? sum / count : 0;
+  };
+  let period;
+  if (!bpm) {
+    const minLag = Math.floor((60 / hi) * rate); const maxLag = Math.ceil((60 / lo) * rate);
+    let best = -Infinity; let bestLag = minLag;
+    const mean = env.reduce((a, b) => a + b, 0) / Math.max(1, n);
+    for (let lag = minLag; lag <= Math.min(maxLag, n - 1); lag++) {
+      let s = 0;
+      for (let i = 0; i + lag < n; i++) s += (env[i] - mean) * (env[i + lag] - mean);
+      const bpmHere = 60 / (lag / rate);
+      const prior = Math.exp(-0.5 * (Math.log2(bpmHere / 120) / 1.0) ** 2); // octave errors lean toward ~120
+      const score = s * (0.6 + 0.4 * prior);
+      if (score > best) { best = score; bestLag = lag; }
+    }
+    // The integer lag is coarse (one envelope frame); settle the period on the comb itself, within that frame.
+    let bestP = bestLag / rate; let bestScore = -Infinity;
+    for (let k = -20; k <= 20; k++) {
+      const p = (bestLag + k / 20) / rate;
+      let top = 0;
+      for (let s = 0; s < 48; s++) top = Math.max(top, comb(p, (s / 48) * p));
+      if (top > bestScore) { bestScore = top; bestP = p; }
+    }
+    period = bestP;
+    bpm = 60 / period;
+  } else period = 60 / bpm;
+  const steps = 96; let bestPhase = 0; let bestSum = -Infinity; let total = 0;
+  for (let s = 0; s < steps; s++) {
+    const ph = (s / steps) * period;
+    const v = comb(period, ph);
+    total += v;
+    if (v > bestSum) { bestSum = v; bestPhase = ph; }
+  }
+  const avg = total / steps;
+  const beats = [];
+  for (let t = from + bestPhase; t < end; t += period) beats.push(+t.toFixed(4));
+  return { bpm: +bpm.toFixed(3), period, phase: from + bestPhase, beats, confidence: +(bestSum / (avg || 1)).toFixed(2) };
+}
+
+/** The beat grid of a file, with an optional low band (the kick) to settle half-beat ambiguity. */
+export function beatsOf(file, { bpm = null, kick = true, start = null, duration = null } = {}) {
+  const sr = 22050;
+  const x = decodeMono(file, { rate: sr, start, duration });
+  // Tempo off spectral flux (steady); phase off short-window energy rises (sharp), full band and the kick band.
+  const full = onsetEnvelope(x, sr);
+  const tempo = beatGrid(full.env, full.rate, { bpm, offset: full.offset });
+  // Music made to a stated tempo is almost always a whole number of BPM: a measurement within 0.15 of one is that number.
+  if (!bpm && Math.abs(tempo.bpm - Math.round(tempo.bpm)) < 0.15) tempo.bpm = Math.round(tempo.bpm);
+  const sharp = energyOnsets(x, sr);
+  const grid = beatGrid(sharp.env, sharp.rate, { bpm: tempo.bpm, offset: sharp.offset });
+  if (!kick) return { ...grid, tempoConfidence: tempo.confidence, duration: x.length / sr };
+  const lowX = decodeMono(file, { rate: sr, start, duration, filter: 'lowpass=f=160,lowpass=f=160' });
+  const low = energyOnsets(lowX, sr, { win: 0.02, hop: 0.004 });
+  const kg = beatGrid(low.env, low.rate, { bpm: tempo.bpm, offset: low.offset });
+  // Prefer the kick's phase when it is clearer than the full-band one (it settles half-beat doubt).
+  const useKick = kg.confidence >= grid.confidence;
+  return { ...(useKick ? kg : grid), tempoConfidence: tempo.confidence, fullConfidence: grid.confidence, kickConfidence: kg.confidence, phaseFrom: useKick ? 'kick' : 'full', duration: x.length / sr };
+}
+
+/**
+ * The lag of `b` against `a` in seconds (positive: b is late), by GCC-PHAT on
+ * band-limited signals, with the peak's height over the median (above ~8 is a
+ * clear answer; a pass-through copy reads 40+).
+ */
+export function lagBetween(a, b, sr, { maxLagS = 0.6 } = {}) {
+  const n = Math.min(a.length, b.length);
+  const N = pow2(2 * n);
+  const ar = new Float64Array(N); const ai = new Float64Array(N); const br = new Float64Array(N); const bi = new Float64Array(N);
+  for (let i = 0; i < n; i++) { ar[i] = a[i]; br[i] = b[i]; }
+  fft(ar, ai); fft(br, bi);
+  const rr = new Float64Array(N); const ri = new Float64Array(N);
+  const kLo = Math.floor((200 * N) / sr); const kHi = Math.ceil((4000 * N) / sr);
+  for (let k = 0; k < N; k++) {
+    const f = k <= N / 2 ? k : N - k;
+    if (f < kLo || f > kHi) continue;
+    // B * conj(A): its peak sits at the lag of b behind a.
+    const xr = br[k] * ar[k] + bi[k] * ai[k]; const xi = bi[k] * ar[k] - br[k] * ai[k];
+    const m = Math.hypot(xr, xi) + 1e-12;
+    rr[k] = xr / m; ri[k] = xi / m;
+  }
+  fft(rr, ri, true);
+  const maxLag = Math.floor(maxLagS * sr);
+  let best = -Infinity; let bestLag = 0; const mags = [];
+  for (let l = -maxLag; l <= maxLag; l++) {
+    const v = rr[(l + N) % N];
+    mags.push(Math.abs(v));
+    if (v > best) { best = v; bestLag = l; }
+  }
+  mags.sort((x, y) => x - y);
+  const median = mags[Math.floor(mags.length / 2)] || 1e-12;
+  return { lagS: bestLag / sr, peak: +(best / median).toFixed(1) };
+}
+
+/** RMS in dBFS over windows of `win` seconds. */
+export function rmsDb(x, sr, win = 0.05) {
+  const w = Math.max(1, Math.round(win * sr)); const out = [];
+  for (let i = 0; i + w <= x.length; i += w) {
+    let s = 0; for (let j = i; j < i + w; j++) s += x[j] * x[j];
+    out.push(10 * Math.log10(s / w + 1e-12));
+  }
+  return out;
+}