hyperframes 0.8.184 → 0.8.185

package/dist/skills/media-use/audio/scripts/carve.test.mjs

@@ -0,0 +1,254 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  DEFAULT_STRENGTH,
+  carveSources,
+  groupSourceRefusal,
+  loadCore,
+  parseArgs,
+} from "./carve.mjs";
+
+const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** A voice as `detectTracks` yields it: an id plus its raw opening tag. */
+function voice(id, group) {
+  const attr = group === undefined ? "" : ` data-audio-group="${group}"`;
+  return { id, tag: `<audio id="${id}"${attr} src="${id}.wav"></audio>` };
+}
+
+/** An audio member as `main` describes it for the source decision. */
+function member(id, group, nameKind) {
+  return { id, group, nameKind };
+}
+
+/** A bed as `mediaElements` yields it: `kind` is what decides group membership. */
+function bed(id, group, kind = "audio") {
+  const attr = group === undefined ? "" : ` data-audio-group="${group}"`;
+  return { id, kind, tag: `<${kind} id="${id}"${attr} src="${id}.mp3"></${kind}>` };
+}
+
+async function inTempDir(run) {
+  const dir = mkdtempSync(join(tmpdir(), "carve-test-"));
+  try {
+    return await run(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("voices sharing one group carve against the group, not their ids", () => {
+  // SKILL.md's invariant: "A carve against more than one clip id is wrong.
+  // Group the clips and carve against the group." Naming the group lets
+  // membership resolve at analysis time, so a voice added later is covered.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover"), voice("vo3", "voiceover")];
+  assert.deepEqual(carveSources(voices, undefined, []), ["voiceover"]);
+});
+
+test("a single grouped voice still records the group", () => {
+  assert.deepEqual(carveSources([voice("vo1", "voiceover")], undefined, []), ["voiceover"]);
+});
+
+test("ungrouped voices keep their ids, so the lint rule can still say so", () => {
+  // Not silently inventing a group: `audio_carve_ungrouped_sources` is the
+  // right signal here, and it needs the ids to fire on.
+  assert.deepEqual(carveSources([voice("vo1"), voice("vo2")], undefined, []), ["vo1", "vo2"]);
+});
+
+test("voices in DIFFERENT groups keep their ids", () => {
+  // One carve cannot name two groups, and picking either would silently drop
+  // the other's members from the analysis.
+  const voices = [voice("vo1", "narration"), voice("vo2", "interview")];
+  assert.deepEqual(carveSources(voices, undefined, []), ["vo1", "vo2"]);
+});
+
+test("a partially grouped set keeps its ids", () => {
+  const voices = [voice("vo1", "voiceover"), voice("vo2")];
+  assert.deepEqual(carveSources(voices, undefined, []), ["vo1", "vo2"]);
+});
+
+test("an empty group attribute is not a group", () => {
+  assert.deepEqual(carveSources([voice("vo1", ""), voice("vo2", "")], undefined, []), [
+    "vo1",
+    "vo2",
+  ]);
+});
+
+// The nine cases above pass `[]` explicitly because they predate the membership
+// check and are about the bed and the group attributes alone. `members` is a
+// required argument: with `[]` the `mixed` refusal cannot fire, so a default
+// would let a call that forgot it return the group form and silently undo the
+// widening fix — see the wiring test at the bottom of this file.
+
+test("a bed inside the voices' group keeps clip ids, so it is never its own source", () => {
+  // `resolveCarveSourceIds` expands a group to every CURRENT member, and it gets
+  // no host element to exclude — so naming a group the bed belongs to puts the
+  // bed in its own voice list on the next analysis, and it is carved against
+  // itself. This run cannot see it (main sums the detected voices directly), so
+  // the check has to happen here.
+  const voices = [voice("vo1", "mix"), voice("vo2", "mix")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "mix"), []), ["vo1", "vo2"]);
+});
+
+test("a bed in a DIFFERENT group leaves the group form alone", () => {
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), []), ["voiceover"]);
+});
+
+test("an ungrouped bed leaves the group form alone", () => {
+  assert.deepEqual(carveSources([voice("vo1", "voiceover")], bed("bgm"), []), ["voiceover"]);
+});
+
+test("a VIDEO bed is immune — group membership is audio-only", () => {
+  // `data-audio-group` on a <video> is ignored by core, so expanding the group
+  // can never pull this bed in and declining would be a false positive.
+  const voices = [voice("vo1", "mix"), voice("vo2", "mix")];
+  assert.deepEqual(carveSources(voices, bed("clip", "mix", "video"), []), ["mix"]);
+});
+
+test("an sfx member of the voices' group blocks the group form", () => {
+  // The group resolves wider than the analysis: `resolveCarveSourceIds` expands
+  // it to every current member and `resolveCarveVoices` keeps any audio with a
+  // src, so an sfx clip sharing the voice group enters the sidechain on the next
+  // analysis and ducks the bed under a whoosh. This run cannot see it — it sums
+  // the voices `detectTracks` returned, which correctly excluded the sfx.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  const members = [
+    member("vo1", "voiceover", "voice"),
+    member("vo2", "voiceover", "voice"),
+    member("whoosh", "voiceover", "sfx"),
+    member("bgm", "music", "music"),
+  ];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["vo1", "vo2"]);
+});
+
+test("a music member of the voices' group blocks it too", () => {
+  const voices = [voice("vo1", "voiceover")];
+  const members = [member("vo1", "voiceover", "voice"), member("pad", "voiceover", "music")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["vo1"]);
+});
+
+test("a voice member this run did NOT analyse keeps the group form", () => {
+  // The designed case, and the one a membership check must not break: a voice
+  // that does not overlap the bed is left out of the analysis on purpose, and
+  // covering it on a later analysis without editing `sources` is the entire
+  // reason SKILL.md says to name the group. Refusing here would collapse the
+  // group form into clip ids for every ordinary narration sequence.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  const members = [
+    member("vo1", "voiceover", "voice"),
+    member("vo2", "voiceover", "voice"),
+    member("vo-outro", "voiceover", "voice"),
+  ];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["voiceover"]);
+});
+
+test("an unclassifiable member keeps the group form", () => {
+  // `unknown` is what `detectTracks` itself treats as a possible voice, so it is
+  // not evidence of a non-voice member — loose in the safe direction, same as
+  // detection.
+  const voices = [voice("vo1", "voiceover")];
+  const members = [member("vo1", "voiceover", "voice"), member("track7", "voiceover", "unknown")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["voiceover"]);
+});
+
+test("an sfx member of a DIFFERENT group is irrelevant", () => {
+  const voices = [voice("vo1", "voiceover")];
+  const members = [member("vo1", "voiceover", "voice"), member("whoosh", "sfx", "sfx")];
+  assert.deepEqual(carveSources(voices, bed("bgm", "music"), members), ["voiceover"]);
+});
+
+test("groupSourceRefusal names which member blocked the group, and why", () => {
+  // The stderr note is built from this, so it has to carry the ids: "sources are
+  // clip ids" plus `audio_carve_ungrouped_sources` reads as nonsense to an author
+  // who did group their clips.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  assert.deepEqual(
+    groupSourceRefusal(voices, bed("bgm", "music"), [member("whoosh", "voiceover", "sfx")]),
+    { group: "voiceover", reason: "mixed", ids: ["whoosh"] },
+  );
+  assert.deepEqual(groupSourceRefusal(voices, bed("bgm", "voiceover"), []), {
+    group: "voiceover",
+    reason: "bed",
+    ids: ["bgm"],
+  });
+  assert.equal(groupSourceRefusal(voices, bed("bgm", "music"), []), null);
+});
+
+test("the CLI still runs when invoked through a symlinked path", () => {
+  // argv[1] keeps the invoked spelling while import.meta.url is the realpath, so
+  // a raw compare in the entry guard skips main() and the CLI exits 0 having
+  // written nothing. macOS /tmp -> /private/tmp reaches this with no symlink of
+  // one's own; so does any skill install placed behind a link.
+  return inTempDir((dir) => {
+    const link = join(dir, "scripts-link");
+    symlinkSync(SCRIPTS_DIR, link, "junction");
+    let status = 0;
+    let stderr = "";
+    try {
+      execFileSync(process.execPath, [join(link, "carve.mjs")], { encoding: "utf-8" });
+    } catch (error) {
+      status = error.status;
+      stderr = String(error.stderr);
+    }
+    // Reaching parseArgs is the proof main() ran at all: no args is an error, and
+    // the broken guard's symptom is a silent exit 0 with no output.
+    assert.equal(status, 1, `expected the usage error, got status ${status}`);
+    assert.match(stderr, /--comp is required/);
+  });
+});
+
+test("loadCore honours an import-only export map, as the published core has", () => {
+  // The published manifest carries only `import` + `types` for these subpaths, so
+  // `require.resolve` cannot resolve them at all and the fallback has to read the
+  // export map itself. A fixture pins that without depending on npm.
+  return inTempDir(async (dir) => {
+    const pkgDir = join(dir, "node_modules", "@hyperframes", "core");
+    mkdirSync(join(pkgDir, "dist"), { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "fixture-project" }));
+    writeFileSync(
+      join(pkgDir, "package.json"),
+      JSON.stringify({
+        name: "@hyperframes/core",
+        version: "0.0.0-fixture",
+        type: "module",
+        exports: {
+          "./package.json": "./package.json",
+          "./audio-carve": { import: "./dist/audioCarve.js" },
+          "./audio-fx": { import: "./dist/audioFx.js" },
+        },
+      }),
+    );
+    writeFileSync(join(pkgDir, "dist", "audioCarve.js"), 'export const marker = "carve";\n');
+    writeFileSync(join(pkgDir, "dist", "audioFx.js"), 'export const marker = "fx";\n');
+
+    const core = await loadCore(dir);
+    assert.equal(core.carve.marker, "carve");
+    assert.equal(core.fx.marker, "fx");
+  });
+});
+
+test("members is required, so dropping it cannot silently restore the group form", () => {
+  // The gap this closes: `main()` is the only code that BUILDS `members`, and no
+  // test runs `main()` (the symlink test stops at the usage error, a real run
+  // needs ffmpeg). With `members = []` defaulted, a refactor that dropped the
+  // third argument would return the group form again with the whole suite green
+  // — the same signature as the bug itself: first pass correct, persisted
+  // attribute wrong, nothing red. Omitting it now throws instead.
+  const voices = [voice("vo1", "voiceover"), voice("vo2", "voiceover")];
+  assert.throws(() => carveSources(voices, bed("bgm", "music")), TypeError);
+  assert.throws(() => groupSourceRefusal(voices, bed("bgm", "music")), TypeError);
+});
+
+test("the default strength is 0.8, and --strength still overrides it", () => {
+  // 0.25 left the bed audibly fighting the voice on narrated builds; a carve at
+  // the default has to already be a finished mix. Pinned so it cannot drift back
+  // unnoticed — core pins its own DEFAULT_CARVE the same way.
+  assert.equal(DEFAULT_STRENGTH, 0.8);
+  assert.equal(parseArgs(["--comp", "x.html"]).strength, 0.8);
+  assert.equal(parseArgs(["--comp", "x.html", "--strength", "0.25"]).strength, 0.25);
+});

