@mevdragon/vidfarm-devcli 0.11.0 → 0.13.0

package/dist/src/cli.js

@@ -9,8 +9,10 @@ import { spawnSync } from "node:child_process";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLayerWithMedia } from "./devcli/composition-edit.js";
+import { runCaptionsCommand } from "./devcli/captions.js";
 import { runClipsCommand } from "./devcli/clips.js";
 import { MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES, loadSpeechAudioLocally, localGenerateSpeech, localTranscribeSpeech, resolveLocalSpeechAuth } from "./devcli/speech.js";
+import { inferSpeechProviderForVoice } from "./services/speech.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
@@ -79,6 +81,9 @@ Discover & inspiration (browse the viral-video catalog, add your own source):
                             local MP4/MOV/WebM file — as a private        (files: presign + PUT via
                             template. --title (uploads; defaults to the    /discover/templates/upload)
                             template id), --tagline, --notes optional.
+                            --raw (uploads) marks it as your own raw
+                            project footage — the editor won't auto-
+                            prompt Decompose on it.
   inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
   inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
 
@@ -141,6 +146,12 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             zoom-out|pan-left|pan-right|pan-up|pan-down|
                             zoom-in-left|zoom-in-right
     --ken-burns-intensity <n>   Travel/zoom strength 0.04-0.5 (default 0.18)
+    --transition <preset>   Scene transition INTO this clip (the previous
+                            butt-cut clip is held beneath it automatically):
+                            crossfade|fade-black|slide-left|slide-right|
+                            slide-up|slide-down|wipe-left|wipe-right|wipe-up|
+                            wipe-down|zoom-in|zoom-out|circle-open
+    --transition-duration <s>   Transition length in seconds 0.1-2.5 (default 0.5)
   remove-video-captions <forkId>   Read the two video sources:        → GET  .../compositions/:forkId/remove-video-captions
                             original vs decomposed (caption-free),
                             non-billing (alias: ghostcut)
@@ -167,7 +178,9 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
                             The VOICE STYLE is promptable via --style.   OPENROUTER_API_KEY, no cloud job
     --style "<direction>"     Voice-style prompt: tone/pacing/accent/emotion/persona
                               (e.g. "calm, warm bedtime narrator", "excited sports announcer")
-    --voice <name>            Provider voice preset (openai: alloy/ash/coral…; gemini: Kore/Puck…)
+    --voice <name>            Provider voice preset (openai: alloy/ash/coral…; gemini: Kore/Puck…).
+                              The provider is inferred from the voice when --provider is omitted;
+                              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
     --cloud                   BACKUP: saved-key platform job   → POST /api/v1/primitives/audio/speech (+ poll)
@@ -183,6 +196,17 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
     --provider <p> --model <m>
     --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)
+
+Animated captions (word-by-word TikTok/CapCut styles on a pulled/served composition):
+  captions generate <dir>   Transcribe the narration & lay down animated  LOCAL: local ffmpeg demux +
+                            caption cue layers (openai = real word        your provider key; writes
+                            timestamps; gemini/openrouter estimated).     composition.html on disk
+    --style <preset>          spotlight|karaoke|word-pop|stack-up|neon|bounce (default spotlight)
+    --audio <file|url> | --srt <file> | --text "<script>"   Pick the transcript source
+    --max-words <n> --active-color <css> --uppercase … (run 'vidfarm captions' for all flags)
+  captions style <dir>      Restyle existing cues (same text/timings)
+  captions list <dir>       Show the current animated caption cues [--json]
+  captions clear <dir>      Remove all animated caption layers
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
   render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
