@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/.agents/skills/embedded-captions/scripts/matte.cjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/*
+ * matte.cjs — subject matting via hyperframes' built-in `remove-background`
+ * (rembg-equivalent u2net_human_seg, Apache-2.0, 320×320 input, ~9 fps on
+ * CoreML). Replaces the previous bundled PP-MattingV2 ONNX (34 MB asset +
+ * an onnxruntime inference loop in this script): one engine, zero bundled
+ * weights — the model auto-downloads once (~168 MB) to ~/.cache/hyperframes/.
+ *
+ * Semantics note (validated 2026-06-12 on 6 scenes + a cold-start E2E): a
+ * HUMAN segmenter by intent, not surgically. Thin offset furniture (mic boom
+ * arms) is usually excluded — captions render over it, behind the person —
+ * but large salient objects near the subject (a telescope rig) can still
+ * leak into the matte and occlude captions. Objects HELD by the subject
+ * (products, phones) may drop out intermittently, letting captions pass in
+ * front. Never assume: sample frames_fg/ before placing the hero.
+ *
+ * Pipeline:
+ *   source.mp4 → hyperframes remove-background → ProRes 4444 .mov (lossless
+ *   alpha; temp, deleted) → ffmpeg fps=<matte.fps> → frames_fg/f_%04d.png.
+ *   frames_bg/ is extracted at the same rate (preview tooling reads it).
+ *
+ *   node matte.cjs <project-dir>
+ * Reads:  <project>/source.mp4 (any video in the project dir is adopted)
+ * Writes: <project>/frames_fg/f_%04d.png (RGBA, subject opaque),
+ *         <project>/frames_bg/f_%04d.png, <project>/matte.fps
+ * Env:    HYPERFRAMES_ROOT — hyperframes checkout (optional; falls back to the
+ *         installed hyperframes npm package, then `npx -y hyperframes`)
+ */
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const cp = require("child_process");
+
+// Resolve the hyperframes CLI as an argv prefix (["node", cli.js] or ["npx", …]).
+// Order: built checkout → installed npm package (vidfarm-devcli ships it) → npx.
+function hfCli() {
+  const roots = [
+    process.env.HYPERFRAMES_ROOT,
+    path.resolve(__dirname, "..", "..", ".."), // skills/embedded-captions/scripts → repo root if in-repo
+    path.join(os.homedir(), "Downloads", "hyperframes"),
+  ].filter(Boolean);
+  for (const root of roots) {
+    const cli = path.join(root, "packages", "cli", "dist", "cli.js");
+    if (fs.existsSync(cli)) return ["node", cli];
+  }
+  try {
+    return ["node", require.resolve("hyperframes/dist/cli.js", { paths: [__dirname, process.cwd()] })];
+  } catch {}
+  return ["npx", "-y", "hyperframes"]; // last resort — fetches the CLI on demand
+}
+
+function ensureSource(project) {
+  const src = path.join(project, "source.mp4");
+  if (!fs.existsSync(src)) {
+    const found = fs
+      .readdirSync(project)
+      .filter((f) => /\.(mp4|mov|webm|mkv)$/i.test(f) && !f.startsWith("_"))
+      .map((f) => path.join(project, f))[0];
+    if (!found) return src;
+    try {
+      fs.symlinkSync(path.basename(found), src);
+    } catch {
+      fs.copyFileSync(found, src);
+    }
+    console.log(`[matte] resolved source.mp4 -> ${path.basename(found)}`);
+  }
+  return src;
+}
+
+function rateOf(expr) {
+  const [n, d] = String(expr || "").split("/");
+  const f = parseFloat(n) / parseFloat(d || "1");
+  return Number.isFinite(f) && f > 0 ? f : 0;
+}
+
+// Prefer avg_frame_rate (frames/duration — the truth) over r_frame_rate (the
+// container's nominal tick rate, which lies on VFR sources: a 24fps screen
+// recording can carry r_frame_rate=60 and would 2.5x-desync the matte).
+function probeRates(src) {
+  try {
+    const out = cp
+      .execFileSync("ffprobe", [
+        "-v",
+        "0",
+        "-select_streams",
+        "v:0",
+        "-show_entries",
+        "stream=r_frame_rate,avg_frame_rate",
+        "-of",
+        "default=nk=1:nw=1",
+        src,
+      ])
+      .toString()
+      .trim()
+      .split("\n");
+    return { r: rateOf(out[0]), avg: rateOf(out[1]) };
+  } catch {
+    return { r: 0, avg: 0 };
+  }
+}
+
+function probeFps(src) {
+  const { r, avg } = probeRates(src);
+  const f = avg || r;
+  return f > 0 ? Math.max(1, Math.round(f)) : 24;
+}
+
+// VFR when nominal and actual disagree by >5% — the remove-background engine
+// mishandles VFR timestamps (observed: 2251 fg frames vs 902 bg on one clip),
+// so VFR sources get normalized to CFR before matting.
+function isVfr(src) {
+  const { r, avg } = probeRates(src);
+  return r > 0 && avg > 0 && Math.abs(r - avg) / avg > 0.05;
+}
+
+function extractFrames(src, dst, fps, extra = []) {
+  fs.mkdirSync(dst, { recursive: true });
+  if (fs.readdirSync(dst).some((f) => f.endsWith(".png"))) return false;
+  cp.execFileSync(
+    "ffmpeg",
+    ["-y", "-i", src, "-vf", `fps=${fps}`, ...extra, path.join(dst, "f_%04d.png")],
+    { stdio: "ignore" },
+  );
+  return true;
+}
+
+function countPngs(dir) {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith(".png")).length;
+  } catch {
+    return 0;
+  }
+}
+
+async function main() {
+  const project = path.resolve(process.argv[2] || "");
+  if (!process.argv[2]) {
+    console.error("usage: matte.cjs <project-dir>");
+    process.exit(1);
+  }
+  const src = ensureSource(project);
+  if (!fs.existsSync(src)) {
+    console.error(`[matte] no source video found in ${project}`);
+    process.exit(2);
+  }
+
+  const fpsFile = path.join(project, "matte.fps");
+  // read-with-catch (no exists-then-read TOCTOU): a missing/corrupt fps file
+  // simply falls through to probing the source.
+  let fps = 0;
+  try {
+    fps = parseInt(fs.readFileSync(fpsFile, "utf8").replace(/\D/g, ""), 10) || 0;
+  } catch {
+    /* no cached fps — probe below */
+  }
+  if (!fps) fps = probeFps(src);
+  fs.writeFileSync(fpsFile, String(fps));
+
+  const framesBg = path.join(project, "frames_bg");
+  const framesFg = path.join(project, "frames_fg");
+  if (extractFrames(src, framesBg, fps))
+    console.log(`[matte] source fps=${fps} → frames_bg extracted`);
+
+  const want = countPngs(framesBg);
+  if (want > 0 && countPngs(framesFg) >= want) {
+    console.log(`[matte] frames_fg already complete (${want} frames) — nothing to do`);
+    return;
+  }
+
+  // 1) subject matte via hyperframes (ProRes 4444 keeps the alpha lossless).
+  //    VFR sources are normalized to CFR first — remove-background trusts
+  //    timestamps and emits a desynced frame count on VFR input (the ghost
+  //    double-subject bug: the pasted matte runs at the wrong speed).
+  let matteSrc = src;
+  if (isVfr(src)) {
+    const cfr = path.join(project, "_src_cfr.mp4");
+    if (!fs.existsSync(cfr)) {
+      console.log(
+        `[matte] VFR source detected (nominal != actual fps) → normalizing to ${fps}fps CFR for matting`,
+      );
+      cp.execFileSync(
+        "ffmpeg",
+        [
+          "-y",
+          "-i",
+          src,
+          "-fps_mode",
+          "cfr",
+          "-r",
+          String(fps),
+          "-c:v",
+          "libx264",
+          "-crf",
+          "16",
+          "-preset",
+          "fast",
+          "-an",
+          cfr,
+        ],
+        { stdio: "ignore" },
+      );
+    }
+    matteSrc = cfr;
+  }
+  const mov = path.join(project, "_matte_tmp.mov");
+  const t0 = Date.now();
+  const cached = fs.existsSync(
+    path.join(
+      os.homedir(),
+      ".cache",
+      "hyperframes",
+      "background-removal",
+      "models",
+      "u2net_human_seg.onnx",
+    ),
+  );
+  console.log(
+    `[matte] hyperframes remove-background (u2net_human_seg${cached ? "" : "; first run downloads ~168 MB"})… model load takes ~1-2 min with no output — not hung`,
+  );
+  const hf = hfCli();
+  const r = cp.spawnSync(hf[0], [...hf.slice(1), "remove-background", matteSrc, "-o", mov], {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      HYPERFRAMES_NO_TELEMETRY: "1",
+      HYPERFRAMES_SKIP_SKILLS: "1",
+      // Fresh empty config dir: a stray ~/.heygen credential must never flip
+      // the CLI's audio-provider preference (same isolation as the devcli's
+      // hyperframes-cli.ts and vidfarm-media's audio.mjs spawn sites).
+      HEYGEN_CONFIG_DIR: fs.mkdtempSync(path.join(os.tmpdir(), "vf-captions-heygen-")),
+    },
+  });
+  if (r.status !== 0 || !fs.existsSync(mov)) {
+    console.error("[matte] remove-background FAILED:");
+    console.error((r.stderr || r.stdout || "").split("\n").slice(-8).join("\n"));
+    process.exit(4);
+  }
+
+  // 2) burst to RGBA pngs at the project rate
+  fs.mkdirSync(framesFg, { recursive: true });
+  cp.execFileSync(
+    "ffmpeg",
+    ["-y", "-i", mov, "-vf", `fps=${fps}`, "-pix_fmt", "rgba", path.join(framesFg, "f_%04d.png")],
+    { stdio: "ignore" },
+  );
+  fs.rmSync(mov, { force: true });
+
+  // 3) count parity with frames_bg. Composite overlays fg by INDEX at matte.fps,
+  //    so any fg/bg count mismatch is a time desync (subject ghosting). Handle
+  //    BOTH directions: pad when short, linearly remap when long — and shout
+  //    when the mismatch is big enough to mean broken timestamps upstream.
+  let got = countPngs(framesFg);
+  const tol = Math.max(2, Math.round(want * 0.01));
+  if (Math.abs(got - want) > tol) {
+    console.error(
+      `[matte] WARN frame-count desync: fg=${got} vs bg=${want} (tolerance ${tol}). ` +
+        `Reconciling by remap — if the source is VFR this run predates the CFR fix; ` +
+        `delete frames_fg/ frames_bg/ matte.fps and re-run matte.cjs.`,
+    );
+  }
+  if (got > want && want > 0) {
+    // keep want frames sampled evenly across got (re-times fg onto the bg timeline)
+    const keep = [];
+    for (let j = 1; j <= want; j++)
+      keep.push(Math.min(got, Math.max(1, Math.round((j - 0.5) * (got / want)))));
+    const tmp = path.join(project, "_fg_remap");
+    fs.mkdirSync(tmp, { recursive: true });
+    keep.forEach((srcIdx, k) => {
+      fs.copyFileSync(
+        path.join(framesFg, `f_${String(srcIdx).padStart(4, "0")}.png`),
+        path.join(tmp, `f_${String(k + 1).padStart(4, "0")}.png`),
+      );
+    });
+    fs.rmSync(framesFg, { recursive: true, force: true });
+    fs.renameSync(tmp, framesFg);
+    got = countPngs(framesFg);
+  }
+  while (got < want && got > 0) {
+    fs.copyFileSync(
+      path.join(framesFg, `f_${String(got).padStart(4, "0")}.png`),
+      path.join(framesFg, `f_${String(got + 1).padStart(4, "0")}.png`),
+    );
+    got++;
+  }
+  console.log(
+    `[matte] done in ${((Date.now() - t0) / 1000).toFixed(1)}s → fg=${got} bg=${want} @ ${fps}fps${got === want ? " (parity ok)" : ""}`,
+  );
+}
+
+main().catch((e) => {
+  console.error("[matte]", e.message);
+  process.exit(1);
+});

