@mevdragon/vidfarm-devcli 0.10.0 → 0.12.0

package/dist/src/cli.js

@@ -9,7 +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
@@ -140,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)
@@ -160,6 +169,41 @@ Clip hunting (the third library — mine long-form video into a reusable clip st
   clips preset list|run <name>|save <name> --from-query '<...>'          → /clips/presets
   clips export <ids...> --to <dir>   Copy clip mp4s + metadata out
                             (run 'vidfarm clips' for the full clips help)
+
+Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit backup:
+  tts "<text>"              Text → narration audio file.                 LOCAL: your OPENAI/GEMINI/
+                            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…).
+                              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)
+  stt <file|url>            Video or audio → transcript (alias: transcribe).  LOCAL: local ffmpeg demux +
+                            Returns BOTH formats: the simple subtitle    your provider key (gemini labels
+                            version (plain text + timed SRT cues) and    speakers; openai/openrouter give
+                            the advanced multi-speaker version           a plain transcript)
+                            (speaker-labeled timed segments).
+    --out <base|.json|.srt|.txt>  Write transcript files — bare base writes all three
+    --no-diarize              Skip speaker attribution (plain transcript only)
+    --language <code>         Expected language hint (e.g. en, es)
+    --prompt "<context>"      Domain/vocabulary hint for the transcriber
+    --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
@@ -252,6 +296,15 @@ Publish-mode options:
   --message <text>    Message attached to the published version snapshot
   --no-snapshot       Only update the working copy; skip the version snapshot
 `;
+// ANSI palette — declared BEFORE main() is invoked because command handlers may
+// reference these synchronously (before their first await) while the rest of
+// this module is still evaluating.
+const FRONTEND = "\x1b[1m\x1b[36m"; // bold cyan — reserved for openable URLs
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
 void main().catch(async (error) => {
     console.error(error instanceof Error ? error.stack ?? error.message : String(error));
     // Report only unexpected crashes (bugs), never the deliberate user-facing
@@ -314,6 +367,13 @@ async function main() {
         case "generate":
             await runGenerateCommand(rest);
             return;
+        case "tts":
+            await runTtsCommand(rest);
+            return;
+        case "stt":
+        case "transcribe":
+            await runSttCommand(rest);
+            return;
         case "place":
             await runPlaceCommand(rest);
             return;
@@ -398,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.
@@ -407,16 +470,6 @@ async function main() {
             throw new Error(`Unknown option before command: ${command}\n\n${HELP}`);
     }
 }
-// ── REST plumbing shared by every wrapper command ───────────────────────────
-// One code path for auth + host + query + JSON. This is what makes the devcli a
-// thin shell over the REST API rather than a second implementation: the named
-// commands below just assemble a method/path/body and hand it here.
-const FRONTEND = "\x1b[1m\x1b[36m"; // bold cyan — reserved for openable URLs
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const GREEN = "\x1b[32m";
-const RED = "\x1b[31m";
-const RESET = "\x1b[0m";
 async function apiRequest(input) {
     const url = new URL(input.path, input.host);
     for (const [key, value] of Object.entries(input.query ?? {})) {
@@ -1957,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
@@ -1988,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" }
         }
     });
@@ -2061,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)
@@ -2075,6 +2134,357 @@ async function runGenerateCommand(argv) {
             console.log(`${DIM}Place it with: vidfarm place <dir> --src "${mediaUrl}" --kind ${mediaType} --at <time>|--replace <layer_key>${RESET}`);
     }
 }
+// ── Speech: tts / stt ────────────────────────────────────────────────────────
+// LOCAL-FIRST like `clips scan`: both commands default to running on the
+// user's OWN AI key (GEMINI_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY or
+// the --*-key flags) via src/services/speech.ts — local ffmpeg demux, direct
+// provider call, no cloud job, no wallet. The REST primitive routes
+// (/api/v1/primitives/audio/speech|transcribe) are the explicit `--cloud`
+// backup. Speech cannot ride on a claude/codex CLI agent (no audio I/O), so
+// "local" means a raw provider key here, not the agent CLI.
+function speechKeyHint(kind) {
+    const preference = kind === "stt"
+        ? "GEMINI_API_KEY (best — it can label speakers), OPENAI_API_KEY, or OPENROUTER_API_KEY"
+        : "OPENAI_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY";
+    return `No local AI key found. Set ${preference} (or pass --gemini-key/--openai-key/--openrouter-key), or run with --cloud to use your saved Vidfarm provider keys.`;
+}
+async function downloadUrlToFile(url, dest) {
+    const res = await fetch(url);
+    if (!res.ok || !res.body)
+        throw new Error(`download failed (${res.status}) for ${url}`);
+    mkdirSync(path.dirname(dest), { recursive: true });
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+}
+async function runTtsCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            text: { type: "string" },
+            style: { type: "string" },
+            instructions: { type: "string" },
+            voice: { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            format: { type: "string" },
+            out: { type: "string" },
+            cloud: { type: "boolean", default: false },
+            "gemini-key": { type: "string" },
+            "openai-key": { type: "string" },
+            "openrouter-key": { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" }
+        }
+    });
+    const text = (parsed.values.text ?? parsed.positionals.join(" ")).trim();
+    if (!text)
+        throw new Error('tts requires text: vidfarm tts "Welcome back to the channel" --style "calm, warm narrator".');
+    const style = (parsed.values.instructions ?? parsed.values.style)?.trim() || undefined;
+    const rawFormat = String(parsed.values.format ?? "mp3").toLowerCase();
+    if (rawFormat !== "mp3" && rawFormat !== "wav")
+        throw new Error("tts --format must be mp3 or wav.");
+    const format = rawFormat;
+    const voice = parsed.values.voice;
+    const json = Boolean(parsed.values.json);
+    if (!parsed.values.cloud) {
+        // 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)
+            console.log(`${DIM}Generating speech locally on your ${auth.provider} key…${RESET}`);
+        const result = await localGenerateSpeech({
+            auth,
+            text,
+            voice,
+            instructions: style,
+            model: parsed.values.model,
+            responseFormat: format
+        });
+        const extension = result.contentType.includes("wav") ? "wav" : "mp3";
+        const outPath = path.resolve(process.cwd(), parsed.values.out ?? `tts-${Date.now().toString(36)}.${extension}`);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        writeFileSync(outPath, result.bytes);
+        if (json) {
+            printJson({ ok: true, mode: "local", provider: result.provider, model: result.model, voice: voice ?? null, style: style ?? null, content_type: result.contentType, bytes: result.bytes.byteLength, out: outPath });
+        }
+        else {
+            console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(${result.provider}/${result.model}, ${Math.round(result.bytes.byteLength / 1024)}KB)${RESET}`);
+            console.log(`${DIM}Get a shareable URL with: vidfarm upload "${outPath}" — then add it to a composition as an audio layer.${RESET}`);
+        }
+        return;
+    }
+    // BACKUP: the platform primitive route (saved provider keys, async job).
+    const ctx = commonContext(parsed.values);
+    const payload = { text, output_format: format };
+    if (voice)
+        payload.voice = voice;
+    if (style)
+        payload.instructions = style;
+    if (parsed.values.provider)
+        payload.provider = parsed.values.provider;
+    if (parsed.values.model)
+        payload.model = parsed.values.model;
+    const tracer = parsed.values.tracer ?? `devcli-tts-${Date.now().toString(36)}`;
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/audio/speech", auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "tts");
+    const jobId = submit.json?.job_id;
+    if (parsed.values["no-wait"] || !jobId) {
+        if (!ctx.json && jobId)
+            console.log(`${DIM}Queued ${jobId} (tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId} — or drop --no-wait to auto-poll.${RESET}`);
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Generating speech (${jobId})… polling every 5s.${RESET}`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const mediaUrl = resolveJobMediaUrl(job);
+    if (!mediaUrl) {
+        if (ctx.json) {
+            printJson({ ok: false, job_id: jobId, status: String(job?.status ?? ""), job });
+        }
+        else {
+            console.log(`${RED}TTS ${String(job?.status ?? "did not finish")} — no audio URL.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const extension = /\.wav(\?|#|$)/i.test(mediaUrl) ? "wav" : "mp3";
+    const outPath = path.resolve(process.cwd(), parsed.values.out ?? `tts-${jobId}.${extension}`);
+    await downloadUrlToFile(mediaUrl, outPath);
+    if (ctx.json) {
+        printJson({ ok: true, mode: "cloud", job_id: jobId, tracer, audio_url: mediaUrl, out: outPath });
+    }
+    else {
+        console.log(`${GREEN}Wrote ${outPath}${RESET} ${DIM}(${mediaUrl})${RESET}`);
+    }
+}
+function formatSpeechClock(totalSeconds) {
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = Math.floor(totalSeconds % 60);
+    return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+// Print/persist BOTH transcript formats: the simple subtitle version (plain
+// text + SRT cues) and the advanced multi-speaker version (speaker-attributed
+// segments → .json). --out picks one via extension or writes all three.
+function emitSttResult(input) {
+    const written = [];
+    if (input.out) {
+        const explicitExtension = /\.(json|srt|txt)$/i.exec(input.out)?.[1]?.toLowerCase() ?? null;
+        const base = explicitExtension ? input.out.slice(0, -(explicitExtension.length + 1)) : input.out;
+        const targets = explicitExtension ? [explicitExtension] : ["json", "srt", "txt"];
+        for (const kind of targets) {
+            const dest = path.resolve(process.cwd(), `${base}.${kind}`);
+            if (kind === "json") {
+                mkdirSync(path.dirname(dest), { recursive: true });
+                writeFileSync(dest, `${JSON.stringify({
+                    source: input.source,
+                    mode: input.mode,
+                    provider: input.provider,
+                    model: input.model,
+                    language: input.result.language,
+                    diarization: input.result.diarization,
+                    text: input.result.text,
+                    speakers: [...new Set((input.result.segments ?? []).map((segment) => segment.speaker))],
+                    segments: input.result.segments ?? []
+                }, null, 2)}\n`);
+                written.push(dest);
+            }
+            else if (kind === "srt") {
+                if (input.result.srt) {
+                    mkdirSync(path.dirname(dest), { recursive: true });
+                    writeFileSync(dest, input.result.srt);
+                    written.push(dest);
+                }
+                else if (explicitExtension === "srt") {
+                    console.log(`${RED}No timed segments — cannot write ${dest}. The plain transcript is still available (--out <base>.txt).${RESET}`);
+                }
+            }
+            else {
+                mkdirSync(path.dirname(dest), { recursive: true });
+                writeFileSync(dest, `${input.result.text ?? ""}\n`);
+                written.push(dest);
+            }
+        }
+    }
+    if (input.json) {
+        printJson({
+            ok: true,
+            mode: input.mode,
+            provider: input.provider,
+            model: input.model,
+            ...(input.jobId ? { job_id: input.jobId } : {}),
+            source: input.source,
+            language: input.result.language,
+            diarization: input.result.diarization,
+            text: input.result.text,
+            segments: input.result.segments ?? [],
+            srt: input.result.srt,
+            written
+        });
+        return;
+    }
+    if (input.result.segments?.length && input.result.diarization === "diarized") {
+        for (const segment of input.result.segments) {
+            const at = typeof segment.start_sec === "number" ? `${DIM}[${formatSpeechClock(segment.start_sec)}]${RESET} ` : "";
+            console.log(`${at}${segment.speaker}: ${segment.text}`);
+        }
+    }
+    else {
+        console.log(input.result.text || "(no speech detected)");
+    }
+    for (const dest of written) {
+        console.log(`${GREEN}Wrote ${dest}${RESET}`);
+    }
+}
+async function runSttCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            "no-diarize": { type: "boolean", default: false },
+            language: { type: "string" },
+            prompt: { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            out: { type: "string" },
+            cloud: { type: "boolean", default: false },
+            "gemini-key": { type: "string" },
+            "openai-key": { type: "string" },
+            "openrouter-key": { type: "string" },
+            "no-wait": { type: "boolean", default: false },
+            tracer: { type: "string" },
+            folder: { type: "string" }
+        }
+    });
+    const target = parsed.positionals[0];
+    if (!target)
+        throw new Error("stt requires a source: `vidfarm stt <video-or-audio file|url>`.");
+    const diarize = !parsed.values["no-diarize"];
+    const json = Boolean(parsed.values.json);
+    const language = parsed.values.language?.trim() || undefined;
+    const prompt = parsed.values.prompt?.trim() || undefined;
+    if (!parsed.values.cloud) {
+        const auth = resolveLocalSpeechAuth(parsed.values, ["gemini", "openai", "openrouter"], parsed.values.provider);
+        if (!auth)
+            throw new Error(speechKeyHint("stt"));
+        if (diarize && auth.provider !== "gemini" && !json) {
+            console.log(`${DIM}Note: speaker labels need a Gemini key; ${auth.provider} returns a plain single-speaker transcript.${RESET}`);
+        }
+        if (!json)
+            console.log(`${DIM}Transcribing locally on your ${auth.provider} key (local ffmpeg demux)…${RESET}`);
+        const audio = await loadSpeechAudioLocally(target);
+        if (audio.bytes.byteLength > MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES) {
+            throw new Error(`Audio is too large to transcribe (${Math.round(audio.bytes.byteLength / (1024 * 1024))}MB > 20MB, roughly 40 minutes of speech). Trim the source first.`);
+        }
+        const result = await localTranscribeSpeech({
+            auth,
+            audio: audio.bytes,
+            contentType: audio.contentType,
+            model: parsed.values.model,
+            prompt,
+            language,
+            diarize
+        });
+        emitSttResult({
+            json,
+            out: parsed.values.out,
+            source: target,
+            mode: "local",
+            provider: result.provider,
+            model: result.model,
+            result: {
+                text: result.text,
+                language: result.language,
+                diarization: result.diarization,
+                segments: result.segments,
+                srt: result.srt
+            }
+        });
+        return;
+    }
+    // BACKUP: the platform primitive route. URLs pass through; local files
+    // upload to the ephemeral temp store first (30-day TTL).
+    const ctx = commonContext(parsed.values);
+    const sourceUrl = /^https?:\/\//i.test(target)
+        ? target
+        : await uploadLocalToTempStore(ctx, path.resolve(process.cwd(), target), parsed.values.folder ?? "temp");
+    const payload = { source_url: sourceUrl, diarize };
+    if (language)
+        payload.language = language;
+    if (prompt)
+        payload.prompt = prompt;
+    if (parsed.values.provider)
+        payload.provider = parsed.values.provider;
+    if (parsed.values.model)
+        payload.model = parsed.values.model;
+    const tracer = parsed.values.tracer ?? `devcli-stt-${Date.now().toString(36)}`;
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/audio/transcribe", auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "stt");
+    const jobId = submit.json?.job_id;
+    if (parsed.values["no-wait"] || !jobId) {
+        if (!ctx.json && jobId)
+            console.log(`${DIM}Queued ${jobId} (tracer ${tracer}). Poll: vidfarm api GET /api/v1/user/me/jobs/${jobId} — or drop --no-wait to auto-poll.${RESET}`);
+        emitResult(submit, ctx.json);
+        return;
+    }
+    if (!ctx.json)
+        console.log(`${DIM}Transcribing (${jobId})… polling every 5s.${RESET}`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const status = String(job?.status ?? "");
+    const rawResult = (job?.result && typeof job.result === "object") ? job.result : {};
+    const output = (rawResult.output && typeof rawResult.output === "object") ? rawResult.output : rawResult;
+    if (status !== "succeeded" && typeof output.text !== "string") {
+        if (ctx.json) {
+            printJson({ ok: false, job_id: jobId, status, job });
+        }
+        else {
+            console.log(`${RED}Transcription ${status || "did not finish"}.${RESET}`);
+            printJson(job);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // Long transcripts stay artifact-only; hydrate the full version from
+    // transcript.json / transcript.srt when the inline copy was truncated.
+    let text = typeof output.text === "string" ? output.text : "";
+    let segments = Array.isArray(output.segments) ? output.segments : null;
+    let srt = typeof output.subtitles?.srt === "string" ? output.subtitles.srt : null;
+    const jsonUrl = typeof output.transcript?.json_url === "string" ? output.transcript.json_url : null;
+    if ((output.text_truncated === true || !segments) && jsonUrl) {
+        const hydrated = await fetch(jsonUrl).then((res) => (res.ok ? res.json() : null)).catch(() => null);
+        if (hydrated && typeof hydrated === "object") {
+            if (typeof hydrated.text === "string")
+                text = hydrated.text;
+            if (Array.isArray(hydrated.segments))
+                segments = hydrated.segments;
+        }
+    }
+    if (!srt && typeof output.subtitles?.srt_url === "string") {
+        srt = await fetch(output.subtitles.srt_url).then((res) => (res.ok ? res.text() : null)).catch(() => null);
+    }
+    emitSttResult({
+        json: ctx.json,
+        out: parsed.values.out,
+        source: target,
+        mode: "cloud",
+        provider: typeof output.transcript?.provider === "string" ? output.transcript.provider : null,
+        model: typeof output.transcript?.model === "string" ? output.transcript.model : null,
+        jobId,
+        result: {
+            text,
+            language: typeof output.language === "string" ? output.language : null,
+            diarization: typeof output.diarization === "string" ? output.diarization : "none",
+            segments,
+            srt
+        }
+    });
+}
 async function runPlaceCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -2094,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
@@ -2136,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);