@@ -437,6 +461,9 @@ async function main() {
         case "clips":
             await runClipsCommand(rest);
             return;
+        case "captions":
+            await runCaptionsCommand(rest);
+            return;
         default:
             if (!command.startsWith("-")) {
                 // Positional template id → default to booting the local editor.
@@ -597,6 +624,11 @@ async function runServeCommand(argv) {
     // local-render by definition — cloud rendering is the EXPLICIT
     // render_target="cloud" upstream handoff (the editor's "Render in Cloud").
     process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
+    // Same trap for clip hunts: a dev-shell .env carrying the staging clip-scan
+    // ARN would route this box's /clips/scan to the cloud Step Functions. serve
+    // hunts are LOCAL-FIRST (local agent CLI / BYOK keys); the upstream cloud is
+    // the explicit backup inside the scan route itself.
+    process.env.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN = "";
     // Same trap as the state machine ARN: a dev-shell .env can carry the staging
     // media-lambda URL, which would route probe/thumbnail/trim/etc. to a cloud
     // Lambda that cannot fetch this box's localhost storage URLs ("fetch
@@ -1241,7 +1273,7 @@ async function runVideosCommand(argv) {
     emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
 }
 async function runInspirationAddCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" }, tagline: { type: "string" }, notes: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" }, tagline: { type: "string" }, notes: { type: "string" }, raw: { type: "boolean", default: false } } });
     const source = parsed.positionals[0];
     if (!source)
         throw new Error("inspiration-add requires a video URL (TikTok/YouTube/Instagram/X) or a local video file path.");
@@ -1261,7 +1293,10 @@ async function runInspirationAddCommand(argv) {
             fileName: path.basename(localPath),
             title: parsed.values.title,
             tagline: parsed.values.tagline,
-            notes: parsed.values.notes
+            notes: parsed.values.notes,
+            // --raw: this is the user's own footage starting a new project, not an
+            // inspiration to study — the editor skips the auto Decompose prompt.
+            origin: parsed.values.raw ? "raw" : undefined
         });
         emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
         return;
@@ -1356,7 +1391,7 @@ async function ingestUploadedVideo(ctx, input) {
         host: ctx.host,
         path: "/discover/templates",
         auth: ctx.auth,
-        body: { upload: { storage_key: storageKey, file_name: uploadedName }, title: input.title, tagline: input.tagline, notes: input.notes }
+        body: { upload: { storage_key: storageKey, file_name: uploadedName }, title: input.title, tagline: input.tagline, notes: input.notes, origin: input.origin }
     });
     assertApiOk(result, "ingest");
     return result;
@@ -1531,7 +1566,10 @@ async function runCreateCommand(argv) {
         throw new Error(`create: could not fetch the generated video (${dl.status}).`);
     const buffer = Buffer.from(await dl.arrayBuffer());
     const title = parsed.values.title ?? prompt.slice(0, 80);
-    const add = await ingestUploadedVideo(ctx, { buffer, fileName: "generated.mp4", contentType: "video/mp4", title });
+    // origin:"raw" — a prompt-generated video is the user's own new project, not
+    // an imported inspiration; the editor must not auto-prompt Decompose (matters
+    // especially with --no-decompose).
+    const add = await ingestUploadedVideo(ctx, { buffer, fileName: "generated.mp4", contentType: "video/mp4", title, origin: "raw" });
     const inspirationId = add.json?.inspiration_id;
     if (!inspirationId)
         throw new Error("create: ingest did not return an inspiration id.");
@@ -1986,6 +2024,8 @@ function placeMediaOnDisk(input) {
         objectFit: input.objectFit,
         kenBurns: input.kenBurns,
         kenBurnsIntensity: input.kenBurnsIntensity,
+        transition: input.transition,
+        transitionDuration: input.transitionDuration,
         slug: input.slug
     };
     const result = input.replace
@@ -2017,6 +2057,8 @@ async function runGenerateCommand(argv) {
             track: { type: "string" },
             "ken-burns": { type: "string" },
             "ken-burns-intensity": { type: "string" },
+            transition: { type: "string" },
+            "transition-duration": { type: "string" },
             "layer-key": { type: "string" }
         }
     });
@@ -2090,6 +2132,8 @@ async function runGenerateCommand(argv) {
             track: parsed.values.track ? Number(parsed.values.track) : undefined,
             kenBurns: parsed.values["ken-burns"],
             kenBurnsIntensity: parsed.values["ken-burns-intensity"] ? Number(parsed.values["ken-burns-intensity"]) : undefined,
+            transition: parsed.values.transition,
+            transitionDuration: parsed.values["transition-duration"] ? Number(parsed.values["transition-duration"]) : undefined,
             layerKey: parsed.values["layer-key"]
         });
         if (!ctx.json)