package/dist/skills/media-use/audio/scripts/extract-audio-data.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+Extract per-frame audio visualization data from an audio or video file.
+
+Outputs JSON with RMS amplitude and frequency band data at the target FPS,
+ready to embed in a HyperFrames composition.
+
+Usage:
+    python extract-audio-data.py input.mp3 -o audio-data.json
+    python extract-audio-data.py input.mp4 --fps 30 --bands 16 -o audio-data.json
+
+Requirements:
+    - Python 3.9+
+    - ffmpeg (for decoding audio)
+    - numpy (pip install numpy)
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+
+import numpy as np
+
+# Windows sizes stdio to the ANSI code page (cp1252). These scripts emit UTF-8 on
+# every platform; say so rather than depending on the console's code page. Carry
+# `errors` across: reconfigure() resets it to "strict", and CPython deliberately gives
+# stderr "backslashreplace" so the diagnostic path can never itself raise.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        _stream.reconfigure(encoding="utf-8", errors=_stream.errors)
+
+# ---------------------------------------------------------------------------
+# FFT parameters
+#
+# A 4096-sample window gives ~10.8 Hz per bin at 44100Hz — enough to resolve
+# low-frequency bands cleanly. The per-frame audio slice (44100/30 = 1470
+# samples at 30fps) is too small and causes low bands to map to the same bins.
+#
+# Frequency range 30Hz–16kHz covers the useful range for music. Below 30Hz is
+# sub-bass most speakers can't reproduce; above 16kHz is noise/harmonics that
+# don't contribute to perceived rhythm or melody.
+# ---------------------------------------------------------------------------
+
+SAMPLE_RATE = 44100
+FFT_SIZE = 4096
+MIN_FREQ = 30.0
+MAX_FREQ = 16000.0
+
+
+def decode_audio(path: str) -> np.ndarray:
+    """Decode audio to mono float32 samples via ffmpeg."""
+    cmd = [
+        "ffmpeg", "-i", path,
+        "-vn", "-ac", "1", "-ar", str(SAMPLE_RATE),
+        "-f", "s16le", "-acodec", "pcm_s16le",
+        "-loglevel", "error",
+        "pipe:1",
+    ]
+    result = subprocess.run(cmd, capture_output=True)
+    if result.returncode != 0:
+        # Decoding ffmpeg's diagnostics strictly makes the reporter the thing that
+        # crashes: a Windows ffmpeg emits cp1252 bytes, and UnicodeDecodeError here
+        # would bury the actual failure it was trying to report.
+        print(f"ffmpeg error: {result.stderr.decode('utf-8', errors='replace')}", file=sys.stderr)
+        sys.exit(1)
+    return np.frombuffer(result.stdout, dtype=np.int16).astype(np.float32) / 32768.0
+
+
+def compute_band_edges(n_bands: int) -> np.ndarray:
+    """Logarithmically-spaced frequency band edges from MIN_FREQ to MAX_FREQ."""
+    return np.array([
+        MIN_FREQ * (MAX_FREQ / MIN_FREQ) ** (i / n_bands)
+        for i in range(n_bands + 1)
+    ])
+
+
+def compute_fft_bands(
+    windowed: np.ndarray, freq_per_bin: float, n_bins: int,
+    band_edges: np.ndarray, n_bands: int,
+) -> np.ndarray:
+    """Compute peak magnitude in logarithmically-spaced frequency bands."""
+    magnitudes = np.abs(np.fft.rfft(windowed))
+
+    bands = np.zeros(n_bands)
+    for b in range(n_bands):
+        low_bin = max(0, int(band_edges[b] / freq_per_bin))
+        high_bin = min(n_bins, int(band_edges[b + 1] / freq_per_bin))
+        if high_bin <= low_bin:
+            high_bin = low_bin + 1
+        # Clamp to valid range to avoid empty slices
+        low_bin = min(low_bin, n_bins - 1)
+        high_bin = min(high_bin, n_bins)
+        bands[b] = np.max(magnitudes[low_bin:high_bin])
+
+    return bands
+
+
+def extract(path: str, fps: int, n_bands: int) -> dict:
+    """Extract per-frame audio data."""
+    print(f"Decoding audio from {path}...", file=sys.stderr)
+    samples = decode_audio(path)
+    duration = len(samples) / SAMPLE_RATE
+    frame_step = SAMPLE_RATE // fps
+    total_frames = int(duration * fps)
+
+    print(f"Duration: {duration:.1f}s, {total_frames} frames at {fps}fps", file=sys.stderr)
+    print(f"FFT window: {FFT_SIZE} samples ({SAMPLE_RATE / FFT_SIZE:.1f} Hz/bin)", file=sys.stderr)
+    print(f"Frequency range: {MIN_FREQ:.0f}-{MAX_FREQ:.0f} Hz, {n_bands} bands", file=sys.stderr)
+
+    # Precompute constants
+    hann = np.hanning(FFT_SIZE)
+    band_edges = compute_band_edges(n_bands)
+    freq_per_bin = SAMPLE_RATE / FFT_SIZE
+    n_bins = FFT_SIZE // 2 + 1
+    half_fft = FFT_SIZE // 2
+
+    # Pass 1: extract raw values
+    rms_values = np.zeros(total_frames)
+    band_values = np.zeros((total_frames, n_bands))
+
+    for f in range(total_frames):
+        # RMS from the frame's audio slice
+        rms_start = f * frame_step
+        rms_end = rms_start + frame_step
+        frame_slice = samples[rms_start:min(rms_end, len(samples))]
+        if len(frame_slice) > 0:
+            rms_values[f] = np.sqrt(np.mean(frame_slice ** 2))
+
+        # FFT from a centered 4096-sample window
+        center = rms_start + frame_step // 2
+        win_start = center - half_fft
+        win_end = center + half_fft
+
+        if win_start >= 0 and win_end <= len(samples):
+            window = samples[win_start:win_end] * hann
+        else:
+            # Zero-pad at edges
+            padded = np.zeros(FFT_SIZE)
+            src_start = max(0, win_start)
+            src_end = min(len(samples), win_end)
+            dst_start = src_start - win_start
+            dst_end = dst_start + (src_end - src_start)
+            padded[dst_start:dst_end] = samples[src_start:src_end]
+            window = padded * hann
+
+        band_values[f] = compute_fft_bands(window, freq_per_bin, n_bins, band_edges, n_bands)
+
+    # Pass 2: normalize
+    peak_rms = rms_values.max() if total_frames > 0 else 1.0
+    if peak_rms > 0:
+        rms_values /= peak_rms
+
+    # Per-band normalization so treble is visible alongside louder bass
+    band_peaks = band_values.max(axis=0)
+    band_peaks[band_peaks == 0] = 1.0
+    band_values /= band_peaks
+
+    # Build output
+    frames = []
+    for f in range(total_frames):
+        frames.append({
+            "time": round(f / fps, 4),
+            "rms": round(float(rms_values[f]), 4),
+            "bands": [round(float(b), 4) for b in band_values[f]],
+        })
+
+    return {
+        "duration": round(duration, 4),
+        "fps": fps,
+        "bands": n_bands,
+        "totalFrames": total_frames,
+        "frames": frames,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract per-frame audio visualization data")
+    parser.add_argument("input", help="Audio or video file")
+    parser.add_argument("-o", "--output", default="audio-data.json", help="Output JSON path")
+    parser.add_argument("--fps", type=int, default=30, help="Frames per second (default: 30)")
+    parser.add_argument("--bands", type=int, default=16, help="Number of frequency bands (default: 16)")
+    args = parser.parse_args()
+
+    if args.fps < 1:
+        parser.error("--fps must be at least 1")
+    if args.bands < 1:
+        parser.error("--bands must be at least 1")
+
+    data = extract(args.input, args.fps, args.bands)
+
+    with open(args.output, "w", encoding="utf-8") as f:
+        json.dump(data, f)
+
+    print(f"Wrote {args.output} ({data['totalFrames']} frames, {data['bands']} bands)", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/dist/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/dist/skills/media-use/references/memory.md

@@ -7,10 +7,10 @@ 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.
 
 ## Recipes — frozen video bundles
 
@@ -18,11 +18,11 @@ 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
 

package/dist/skills/media-use/references/mixing.md

@@ -0,0 +1,71 @@
+# Mixing in HyperFrames
+
+Preview and render run the same Web Audio graph, so what plays while scrubbing is what renders. Everything lives in attributes on the `<audio>` or `<video>` element.
+
+## Level and fades
+
+| Attribute                       | Meaning                                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| `data-volume`                   | Track gain, 1 = 0 dB                                                                      |
+| `data-fade-in`, `data-fade-out` | Edge fades in seconds                                                                     |
+| `data-playback-rate`            | Constant speed, 0.1–10, pitch preserved; give a video and its paired audio the same value |
+
+A crossfade is two clips on different tracks that overlap, each with a fade.
+
+## `data-automation`: envelopes
+
+```html
+<audio
+  id="music"
+  data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":1},{"t":2.5,"v":0.35}]}]}'
+  …
+></audio>
+```
+
+- `target` is `volume`, `rate` (a speed ramp, 0.1–10, overrides `data-playback-rate`) or `fx.<nodeId>.<param>`.
+- `t` is seconds from the start of the clip, not of the composition. `v` is in the parameter's unit: 0..1 for volume, dB for a gain, Hz for a frequency.
+- A lane holds its first value back to the clip's start and its last value to its end, so a bed that starts before the voice needs an explicit full-level point at `t: 0`.
+- `curve` (-1..1) bends the segment leaving a point. 512 points per lane at most.
+- Don't also tween `volume` with GSAP on a track that has a volume lane or a `data-volume`; lint flags both.
+
+## `data-fx-chain`: effects
+
+```json
+{
+  "version": 1,
+  "nodes": [
+    { "type": "highpass", "id": "n1", "label": "Remove rumble", "params": { "frequency": 80 } },
+    {
+      "type": "peaking",
+      "id": "n2",
+      "label": "Clarity",
+      "params": { "frequency": 3000, "gain": 2.5, "q": 1 }
+    },
+    { "type": "limiter", "id": "n3", "params": { "limit": -1 } }
+  ]
+}
+```
+
+- Write the attribute double-quoted with the JSON's quotes as `&quot;`.
+- Order is signal order. `id` is what automation targets (`fx.n2.gain`); give every node one, and a `label` when it does a named job. `enabled: false` bypasses a node.
+- Effects: `gain`, `highpass`, `lowpass`, `peaking`, `lowshelf`, `highshelf`, `compressor`, `limiter`, `gate`, `saturate`, `delay`, `reverb`, `chorus`, `phaser`, `bitcrush`.
+- `compressor`, `limiter`, `gate` and `bitcrush` can't be automated; a lane on them does nothing. Automate a `gain` before them instead.
+- Never set `fromCarve` by hand.
+- `reverb` and `delay` make the rendered track longer than its source; that is expected.
+
+| It sounds like              | Reach for                                   |
+| --------------------------- | ------------------------------------------- |
+| Hum, rumble, handling noise | `highpass` at 80 Hz                         |
+| Boomy, too close            | `peaking` 200 Hz, −4 dB                     |
+| Muffled                     | `peaking` 250 Hz, −3 dB                     |
+| Words hard to make out      | `peaking` 3 kHz, +2.5 dB, or duck the music |
+| Harsh                       | `peaking` 3.2 kHz, −3 dB                    |
+| Peaks clipping              | `limiter` last in the chain                 |
+
+## Music under a voice
+
+Duck the bed with a `volume` lane on the music: full level before the voice, down to about 0.3–0.4 while anyone speaks (word timings from `npx hyperframes transcribe` or the voiceover give the times), back up after. Then carve the bed, which dips only the bands the voice uses: `node <SKILL_DIR>/audio/scripts/carve.mjs --comp index.html` (needs `ffmpeg` and `@hyperframes/core` in the project; `--dry-run` to see the plan). It is the same analysis as Studio's carve panel. It reads only double-quoted attributes (JSON quotes as `&quot;`), so write the bed's chain and lanes that way or it overwrites them. Never put a carve on a voice track.
+
+## Group buses
+
+Give clips the same `data-audio-group="<id>"` to treat them as one group. An `<hf-audio-group id="<id>">` element with that id makes the group a submix bus with one `data-fx-chain`, one volume and one automation clock for every member. Keep one role per group: `voiceover`, `music`, `sfx`.

package/dist/skills/media-use/references/operations.md

@@ -16,7 +16,7 @@ ffmpeg -i in.mp4 -ss 00:00:12 -to 00:00:20 -c copy out.mp4   # 0:12–0:20, no r
 ```
 
 In-composition trimming usually needs **no new file**: a clip plays a sub-window
-via `data-media-start` + `data-duration` (see hyperframes-core). Only cut a
+via `data-media-start` + `data-duration` (see `/hyperframes` → `references/format.md`). Only cut a
 physical file when exporting/assembling outside the composition.
 
 ## Reframe / crop: change aspect ratio

package/dist/skills/media-use/scripts/compatibility.test.mjs

@@ -1,10 +1,8 @@
-import assert from "node:assert/strict";
-import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import test from "node:test";
-import { pathToFileURL } from "node:url";
 
 process.env.HYPERFRAMES_MEDIA_HOME = mkdtempSync(join(tmpdir(), "media-use-compat-home-"));
 
@@ -41,56 +39,3 @@ test("published audio helpers import without the CLI package tree", () => {
     rmSync(root, { recursive: true, force: true });
   }
 });
-
-for (const name of ["faceless-explainer", "pr-to-video", "product-launch-video"]) {
-  test(name + " assembles from its installed directory alone", () => {
-    const root = mkdtempSync(join(tmpdir(), "installed-workflow-"));
-    try {
-      const skill = join(root, name);
-      cpSync(new URL("../../" + name, import.meta.url), skill, { recursive: true });
-      const project = join(root, "project");
-      mkdirSync(join(project, "compositions/frames"), { recursive: true });
-      writeFileSync(
-        join(project, "STORYBOARD.md"),
-        "---\nformat: 1920x1080\nmessage: Test\n---\n\n## Frame 1\n- duration: 3s\n- src: compositions/frames/01-a.html\n",
-      );
-      writeFileSync(
-        join(project, "compositions/frames/01-a.html"),
-        '<template><div data-composition-id="01-a" data-duration="3" data-width="1920" data-height="1080"><section class="clip" data-start="0" data-duration="3"></section></div></template>',
-      );
-      run(join(skill, "scripts"), "assemble-index.mjs", [
-        "--hyperframes",
-        project,
-        "--storyboard",
-        join(project, "STORYBOARD.md"),
-      ]);
-      assert.match(readFileSync(join(project, "index.html"), "utf8"), /01-a/);
-      importPacketBuilder(join(skill, "scripts/frame-packets.mjs"));
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-}
-
-test("general-video packet builder starts from its installed directory alone", () => {
-  const root = mkdtempSync(join(tmpdir(), "installed-packets-"));
-  try {
-    cpSync(new URL("../../general-video", import.meta.url), root, { recursive: true });
-    importPacketBuilder(join(root, "scripts/frame-packets.mjs"));
-  } finally {
-    rmSync(root, { recursive: true, force: true });
-  }
-});
-
-function importPacketBuilder(path) {
-  execFileSync(
-    process.execPath,
-    [
-      "--input-type=module",
-      "-e",
-      'const m = await import(process.argv[1]); if (typeof m.buildFramePackets !== "function") throw new Error("missing builder");',
-      pathToFileURL(path).href,
-    ],
-    { stdio: "pipe" },
-  );
-}