@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/dist/src/devcli/stills.js

@@ -0,0 +1,249 @@
+// `vidfarm stills` — render PNG still frames of the CURRENT composition
+// in-process, without a full MP4 render. This is the coding agent's visual
+// self-verification loop: edit composition.html, render 3-8 stills, look at
+// them, iterate.
+//
+// Implementation mirrors HyperframesService.renderStill (src/services/
+// hyperframes.ts): stage the composition as a HyperFrames project dir, drive
+// @hyperframes/producer's createRenderJob/executeRenderJob with the
+// "png-sequence" format, then pick the captured frames nearest each requested
+// timestamp. Deliberately NOT importing HyperframesService — that class drags
+// in config.ts (which mkdirs at import) and the whole cloud-render surface;
+// this is a lean local-file implementation.
+//
+// Cost control: png-sequence captures EVERY frame on the fps grid, so we
+// (a) cap the staged composition's duration at the last requested timestamp
+// and (b) render on a coarse integer fps grid (4fps → 0.25s accuracy, dropped
+// to 2/1fps for long timelines) instead of the composition's native 30fps.
+// Requested timestamps are snapped to that grid; the actually-captured time
+// is reported next to each written PNG.
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseHTML } from "linkedom";
+import { inspectComposition } from "./composition-edit.js";
+const MAX_DEFAULT_STILLS = 8;
+const MAX_GRID_FRAMES = 600;
+// The in-process producer shells out to ffmpeg/ffprobe resolved from
+// HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH (then PATH). Point it at
+// the bundled static binaries, same as src/services/hyperframes.ts does.
+async function ensureProducerFfmpegEnv() {
+    if (!process.env.HYPERFRAMES_FFMPEG_PATH?.trim()) {
+        try {
+            const mod = (await import("ffmpeg-static"));
+            const resolved = typeof mod === "string" ? mod : mod.default;
+            if (typeof resolved === "string" && resolved && existsSync(resolved)) {
+                process.env.HYPERFRAMES_FFMPEG_PATH = resolved;
+            }
+        }
+        catch { /* PATH fallback */ }
+    }
+    if (!process.env.HYPERFRAMES_FFPROBE_PATH?.trim()) {
+        try {
+            const mod = (await import("ffprobe-static"));
+            const resolved = (mod.path ?? mod.default?.path);
+            if (typeof resolved === "string" && resolved && existsSync(resolved)) {
+                process.env.HYPERFRAMES_FFPROBE_PATH = resolved;
+            }
+        }
+        catch { /* PATH fallback */ }
+    }
+}
+/**
+ * Default timestamps when --at is omitted: the midpoint of each distinct
+ * scene clip on the LOWEST video track (capped at 8), else 0 / mid / end of
+ * the composition.
+ */
+export function defaultStillTimestamps(layers, durationSeconds) {
+    const isSceneClip = (layer) => layer.duration > 0 && (layer.is_timeline_proxy ||
+        layer.kind === "video" ||
+        layer.kind === "scene" ||
+        (layer.src !== null && /\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(layer.src)) ||
+        // Canvas-filling clips of any kind read as scenes (image scenes,
+        // solid/title cards) — overlays/captions are never full-canvas.
+        layer.is_full_canvas);
+    const scenes = layers.filter(isSceneClip);
+    if (scenes.length > 0) {
+        const lowestTrack = Math.min(...scenes.map((layer) => layer.track));
+        const seen = new Set();
+        const midpoints = [];
+        for (const layer of scenes.filter((l) => l.track === lowestTrack).sort((a, b) => a.start - b.start)) {
+            const key = layer.key || `${layer.start}-${layer.duration}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            midpoints.push(layer.start + layer.duration / 2);
+            if (midpoints.length >= MAX_DEFAULT_STILLS)
+                break;
+        }
+        if (midpoints.length > 0)
+            return midpoints;
+    }
+    if (durationSeconds <= 0)
+        return [0];
+    return [...new Set([0, durationSeconds / 2, Math.max(0, durationSeconds - 0.5)])];
+}
+// Pick the coarsest integer fps grid that keeps capture cheap while staying
+// within 0.25s of any requested timestamp where possible.
+function pickGridFps(maxTimestamp) {
+    for (const fps of [4, 2, 1]) {
+        if ((maxTimestamp + 1) * fps <= MAX_GRID_FRAMES)
+            return fps;
+    }
+    return 1;
+}
+// Cap the staged copy's root data-duration so the producer never captures
+// frames past the last requested still.
+function capCompositionDuration(html, capSeconds) {
+    const { document } = parseHTML(html);
+    const root = document.querySelector("[data-composition-id]");
+    if (!root)
+        throw new Error("Composition root ([data-composition-id]) not found in composition.html.");
+    const existing = Number.parseFloat(root.getAttribute("data-duration") ?? "");
+    const capped = Number.isFinite(existing) && existing > 0 ? Math.min(existing, capSeconds) : capSeconds;
+    root.setAttribute("data-duration", String(Number(capped.toFixed(3))));
+    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+}
+// Same guard as renderLocal: libx264-adjacent tooling (and the runtime's
+// canvas sizing) prefers even data-width/data-height.
+function forceEvenDimensions(html) {
+    return html.replace(/\bdata-(width|height)=(["'])(\d+)\2/gi, (match, dim, quote, value) => {
+        const n = Number.parseInt(value, 10);
+        if (!Number.isFinite(n) || n % 2 === 0)
+            return match;
+        return `data-${dim}=${quote}${n - 1}${quote}`;
+    });
+}
+/**
+ * Stage the composition as a HyperFrames project dir: the (duration-capped)
+ * composition.html becomes index.html, and every sibling file/dir is copied in
+ * so relative asset references keep resolving. Mirrors stageProject in
+ * src/services/hyperframes.ts, but against a local composition dir.
+ */
+function stageCompositionProject(htmlPath, stagedHtml) {
+    const sourceDir = path.dirname(htmlPath);
+    const projectDir = mkdtempSync(path.join(os.tmpdir(), "vidfarm-stills-"));
+    writeFileSync(path.join(projectDir, "index.html"), stagedHtml, "utf8");
+    for (const entry of readdirSync(sourceDir)) {
+        if (entry === path.basename(htmlPath) || entry === "index.html" || entry === "stills")
+            continue;
+        const from = path.join(sourceDir, entry);
+        try {
+            const info = statSync(from);
+            if (info.isDirectory()) {
+                cpSync(from, path.join(projectDir, entry), { recursive: true, force: true });
+            }
+            else if (info.isFile()) {
+                copyFileSync(from, path.join(projectDir, entry));
+            }
+        }
+        catch {
+            // best-effort: a missing/unreadable sibling never blocks the stills
+        }
+    }
+    return projectDir;
+}
+export async function renderCompositionStills(input) {
+    const html = readFileSync(input.htmlPath, "utf8");
+    if (!html.includes("data-composition-id=")) {
+        throw new Error(`stills requires composition HTML with data-composition-id (${input.htmlPath}).`);
+    }
+    const info = inspectComposition(html);
+    const durationSeconds = info.duration_seconds > 0 ? info.duration_seconds : 1;
+    const requested = (input.at && input.at.length > 0
+        ? input.at
+        : defaultStillTimestamps(info.layers, durationSeconds))
+        .map((t) => Math.min(Math.max(0, t), Math.max(0, durationSeconds - 0.01)))
+        .sort((a, b) => a - b);
+    if (requested.length === 0)
+        throw new Error("stills: no timestamps to render.");
+    const gridFps = pickGridFps(requested[requested.length - 1]);
+    const capSeconds = Math.min(durationSeconds, requested[requested.length - 1] + 2 / gridFps);
+    await ensureProducerFfmpegEnv();
+    const stagedHtml = forceEvenDimensions(capCompositionDuration(html, capSeconds));
+    const projectDir = stageCompositionProject(input.htmlPath, stagedHtml);
+    const framesDir = mkdtempSync(path.join(os.tmpdir(), "vidfarm-stills-frames-"));
+    const outDir = path.resolve(input.outDir ?? path.join(path.dirname(input.htmlPath), "stills"));
+    mkdirSync(outDir, { recursive: true });
+    // Declarative vidfarm compositions carry no scripts (cloud saves strip
+    // them), so they can never satisfy the engine's window.__timelines
+    // sub-composition poll — which otherwise stalls capture-session init for the
+    // full 45s playerReadyTimeout before proceeding anyway. When the html has no
+    // timeline registration at all, cap that wait via the engine's env knob.
+    // Compositions that DO register GSAP timelines keep the default.
+    const priorReadyTimeout = process.env.PRODUCER_PLAYER_READY_TIMEOUT_MS;
+    if (!priorReadyTimeout?.trim() && !stagedHtml.includes("__timelines")) {
+        process.env.PRODUCER_PLAYER_READY_TIMEOUT_MS = "10000";
+    }
+    try {
+        // Same producer entry points renderStill uses; "png-sequence" writes the
+        // frames dir as frame_000001.png … at 1/gridFps intervals.
+        const { createRenderJob, executeRenderJob } = await import("@hyperframes/producer");
+        // Quiet mode (--json) swaps in a no-op logger so stdout stays parseable —
+        // the producer's default logger writes progress lines to stdout.
+        const silentLogger = { error() { }, warn() { }, info() { }, debug() { } };
+        const job = createRenderJob({
+            fps: gridFps,
+            quality: "high",
+            format: "png-sequence",
+            ...(input.quiet ? { logger: silentLogger } : {})
+        });
+        let lastStatus = null;
+        const executeRender = () => executeRenderJob(job, projectDir, framesDir, (progressJob) => {
+            if (!input.quiet && progressJob.status !== lastStatus) {
+                lastStatus = progressJob.status;
+                console.log(`\x1b[2m  ${progressJob.status}\x1b[0m`);
+            }
+        });
+        // The engine also logs init/browser lines via console.log directly (they
+        // bypass the producer logger); in quiet mode reroute console stdout to
+        // stderr for the duration of the render so stdout stays pure JSON.
+        const originalConsole = { log: console.log, info: console.info, debug: console.debug };
+        if (input.quiet) {
+            const toStderr = (...args) => {
+                process.stderr.write(`${args.map((value) => (typeof value === "string" ? value : JSON.stringify(value))).join(" ")}\n`);
+            };
+            console.log = toStderr;
+            console.info = toStderr;
+            console.debug = toStderr;
+        }
+        try {
+            await executeRender();
+        }
+        finally {
+            console.log = originalConsole.log;
+            console.info = originalConsole.info;
+            console.debug = originalConsole.debug;
+        }
+        const frameFiles = readdirSync(framesDir)
+            .filter((name) => name.toLowerCase().endsWith(".png"))
+            .sort();
+        if (frameFiles.length === 0) {
+            throw new Error("stills render produced no frames — check the composition with `vidfarm lint` first.");
+        }
+        const stills = [];
+        for (const t of requested) {
+            const frameIndex = Math.min(frameFiles.length - 1, Math.max(0, Math.round(t * gridFps)));
+            const capturedSec = Number((frameIndex / gridFps).toFixed(3));
+            const stillName = `still-${capturedSec.toFixed(2).padStart(6, "0")}s.png`;
+            const dest = path.join(outDir, stillName);
+            copyFileSync(path.join(framesDir, frameFiles[frameIndex]), dest);
+            stills.push({ requested_sec: Number(t.toFixed(3)), captured_sec: capturedSec, path: dest });
+        }
+        return {
+            ok: true,
+            composition: input.htmlPath,
+            out_dir: outDir,
+            grid_fps: gridFps,
+            duration_seconds: durationSeconds,
+            stills
+        };
+    }
+    finally {
+        if (!priorReadyTimeout?.trim())
+            delete process.env.PRODUCER_PLAYER_READY_TIMEOUT_MS;
+        rmSync(framesDir, { recursive: true, force: true });
+        rmSync(projectDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=stills.js.map

package/dist/src/devcli/transitions.js

@@ -0,0 +1,205 @@
+// devcli `vidfarm transitions …` — first-class scene transitions for a
+// composition.html on disk. Pure local DOM edit (linkedom), no cloud, no
+// wallet; a running `vidfarm serve` live-morphs the change into open editor
+// tabs and `publish` pushes it like any browser edit. Same semantics as the
+// editor's timeline chips and the AI's set_transitions action: junction
+// transitions live as data-transition on the INCOMING clip (the stored
+// timeline stays butt-cut — the runtime/publish normalizer grants the
+// overlap), exit transitions as data-transition-out on the departing clip.
+import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { applyTransitionsAcross, clearAllTransitions, readTransitions, setLayerTransitions } from "./composition-edit.js";
+import { TRANSITION_OUT_PRESETS, TRANSITION_PRESETS } from "../hyperframes/composition.js";
+export const TRANSITIONS_HELP = `vidfarm transitions — scene transitions between clips (local file write)
+
+  transitions apply <dir|composition.html>   Apply across the whole timeline in one pass
+    --preset <p>              Junction preset applied at EVERY cut (every scene clip
+                              except each track's first). "none" clears junctions.
+    --duration <sec>          Transition length 0.1-2.5 (default 0.5)
+    --intro <p>               Entrance for the very FIRST clip (e.g. fade-black opens from black)
+    --outro <p>               Exit for the very LAST clip (e.g. fade-black ends on black)
+    --outro-duration <sec>    Outro length (defaults to --duration)
+    --json
+
+  transitions set <dir|composition.html> --layer <key>   Configure one clip
+    --in <p>                  Entrance preset ("none" clears)
+    --in-duration <sec>
+    --out <p>                 Exit preset ("none" clears)
+    --out-duration <sec>
+    --json
+
+  transitions list  <dir|composition.html> [--json]      Show transitions on every scene clip
+  transitions clear <dir|composition.html>               Remove all transitions
+
+Entrance presets: ${TRANSITION_PRESETS.join(" | ")}
+Exit presets:     ${TRANSITION_OUT_PRESETS.join(" | ")}
+
+The incoming clip owns the junction transition; the previous butt-cut clip is held on
+screen beneath it automatically in preview, serve live-morph, local render, and cloud
+render — never retime clips to "make room". Exit transitions play over the clip's last
+seconds via an inline delay, re-derived automatically after retimes.
+`;
+export async function runTransitionsCommand(argv) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    switch (sub) {
+        case "apply":
+            return runApply(rest);
+        case "set":
+            return runSet(rest);
+        case "list":
+            return runList(rest);
+        case "clear":
+            return runClear(rest);
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(TRANSITIONS_HELP);
+            return;
+        default:
+            console.error(`Unknown transitions subcommand: ${sub}\n`);
+            console.log(TRANSITIONS_HELP);
+            process.exitCode = 1;
+    }
+}
+// Same dir-or-file resolution as `vidfarm place` / `vidfarm captions`.
+function resolveCompositionHtml(target) {
+    if (!target)
+        throw new Error("Provide the composition dir or composition.html path.");
+    const abs = path.resolve(process.cwd(), target);
+    if (existsSync(abs) && statSync(abs).isDirectory()) {
+        const inside = path.join(abs, "composition.html");
+        if (!existsSync(inside))
+            throw new Error(`No composition.html inside ${abs}. Run \`vidfarm pull <forkId> --dir ${target}\` first.`);
+        return inside;
+    }
+    if (!existsSync(abs))
+        throw new Error(`No such composition file or dir: ${abs}.`);
+    return abs;
+}
+function num(values, key) {
+    const raw = values[key];
+    if (typeof raw !== "string" || !raw.trim())
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        throw new Error(`--${key} must be a number.`);
+    return parsed;
+}
+function runApply(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            preset: { type: "string" },
+            duration: { type: "string" },
+            intro: { type: "string" },
+            outro: { type: "string" },
+            "outro-duration": { type: "string" },
+            json: { type: "boolean" }
+        }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    const html = readFileSync(file, "utf8");
+    const result = applyTransitionsAcross(html, {
+        junction: typeof values.preset === "string" ? values.preset : undefined,
+        duration: num(values, "duration"),
+        intro: typeof values.intro === "string" ? values.intro : undefined,
+        outro: typeof values.outro === "string" ? values.outro : undefined,
+        outroDuration: num(values, "outro-duration")
+    });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, junctions: result.junctions, intro: result.intro, outro: result.outro }, null, 2));
+        return;
+    }
+    const parts = [];
+    if (typeof values.preset === "string") {
+        parts.push(values.preset === "none" ? `cleared junction transitions on ${result.junctions} clips` : `${values.preset} at ${result.junctions} junctions`);
+    }
+    if (typeof values.intro === "string")
+        parts.push(values.intro === "none" ? "intro cleared" : `intro ${values.intro}`);
+    if (typeof values.outro === "string")
+        parts.push(values.outro === "none" ? "outro cleared" : `outro ${values.outro}`);
+    console.log(`Set scene transitions: ${parts.join(", ")}.`);
+    console.log(`Wrote ${file}`);
+}
+function runSet(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            layer: { type: "string" },
+            in: { type: "string" },
+            "in-duration": { type: "string" },
+            out: { type: "string" },
+            "out-duration": { type: "string" },
+            json: { type: "boolean" }
+        }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    if (typeof values.layer !== "string" || !values.layer.trim()) {
+        throw new Error("transitions set requires --layer <layerKey|slug>.");
+    }
+    const html = readFileSync(file, "utf8");
+    const result = setLayerTransitions(html, values.layer, {
+        transition: typeof values.in === "string" ? values.in : undefined,
+        transitionDuration: num(values, "in-duration"),
+        transitionOut: typeof values.out === "string" ? values.out : undefined,
+        transitionOutDuration: num(values, "out-duration")
+    });
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, layerKey: result.layerKey, in: values.in ?? null, out: values.out ?? null }, null, 2));
+        return;
+    }
+    const parts = [];
+    if (typeof values.in === "string")
+        parts.push(`in=${values.in}`);
+    if (typeof values.out === "string")
+        parts.push(`out=${values.out}`);
+    console.log(`Updated transitions on ${result.layerKey} (${parts.join(" ")}).`);
+    console.log(`Wrote ${file}`);
+}
+function runList(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { json: { type: "boolean" } }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    const entries = readTransitions(readFileSync(file, "utf8"));
+    if (values.json) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    if (!entries.length) {
+        console.log("No scene clips found.");
+        return;
+    }
+    for (const entry of entries) {
+        const inLabel = entry.transition ? `${entry.transition} (${entry.transition_duration ?? 0.5}s)` : "-";
+        const outLabel = entry.transition_out ? `${entry.transition_out} (${entry.transition_out_duration ?? 0.5}s)` : "-";
+        console.log(`${entry.start.toFixed(2).padStart(8)}s  L${entry.track}  ${entry.layerKey.padEnd(28)}  in: ${inLabel.padEnd(22)}  out: ${outLabel}  ${entry.label ?? ""}`);
+    }
+}
+function runClear(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { json: { type: "boolean" } }
+    });
+    const file = resolveCompositionHtml(positionals[0]);
+    const result = clearAllTransitions(readFileSync(file, "utf8"));
+    writeFileSync(file, result.html, "utf8");
+    if (values.json) {
+        console.log(JSON.stringify({ file, cleared: result.cleared }, null, 2));
+        return;
+    }
+    console.log(`Cleared transitions on ${result.cleared} clips.`);
+    console.log(`Wrote ${file}`);
+}
+//# sourceMappingURL=transitions.js.map