@@ -2158,7 +2202,10 @@ async function runTtsCommand(argv) {
     const voice = parsed.values.voice;
     const json = Boolean(parsed.values.json);
     if (!parsed.values.cloud) {
-        const auth = resolveLocalSpeechAuth(parsed.values, ["openai", "gemini", "openrouter"], parsed.values.provider);
+        // 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 auth = resolveLocalSpeechAuth(parsed.values, keyPreference, parsed.values.provider);
         if (!auth)
             throw new Error(speechKeyHint("tts"));
         if (!json)
@@ -2471,6 +2518,8 @@ async function runPlaceCommand(argv) {
             "object-fit": { type: "string" },
             "ken-burns": { type: "string" },
             "ken-burns-intensity": { type: "string" },
+            transition: { type: "string" },
+            "transition-duration": { type: "string" },
             "layer-key": { type: "string" },
             slug: { type: "string" },
             // Local file support: where a serve box serves /storage from, and which
@@ -2513,6 +2562,8 @@ async function runPlaceCommand(argv) {
         objectFit: parsed.values["object-fit"],
         kenBurns: parsed.values["ken-burns"],
         kenBurnsIntensity: num(parsed.values["ken-burns-intensity"]),
+        transition: parsed.values.transition,
+        transitionDuration: num(parsed.values["transition-duration"]),
         layerKey: parsed.values["layer-key"],
         slug: parsed.values.slug
     });

package/dist/src/composition-runtime.js

@@ -171,14 +171,137 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
     }
   }
 
