dsh-hyperframes 0.9.1 → 0.9.3

package/skills/media-use/audio/scripts/lib/tts.cleanup.test.mjs

@@ -0,0 +1,175 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const ttsUrl = new URL("./tts.mjs", import.meta.url).href;
+const stub = `#!${process.execPath}
+const fs = require("node:fs");
+const path = require("node:path");
+const args = process.argv.slice(2);
+if (args[0] === "--version") {
+  console.log("Python 3.12.0");
+  process.exit(0);
+}
+const input = args[2];
+const output = args[0] === "-c" ? args[4] : args[args.indexOf("--output") + 1];
+const text = fs.readFileSync(input, "utf8");
+fs.writeFileSync(output + ".started", input);
+const finish = () => {
+  if (text === "slow" && !fs.existsSync(process.env.RELEASE_FILE)) {
+    setTimeout(finish, 5);
+    return;
+  }
+  const consumed = fs.readFileSync(input, "utf8");
+  fs.writeFileSync(output + ".json", JSON.stringify({ input, text, consumed, args }));
+  if (process.env.CASE_MODE === "nonzero") process.exit(7);
+  if (process.env.CASE_MODE !== "no-output") fs.writeFileSync(output, consumed);
+};
+setTimeout(finish, 10);
+`;
+
+const exercise = `
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import childProcess from "node:child_process";
+import { syncBuiltinESMExports } from "node:module";
+import { join, dirname } from "node:path";
+const { CASE_ROOT: root, CASE_MODE: mode, CASE_PROVIDER: provider } = process.env;
+const temp = join(root, "tmp");
+const preexisting = join(temp, "hf-txt-preexisting");
+fs.mkdirSync(preexisting);
+fs.writeFileSync(join(preexisting, "marker"), "keep");
+const injected = Object.assign(new Error("synthetic " + mode), { code: "EACCES" });
+const originalMkdtemp = fs.mkdtempSync;
+const originalWrite = fs.writeFileSync;
+const originalRm = fs.rmSync;
+if (mode === "allocation") fs.mkdtempSync = (prefix, ...args) => {
+  if (prefix.startsWith(join(temp, "hf-txt-"))) throw injected;
+  return originalMkdtemp(prefix, ...args);
+};
+if (mode === "write") fs.writeFileSync = (file, ...args) => {
+  if (String(file).endsWith("line.txt")) {
+    originalWrite(file, "partial");
+    throw injected;
+  }
+  return originalWrite(file, ...args);
+};
+if (mode === "spawn-throw") childProcess.spawn = () => { throw injected; };
+if (mode === "cleanup") fs.rmSync = (dir, ...args) => {
+  if (String(dir).startsWith(join(temp, "hf-txt-"))) throw injected;
+  return originalRm(dir, ...args);
+};
+syncBuiltinESMExports();
+const { synthesizeOne } = await import(${JSON.stringify(ttsUrl)});
+const project = join(root, "project");
+const wavAbs = join(project, "line.wav");
+const request = (chosen = provider, text = "synthetic café", output = wavAbs) =>
+  synthesizeOne({ provider: chosen, text, voiceId: "synthetic-voice", lang: "es",
+    speed: 0.8, wavAbs: output, hyperframesDir: project });
+const owned = () => fs.readdirSync(temp).filter(name => name !== "hf-txt-preexisting");
+if (["allocation", "write", "spawn-throw"].includes(mode)) {
+  await assert.rejects(request(), error => error === injected);
+  assert.equal(fs.existsSync(wavAbs), false);
+} else if (mode === "concurrent") {
+  const slowWav = join(project, "slow.wav");
+  const slow = request("elevenlabs", "slow", slowWav);
+  try {
+    const deadline = Date.now() + 5000;
+    while (!fs.existsSync(slowWav + ".started")) {
+      assert.ok(Date.now() < deadline, "slow subprocess must start");
+      await new Promise(resolve => setTimeout(resolve, 5));
+    }
+    const slowInput = fs.readFileSync(slowWav + ".started", "utf8");
+    assert.deepEqual(await request("kokoro"), { ok: true, words: null });
+    assert.deepEqual(owned(), [dirname(slowInput).split(/[\\\\/]/).pop()]);
+    assert.equal(fs.readFileSync(slowInput, "utf8"), "slow");
+  } finally {
+    fs.writeFileSync(process.env.RELEASE_FILE, "release");
+    await slow;
+  }
+  assert.equal(fs.readFileSync(slowWav, "utf8"), "slow");
+} else {
+  const result = await request();
+  const label = provider === "elevenlabs" ? "elevenlabs (python)" : "kokoro (npx hyperframes tts)";
+  if (["nonzero", "enoent", "no-output"].includes(mode)) {
+    const error = mode === "no-output" ? label + " produced no wav file" :
+      label + " exited with status " + (mode === "enoent" ? -1 : 7);
+    assert.deepEqual(result, { ok: false, words: null, error });
+    assert.equal(fs.existsSync(wavAbs), false);
+  } else {
+    assert.deepEqual(result, { ok: true, words: null });
+    assert.equal(fs.readFileSync(wavAbs, "utf8"), "synthetic café");
+  }
+  if (mode !== "enoent") {
+    const log = JSON.parse(fs.readFileSync(wavAbs + ".json", "utf8"));
+    assert.equal(log.text, "synthetic café");
+    assert.equal(log.consumed, log.text);
+    if (provider === "kokoro") assert.deepEqual(log.args.slice(-4), ["--lang", "es", "--speed", "0.8"]);
+  }
+}
+if (mode === "cleanup") assert.equal(owned().length, 1);
+else assert.deepEqual(owned(), [], "owned text directories must be removed");
+assert.equal(fs.readFileSync(join(preexisting, "marker"), "utf8"), "keep");
+`;
+
+function runCase(provider, mode) {
+  const root = mkdtempSync(join(tmpdir(), "tts-cleanup-test-"));
+  try {
+    for (const dir of ["home", "tmp", "bin", "project"]) mkdirSync(join(root, dir));
+    if (mode !== "enoent") {
+      for (const name of ["npx", "python3"]) {
+        const executable = join(root, "bin", name);
+        writeFileSync(executable, stub);
+        chmodSync(executable, 0o755);
+      }
+    }
+    const result = spawnSync(process.execPath, ["--input-type=module", "-e", exercise], {
+      encoding: "utf8",
+      timeout: 15000,
+      env: {
+        HOME: join(root, "home"),
+        USERPROFILE: join(root, "home"),
+        TMPDIR: join(root, "tmp"),
+        TMP: join(root, "tmp"),
+        TEMP: join(root, "tmp"),
+        PATH: join(root, "bin"),
+        CASE_ROOT: root,
+        CASE_PROVIDER: provider,
+        CASE_MODE: mode,
+        RELEASE_FILE: join(root, "release"),
+      },
+    });
+    assert.equal(result.error, undefined);
+    assert.equal(result.status, 0, result.stdout + result.stderr);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const provider of ["elevenlabs", "kokoro"]) {
+  for (const mode of [
+    "success",
+    "nonzero",
+    "no-output",
+    "enoent",
+    "spawn-throw",
+    "allocation",
+    "write",
+    "cleanup",
+  ]) {
+    test(
+      `synthesizeOne(${provider}) preserves ${mode} behavior and cleans only its text directory`,
+      { skip: process.platform === "win32" },
+      () => runCase(provider, mode),
+    );
+  }
+}
+
+test(
+  "concurrent providers retain each other's text until their subprocess finishes",
+  { skip: process.platform === "win32" },
+  () => runCase("kokoro", "concurrent"),
+);

package/skills/media-use/audio/scripts/lib/tts.mjs

@@ -18,7 +18,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { heygenAuthHeaders, heygenCredential, heygenJSON } from "./heygen.mjs";
+import { heygenAuthHeaders, heygenCredential, heygenJSON, heygenMessage } from "./heygen.mjs";
 import { pythonInvocation } from "./python.mjs";
 import { synthesizeGemini } from "./gemini-tts.mjs";
 import { geminiConfigured } from "./gemini-auth.mjs";
@@ -45,10 +45,8 @@ export function pickProvider(userProvider) {
       throw new Error(
         "provider=gemini needs GEMINI_API_KEY or GOOGLE_API_KEY, or service-account credentials (GOOGLE_APPLICATION_CREDENTIALS or GCS_CREDS)",
       );
-    if (userProvider === "heygen" && !heygenAvailable())
-      throw new Error(
-        "provider=heygen but no HeyGen credentials (set $HEYGEN_API_KEY or run `npx hyperframes auth login`)",
-      );
+    // heygenAuthHeaders owns the reason and its fix: no credential, or a credentials path that cannot be read.
+    if (userProvider === "heygen" && !heygenAvailable()) heygenAuthHeaders();
     if (userProvider === "elevenlabs" && !process.env.ELEVENLABS_API_KEY)
       throw new Error("provider=elevenlabs but $ELEVENLABS_API_KEY is not set");
     return userProvider;
@@ -236,7 +234,7 @@ import os, sys
 from elevenlabs.client import ElevenLabs
 from elevenlabs import save
 client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])
