@mevdragon/vidfarm-devcli 0.14.0 → 0.15.0

package/dist/src/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { copyFileSync, createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, createWriteStream, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
@@ -13,7 +13,13 @@ import { runCaptionsCommand } from "./devcli/captions.js";
 import { runClipsCommand } from "./devcli/clips.js";
 import { runTransitionsCommand } from "./devcli/transitions.js";
 import { MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES, loadSpeechAudioLocally, localGenerateSpeech, localTranscribeSpeech, resolveLocalSpeechAuth } from "./devcli/speech.js";
-import { inferSpeechProviderForVoice } from "./services/speech.js";
+import { buildSrtFromSegments, inferSpeechProviderForVoice } from "./services/speech.js";
+import { formatCompositionLintIssues, lintCompositionHtml } from "./services/composition-lint.js";
+import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
+import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
+import { renderCompositionStills } from "./devcli/stills.js";
+import { runDoctorCommand } from "./devcli/doctor.js";
+import { runSkillsCommand } from "./devcli/skills.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
 // `serve` command boots the FULL editor locally (single origin, disk-backed
@@ -189,6 +195,9 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
                               a voice from the wrong provider family is rejected with a clear error.
     --out <file>              Output audio path (default tts-<id>.mp3|wav)
     --provider <p> --model <m> --format mp3|wav
+    --engine local            KEYLESS local Kokoro-82M engine (free, no account) — fixed voice
+                              presets (af_heart, am_adam, bf_emma, …), no --style. When NO
+                              provider key is found the default byok engine auto-falls back here.
     --cloud                   BACKUP: saved-key platform job   → POST /api/v1/primitives/audio/speech (+ poll)
   stt <file|url>            Video or audio → transcript (alias: transcribe).  LOCAL: local ffmpeg demux +
                             Returns BOTH formats: the simple subtitle    your provider key (gemini labels
@@ -200,6 +209,10 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
     --language <code>         Expected language hint (e.g. en, es)
     --prompt "<context>"      Domain/vocabulary hint for the transcriber
     --provider <p> --model <m>
+    --engine whisper          KEYLESS local whisper.cpp engine (free, no account) — WORD-level
+                              timestamps (words[] in the .json/--json output), no speaker labels.
+                              When NO provider key is found the default byok engine auto-falls
+                              back here. --model then picks the whisper model (tiny.en…large-v3).
     --cloud                   BACKUP: saved-key platform job   → POST /api/v1/primitives/audio/transcribe (+ poll)
                               (a local file uploads to your temp folder first — 30-day TTL)
 
@@ -233,6 +246,37 @@ Scene transitions (between clips on a pulled/served composition — local file w
   clone <forkId>            Clone a fork as a new starting point         → POST .../compositions/:forkId/clone
   share-link <forkId>       Mint a share-token URL for a fork            → POST .../compositions/:forkId/share-links
 
+Local media engines & toolchain (all local, free, no account — no cloud key needed):
+  remove-background <file|url>  Cut the background out of a video/image   (local ONNX — free, no account)
+                            → transparent WebM (video) / PNG (image)
+    --out <path>              Output path .webm|.mov|.png (default <name>.transparent.webm|.png)
+    --background-out <path>   Also write the inverse background plate (.webm|.mov)
+  capture <url>             Capture a website: screenshots + assets +     (local headless Chrome — free,
+                            video manifest, for site-to-video work        no account)
+    --out <dir>               Output directory (default ./capture)
+    --max-screenshots <n> --timeout <ms> --skip-assets
+  beats <audioFile|url>     Detect musical beats → timestamps JSON to     (local — free, no account)
+                            sync transitions/captions timing against
+    --out <path>              Output JSON path (default <audio>.beats.json)
+  lint <dir|composition.html>   Validate a composition on disk (same      (local)
+                            checks the /editor chat preflights); prints
+                            errors/warnings, exit 1 on errors [--json]
+  stills <dir|composition.html>   Render PNG stills of the CURRENT        (local in-process render)
+                            composition — the visual self-check loop
+                            ("did my edit look right") without a full render
+    --at 0,2.5,7              Timestamps (default: midpoint of each scene clip, cap 8)
+    --out <dir>               Output dir (default <dir>/stills)
+  doctor                    Health-check the local toolchain: node,       (local)
+                            ffmpeg, hyperframes engines, Chrome, API key
+                            (whoami), provider keys, agent CLI, poisoned
+                            env, port 3000, installed skills [--json]
+  skills <list|add <names…>|update>   Install/refresh agent skills into   → GET /skill-pack/* (or the
+                            <root>/.agents/skills/<name> + a relative      copies bundled in this repo)
+                            .claude/skills symlink; skills-lock.json is
+                            merged, never clobbered [--json]
+    --dir <root>              Project root (default: walk up from cwd to .agents/skills or .git)
+    --host <url>              Skill-pack host (default VIDFARM_SKILLS_HOST/VIDFARM_HOST or ${DEFAULT_HOST})
+
 Approve & schedule (publish a finished MP4 as a shareable post):
   approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
     --video <url|file>      Primary MP4 (URL, or a local file auto-uploaded to temp/)
@@ -493,6 +537,30 @@ async function main() {
         case "transitions":
             await runTransitionsCommand(rest);
             return;
+        // Local media engines + toolchain (bundled HyperFrames local commands —
+        // free, no account — plus vidfarm-native lint/stills/doctor/skills).
+        case "remove-background":
+        case "rmbg":
+            await runRemoveBackgroundCommand(rest);
+            return;
+        case "capture":
+            await runCaptureCommand(rest);
+            return;
+        case "beats":
+            await runBeatsCommand(rest);
+            return;
+        case "lint":
+            await runLintCommand(rest);
+            return;
+        case "stills":
+            await runStillsCommand(rest);
+            return;
+        case "doctor":
+            await runDoctorCommand(rest);
+            return;
+        case "skills":
+            await runSkillsCommand(rest);
+            return;
         default:
             if (!command.startsWith("-")) {
                 // Positional template id → default to booting the local editor.
@@ -669,6 +737,10 @@ async function runServeCommand(argv) {
     process.env.PORT = String(port);
     if (!process.env.NODE_ENV)
         process.env.NODE_ENV = "development";
+    // Harden any hyperframes tooling the serve runtime (or its children) may
+    // shell out to: no telemetry pings, no skill-install prompts.
+    process.env.HYPERFRAMES_NO_TELEMETRY ||= "1";
+    process.env.HYPERFRAMES_SKIP_SKILLS ||= "1";
     // Cloud passthrough: only the editor is local — /discover and /library keep
     // listing the upstream (cloud) catalog, templates seed onto disk on demand,
     // and the editor's Render button can hand off to the cloud renderer. The
@@ -2218,6 +2290,7 @@ async function runTtsCommand(argv) {
             model: { type: "string" },
             format: { type: "string" },
             out: { type: "string" },
+            engine: { type: "string" },
             cloud: { type: "boolean", default: false },
             "gemini-key": { type: "string" },
             "openai-key": { type: "string" },
@@ -2230,19 +2303,48 @@ async function runTtsCommand(argv) {
     if (!text)
         throw new Error('tts requires text: vidfarm tts "Welcome back to the channel" --style "calm, warm narrator".');
     const style = (parsed.values.instructions ?? parsed.values.style)?.trim() || undefined;
-    const rawFormat = String(parsed.values.format ?? "mp3").toLowerCase();
+    const explicitFormat = parsed.values.format?.trim().toLowerCase();
+    const rawFormat = explicitFormat ?? "mp3";
     if (rawFormat !== "mp3" && rawFormat !== "wav")
         throw new Error("tts --format must be mp3 or wav.");
     const format = rawFormat;
     const voice = parsed.values.voice;
     const json = Boolean(parsed.values.json);
-    if (!parsed.values.cloud) {
+    // Engine selection: byok (default — the user's own provider key), local
+    // (keyless Kokoro-82M via the bundled hyperframes engine — free, no
+    // account), cloud (the platform primitive job, same as --cloud).
+    const engine = parsed.values.engine?.trim().toLowerCase();
+    if (engine && engine !== "local" && engine !== "byok" && engine !== "cloud") {
+        throw new Error("tts --engine must be local (keyless Kokoro), byok (your provider key — default), or cloud.");
+    }
+    const wantCloud = Boolean(parsed.values.cloud) || engine === "cloud";
+    if (engine === "local") {
+        await runLocalKokoroTts({ text, voice, style, out: parsed.values.out, format: explicitFormat, json });
+        return;
+    }
+    if (!wantCloud) {
         // A Gemini voice preset ("Kore", "Puck", …) should find a Gemini-capable
         // key first — openrouter's default TTS model is Gemini-family too.
-        const keyPreference = inferSpeechProviderForVoice(voice) === "gemini" ? ["gemini", "openrouter", "openai"] : ["openai", "gemini", "openrouter"];
+        const voiceProvider = inferSpeechProviderForVoice(voice);
+        const keyPreference = voiceProvider === "gemini" ? ["gemini", "openrouter", "openai"] : ["openai", "gemini", "openrouter"];
         const auth = resolveLocalSpeechAuth(parsed.values, keyPreference, parsed.values.provider);
-        if (!auth)
-            throw new Error(speechKeyHint("tts"));
+        if (!auth) {
+            // EXPLICIT intent (--provider, or a provider voice preset like "alloy"/
+            // "Kore") must never be silently downgraded to Kokoro — hard-error with
+            // the key hint so the user knows the named provider was not used.
+            const requestedProvider = parsed.values.provider?.trim();
+            if (requestedProvider || voiceProvider) {
+                const wanted = requestedProvider ?? `${voiceProvider} (implied by --voice "${voice}")`;
+                throw new Error(`tts: provider ${wanted} was requested but no matching key is configured. ${speechKeyHint("tts")}`);
+            }
+            // Keyless fallback (no explicit provider/voice): rather than erroring
+            // (speechKeyHint), speak through the local Kokoro engine so agents
+            // always get audio out of the box.
+            if (!json)
+                console.log(`${DIM}No provider key found — using the local Kokoro engine; pass --engine cloud + a key for BYOK voices. (${speechKeyHint("tts")})${RESET}`);
+            await runLocalKokoroTts({ text, voice, style, out: parsed.values.out, format: explicitFormat, json, fallback: true });
+            return;
+        }
         if (!json)
             console.log(`${DIM}Generating speech locally on your ${auth.provider} key…${RESET}`);
         const result = await localGenerateSpeech({
@@ -2312,6 +2414,52 @@ async function runTtsCommand(argv) {
         console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(${mediaUrl})${RESET}`);
     }
 }
+// Keyless local TTS via the bundled hyperframes engine (Kokoro-82M ONNX —
+// free, no account, no HeyGen). Used by `--engine local` and as the automatic
+// fallback when no provider key is configured. Kokoro emits WAV natively; an
+// mp3 request transcodes through the bundled ffmpeg.
+async function runLocalKokoroTts(input) {
+    const wantMp3 = input.format === "mp3" || /\.mp3(\?|#|$)/i.test(input.out ?? "");
+    // Kokoro voice ids look like af_heart / am_adam / bf_emma. A provider voice
+    // (openai "alloy", gemini "Kore") passed through the fallback path would
+    // just error — drop it to the default with a note instead.
+    let voice = input.voice?.trim() || undefined;
+    if (voice && !/^[a-z]{2}_[a-z0-9]+$/i.test(voice)) {
+        if (!input.json)
+            console.log(`${DIM}Voice "${voice}" is a provider voice — the local Kokoro engine has its own presets (af_heart, af_nova, am_adam, bf_emma, …). Using the default voice.${RESET}`);
+        voice = undefined;
+    }
+    if (input.style && !input.json) {
+        console.log(`${DIM}Note: --style voice direction is BYOK-only; the local Kokoro engine uses fixed voice presets.${RESET}`);
+    }
+    const outPath = path.resolve(process.cwd(), input.out ?? `tts-${Date.now().toString(36)}.${wantMp3 ? "mp3" : "wav"}`);
+    mkdirSync(path.dirname(outPath), { recursive: true });
+    const wavPath = wantMp3 ? path.join(mkdtempSync(path.join(tmpdir(), "vidfarm-tts-")), "speech.wav") : outPath;
+    if (!input.json)
+        console.log(`${DIM}Generating speech with the local Kokoro-82M engine (free, no account)…${RESET}`);
+    const run = await runHyperframesCommand("tts", [input.text, "-o", wavPath, ...(voice ? ["-v", voice] : [])], { stdio: input.json ? "capture" : "inherit" });
+    if (run.code !== 0 || !existsSync(wavPath)) {
+        const detail = run.stderr.trim().split("\n").pop() ?? "";
+        throw new Error(`local Kokoro tts failed (exit ${run.code})${detail ? `: ${detail}` : " — see the engine output above"}. ` +
+            "First use needs `pip install kokoro-onnx soundfile` and downloads the model (~340MB); or pass a provider key for BYOK tts.");
+    }
+    if (wantMp3) {
+        const ffmpeg = await resolveFfmpeg();
+        const transcode = spawnSync(ffmpeg, ["-y", "-hide_banner", "-loglevel", "error", "-i", wavPath, "-b:a", "128k", outPath], { stdio: "ignore" });
+        rmSync(path.dirname(wavPath), { recursive: true, force: true });
+        if (transcode.status !== 0 || !existsSync(outPath)) {
+            throw new Error("ffmpeg mp3 transcode failed after local TTS — pass --format wav to keep the native WAV.");
+        }
+    }
+    const bytes = safeSize(outPath);
+    if (input.json) {
+        printJson({ ok: true, mode: "local-engine", engine: "kokoro-82m", provider: null, voice: voice ?? "af_heart", fallback: Boolean(input.fallback), content_type: wantMp3 ? "audio/mpeg" : "audio/wav", bytes, out: outPath });
+    }
+    else {
+        console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(local Kokoro-82M — free, no account, ${formatBytes(bytes)})${RESET}`);
+        console.log(`${DIM}Get a shareable URL with: vidfarm upload "${outPath}" — then add it to a composition as an audio layer.${RESET}`);
+    }
+}
 function formatSpeechClock(totalSeconds) {
     const minutes = Math.floor(totalSeconds / 60);
     const seconds = Math.floor(totalSeconds % 60);
@@ -2339,7 +2487,8 @@ function emitSttResult(input) {
                     diarization: input.result.diarization,
                     text: input.result.text,
                     speakers: [...new Set((input.result.segments ?? []).map((segment) => segment.speaker))],
-                    segments: input.result.segments ?? []
+                    segments: input.result.segments ?? [],
+                    ...(input.result.words ? { words: input.result.words } : {})
                 }, null, 2)}\n`);
                 written.push(dest);
             }
@@ -2372,6 +2521,7 @@ function emitSttResult(input) {
             diarization: input.result.diarization,
             text: input.result.text,
             segments: input.result.segments ?? [],
+            ...(input.result.words ? { words: input.result.words } : {}),
             srt: input.result.srt,
             written
         });
@@ -2402,6 +2552,7 @@ async function runSttCommand(argv) {
             provider: { type: "string" },
             model: { type: "string" },
             out: { type: "string" },
+            engine: { type: "string" },
             cloud: { type: "boolean", default: false },
             "gemini-key": { type: "string" },
             "openai-key": { type: "string" },
@@ -2418,10 +2569,42 @@ async function runSttCommand(argv) {
     const json = Boolean(parsed.values.json);
     const language = parsed.values.language?.trim() || undefined;
     const prompt = parsed.values.prompt?.trim() || undefined;
-    if (!parsed.values.cloud) {
+    // Engine selection: byok (default — the user's own provider key), whisper
+    // (keyless local whisper.cpp via the bundled hyperframes engine — word-level
+    // timestamps, free, no account), cloud (the platform primitive job).
+    const engine = parsed.values.engine?.trim().toLowerCase();
+    if (engine && engine !== "whisper" && engine !== "byok" && engine !== "cloud") {
+        throw new Error("stt --engine must be whisper (keyless local whisper.cpp), byok (your provider key — default), or cloud.");
+    }
+    const wantCloud = Boolean(parsed.values.cloud) || engine === "cloud";
+    if (engine === "whisper") {
+        await runLocalWhisperStt({
+            target,
+            out: parsed.values.out,
+            json,
+            language,
+            model: parsed.values.model
+        });
+        return;
+    }
+    if (!wantCloud) {
         const auth = resolveLocalSpeechAuth(parsed.values, ["gemini", "openai", "openrouter"], parsed.values.provider);
-        if (!auth)
-            throw new Error(speechKeyHint("stt"));
+        if (!auth) {
+            // EXPLICIT intent (--provider) must never be silently downgraded to the
+            // local whisper engine (no speaker labels, different quality) — hard-error
+            // with the key hint so the user knows the named provider was not used.
+            const requestedProvider = parsed.values.provider?.trim();
+            if (requestedProvider) {
+                throw new Error(`stt: provider ${requestedProvider} was requested but no matching key is configured. ${speechKeyHint("stt")}`);
+            }
+            // Keyless fallback (no explicit provider): rather than erroring
+            // (speechKeyHint), transcribe with the local whisper.cpp engine (word
+            // timestamps, no speaker labels).
+            if (!json)
+                console.log(`${DIM}No provider key found — using the local whisper.cpp engine; pass --engine cloud + a key for BYOK transcription (gemini adds speaker labels). (${speechKeyHint("stt")})${RESET}`);
+            await runLocalWhisperStt({ target, out: parsed.values.out, json, language, fallback: true });
+            return;
+        }
         if (diarize && auth.provider !== "gemini" && !json) {
             console.log(`${DIM}Note: speaker labels need a Gemini key; ${auth.provider} returns a plain single-speaker transcript.${RESET}`);
         }
@@ -2534,6 +2717,108 @@ async function runSttCommand(argv) {
         }
     });
 }
+// Group whisper's word-level timings into subtitle-sized segments (new cue on
+// a >0.8s silence gap, sentence-ending punctuation, or 12 words) so the
+// existing SttEmitInput/SRT plumbing consumes whisper output unchanged.
+function groupWhisperWordsIntoSegments(words) {
+    const segments = [];
+    let current = null;
+    const flush = () => {
+        if (!current || current.parts.length === 0)
+            return;
+        segments.push({
+            speaker: "speaker_1",
+            start_sec: Number(current.start.toFixed(3)),
+            end_sec: Number(current.end.toFixed(3)),
+            text: current.parts.join(" ").replace(/\s+/g, " ").trim()
+        });
+        current = null;
+    };
+    for (const word of words) {
+        if (!word || typeof word.text !== "string" || !Number.isFinite(word.start) || !Number.isFinite(word.end))
+            continue;
+        const endsSentence = current ? /[.!?]["')\]]?$/.test(current.parts[current.parts.length - 1] ?? "") : false;
+        if (current && (word.start - current.end > 0.8 || current.parts.length >= 12 || endsSentence))
+            flush();
+        if (!current)
+            current = { start: word.start, end: word.end, parts: [] };
+        current.parts.push(word.text.trim());
+        current.end = Math.max(current.end, word.end);
+    }
+    flush();
+    return segments;
+}
+// Keyless local STT via the bundled hyperframes engine (whisper.cpp — word-level
+// timestamps, free, no account, no HeyGen). Used by `--engine whisper` and as
+// the automatic fallback when no provider key is configured. IMPORTANT: the
+// hyperframes transcribe command writes transcript.json into --dir AND patches
+// `const script = [...]` blocks in any HTML under that dir, so it always runs
+// against a fresh temp dir here — never the user's own directory.
+async function runLocalWhisperStt(input) {
+    let localPath = input.target;
+    let downloadDir = null;
+    if (/^https?:\/\//i.test(input.target)) {
+        downloadDir = mkdtempSync(path.join(tmpdir(), "vidfarm-whisper-dl-"));
+        localPath = path.join(downloadDir, path.basename(new URL(input.target).pathname) || "media.bin");
+        if (!input.json)
+            console.log(`${DIM}Downloading source for the local whisper engine…${RESET}`);
+        await downloadUrlToFile(input.target, localPath);
+    }
+    const absPath = path.resolve(process.cwd(), localPath);
+    if (!existsSync(absPath))
+        throw new Error(`No such local file: ${absPath}`);
+    const workDir = mkdtempSync(path.join(tmpdir(), "vidfarm-whisper-"));
+    try {
+        if (!input.json)
+            console.log(`${DIM}Transcribing with the local whisper.cpp engine (word-level timestamps — free, no account)…${RESET}`);
+        const run = await runHyperframesCommand("transcribe", [
+            absPath,
+            "--dir", workDir,
+            "--json",
+            ...(input.language ? ["--language", input.language] : []),
+            ...(input.model ? ["--model", input.model] : [])
+        ], { stdio: "capture" });
+        const summary = parseHyperframesJson(run.stdout) ?? parseHyperframesJson(run.stderr);
+        if (run.code !== 0 || summary?.ok === false) {
+            const reason = (typeof summary?.error === "string" && summary.error)
+                || (typeof summary?.reason === "string" && summary.reason)
+                || run.stderr.trim().split("\n").pop()
+                || "";
+            throw new Error(`local whisper transcription failed${reason ? `: ${reason}` : ""}. First run downloads whisper.cpp + the model — check network/disk, or pass a provider key for BYOK stt.`);
+        }
+        const transcriptPath = typeof summary?.transcriptPath === "string" && existsSync(summary.transcriptPath)
+            ? summary.transcriptPath
+            : path.join(workDir, "transcript.json");
+        if (!existsSync(transcriptPath))
+            throw new Error("local whisper transcription produced no transcript.json.");
+        const words = JSON.parse(readFileSync(transcriptPath, "utf8"))
+            .filter((word) => word && typeof word.text === "string" && Number.isFinite(word.start) && Number.isFinite(word.end))
+            .map((word) => ({ text: String(word.text).trim(), start: Number(word.start), end: Number(word.end) }));
+        const segments = groupWhisperWordsIntoSegments(words);
+        const text = words.map((word) => word.text).join(" ").replace(/\s+/g, " ").trim();
+        emitSttResult({
+            json: input.json,
+            out: input.out,
+            source: input.target,
+            mode: "local",
+            provider: "whisper.cpp",
+            model: (typeof summary?.model === "string" && summary.model) || input.model || "small.en",
+            result: {
+                text,
+                language: input.language ?? null,
+                diarization: "none",
+                segments,
+                srt: buildSrtFromSegments(segments),
+                words
+            }
+        });
+    }
+    finally {
+        rmSync(workDir, { recursive: true, force: true });
+        if (downloadDir)
+            rmSync(downloadDir, { recursive: true, force: true });
+    }
+}
 async function runPlaceCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -3092,6 +3377,238 @@ async function runPutFileCommand(argv) {
     assertApiOk(result, "put-file");
     emitResult(result, ctx.json, [["My Files URL", result.json?.attachment?.viewUrl]]);
 }
+// ── Local media engines + toolchain ─────────────────────────────────────────
+// Wrappers over the bundled hyperframes LOCAL commands (free, no account, no
+// HeyGen — see src/devcli/hyperframes-cli.ts for the account/telemetry guard)
+// plus vidfarm-native lint/stills. These give a local coding agent the full
+// media toolchain without any cloud credential.
+// `vidfarm remove-background <file|url>` → transparent WebM (video) or PNG
+// (image) via the local ONNX matting model.
+async function runRemoveBackgroundCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            out: { type: "string" },
+            "background-out": { type: "string" },
+            device: { type: "string" },
+            quality: { type: "string" },
+            json: { type: "boolean", default: false }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("remove-background requires a source: `vidfarm remove-background <video-or-image file|url> [--out <path>]`.");
+    const json = Boolean(parsed.values.json);
+    let localPath = target;
+    let downloadDir = null;
+    if (/^https?:\/\//i.test(target)) {
+        downloadDir = mkdtempSync(path.join(tmpdir(), "vidfarm-rmbg-dl-"));
+        localPath = path.join(downloadDir, path.basename(new URL(target).pathname) || "media.bin");
+        if (!json)
+            console.log(`${DIM}Downloading source…${RESET}`);
+        await downloadUrlToFile(target, localPath);
+    }
+    const absPath = path.resolve(process.cwd(), localPath);
+    if (!existsSync(absPath))
+        throw new Error(`No such local file: ${absPath}`);
+    const isImage = /\.(png|jpe?g|webp)(\?|#|$)/i.test(absPath);
+    const stem = path.basename(absPath).replace(/\.[^.]+$/, "");
+    const outPath = path.resolve(process.cwd(), parsed.values.out ?? `${stem}.transparent.${isImage ? "png" : "webm"}`);
+    mkdirSync(path.dirname(outPath), { recursive: true });
+    try {
+        if (!json)
+            console.log(`${DIM}Removing background with the local ONNX matting model (free, no account)…${RESET}`);
+        const run = await runHyperframesCommand("remove-background", [
+            absPath,
+            "-o", outPath,
+            ...(parsed.values["background-out"] ? ["--background-output", path.resolve(process.cwd(), String(parsed.values["background-out"]))] : []),
+            ...(parsed.values.device ? ["--device", String(parsed.values.device)] : []),
+            ...(parsed.values.quality ? ["--quality", String(parsed.values.quality)] : []),
+            ...(json ? ["--json"] : [])
+        ], { stdio: json ? "capture" : "inherit" });
+        if (run.code !== 0 || !existsSync(outPath)) {
+            const summary = parseHyperframesJson(run.stdout) ?? parseHyperframesJson(run.stderr);
+            const reason = (typeof summary?.error === "string" && summary.error) || run.stderr.trim().split("\n").pop() || "";
+            throw new Error(`remove-background failed (exit ${run.code})${reason ? `: ${reason}` : ""}.`);
+        }
+        if (json) {
+            const summary = parseHyperframesJson(run.stdout);
+            printJson({ ok: true, mode: "local-engine", source: target, out: outPath, bytes: safeSize(outPath), ...(summary ?? {}) });
+        }
+        else {
+            console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(${formatBytes(safeSize(outPath))} — drop it on a composition with \`vidfarm place <dir> --src ${outPath}\`)${RESET}`);
+        }
+    }
+    finally {
+        if (downloadDir)
+            rmSync(downloadDir, { recursive: true, force: true });
+    }
+}
+// `vidfarm capture <url>` → screenshots + assets + video manifest of a website
+// via local headless Chrome (for website-to-video style workflows).
+async function runCaptureCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            out: { type: "string" },
+            "max-screenshots": { type: "string" },
+            timeout: { type: "string" },
+            "skip-assets": { type: "boolean", default: false },
+            json: { type: "boolean", default: false }
+        }
+    });
+    const url = parsed.positionals[0];
+    if (!url || !/^https?:\/\//i.test(url))
+        throw new Error("capture requires a website URL: `vidfarm capture <url> [--out <dir>]`.");
+    const json = Boolean(parsed.values.json);
+    const outDir = parsed.values.out ? path.resolve(process.cwd(), String(parsed.values.out)) : undefined;
+    const run = await runHyperframesCommand("capture", [
+        url,
+        ...(outDir ? ["-o", outDir] : []),
+        ...(parsed.values["max-screenshots"] ? ["--max-screenshots", String(parsed.values["max-screenshots"])] : []),
+        ...(parsed.values.timeout ? ["--timeout", String(parsed.values.timeout)] : []),
+        ...(parsed.values["skip-assets"] ? ["--skip-assets"] : []),
+        ...(json ? ["--json"] : [])
+    ], { stdio: json ? "capture" : "inherit" });
+    if (json) {
+        const summary = parseHyperframesJson(run.stdout);
+        printJson(summary ?? { ok: run.code === 0, out: outDir ?? null });
+    }
+    if (run.code !== 0) {
+        process.exitCode = 1;
+        if (!json)
+            console.log(`${RED}capture failed (exit ${run.code}).${RESET}`);
+    }
+}
+// `vidfarm beats <audioFile>` → beat-timestamp JSON an agent can feed into
+// transition/caption timing. The hyperframes beats command analyzes a PROJECT
+// dir's music track, so stage a throwaway project around the audio file.
+async function runBeatsCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            out: { type: "string" },
+            json: { type: "boolean", default: false }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("beats requires an audio file: `vidfarm beats <audioFile> [--out <path>]`.");
+    const json = Boolean(parsed.values.json);
+    let localPath = target;
+    let downloadDir = null;
+    if (/^https?:\/\//i.test(target)) {
+        downloadDir = mkdtempSync(path.join(tmpdir(), "vidfarm-beats-dl-"));
+        localPath = path.join(downloadDir, path.basename(new URL(target).pathname) || "audio.mp3");
+        if (!json)
+            console.log(`${DIM}Downloading audio…${RESET}`);
+        await downloadUrlToFile(target, localPath);
+    }
+    const absPath = path.resolve(process.cwd(), localPath);
+    if (!existsSync(absPath))
+        throw new Error(`No such local file: ${absPath}`);
+    const audioName = path.basename(absPath);
+    const stem = audioName.replace(/\.[^.]+$/, "");
+    const projectDir = mkdtempSync(path.join(tmpdir(), "vidfarm-beats-"));
+    try {
+        copyFileSync(absPath, path.join(projectDir, audioName));
+        // Minimal project whose music track is the given audio file (the beats
+        // command locates it via data-timeline-role="music").
+        writeFileSync(path.join(projectDir, "index.html"), `<!doctype html>\n<html><body data-composition-id="vidfarm-beats" data-width="720" data-height="1280" data-duration="1">` +
+            `<audio id="music" data-timeline-role="music" src="${audioName}" data-start="0" data-track-index="0"></audio>` +
+            `</body></html>\n`, "utf8");
+        if (!json)
+            console.log(`${DIM}Detecting beats locally (free, no account)…${RESET}`);
+        const run = await runHyperframesCommand("beats", [projectDir, "--json"], { stdio: "capture" });
+        const beatsDir = path.join(projectDir, "beats");
+        const beatsFile = existsSync(beatsDir)
+            ? readdirSync(beatsDir).filter((name) => name.toLowerCase().endsWith(".json")).map((name) => path.join(beatsDir, name))[0]
+            : undefined;
+        if (run.code !== 0 || !beatsFile) {
+            const summary = parseHyperframesJson(run.stdout) ?? parseHyperframesJson(run.stderr);
+            const reason = (typeof summary?.error === "string" && summary.error) || run.stderr.trim().split("\n").pop() || run.stdout.trim().split("\n").pop() || "";
+            throw new Error(`beat detection failed (exit ${run.code})${reason ? `: ${reason}` : ""}.`);
+        }
+        const beatsJson = JSON.parse(readFileSync(beatsFile, "utf8"));
+        const outPath = path.resolve(process.cwd(), parsed.values.out ?? `${stem}.beats.json`);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        writeFileSync(outPath, `${JSON.stringify(beatsJson, null, 2)}\n`, "utf8");
+        const beatCount = Array.isArray(beatsJson?.beats) ? beatsJson.beats.length : Array.isArray(beatsJson) ? beatsJson.length : null;
+        if (json) {
+            printJson({ ok: true, mode: "local-engine", source: target, out: outPath, beat_count: beatCount, beats: beatsJson });
+        }
+        else {
+            console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(${beatCount ?? "?"} beats — sync transitions/captions to these timestamps)${RESET}`);
+        }
+    }
+    finally {
+        rmSync(projectDir, { recursive: true, force: true });
+        if (downloadDir)
+            rmSync(downloadDir, { recursive: true, force: true });
+    }
+}
+// `vidfarm lint <dir|composition.html>` — static composition validation (the
+// same checks the /editor chat runs before accepting replacement HTML).
+async function runLintCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { json: { type: "boolean", default: false } }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("lint requires a composition path: `vidfarm lint <dir-or-composition.html>`.");
+    const htmlPath = resolveCompositionHtmlPath(target);
+    const result = lintCompositionHtml(readFileSync(htmlPath, "utf8"));
+    if (parsed.values.json) {
+        printJson(result);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    const formatted = formatCompositionLintIssues(result);
+    if (formatted)
+        console.log(formatted);
+    const mark = result.ok ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
+    console.log(`${mark} ${result.errors.length} error(s), ${result.warnings.length} warning(s) ${DIM}— ${htmlPath}${RESET}`);
+    if (!result.ok)
+        process.exitCode = 1;
+}
+// `vidfarm stills <dir|composition.html>` — render PNG stills of the CURRENT
+// composition in-process (the agent's visual self-verification loop).
+async function runStillsCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            at: { type: "string" },
+            out: { type: "string" },
+            json: { type: "boolean", default: false }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("stills requires a composition path: `vidfarm stills <dir-or-composition.html> [--at 0,2.5,7] [--out <dir>]`.");
+    const htmlPath = resolveCompositionHtmlPath(target);
+    const json = Boolean(parsed.values.json);
+    const at = parsed.values.at
+        ? String(parsed.values.at).split(",").map((value) => parseTimeToSeconds(value.trim())).filter((value) => Number.isFinite(value))
+        : undefined;
+    if (!json)
+        console.log(`${DIM}Rendering stills in-process (free, local Chrome capture)…${RESET}`);
+    const result = await renderCompositionStills({ htmlPath, at, outDir: parsed.values.out, quiet: json });
+    if (json) {
+        printJson(result);
+        return;
+    }
+    for (const still of result.stills) {
+        console.log(`  ${GREEN}${still.path}${RESET} ${DIM}(requested ${still.requested_sec}s → captured ${still.captured_sec}s)${RESET}`);
+    }
+    console.log(`${DIM}${result.stills.length} still(s) at ${result.grid_fps}fps grid accuracy — open them to verify the edit before rendering.${RESET}`);
+}
 // ── Agent skill ───────────────────────────────────────────────────────────────
 // Install the latest director skill onto disk as a Claude Code / agent skill so
 // the user's AI agent can read SKILL.director.md and act. We pull the freshest