@mevdragon/vidfarm-devcli 0.11.0 → 0.12.0

package/dist/src/app.js

@@ -21,7 +21,7 @@ import { writeForkManifest } from "./services/fork-manifest.js";
 import { renderHelpPage } from "./help-page.js";
 import { renderHomepage } from "./homepage.js";
 import { COMPOSITION_RUNTIME_SCRIPT_BODY } from "./composition-runtime.js";
-import { KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER } from "./hyperframes/composition.js";
+import { CAPTION_ANIM_CSS, CAPTION_STYLE_MARKER, KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, TRANSITION_CSS, TRANSITION_STYLE_MARKER } from "./hyperframes/composition.js";
 import { normalizeCompositionZIndexHtml, sanitizeCompositionHtml } from "./services/composition-sanitize.js";
 import { applyMarkupUsd } from "./services/billing-pricing.js";
 import { primitiveRegistry } from "./primitive-registry.js";
@@ -3089,7 +3089,7 @@ function buildPrimitiveEditorDocsRoutes() {
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/probe`, summary: "Primitive audio probe job. Body must be { tracer, payload: { source_audio_url }, webhook_url? }. Returns durable JSON metadata." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/concat`, summary: "Primitive audio concat job. Body must be { tracer, payload: { source_audio_urls, output_format?, audio_bitrate_kbps? }, webhook_url? }." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/normalize`, summary: "Primitive audio normalization job. Body must be { tracer, payload: { source_audio_url, output_format?, audio_bitrate_kbps?, sample_rate_hz? }, webhook_url? }." },
-        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/speech`, summary: "Primitive text-to-speech (TTS) job using saved OpenAI, Gemini, or OpenRouter provider keys. Body must be { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? }, webhook_url? }. instructions is a free-form voice-style prompt (tone, pacing, accent, emotion, persona — e.g. \"calm, warm bedtime narrator with a slight British accent\"). Returns a durable platform audio URL (mp3 or wav). Alias: POST /api/v1/primitives/tts." },
+        { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/speech`, summary: "Primitive text-to-speech (TTS) job using saved OpenAI, Gemini, or OpenRouter provider keys. Body must be { tracer, payload: { text, voice?, instructions?, provider?, model?, output_format? }, webhook_url? }. instructions is a free-form voice-style prompt (tone, pacing, accent, emotion, persona — e.g. \"calm, warm bedtime narrator with a slight British accent\"). voice is a provider preset (OpenAI: alloy/ash/coral/…; Gemini: Kore/Puck/Charon/…); provider is inferred from the voice when omitted, and a voice paired with the wrong provider is rejected with a 400. Returns a durable platform audio URL (mp3 or wav). Alias: POST /api/v1/primitives/tts." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/audio/transcribe`, summary: "Primitive speech-to-text (STT) job using saved provider keys. Accepts VIDEO or AUDIO sources; video audio is demuxed automatically. Body must be { tracer, payload: { source_url (aliases: source_video_url, source_audio_url, url), diarize?, language?, prompt?, provider?, model? }, webhook_url? }. Returns TWO formats in one job: a simple subtitle transcript (plain text + timed SRT cues, no speakers) and an advanced multi-speaker version (speaker-attributed timed segments for multi-narration), plus transcript.json/.srt/.txt artifacts. diarize defaults to true; speaker attribution needs a Gemini key (openai/openrouter degrade to a plain single-speaker transcript). Sources over ~40 minutes of speech must be trimmed first. Alias: POST /api/v1/primitives/stt." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/brainstorm/coldstart`, summary: "Primitive cold-start strategy questionnaire. Body should usually be { tracer, payload: { user_message }, webhook_url? }. user_message can be rough, like \"I don't know where to start\" or a messy description. count is optional only when the user explicitly wants more or fewer questions. offer_description remains accepted as a backward-compatible alias." },
         { method: "POST", path: `${PRIMITIVES_PREFIX}/brainstorm/awareness_stages`, summary: "Primitive awareness-stage recommendation. Body must be { tracer, payload: { offer_description }, webhook_url? }. Use this when the customer is unsure what type of ads to produce." },
@@ -4187,8 +4187,9 @@ function createEditorActionTool() {
                 "ungroup_layers",
                 "replace_composition_html",
                 "export_composition",
-                "generate_layer"
-            ]).describe("Which mutation to perform. Use generate_layer to AI-generate a video/image and auto-place it on the timeline (fill a gap or replace a scene). Use export_composition to trigger the same Export button available in the editor UI — this queues an AWS Lambda render and the finished MP4 URL will surface in the next editor_context as last_export_url."),
+                "generate_layer",
+                "set_captions"
+            ]).describe("Which mutation to perform. Use generate_layer to AI-generate a video/image and auto-place it on the timeline (fill a gap or replace a scene). Use export_composition to trigger the same Export button available in the editor UI — this queues an AWS Lambda render and the finished MP4 URL will surface in the next editor_context as last_export_url. Use set_captions to lay down a full run of ANIMATED word-by-word captions (TikTok/CapCut style): pass captions[] cues (or text + start/duration to auto-page), plus caption_style; it replaces any existing animated caption layers. To restyle existing captions without changing text/timing, use set_layer_style with caption_* fields on each caption layer."),
             layer_key: z.string().optional().describe("Existing layer key from editor_context (required for remove/set/duplicate/split). MAY be either the element_id (data-hf-id) or the slug (data-hf-slug). For add_layer, optionally provide a stable id (starts with a letter, [A-Za-z0-9_-], <=64 chars) to reuse in later tool calls this turn."),
             slug: z.string().optional().describe("snake_case slug for the layer. On add_layer, seeds data-hf-slug. On set_layer_identity, sets it. Slugs give viral DNA a stable handle for the element."),
             note: z.string().optional().describe("Human-facing note explaining the layer's role, referenced by viral DNA. On add_layer seeds data-hf-note. On set_layer_identity, sets it. Empty string removes."),
@@ -4221,6 +4222,23 @@ function createEditorActionTool() {
             object_position: z.string().optional().describe("CSS object-position for image/video (e.g., center, top, bottom left)."),
             ken_burns: z.enum(["zoom-in", "zoom-out", "pan-left", "pan-right", "pan-up", "pan-down", "zoom-in-left", "zoom-in-right", "none"]).optional().describe("Ken Burns motion for still-image layers: a slow pan/zoom spanning the clip's full duration. Apply with set_layer_media on an existing image, or seed it on add_layer/generate_layer when kind/media_type is image. 'none' removes the effect. When the user says 'animate the images' / 'ken burns', apply it to every still image, varying presets across adjacent clips (zoom-in, pan-left, zoom-out, ...) for a documentary feel."),
             ken_burns_intensity: z.number().optional().describe("Ken Burns strength: extra zoom / pan travel as a fraction of the frame, 0.04-0.5 (default 0.18; ~0.1 subtle, ~0.3 dramatic). Only meaningful alongside ken_burns."),
+            transition: z.enum(["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", "none"]).optional().describe("Scene transition INTO this clip at its start, from the previous clip on the same track. Set it on the INCOMING clip (the one after the cut) with set_layer_media, or seed it on add_layer/generate_layer. Works on video and image scene clips; 'none' removes it. The previous butt-cut clip is automatically held on screen beneath the incoming one for the transition window — do not retime anything yourself. When the user asks for 'transitions between scenes' / 'smooth cuts', apply one to EVERY scene clip except the first, varying or matching presets to the template's energy (crossfade/fade-black = calm, slide/wipe = energetic, zoom/circle-open = punchy)."),
+            transition_duration: z.number().optional().describe("Transition length in seconds, 0.1-2.5 (default 0.5; ~0.3 snappy, ~1.0 slow cinematic). Only meaningful alongside transition."),
+            caption_style: z.enum(["spotlight", "karaoke", "word-pop", "stack-up", "neon", "bounce"]).optional().describe("Animated caption preset look: spotlight (active word gets a highlight pill, bold outline text), karaoke (words fill with color as spoken), word-pop (one word at a time, punchy scale-in), stack-up (words fade/rise in and stay), neon (active word glow pulse), bounce (active word bounces). Applies animation + colors + background treatment in one go; individual caption_*/color/background/background_style fields override specifics."),
+            caption_animation: z.enum(["highlight-pop", "karaoke-fill", "word-pop", "cumulative-reveal", "glow-pulse", "bounce-wave", "none"]).optional().describe("Word-by-word caption animation, if you want to set it directly instead of via caption_style. Works on set_captions, add_layer (kind=text), and set_layer_style. 'none' removes the animation and flattens the layer back to static text."),
+            caption_active_color: z.string().optional().describe("CSS color the active word takes while it is spoken (karaoke fill color, highlight text color, glow color)."),
+            caption_highlight_color: z.string().optional().describe("CSS color of the rounded pill behind the active word (highlight-pop animation only)."),
+            caption_uppercase: z.boolean().optional().describe("Render caption words in uppercase."),
+            captions: z.array(z.object({
+                text: z.string().describe("Cue text — one page of ~3-5 words shown together."),
+                start: z.number().describe("Cue start in seconds on the composition timeline."),
+                duration: z.number().describe("Cue length in seconds (cues must not overlap)."),
+                words: z.array(z.object({
+                    text: z.string(),
+                    start: z.number().describe("Word start in seconds RELATIVE to the cue start."),
+                    end: z.number().describe("Word end in seconds RELATIVE to the cue start.")
+                })).optional().describe("Word-level timings relative to the cue start (e.g. from a transcript). Omit to auto-estimate across the cue.")
+            })).optional().describe("set_captions: the full animated-caption cue list, one caption layer per cue on a shared free track. Replaces ALL existing animated caption layers. Derive cue timing from the video's transcript/segments when available. Alternatively omit this and pass text (+ start/duration window) to auto-page plain text."),
             volume: z.number().optional().describe("Volume 0..1 for audio/video."),
             muted: z.boolean().optional().describe("Toggle mute on audio/video."),
             group_label: z.string().optional().describe("Optional label for group_layers."),
@@ -4615,6 +4633,34 @@ function rewriteHyperframesDraftCompositionHtml(html, draftPath) {
             rewritten = `${rewritten}\n${kenBurnsTag}`;
         }
     }
+    // Same deal for the animated-caption keyframes: applying a caption style in
+    // the editor must animate immediately on older stored compositions.
+    if (!rewritten.includes(CAPTION_STYLE_MARKER)) {
+        const captionTag = `<style data-vf-captions="true">${CAPTION_ANIM_CSS}</style>`;
+        if (/<\/head>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/head>/i, `${captionTag}\n</head>`);
+        }
+        else if (/<\/body>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/body>/i, `${captionTag}\n</body>`);
+        }
+        else {
+            rewritten = `${rewritten}\n${captionTag}`;
+        }
+    }
+    // And the scene-transition keyframes: toggling data-transition on a clip
+    // must animate immediately on older stored compositions.
+    if (!rewritten.includes(TRANSITION_STYLE_MARKER)) {
+        const transitionTag = `<style data-vf-transitions="true">${TRANSITION_CSS}</style>`;
+        if (/<\/head>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/head>/i, `${transitionTag}\n</head>`);
+        }
+        else if (/<\/body>/i.test(rewritten)) {
+            rewritten = rewritten.replace(/<\/body>/i, `${transitionTag}\n</body>`);
+        }
+        else {
+            rewritten = `${rewritten}\n${transitionTag}`;
+        }
+    }
     return rewritten;
 }
 async function renderHyperframesStudioEditorPage(input) {

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
@@ -141,6 +143,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 +175,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 +193,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 +458,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.
@@ -1986,6 +2010,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 +2043,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 +2118,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 +2188,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 +2504,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 +2548,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,88 @@ 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.
+  function syncCaptionClip(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-cap-") !== 0) continue;
+      try {
+        anim.pause();
+        anim.currentTime = offsetMs;
+      } 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 +260,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);

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