-text = open(sys.argv[1]).read()
+text = open(sys.argv[1], encoding="utf-8").read()
 audio = client.text_to_speech.convert(
     text=text, voice_id=sys.argv[2],
     model_id="eleven_multilingual_v2", output_format="mp3_44100_128",
@@ -276,22 +274,21 @@ export async function synthesizeOne({
     } catch {
       return { ok: false, words: null };
     }
-    const { cmd, args } = pythonInvocation([
-      "-c",
-      ELEVENLABS_PY,
-      writeTmpText(text),
-      voiceId,
-      wavAbs,
-    ]);
-    const r = await spawnP(cmd, args, {});
-    return synthResult(r, wavAbs, "elevenlabs (python)");
+    return withTmpText(text, async (textPath) => {
+      const { cmd, args } = pythonInvocation(["-c", ELEVENLABS_PY, textPath, voiceId, wavAbs]);
+      const r = await spawnP(cmd, args, {});
+      return synthResult(r, wavAbs, "elevenlabs (python)");
+    });
   }
   // kokoro — via the published CLI; --output is relative to the project dir.
   const wavRel = relTo(hyperframesDir, wavAbs);
-  const args = ["hyperframes", "tts", writeTmpText(text), "--voice", voiceId, "--output", wavRel];
-  if (lang !== "en") args.push("--lang", lang);
-  const r = await spawnP("npx", args, { cwd: hyperframesDir });
-  return synthResult(r, wavAbs, "kokoro (npx hyperframes tts)");
+  return withTmpText(text, async (textPath) => {
+    const args = ["hyperframes", "tts", textPath, "--voice", voiceId, "--output", wavRel];
+    if (lang !== "en") args.push("--lang", lang);
+    if (speed !== 1) args.push("--speed", String(speed));
+    const r = await spawnP("npx", args, { cwd: hyperframesDir });
+    return synthResult(r, wavAbs, "kokoro (npx hyperframes tts)");
+  });
 }
 
 // Shape a spawn result into { ok, words, error }, naming why on failure so the