+  // Scene transitions: a [data-transition] clip animates in (vf-tr-*
+  // keyframes) over its first data-transition-duration seconds, ON TOP of the
+  // previous clip on its track — so that previous clip must stay active for
+  // the transition window. Publish materializes this overlap into
+  // data-duration (normalizePublishHtml); the preview grants it live so
+  // butt-cut drafts preview exactly like the render.
+  function collectTransitionWindows() {
+    const windows = [];
+    for (const clip of clips) {
+      if (!(clip instanceof HTMLElement) || clip instanceof HTMLAudioElement) continue;
+      if (!clip.hasAttribute("data-transition")) continue;
+      const timing = readTiming(clip);
+      let transitionDuration = Number(clip.getAttribute("data-transition-duration"));
+      if (!Number.isFinite(transitionDuration) || transitionDuration <= 0) transitionDuration = 0.5;
+      windows.push({
+        track: Number(clip.getAttribute("data-track-index")) || 0,
+        start: timing.start,
+        duration: Math.min(transitionDuration, timing.duration)
+      });
+    }
+    return windows;
+  }
+
+  function transitionHoldFor(clip, timing, windows) {
+    if (!windows.length) return 0;
+    if (!(clip instanceof HTMLElement) || clip instanceof HTMLAudioElement) return 0;
+    const track = Number(clip.getAttribute("data-track-index")) || 0;
+    let hold = 0;
+    for (const window of windows) {
+      if (window.track !== track) continue;
+      // Nominal-end adjacency: already-materialized holds (published HTML)
+      // shift this clip's end past the next start, fail the check, and are
+      // simply not re-granted — no double extension either way.
+      if (Math.abs(window.start - timing.end) > 0.05) continue;
+      if (window.duration > hold) hold = window.duration;
+    }
+    return hold;
+  }
+
+  function syncTransitionClip(clip, timing) {
+    if (typeof clip.getAnimations !== "function") return;
+    const offsetMs = Math.max(0, (time - timing.start)) * 1000;
+    let anims = [];
+    try { anims = clip.getAnimations({ subtree: true }); } catch { return; }
+    for (const anim of anims) {
+      if (typeof anim.animationName !== "string" || anim.animationName.indexOf("vf-tr-") !== 0) continue;
+      try {
+        anim.pause();
+        anim.currentTime = offsetMs;
+      } catch {}
+    }
+  }
+
+  // Animated caption words carry vf-cap-* keyframes whose inline delay/
+  // duration ARE the word windows relative to the layer start, so unlike Ken
+  // Burns there is nothing to normalize — the scrub is simply the absolute
+  // offset into the layer. Paused-by-stylesheet + scrubbed-here matches the
+  // render producer's CSS adapter exactly.
+  //
+  // Stability: Chrome PERMANENTLY drops a paused fill:none CSS animation the
+  // moment its currentTime is pushed past the effect end, and never re-creates
+  // it while the computed animation-name is unchanged — so one forward scrub
+  // across a word's window would leave that word stuck in its resting state
+  // (invisible for word-pop/stack-up) on every later frame. Past the end, a
+  // parked fill:none animation looks identical to the resting styles, so park
+  // at 0 instead of overshooting. fill:forwards presets (karaoke-fill,
+  // cumulative-reveal) must overshoot to hold their final keyframe — finished
+  // + forwards animations keep applying their effect and survive. If a word's
+  // animation is missing anyway (dropped before this guard, or an innerHTML
+  // morph replaced the spans mid-scrub), restart it declaratively by cycling
+  // animation-name through none.
+  function captionWordAnimationFor(word) {
+    let anims = [];
+    try { anims = word.getAnimations(); } catch { return null; }
+    for (const anim of anims) {
+      if (typeof anim.animationName === "string" && anim.animationName.indexOf("vf-cap-") === 0) return anim;
+    }
+    return null;
+  }
+
+  function syncCaptionClip(clip, timing) {
+    if (typeof clip.getAnimations !== "function") return;
+    const offsetMs = Math.max(0, (time - timing.start)) * 1000;
+    let words = [];
+    try { words = Array.from(clip.querySelectorAll('[data-cap-word="true"]')); } catch { return; }
+    for (const word of words) {
+      if (typeof word.getAnimations !== "function") continue;
+      let anim = captionWordAnimationFor(word);
+      if (!anim) {
+        const inlineEndMs =
+          ((parseFloat(word.style.animationDelay) || 0) + (parseFloat(word.style.animationDuration) || 0)) * 1000;
+        let needed = offsetMs <= inlineEndMs;
+        if (!needed) {
+          try { needed = getComputedStyle(word).animationFillMode.indexOf("forward") !== -1 || getComputedStyle(word).animationFillMode.indexOf("both") !== -1; } catch {}
+        }
+        if (!needed) continue;
+        try {
+          word.style.animationName = "none";
+          void word.offsetWidth;
+          word.style.removeProperty("animation-name");
+        } catch { continue; }
+        anim = captionWordAnimationFor(word);
+        if (!anim) continue;
+      }
+      let target = offsetMs;
+      try {
+        const computed = anim.effect && typeof anim.effect.getComputedTiming === "function"
+          ? anim.effect.getComputedTiming()
+          : null;
+        if (computed && typeof computed.endTime === "number" && offsetMs >= computed.endTime
+            && computed.fill !== "forwards" && computed.fill !== "both") {
+          target = 0;
+        }
+      } catch {}
+      try {
+        anim.pause();
+        anim.currentTime = target;
+      } catch {}
+    }
+  }
+
   function apply(nextTime, options = {}) {
     const forceSeek = Boolean(options.forceSeek);
     const fromClock = Boolean(options.fromClock);
     time = clampTime(nextTime);
     let activeVideoProxy = null;
+    const transitionWindows = collectTransitionWindows();
     for (const clip of clips) {
       const timing = readTiming(clip);
-      const active = time >= timing.start && time < timing.end;
+      const hold = transitionHoldFor(clip, timing, transitionWindows);
+      const active = time >= timing.start && time < timing.end + hold;
       if (clip instanceof HTMLElement && !(clip instanceof HTMLAudioElement)) {
         if (clip.getAttribute("data-vf-timeline-proxy") === "video") {
           if (active) activeVideoProxy = clip;
@@ -186,6 +309,8 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
           setVisibility(clip, active);
         }
         if (clip.hasAttribute("data-kenburns")) syncKenBurnsClip(clip, timing);
+        if (clip.hasAttribute("data-caption-animation")) syncCaptionClip(clip, timing);
+        if (clip.hasAttribute("data-transition")) syncTransitionClip(clip, timing);
       }
       if (clip instanceof HTMLMediaElement) {
         applyMediaState(clip);
@@ -293,7 +418,16 @@ export const COMPOSITION_RUNTIME_SCRIPT_BODY = `
       return playbackRate;
     },
     setMuted,
-    refreshClips
+    refreshClips,
+    // Re-scrub caption word animations at the current playhead without a full
+    // apply(). The editor calls this after live-patching a caption layer's
+    // DOM (style/text edits rebuild the word spans, whose fresh CSS-paused
+    // animations sit at currentTime 0 — resting/invisible — until scrubbed).
+    syncCaptions() {
+      for (const clip of Array.from(document.querySelectorAll("[data-caption-animation]"))) {
+        if (clip instanceof HTMLElement) syncCaptionClip(clip, readTiming(clip));
+      }
+    }
   };
 
   refreshClips();

package/dist/src/devcli/captions.js

@@ -0,0 +1,310 @@
+// devcli `vidfarm captions …` — animated word-by-word captions (TikTok/CapCut
+// style) for a composition.html on disk. LOCAL-FIRST like `place`/`stt`: the
+// transcript comes from the user's own provider key (openai gives REAL
+// word-level timings via whisper-1; gemini/openrouter fall back to estimated
+// word windows), the DOM edit is a local file write, and a running
+// `vidfarm serve` live-morphs the change into open editor tabs. No cloud job,
+// no wallet. Feed it an --srt file (e.g. from `vidfarm stt --cloud`) to skip
+// STT entirely, or --text to page a script without any transcript.
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { clearCaptionLayers, computeCompositionGaps, inspectComposition, insertCaptionLayers, readCaptionCues, restyleCaptionLayers } from "./composition-edit.js";
+import { loadSpeechAudioLocally, localTranscribeSpeech, resolveLocalSpeechAuth, MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES } from "./speech.js";
+import { buildCaptionCues, cuesFromText } from "../services/captions.js";
+import { CAPTION_ANIMATIONS, CAPTION_STYLE_PRESETS } from "../hyperframes/composition.js";
+export const CAPTIONS_HELP = `vidfarm captions — animated word-by-word captions (local STT + local file write)
+
+  captions generate <dir|composition.html>   Transcribe narration & lay down animated caption cues
+    --audio <file|url>        Audio/video to transcribe. Default: the composition's first
+                              audio layer src, else its first video layer src.
+    --srt <file>              Skip STT; build cues from this SRT subtitle file.
+    --text "<script>"         Skip STT; page this text across [--start, --start+--duration].
+    --style <preset>          ${CAPTION_STYLE_PRESETS.map((p) => p.id).join(" | ")}   (default: spotlight)
+    --animation <anim>        ${CAPTION_ANIMATIONS.join(" | ")}
+    --active-color <css>      Color the active word takes while spoken
+    --highlight-color <css>   Pill behind the active word (highlight-pop)
+    --color / --background / --background-style plain|outline|highlight-solid|highlight-translucent
+    --font <family> / --font-size <px> / --uppercase
+    --max-words <n>           Words per cue page (default 4)
+    --track <n> / --x / --y / --width / --height (%)
+    --provider <p>            openai | gemini | openrouter (default: openai first — it has
+                              real word timestamps; gemini/openrouter estimate word windows)
+    --language <code>         Expected audio language
+    --offset <sec>            Shift every cue (e.g. narration layer's start)
+    --start <sec> --duration <sec>   Window for --text paging
+    --json
+
+  captions style <dir|composition.html> --style <preset>   Restyle existing cues (same text/timing)
+  captions list  <dir|composition.html> [--json]           Show current animated caption cues
+  captions clear <dir|composition.html>                    Remove all animated caption layers
+
+Word timings ride inside each cue layer (per-word animation-delay/duration), so preview,
+serve live-morph, local render, and cloud render all animate identically. \`publish\` pushes
+the edited composition to the cloud as usual.
+`;
+const STYLE_FLAG_OPTIONS = {
+    style: { type: "string" },
+    animation: { type: "string" },
+    "active-color": { type: "string" },
+    "highlight-color": { type: "string" },
+    color: { type: "string" },
+    background: { type: "string" },
+    "background-style": { type: "string" },
+    font: { type: "string" },
+    "font-size": { type: "string" },
+    uppercase: { type: "boolean" },
+    track: { type: "string" },
+    x: { type: "string" },
+    y: { type: "string" },
+    width: { type: "string" },
+    height: { type: "string" }
+};
+export async function runCaptionsCommand(argv) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    switch (sub) {
+        case "generate":
+            return runGenerate(rest);
+        case "style":
+            return runStyle(rest);
+        case "list":
+            return runListCues(rest);
+        case "clear":
+            return runClear(rest);
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(CAPTIONS_HELP);
+            return;
+        default:
+            console.error(`Unknown captions subcommand: ${sub}\n`);
+            console.log(CAPTIONS_HELP);
+            process.exitCode = 1;
+    }
+}
+// Same dir-or-file resolution as `vidfarm place` (cli.ts resolveCompositionHtmlPath).
+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 styleOptionsFromFlags(values) {
+    const num = (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;
+    };
+    return {
+        style: typeof values.style === "string" ? values.style : undefined,
+        animation: typeof values.animation === "string" ? values.animation : undefined,
+        activeColor: typeof values["active-color"] === "string" ? values["active-color"] : undefined,
+        highlightColor: typeof values["highlight-color"] === "string" ? values["highlight-color"] : undefined,
+        uppercase: values.uppercase === true ? true : undefined,
+        color: typeof values.color === "string" ? values.color : undefined,
+        background: typeof values.background === "string" ? values.background : undefined,
+        backgroundStyle: typeof values["background-style"] === "string" ? values["background-style"] : undefined,
+        fontFamily: typeof values.font === "string" ? values.font : undefined,
+        fontSize: num("font-size"),
+        track: num("track"),
+        x: num("x"),
+        y: num("y"),
+        width: num("width"),
+        height: num("height")
+    };
+}
+// Minimal SRT reader: index / "start --> end" / text lines. Produces the same
+// segment shape STT returns so cue building is one code path.
+export function parseSrtToSegments(srt) {
+    const toSeconds = (stamp) => {
+        const match = /(\d+):(\d+):(\d+)[,.](\d+)/.exec(stamp.trim());
+        if (!match)
+            return null;
+        return Number(match[1]) * 3600 + Number(match[2]) * 60 + Number(match[3]) + Number(match[4].padEnd(3, "0").slice(0, 3)) / 1000;
+    };
+    const segments = [];
+    for (const block of srt.split(/\r?\n\r?\n+/)) {
+        const lines = block.split(/\r?\n/).filter((line) => line.trim());
+        const timingIndex = lines.findIndex((line) => line.includes("-->"));
+        if (timingIndex === -1)
+            continue;
+        const [startRaw, endRaw] = lines[timingIndex].split("-->");
+        const start = toSeconds(startRaw ?? "");
+        const end = toSeconds(endRaw ?? "");
+        const text = lines.slice(timingIndex + 1).join(" ").replace(/<[^>]+>/g, "").trim();
+        if (start === null || !text)
+            continue;
+        segments.push({ speaker: "speaker_1", start_sec: start, end_sec: end, text });
+    }
+    return segments;
+}
+// Default transcription source: the composition's own narration. Prefer a
+// dedicated audio layer; fall back to the first video layer with a src.
+function defaultAudioSource(htmlPath, html) {
+    const info = inspectComposition(html);
+    const candidate = info.layers.find((layer) => layer.kind === "audio" && layer.src)
+        ?? info.layers.find((layer) => layer.kind === "video" && layer.src);
+    if (!candidate?.src)
+        return null;
+    const src = candidate.src;
+    if (/^https?:\/\//i.test(src))
+        return src;
+    // Relative srcs resolve against the composition dir (pull/serve layouts).
+    return path.resolve(path.dirname(htmlPath), src.replace(/^\.\//, ""));
+}
+async function runGenerate(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...STYLE_FLAG_OPTIONS,
+            audio: { type: "string" },
+            srt: { type: "string" },
+            text: { type: "string" },
+            "max-words": { type: "string" },
+            provider: { type: "string" },
+            language: { type: "string" },
+            offset: { type: "string" },
+            start: { type: "string" },
+            duration: { type: "string" },
+            "gemini-key": { type: "string" },
+            "openai-key": { type: "string" },
+            "openrouter-key": { type: "string" },
+            json: { type: "boolean" }
+        }
+    });
+    const htmlPath = resolveCompositionHtml(positionals[0]);
+    const html = readFileSync(htmlPath, "utf8");
+    const info = inspectComposition(html);
+    const maxWords = values["max-words"] ? Math.max(1, Math.round(Number(values["max-words"]))) : 4;
+    const offsetSec = values.offset ? Number(values.offset) : 0;
+    if (!Number.isFinite(offsetSec))
+        throw new Error("--offset must be a number of seconds.");
+    let cues;
+    let sourceNote;
+    if (typeof values.text === "string" && values.text.trim()) {
+        const start = values.start ? Number(values.start) : 0;
+        const duration = values.duration ? Number(values.duration) : Math.max(0.4, info.duration_seconds - start);
+        cues = cuesFromText(values.text, start + offsetSec, duration, { maxWordsPerCue: maxWords });
+        sourceNote = "provided text (estimated word timings)";
+    }
+    else if (typeof values.srt === "string" && values.srt.trim()) {
+        const srtPath = path.resolve(process.cwd(), values.srt);
+        if (!existsSync(srtPath))
+            throw new Error(`No such SRT file: ${srtPath}`);
+        const segments = parseSrtToSegments(readFileSync(srtPath, "utf8"));
+        if (!segments.length)
+            throw new Error(`No cues found in ${srtPath}.`);
+        cues = buildCaptionCues(segments, { maxWordsPerCue: maxWords, offsetSec, fallbackDurationSec: info.duration_seconds });
+        sourceNote = `${path.basename(srtPath)} (${segments.length} SRT cues, estimated word timings)`;
+    }
+    else {
+        // openai first: whisper-1 verbose_json is the only path with REAL word
+        // timestamps, which is what makes the word-by-word animation land on beat.
+        const auth = resolveLocalSpeechAuth(values, ["openai", "gemini", "openrouter"], typeof values.provider === "string" ? values.provider : undefined);
+        if (!auth) {
+            throw new Error("No local provider key found. Export OPENAI_API_KEY (best: real word timings), GEMINI_API_KEY, or OPENROUTER_API_KEY — or pass --srt/--text instead.");
+        }
+        const audioTarget = typeof values.audio === "string" && values.audio.trim()
+            ? values.audio.trim()
+            : defaultAudioSource(htmlPath, html);
+        if (!audioTarget) {
+            throw new Error("Could not find narration to transcribe (no audio/video layer with a src). Pass --audio <file|url>, --srt, or --text.");
+        }
+        console.log(`Transcribing ${audioTarget} (${auth.provider}, local key)…`);
+        const audio = await loadSpeechAudioLocally(audioTarget);
+        if (audio.bytes.byteLength > MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES) {
+            throw new Error(`Audio is ${(audio.bytes.byteLength / (1024 * 1024)).toFixed(1)}MB (limit ${(MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES / (1024 * 1024)).toFixed(0)}MB). Trim it or transcribe externally and pass --srt.`);
+        }
+        const transcript = await localTranscribeSpeech({
+            auth,
+            audio: audio.bytes,
+            contentType: audio.contentType,
+            language: typeof values.language === "string" ? values.language : undefined,
+            diarize: auth.provider === "gemini",
+            wordTimestamps: true
+        });
+        if (!transcript.segments.length)
+            throw new Error("Transcription returned no speech segments.");
+        cues = buildCaptionCues(transcript.segments, { maxWordsPerCue: maxWords, offsetSec, fallbackDurationSec: info.duration_seconds });
+        const hasRealWords = transcript.segments.some((segment) => segment.words?.length);
+        sourceNote = `${transcript.provider}/${transcript.model} (${hasRealWords ? "word-level timestamps" : "estimated word timings"})`;
+    }
+    if (!cues.length)
+        throw new Error("No caption cues produced.");
+    // Keep cues inside the composition's duration.
+    cues = cues.filter((cue) => cue.start < info.duration_seconds)
+        .map((cue) => ({ ...cue, duration: Math.min(cue.duration, Math.max(0.1, info.duration_seconds - cue.start)) }));
+    const result = insertCaptionLayers(html, cues, styleOptionsFromFlags(values));
+    writeFileSync(htmlPath, result.html);
+    if (values.json) {
+        console.log(JSON.stringify({ ok: true, style: result.styleId, cues: cues.length, replaced: result.replaced, layer_keys: result.layerKeys, source: sourceNote, gaps: computeCompositionGaps(result.html) }, null, 2));
+        return;
+    }
+    console.log(`Wrote ${cues.length} animated caption cues (style: ${result.styleId}) from ${sourceNote}.`);
+    if (result.replaced > 0)
+        console.log(`Replaced ${result.replaced} previous caption cues.`);
+    console.log(`Updated ${htmlPath} — a running \`vidfarm serve\` live-morphs it; \`vidfarm publish\` pushes to cloud.`);
+}
+async function runStyle(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...STYLE_FLAG_OPTIONS, json: { type: "boolean" } }
+    });
+    const htmlPath = resolveCompositionHtml(positionals[0]);
+    const opts = styleOptionsFromFlags(values);
+    if (!opts.style && !opts.animation && !opts.activeColor && !opts.highlightColor && opts.uppercase === undefined && !opts.color && !opts.background && !opts.backgroundStyle && !opts.fontFamily && opts.fontSize === undefined) {
+        throw new Error("captions style needs at least one style flag (e.g. --style karaoke).");
+    }
+    const result = restyleCaptionLayers(readFileSync(htmlPath, "utf8"), opts);
+    writeFileSync(htmlPath, result.html);
+    if (values.json) {
+        console.log(JSON.stringify({ ok: true, style: result.styleId, cues: result.layerKeys.length }, null, 2));
+        return;
+    }
+    console.log(`Restyled ${result.layerKeys.length} caption cues to ${result.styleId}.`);
+}
+async function runListCues(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { json: { type: "boolean" } }
+    });
+    const htmlPath = resolveCompositionHtml(positionals[0]);
+    const cues = readCaptionCues(readFileSync(htmlPath, "utf8"));
+    if (values.json) {
+        console.log(JSON.stringify({ cues }, null, 2));
+        return;
+    }
+    if (!cues.length) {
+        console.log("No animated caption layers. Run `vidfarm captions generate <dir>` to add some.");
+        return;
+    }
+    for (const cue of cues) {
+        console.log(`${cue.start.toFixed(2).padStart(8)}s +${cue.duration.toFixed(2)}s  ${cue.text}`);
+    }
+    console.log(`${cues.length} cues on track ${cues[0].track}.`);
+}
+async function runClear(argv) {
+    const { positionals } = parseArgs({ args: argv, allowPositionals: true, options: {} });
+    const htmlPath = resolveCompositionHtml(positionals[0]);
+    const result = clearCaptionLayers(readFileSync(htmlPath, "utf8"));
+    writeFileSync(htmlPath, result.html);
+    console.log(`Removed ${result.removed} animated caption layer${result.removed === 1 ? "" : "s"}.`);
+}
+//# sourceMappingURL=captions.js.map