package/.agents/skills/embedded-captions/scripts/measure-layout.cjs

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * measure-layout.cjs — pixel-perfect bbox measurement using headless Chromium.
+ *
+ * Loads the compiled index.html, seeks the GSAP timeline to specified sample
+ * times, queries every .cap container + every .w word span via
+ * getBoundingClientRect(), writes results to _layout.json.
+ *
+ * check-occlusion.cjs then reads _layout.json + frames_fg/*.png and computes
+ * per-word occlusion against the actual subject silhouette (matte alpha via
+ * sharp) — pixel accurate, no char_ratio guessing.
+ *
+ * Usage:
+ *   node measure-layout.cjs <project-dir> [times...]
+ * If no times given, samples groups['in', 'out'] midpoints.
+ */
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+// Locate hyperframes' bundled puppeteer. render-and-composite.sh exports
+// HYPERFRAMES_ROOT; standalone we also try the in-repo path + ~/Downloads, and
+// accept ANY puppeteer@* the bun store holds (not a pinned version).
+const HF_ROOTS = [
+  process.env.HYPERFRAMES_ROOT,
+  path.resolve(__dirname, "../../.."), // skills/embedded-captions/scripts → repo root if in-repo
+  path.join(os.homedir(), "Downloads", "hyperframes"),
+].filter(Boolean);
+let puppeteer = null;
+for (const root of HF_ROOTS) {
+  const cands = [path.join(root, "node_modules", "puppeteer")];
+  const bunDir = path.join(root, "node_modules", ".bun");
+  try {
+    if (fs.existsSync(bunDir)) {
+      for (const d of fs.readdirSync(bunDir)) {
+        if (d.startsWith("puppeteer@"))
+          cands.push(path.join(bunDir, d, "node_modules", "puppeteer"));
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  for (const p of cands) {
+    try {
+      if (fs.existsSync(p)) {
+        puppeteer = require(p);
+        break;
+      }
+    } catch {
+      /* try next */
+    }
+  }
+  if (puppeteer) break;
+}
+if (!puppeteer) {
+  console.error(
+    "[measure] could not locate puppeteer — set HYPERFRAMES_ROOT to a built hyperframes checkout",
+  );
+  process.exit(3);
+}
+
+// Resolve hyperframes' bundled GSAP. The templates load GSAP from a CDN
+// (cdn.jsdelivr.net), but in headless Chromium that request can be slow or
+// blocked — the page's inline `gsap.timeline()` then throws "gsap is not
+// defined" and the occlusion gate hard-fails. We inject this local copy on
+// every new document (before any page script runs) so window.gsap always
+// exists, and abort the CDN request so the parser never stalls on it. The
+// render path is unaffected — this is measurement-only.
+let gsapSource = null;
+for (const root of HF_ROOTS) {
+  const cands = [path.join(root, "node_modules", "gsap", "dist", "gsap.min.js")];
+  const bunDir = path.join(root, "node_modules", ".bun");
+  try {
+    if (fs.existsSync(bunDir)) {
+      for (const d of fs.readdirSync(bunDir)) {
+        if (d.startsWith("gsap@"))
+          cands.push(path.join(bunDir, d, "node_modules", "gsap", "dist", "gsap.min.js"));
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  for (const p of cands) {
+    try {
+      if (fs.existsSync(p)) {
+        gsapSource = fs.readFileSync(p, "utf8");
+        break;
+      }
+    } catch {
+      /* try next */
+    }
+  }
+  if (gsapSource) break;
+}
+
+async function main() {
+  const projectDir = process.argv[2];
+  if (!projectDir) {
+    console.error("usage: measure-layout.cjs <project-dir> [t1 t2 ...]");
+    process.exit(1);
+  }
+  const indexPath = path.resolve(projectDir, "index.html");
+  if (!fs.existsSync(indexPath)) {
+    console.error(`[measure] missing ${indexPath} — run make-composition.cjs first`);
+    process.exit(2);
+  }
+
+  // Load plan to get groups + sample times
+  const planPath = path.join(projectDir, "plan.json");
+  let plan = null;
+  if (fs.existsSync(planPath)) plan = JSON.parse(fs.readFileSync(planPath, "utf8"));
+
+  // Determine sample times: per group, sample multiple points across [in, out]
+  // (catches subject motion within block, multi-frame validation).
+  const explicitTimes = process.argv.slice(3).map(Number).filter(Number.isFinite);
+  let sampleTimes = explicitTimes;
+  if (sampleTimes.length === 0 && plan?.groups) {
+    const allTimes = new Set();
+    for (const g of plan.groups) {
+      const dur = g.out - g.in;
+      // 4 samples per group: 15%, 40%, 65%, 90% through window — covers entry/peak/exit
+      [0.15, 0.4, 0.65, 0.9].forEach((p) => allTimes.add(+(g.in + dur * p).toFixed(3)));
+    }
+    sampleTimes = [...allTimes].sort((a, b) => a - b);
+  }
+
+  // Match render-and-composite's Chrome detection
+  const exe =
+    process.platform === "darwin"
+      ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+      : "/usr/bin/google-chrome";
+
+  const W = plan?.width || 720;
+  const H = plan?.height || 1290;
+  const FPS = plan?.fps || 24;
+
+  const browser = await puppeteer.launch({
+    headless: "new",
+    executablePath: fs.existsSync(exe) ? exe : undefined,
+    args: [
+      "--disable-web-security",
+      "--allow-file-access-from-files",
+      `--window-size=${W},${H}`,
+      "--disable-dev-shm-usage",
+    ],
+  });
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: W, height: H, deviceScaleFactor: 1 });
+    page.on("pageerror", (err) => console.error(`[browser-error] ${err.message}`));
+
+    // Inject local GSAP before any page script + abort the CDN <script> so the
+    // page never depends on network for GSAP (see resolver note above). Falls
+    // back to the page's own CDN load if no local copy was found.
+    if (gsapSource) {
+      await page.evaluateOnNewDocument(gsapSource);
+      await page.setRequestInterception(true);
+      page.on("request", (req) => {
+        const u = req.url();
+        if (req.resourceType() === "script" && /gsap/i.test(u) && /^https?:/i.test(u)) req.abort();
+        else req.continue();
+      });
+    }
+
+    await page.goto(`file://${indexPath}`, { waitUntil: "load", timeout: 15000 });
+    // GSAP is injected locally above; poll for the page's timeline registration.
+    const start = Date.now();
+    let ready = false;
+    while (Date.now() - start < 15000) {
+      const r = await page.evaluate(() => !!(window.__timelines && window.__timelines.main));
+      if (r) {
+        ready = true;
+        break;
+      }
+      await new Promise((res) => setTimeout(res, 200));
+    }
+    if (!ready) {
+      console.error("[measure] GSAP timeline never registered");
+      process.exit(4);
+    }
+    // Inject the skill's bundled @font-face set so headless Chromium measures the SAME
+    // glyph metrics the renderer will use. Without this, Inter/etc fall back to system
+    // fonts here while the real render uses the true (often wider) face → wrapped line
+    // counts differ → slot layout / occlusion verdicts are measured on the wrong text.
+    try {
+      const fontsCss = path.join(__dirname, "..", "modes", "standard", "fonts", "fonts.css");
+      if (fs.existsSync(fontsCss))
+        await page.addStyleTag({ content: fs.readFileSync(fontsCss, "utf8") });
+    } catch {
+      /* best-effort — fonts.css missing just reverts to old behavior */
+    }
+    // let webfonts settle so measured glyph metrics match the render
+    await page.evaluate(async () => {
+      try {
+        await document.fonts.ready;
+      } catch {}
+    });
+
+    const samples = [];
+    for (const t of sampleTimes) {
+      // Seek timeline
+      await page.evaluate((t) => {
+        const tl = window.__timelines.main;
+        tl.seek(t);
+        // Force layout flush
+        void document.body.offsetHeight;
+      }, t);
+      // Tiny settle for animations / fonts
+      await new Promise((r) => setTimeout(r, 30));
+
+      // Measure every .cap and its .w children
+      const measurements = await page.evaluate(() => {
+        const caps = [...document.querySelectorAll(".cap")];
+        const out = [];
+        for (const cap of caps) {
+          const cs = getComputedStyle(cap);
+          if (cs.opacity === "0" || cs.display === "none") continue;
+          const cb = cap.getBoundingClientRect();
+          if (cb.width === 0 || cb.height === 0) continue;
+          const id = cap.id || "";
+          const layer = cap.dataset.layer || "";
+          // Per-line via Range over all word spans
+          const ws = [...cap.querySelectorAll(".w")];
+          const words = [];
+          for (const w of ws) {
+            const wcs = getComputedStyle(w);
+            if (wcs.opacity === "0") continue; // not yet animated in
+            const wb = w.getBoundingClientRect();
+            if (wb.width === 0) continue;
+            words.push({
+              text: w.textContent,
+              x: +wb.x.toFixed(1),
+              y: +wb.y.toFixed(1),
+              w: +wb.width.toFixed(1),
+              h: +wb.height.toFixed(1),
+              opacity: +wcs.opacity,
+            });
+          }
+          // Group by line (same y ± 2px)
+          const lines = [];
+          for (const w of words) {
+            const line = lines.find((l) => Math.abs(l.y - w.y) < 3);
+            if (line) {
+              line.words.push(w);
+              line.x = Math.min(line.x, w.x);
+              line.w = Math.max(line.x + line.w, w.x + w.w) - line.x;
+              line.h = Math.max(line.h, w.h);
+            } else {
+              lines.push({ x: w.x, y: w.y, w: w.w, h: w.h, words: [w] });
+            }
+          }
+          out.push({
+            id,
+            layer,
+            cap_bbox: {
+              x: +cb.x.toFixed(1),
+              y: +cb.y.toFixed(1),
+              w: +cb.width.toFixed(1),
+              h: +cb.height.toFixed(1),
+            },
+            opacity: +cs.opacity,
+            lines,
+            words, // also keep flat list
+          });
+        }
+        return out;
+      });
+      const frame_idx = Math.max(1, Math.round(t * FPS));
+      samples.push({ t, frame_idx, caps: measurements });
+    }
+
+    const layout = { width: W, height: H, fps: FPS, samples };
+    const outPath = path.join(projectDir, "_layout.json");
+    fs.writeFileSync(outPath, JSON.stringify(layout, null, 2));
+    console.log(
+      `[measure] wrote ${outPath} (${sampleTimes.length} sample frames, ${samples.reduce((a, s) => a + s.caps.length, 0)} cap measurements)`,
+    );
+  } finally {
+    // Chromium occasionally hangs on shutdown. This script runs synchronously
+    // inside check-occlusion.cjs, which the render gate blocks on — a hung close
+    // would wedge the whole render. Cap the close, then force-exit below.
+    await Promise.race([browser.close().catch(() => {}), new Promise((r) => setTimeout(r, 8000))]);
+  }
+}
+
+// Force a hard exit so a lingering Chromium/libuv handle can't keep the process
+// (and the render gate that spawned it) alive indefinitely.
+main()
+  .then(() => process.exit(0))
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });

package/.agents/skills/embedded-captions/scripts/prepare.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# prepare.sh — one-command pre-processing for a captions project.
+#
+#   bash prepare.sh <project-dir>
+#
+# Runs the three deterministic pre-steps with maximum parallelism:
+#   matte.cjs (CPU-heavy ONNX)  ∥  transcribe.cjs (whisper)   → then safe-zones.cjs
+# (matte and transcribe are independent; safe-zones needs the matte's frames_fg.)
+# Replaces hand-running steps 2 / 3 / 3b — one call, nothing forgotten, ~the cost
+# of the slower of the two instead of their sum.
+#
+# After this completes the project has: frames_bg/ frames_fg/ matte.fps
+# transcript.json safe-zones.json — everything the authoring step needs.
+set -euo pipefail
+
+PROJECT="${1:?usage: prepare.sh <project-dir>}"
+PROJECT="$(cd "$PROJECT" && pwd)"
+SD="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "[prepare] matte ∥ transcribe ∥ envelope …"
+MLOG="$PROJECT/_prepare_matte.log"; TLOG="$PROJECT/_prepare_transcribe.log"; ELOG="$PROJECT/_prepare_envelope.log"
+node "$SD/matte.cjs" "$PROJECT"      > "$MLOG" 2>&1 &  MPID=$!
+node "$SD/transcribe.cjs" "$PROJECT" > "$TLOG" 2>&1 &  TPID=$!
+node "$SD/audio-envelope.cjs" "$PROJECT" > "$ELOG" 2>&1 &  EPID=$!
+
+MRC=0; TRC=0
+wait "$MPID" || MRC=$?
+wait "$TPID" || TRC=$?
+wait "$EPID" || echo "[prepare] (envelope skipped — hero amplitude falls back to neutral)" >&2
+# surface both logs (they contain the guards' warnings — near-silent audio, tail trim)
+sed 's/^/  [matte] /'      "$MLOG" | tail -6
+sed 's/^/  [transcribe] /' "$TLOG" | tail -12
+if (( MRC != 0 )); then echo "[prepare] matte FAILED (rc=$MRC) — see $MLOG" >&2; exit "$MRC"; fi
+if (( TRC != 0 )); then echo "[prepare] transcribe FAILED (rc=$TRC) — see $TLOG" >&2; exit "$TRC"; fi
+
+echo "[prepare] safe-zones …"
+node "$SD/safe-zones.cjs" "$PROJECT"
+
+echo "[prepare] ✅ ready: frames_fg/ transcript.json safe-zones.json — author next (see SKILL.md step 4)"