@@ -351,7 +348,7 @@ export async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }, d
       : [];
     return { ok: true, words };
   } catch (e) {
-    return { ok: false, words: null, error: e?.message ? String(e.message) : String(e) };
+    return { ok: false, words: null, error: heygenMessage(e) };
   }
 }
 
@@ -379,11 +376,18 @@ export async function transcribeWav({ wavRel, lang = "en", hyperframesDir }) {
 }
 
 // ── tiny local utils ──────────────────────────────────────────────────────────
-function writeTmpText(text) {
+async function withTmpText(text, run) {
   const td = mkdtempSync(join(tmpdir(), "hf-txt-"));
-  const p = join(td, "line.txt");
-  writeFileSync(p, text);
-  return p;
+  try {
+    const p = join(td, "line.txt");
+    writeFileSync(p, text);
+    return await run(p);
+  } finally {
+    // Cleanup must preserve the synthesis result or the original write/spawn error.
+    try {
+      rmSync(td, { recursive: true, force: true });
+    } catch {}
+  }
 }
 function relTo(base, abs) {
   return abs.startsWith(base + "/") ? abs.slice(base.length + 1) : abs;

package/skills/media-use/audio/scripts/lib/tts.test.mjs

@@ -1,6 +1,14 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, chmodSync, rmSync, existsSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  rmSync,
+  existsSync,
+} from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import {
@@ -9,6 +17,7 @@ import {
   synthesizeOne,
   synthesizeHeygen,
   synthResult,
+  pickProvider,
 } from "./tts.mjs";
 
 test("parseFfmpegDurationBanner reads ffmpeg's stderr Duration line", () => {
@@ -155,3 +164,67 @@ test("synthResult names a non-zero subprocess exit", () => {
   assert.equal(res.ok, false);
   assert.match(res.error, /kokoro .* exited with status 2/);
 });
+
+// Kokoro shells out to `npx hyperframes tts`; a fake npx on PATH records the argv
+// synthesizeOne really builds, so a dropped flag fails here. Windows runs npx via
+// node directly, so the stub never resolves there.
+async function kokoroArgv(options) {
+  const dir = mkdtempSync(join(tmpdir(), "tts-kokoro-argv-"));
+  const argvLog = join(dir, "argv.txt");
+  writeFileSync(join(dir, "npx"), `#!/bin/sh\nprintf '%s\\n' "$@" > "${argvLog}"\n`);
+  chmodSync(join(dir, "npx"), 0o755);
+  const originalPath = process.env.PATH;
+  try {
+    process.env.PATH = dir;
+    await synthesizeOne({
+      provider: "kokoro",
+      text: "hi",
+      voiceId: "am_michael",
+      wavAbs: join(dir, "line-0.wav"),
+      hyperframesDir: dir,
+      ...options,
+    });
+    return readFileSync(argvLog, "utf8").trim().split("\n");
+  } finally {
+    process.env.PATH = originalPath;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test(
+  "synthesizeOne(kokoro) forwards a non-default speed to the CLI",
+  { skip: process.platform === "win32" },
+  async () => {
+    const argv = await kokoroArgv({ speed: 0.8, lang: "es" });
+    assert.deepEqual(argv.slice(-4), ["--lang", "es", "--speed", "0.8"]);
+  },
+);
+
+test(
+  "synthesizeOne(kokoro) leaves --speed off at the default",
+  { skip: process.platform === "win32" },
+  async () => {
+    assert.ok(!(await kokoroArgv({})).includes("--speed"));
+  },
+);
+
+test("pickProvider heygen with an unreadable credentials path says to fix that path", () => {
+  const saved = ["HEYGEN_API_KEY", "HYPERFRAMES_API_KEY", "HEYGEN_CONFIG_DIR"].map((k) => [
+    k,
+    process.env[k],
+  ]);
+  const dir = mkdtempSync(join(tmpdir(), "tts-cred-"));
+  try {
+    delete process.env.HEYGEN_API_KEY;
+    delete process.env.HYPERFRAMES_API_KEY;
+    process.env.HEYGEN_CONFIG_DIR = dir;
+    mkdirSync(join(dir, "credentials"));
+    assert.throws(() => pickProvider("heygen"), /fix or remove that path/);
+  } finally {
+    for (const [k, v] of saved) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/skills/media-use/audio/scripts/wait-bgm.mjs

@@ -15,6 +15,7 @@
 
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { recordInManifest } from "./lib/media-record.mjs";
 
 const argv = process.argv.slice(2);
 const flag = (name, def) => {
@@ -132,6 +133,9 @@ while (Date.now() - started <= timeoutMs) {
       message: `BGM ready at ${bgmPath}.`,
     });
     console.log(`✓ bgm: ready (${bgmPath}, ${size}B)`);
+    const generated = { path: bgmPath, type: "bgm", source: "generated", provider: base.provider };
+    for (const anomaly of recordInManifest(hyperframesDir, [generated]))
+      console.error(`  ${anomaly}`);
     process.exit(0);
   }
 

package/skills/media-use/audio/scripts/wait-bgm.test.mjs

@@ -1,5 +1,8 @@
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 import { test } from "node:test";
 import { runInNewContext } from "node:vm";
 
@@ -63,3 +66,43 @@ test("empty log path does not access the filesystem", () => {
     "",
   );
 });
+
+test("records locally made music as generated once it is ready", () => {
+  const dir = mkdtempSync(join(tmpdir(), "mu-wait-bgm-"));
+  try {
+    mkdirSync(join(dir, "assets/bgm"), { recursive: true });
+    writeFileSync(join(dir, "assets/bgm/track.wav"), "generated music");
+    writeFileSync(
+      join(dir, "audio_meta.json"),
+      JSON.stringify({
+        bgm: { path: "assets/bgm/track.wav" },
+        bgm_pending: true,
+        bgm_provider: "musicgen",
+        bgm_mode: "detached-single",
+      }),
+    );
+    const script = new URL("./wait-bgm.mjs", import.meta.url).pathname;
+    const args = ["--audio-meta", join(dir, "audio_meta.json"), "--hyperframes", dir];
+
+    const run = spawnSync(process.execPath, [script, ...args, "--timeout-ms", "1000"], {
+      encoding: "utf8",
+    });
+
+    assert.equal(run.status, 0, run.stderr);
+    const records = readFileSync(join(dir, ".media/manifest.jsonl"), "utf8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    assert.deepEqual(
+      records.map(({ path, type, source, provenance }) => [
+        path,
+        type,
+        source,
+        provenance.provider,
+      ]),
+      [["assets/bgm/track.wav", "bgm", "generated", "musicgen"]],
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/skills/media-use/references/audio.md

@@ -12,9 +12,9 @@ node <SKILL_DIR>/audio/scripts/audio.mjs --request ./audio_request.json --out ./
 - **Request** `{ provider?, voice?, lang?, speed?, tts_model?, style?, lines: [{ id, text, style?, sfx?: [names] }], bgm: { mode?, query?, prompt? } }`: `id` joins each line back to your model; `bgm.mode` = `retrieve | generate | none` (omit for auto). `--only tts,bgm,sfx` runs a subset and merges into an existing `--out`.
 - **Gemini narration** is opt-in with `provider: "gemini"` and an API key or service-account credentials. `tts_model` defaults to `gemini-3.8-flash-tts`; 3.8 Flash-Lite, 3.1 Flash Preview, and 2.5 Pro/Flash Preview TTS are also supported. `style` directs delivery; a line's style overrides the request's style. CLI overrides: `--tts-model`, `--style`. See `audio/references/tts.md` for a complete request. The existing automatic provider order is unchanged.
 - **Output** `audio_meta.json` (id-keyed): `voices[].{path,duration_s,words[]}` (word timestamps for captions), `sfx[]`, `bgm`, `total_duration_s`.
-- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music/SFX retrieval. Local/provider-specific generators are explicit alternatives where installed; run `npx hyperframes media-use resolve --doctor` before assuming retrieval or TTS will work.
+- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music retrieval; SFX come from Openverse with no account (`audio/references/sfx.md`). Local/provider-specific generators are explicit alternatives where installed; run `npx hyperframes media-use resolve --doctor` before assuming retrieval or TTS will work.
 - If BGM took the generate path (`bgm_pending: true`), run `audio/scripts/wait-bgm.mjs` before final render.
 
 Single-shot helpers: `audio/scripts/heygen-tts.mjs` (one voice file). Transcription / background removal / captions use the `hyperframes` CLI (`transcribe`, `remove-background`), see the per-topic guides in `audio/references/` (`tts.md`, `bgm.md`, `sfx.md`, `transcribe.md`, `remove-background.md`, `captions/`).
 
-Transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`).
+Transcription through `scripts/transcribe.mjs` defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster), with whisper.cpp auto-fallback (see `references/operations.md`). `npx hyperframes transcribe` picks its own engine: Parakeet when installed, otherwise whisper with the `small.en` model by default.

package/skills/media-use/references/grading.md

@@ -17,7 +17,7 @@ Stop here and use that treatment workflow for requests such as retro, old home
 video, camcorder, film, print, ASCII, glitch, privacy, or a media reveal. Do not
 assemble those from a generic LUT plus handmade CSS vignette/grain/opacity.
 
-**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered, or `cube-validate.mjs` for a one-line `{ok,size}` check. Read `.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
+**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered. `npx hyperframes media-use resolve --type lut --intent "<look description>" --project .` validates generated or downloaded LUTs before freezing them; the validator is bundled in the CLI, not shipped as a standalone skill script. Read `<project>/.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
 
 ```bash
 npx hyperframes media-use resolve --type grade --intent "warm daylight" --project . --json
@@ -83,8 +83,10 @@ on that same real media element with its registered paused GSAP timeline:
 | `--hf-color-grading-ascii`         | 0 to 1  |
 | `--hf-color-grading-dither`        | 0 to 1  |
 
-Author the initial value directly in the media element's inline `style`, then
-use finite `tl.to()` keyframes. Do not use a frame-zero `tl.set()`, CSS
+Once set (inline, in a stylesheet or on a parent), a property overrides the
+payload's value for that control, so set it only on media you animate: put the
+tween's first value in the element's inline `style`, then use finite `tl.to()`
+keyframes. Leave it unset for a static grade. Do not use a frame-zero `tl.set()`, CSS
 animation clocks, timers, random values, or `onUpdate` callbacks. The static
 `data-color-grading` payload remains the fallback and source of the other
 controls.
@@ -156,5 +158,4 @@ validates generated or downloaded cubes as it freezes them under
 
 ```bash
 npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project . --json
-node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube
 ```

package/skills/media-use/references/local.md

@@ -0,0 +1,24 @@
+# Local media commands
+
+These run on this machine, free, and write into the project.
+
+## Grade and style footage and images
+
+- Measure, then correct: `npx hyperframes media-treatment --selector '#hero' --analyze --json`, then `--grading '<json>' --apply`. `--dry-run` previews; `--clear` removes the treatment.
+- `--file` defaults to `index.html`: for media inside a scene, pass `--file compositions/<scene>.html`.
+- Grain, blur, vignette, presets, palettes: `npx hyperframes media-treatment --capabilities --json`, then `--capability <id>` for one family's controls and ranges.
+- The result is a `data-color-grading` attribute on the media element. It treats the whole element in SDR, so it can't blur one region such as a face.
+- To animate it, set the start value in the element's inline `style` and tween these custom properties with finite `tl.to()` on the composition's timeline: `--hf-color-grading-` followed by `intensity`, `lut-intensity`, `blur`, `kuwahara`, `pixelate`, `ascii` or `dither` (each 0–1), `exposure` (−2 to 2) or `bloom` (0–3).
+- Compare candidate grades on one frame: `npx hyperframes grade-compare --for frame.png --grades grades.json --json`, or `--luts a.cube,b.cube`.
+
+## Cutouts
+
+- `npx hyperframes remove-background <in> -o cutout.webm` (`.png` for an image; `--quality best` for a closer colour match over its source). `--background-output plate.webm` also writes the background with the subject cut out.
+- A cutout over its own source: both clips `data-start="0"` and `data-media-start="0"`, so they decode in sync.
+- The runtime forces `opacity: 1` on a timed clip. To fade a cutout, wrap it in an untimed `<div>` and animate the wrapper.
+
+## Sound
+
+- Match loudness: `npx hyperframes normalize-audio --reference <id> --target <id> --write`, or `--lufs=-16` (the default target; write a negative value with `=`) without a reference. `--write` edits the volume in the HTML.
+- Beat grid: `npx hyperframes beats --json` reads the local music `<audio>` (marked `data-timeline-role="music"`, or an id containing music, bgm or soundtrack) and writes `beats/<path>.json`, which Studio shows as its beat grid. A beat time minus a scene's `data-start` is its time inside that scene.
+- Local transcription, or importing `.srt`, `.vtt` or Whisper JSON: `npx hyperframes transcribe <file> --json`. The default model translates non-English speech: see `../../hyperframes/references/captions.md`.

package/skills/media-use/references/media-treatments.md

@@ -159,9 +159,13 @@ drops frames. Do not impose or claim a universal hard cap from one machine.
    GSAP only for supported animated values and Registry overlay blocks only
    for authored dressing.
    ```bash
-   hyperframes media-treatment --selector "<unique selector>" \
+   hyperframes media-treatment --selector "<selector>" \
      --grading '<nested JSON patch>' --apply --json
    ```
+   A selector that matches several images or videos patches every match, each
+   merged into its own current grading (the JSON reports `count` and each
+   target); run `--clear` first for an identical look, or add
+   `--selector-index` to patch only one.
    For a temporal reveal, use the focused capability result's `animation`
    contract. If it is `null`, the capability is static. Author the starting CSS
    property inline on the real media element and return temporary treatment

package/skills/media-use/references/memory.md

@@ -7,10 +7,14 @@ The lightweight tier of user memory: confirmed brief answers (destination, aspec
 ```bash
 node <SKILL_DIR>/scripts/prefs.mjs get --hyperframes . --json      # merged view (project overrides user)
 node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key destination --value x-feed
-node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key style_preset --value pin-and-paper --workflow faceless-explainer
+node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key style_preset --value pin-and-paper --workflow explainer
 ```
 
-Only what the user actually confirmed gets recorded — never an inferred or defaulted value. How workflows consume these (a remembered value becomes the recommended default with a receipt, and never skips a question) is the brief contract's rule: `hyperframes/references/brief-contract.md` § 2, Remembered defaults.
+Only what the user actually confirmed gets recorded — never an inferred or defaulted value. A remembered value becomes the recommended default, shown with where it came from; it never skips a question.
+
+Preference records serialize writes with `preferences.json.lock` beside each tier's file. If a process stops while holding that lock, later records leave it in place and report "Settings are locked…". After confirming no HyperFrames process is recording preferences, delete the named lock file and retry. A locked personal tier does not fail the project record; personal promotion waits for a later record.
+
+Keep the project's preference file committed, and add `.media/*.lock` to the project's `.gitignore` so transient locks are never shared with the team.
 
 ## Recipes — frozen video bundles
 
@@ -18,15 +22,16 @@ The heavyweight tier of user memory: one approved run frozen as a named, version
 
 ```bash
 node <SKILL_DIR>/scripts/recipe.mjs freeze --hyperframes . --name weekly-promo   # workflow read from BRIEF.md (--workflow only for briefless projects)
-node <SKILL_DIR>/scripts/recipe.mjs list --hyperframes . --workflow product-launch-video
+node <SKILL_DIR>/scripts/recipe.mjs list --hyperframes . --workflow explainer
 node <SKILL_DIR>/scripts/recipe.mjs use --hyperframes . --name weekly-promo   # also: resolve.mjs --type recipe --entity weekly-promo
 ```
 
-The freeze is offered once after the final approval (`hyperframes/references/review-loop.md` § 4), and the intent layer (`/hyperframes` → `references/intent-interview.md`, step 1) checks for a match before its first question. Adopting a recipe fills the brief, the design spec, and the storyboard skeleton — and unlike preferences it may skip the questions it answers: the bundle was approved as a whole, and adoption itself is the question.
+Offer the freeze once, after the final approval; before the first question about a new video, check `recipe.mjs list` for a match. Adopting a recipe fills the brief, the design spec, and the storyboard skeleton — and unlike preferences it may skip the questions it answers: the bundle was approved as a whole, and adoption itself is the question.
 
 ## Files
 
-- `.media/manifest.jsonl`: machine SSOT, one JSON record per line
+- `.media/manifest.jsonl`: machine SSOT, one JSON record per line. Records are keyed by path and only appended, so
+  the last record for a path is the file's record; a file moved or replaced by hand keeps (or loses) its record by path.
 - `.media/index.md`: agent-readable table (id, type, dur, dims, path, description)
 - `.media/preferences.json`: the project's remembered defaults (committed)
 - `~/.media/`: global cross-project reuse cache (content-addressed, SHA-256)

package/skills/media-use/references/meta.md

@@ -4,22 +4,22 @@ Maintainer-facing reference. Nothing here changes how you resolve or operate on
 
 ## What it owns (the gaps HyperFrames leaves)
 
-HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `scripts/lib/coverage.test.mjs` so the claim can't rot.
-
-| HyperFrames gap                            | media-use owns it via                                                                                                                                                                                                                                                               |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Audio-only, no image/icon                  | `resolve --type image\|icon` (heygen asset search)                                                                                                                                                                                                                                  |
-| No third-party brand logos                 | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon)                                                                                                                                                                                                                 |
-| No voice / audio generation                | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`)                                                                                                                                                           |
-| Scattered/duplicated audio engine          | one consolidated engine under `audio/` (hyperframes-media retired)                                                                                                                                                                                                                  |
-| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs                                                                                                                                                                                                                   |
-| No transcript-driven cutting               | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists                                                                                                                                                                                                           |
-| No auto-duck / publish loudness            | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes                                                                                                                                                                                                    |
-| No cross-project memory                    | global content-addressed cache + auto-promote (`~/.media`)                                                                                                                                                                                                                          |
-| Grade recipes and LUT freezing             | `resolve --type grade` emits a paste-ready recipe and `resolve --type lut` freezes validated `.cube` files; direct element analysis/authoring lives in `hyperframes media-treatment`                                                                                                |
-| No image generation                        | RAM-graded local mflux (FLUX) via `scripts/lib/mflux-provider.mjs`, codex `image_gen` upsell (`scripts/lib/codex-provider.mjs`)                                                                                                                                                     |
-| No video generation                        | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` in `scripts/lib/local-models.mjs`); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
-| Weak local-model defaults                  | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives (`scripts/lib/local-run.mjs`)                                                                                                                                                      |
+HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `packages/cli/src/media-use/lib/coverage.test.mjs` so the claim can't rot.
+
+| HyperFrames gap                            | media-use owns it via                                                                                                                                                                                                                                    |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Audio-only, no image/icon                  | `resolve --type image\|icon` (heygen asset search)                                                                                                                                                                                                       |
+| No third-party brand logos                 | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon)                                                                                                                                                                                      |
+| No voice / audio generation                | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`)                                                                                                                                |
+| Scattered/duplicated audio engine          | one consolidated engine under `audio/` (hyperframes-media retired)                                                                                                                                                                                       |
+| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs                                                                                                                                                                                        |
+| No transcript-driven cutting               | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists                                                                                                                                                                                |
+| No auto-duck / publish loudness            | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes                                                                                                                                                                         |
+| No cross-project memory                    | global content-addressed cache + auto-promote (`~/.media`)                                                                                                                                                                                               |
+| Grade recipes and LUT freezing             | `resolve --type grade` emits a paste-ready recipe and `resolve --type lut` freezes validated `.cube` files; direct element analysis/authoring lives in `hyperframes media-treatment`                                                                     |
+| No image generation                        | `resolve --type image` — RAM-graded local mflux (FLUX), codex `image_gen` upsell                                                                                                                                                                         |
+| No video generation                        | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` ladder); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
+| Weak local-model defaults                  | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives                                                                                                                                                         |
 
 ## Usage stats
 
@@ -47,7 +47,7 @@ dev). Same public PostHog project key and opt-outs as the `hyperframes` CLI.
 
 HeyGen request tagging: every generating `heygen` call (TTS, avatar video, catalog
 search) carries the allowlisted `X-HeyGen-Client-Source: media-use` header, sourced
-from one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `scripts/lib/heygen-cli.mjs`)
+from one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `packages/cli/src/media-use/lib/heygen-cli.mjs`)
 so a future call site can't silently ship untagged. Read-only discovery calls
 (`voice list`, `avatar list`) are intentionally left untagged.