@mevdragon/vidfarm-devcli 0.12.0 → 0.14.0

package/dist/src/hyperframes/composition.js

@@ -98,10 +98,16 @@ export function normalizeKenBurns(value) {
 export const TRANSITION_PRESETS = [
     "crossfade",
     "fade-black",
+    "fade-white",
+    "flash",
+    "smoke",
+    "blur",
     "slide-left",
     "slide-right",
     "slide-up",
     "slide-down",
+    "whip-left",
+    "whip-right",
     "wipe-left",
     "wipe-right",
     "wipe-up",
@@ -110,14 +116,49 @@ export const TRANSITION_PRESETS = [
     "zoom-out",
     "circle-open"
 ];
+// Exit transitions: the clip animates AWAY over its last data-transition-out-
+// duration seconds. Same declarative contract as the entrance presets; the
+// keyframes omit the `from` state so the animation departs from the element's
+// own inline styles, and the inline --vf-tr-out-delay var (clip duration minus
+// out duration) positions the animation window at the clip's tail so the
+// time-based scrub in the producer and preview runtimes needs no extra logic.
+export const TRANSITION_OUT_PRESETS = [
+    "fade",
+    "fade-black",
+    "fade-white",
+    "flash",
+    "smoke",
+    "blur",
+    "slide-left",
+    "slide-right",
+    "slide-up",
+    "slide-down",
+    "wipe-left",
+    "wipe-right",
+    "wipe-up",
+    "wipe-down",
+    "zoom-in",
+    "zoom-out",
+    "circle-close"
+];
 export const TRANSITION_DEFAULT_DURATION = 0.5;
 export const TRANSITION_MIN_DURATION = 0.1;
 export const TRANSITION_MAX_DURATION = 2.5;
 // Two butt-cut clips can drift by a few ms through timeline edits; treat ends
 // within this window as adjacent when granting the outgoing clip's hold.
 export const TRANSITION_ADJACENCY_EPSILON = 0.05;
-export const TRANSITION_STYLE_MARKER = "__VF_TRANSITIONS_V1__";
-export const TRANSITION_CSS = `/*${TRANSITION_STYLE_MARKER}*/
+// V2: entrance AND exit animations compose on one element via cascading custom
+// properties (--vf-tr-in-name / --vf-tr-out-name) feeding a two-slot animation
+// list — per-preset attribute selectors can't merge two animation-names, vars
+// can. The [data-kenburns] combo rules below fix a V1 latent clash where Ken
+// Burns and a transition on the same <img> fought over animation-name (equal
+// specificity, last stylesheet won); the (0,2,0) combo selectors prepend the
+// vf-kb animation to the list instead.
+export const TRANSITION_STYLE_MARKER = "__VF_TRANSITIONS_V2__";
+// The exact V1 block previous builds baked into stored compositions. Injectors
+// string-replace this with the current TRANSITION_CSS so old drafts/publishes
+// upgrade in place instead of accumulating duplicate style blocks.
+export const LEGACY_TRANSITION_CSS_V1 = `/*__VF_TRANSITIONS_V1__*/
 @keyframes vf-tr-crossfade { from { opacity: 0; } }
 @keyframes vf-tr-fade-black { 0% { opacity: 0; filter: brightness(0); } 35% { opacity: 1; filter: brightness(0); } }
 @keyframes vf-tr-slide-left { from { translate: 100% 0; } }
@@ -151,12 +192,119 @@ export const TRANSITION_CSS = `/*${TRANSITION_STYLE_MARKER}*/
 [data-transition="zoom-out"] { animation-name: vf-tr-zoom-out; }
 [data-transition="circle-open"] { animation-name: vf-tr-circle-open; }
 `;
+export const TRANSITION_CSS = `/*${TRANSITION_STYLE_MARKER}*/
+@keyframes vf-tr-crossfade { from { opacity: 0; } }
+@keyframes vf-tr-fade-black { 0% { opacity: 0; filter: brightness(0); } 35% { opacity: 1; filter: brightness(0); } }
+@keyframes vf-tr-fade-white { 0% { opacity: 0; filter: saturate(0.55) brightness(3); } 45% { opacity: 1; filter: saturate(0.7) brightness(2.1); } }
+@keyframes vf-tr-flash { 0% { filter: saturate(0.3) brightness(5); } 55% { filter: saturate(0.9) brightness(1.6); } }
+@keyframes vf-tr-smoke { 0% { opacity: 0; filter: blur(26px) saturate(0.65) brightness(1.55); } 55% { opacity: 1; } }
+@keyframes vf-tr-blur { from { opacity: 0; filter: blur(16px); } }
+@keyframes vf-tr-slide-left { from { translate: 100% 0; } }
+@keyframes vf-tr-slide-right { from { translate: -100% 0; } }
+@keyframes vf-tr-slide-up { from { translate: 0 100%; } }
+@keyframes vf-tr-slide-down { from { translate: 0 -100%; } }
+@keyframes vf-tr-whip-left { 0% { translate: 110% 0; filter: blur(14px); } 60% { filter: blur(5px); } }
+@keyframes vf-tr-whip-right { 0% { translate: -110% 0; filter: blur(14px); } 60% { filter: blur(5px); } }
+@keyframes vf-tr-wipe-left { from { clip-path: inset(0 0 0 100%); } to { clip-path: inset(0 0 0 0); } }
+@keyframes vf-tr-wipe-right { from { clip-path: inset(0 100% 0 0); } to { clip-path: inset(0 0 0 0); } }
+@keyframes vf-tr-wipe-up { from { clip-path: inset(100% 0 0 0); } to { clip-path: inset(0 0 0 0); } }
+@keyframes vf-tr-wipe-down { from { clip-path: inset(0 0 100% 0); } to { clip-path: inset(0 0 0 0); } }
+@keyframes vf-tr-zoom-in { from { opacity: 0; scale: 1.18; } }
+@keyframes vf-tr-zoom-out { from { opacity: 0; scale: 0.82; } }
+@keyframes vf-tr-circle-open { from { clip-path: circle(0% at 50% 50%); } to { clip-path: circle(75% at 50% 50%); } }
+@keyframes vf-tr-out-fade { to { opacity: 0; } }
+@keyframes vf-tr-out-fade-black { to { filter: brightness(0); } }
+@keyframes vf-tr-out-fade-white { to { filter: saturate(0.35) brightness(6); } }
+@keyframes vf-tr-out-flash { 65% { filter: brightness(1); } 100% { filter: saturate(0.3) brightness(5); } }
+@keyframes vf-tr-out-smoke { to { opacity: 0; filter: blur(24px) saturate(0.7) brightness(1.5); } }
+@keyframes vf-tr-out-blur { to { opacity: 0; filter: blur(16px); } }
+@keyframes vf-tr-out-slide-left { to { translate: -100% 0; } }
+@keyframes vf-tr-out-slide-right { to { translate: 100% 0; } }
+@keyframes vf-tr-out-slide-up { to { translate: 0 -100%; } }
+@keyframes vf-tr-out-slide-down { to { translate: 0 100%; } }
+@keyframes vf-tr-out-wipe-left { from { clip-path: inset(0 0 0 0); } to { clip-path: inset(0 100% 0 0); } }
+@keyframes vf-tr-out-wipe-right { from { clip-path: inset(0 0 0 0); } to { clip-path: inset(0 0 0 100%); } }
+@keyframes vf-tr-out-wipe-up { from { clip-path: inset(0 0 0 0); } to { clip-path: inset(0 0 100% 0); } }
+@keyframes vf-tr-out-wipe-down { from { clip-path: inset(0 0 0 0); } to { clip-path: inset(100% 0 0 0); } }
+@keyframes vf-tr-out-zoom-in { to { opacity: 0; scale: 1.18; } }
+@keyframes vf-tr-out-zoom-out { to { opacity: 0; scale: 0.82; } }
+@keyframes vf-tr-out-circle-close { from { clip-path: circle(75% at 50% 50%); } to { clip-path: circle(0% at 50% 50%); } }
+[data-transition], [data-transition-out] {
+  animation-name: var(--vf-tr-in-name, none), var(--vf-tr-out-name, none);
+  animation-duration: var(--vf-tr-dur, 0.5s), var(--vf-tr-out-dur, 0.5s);
+  animation-delay: 0s, var(--vf-tr-out-delay, 0s);
+  animation-timing-function: var(--vf-tr-ease, ease-in-out), var(--vf-tr-out-ease, ease-in-out);
+  animation-fill-mode: both, both;
+  animation-play-state: paused, paused;
+}
+[data-kenburns][data-transition], [data-kenburns][data-transition-out] {
+  animation-name: var(--vf-kb-name, none), var(--vf-tr-in-name, none), var(--vf-tr-out-name, none);
+  animation-duration: var(--vf-kb-dur, 5s), var(--vf-tr-dur, 0.5s), var(--vf-tr-out-dur, 0.5s);
+  animation-delay: 0s, 0s, var(--vf-tr-out-delay, 0s);
+  animation-timing-function: var(--vf-kb-ease, linear), var(--vf-tr-ease, ease-in-out), var(--vf-tr-out-ease, ease-in-out);
+  animation-fill-mode: both, both, both;
+  animation-play-state: paused, paused, paused;
+}
+[data-kenburns="zoom-in"] { --vf-kb-name: vf-kb-zoom-in; }
+[data-kenburns="zoom-out"] { --vf-kb-name: vf-kb-zoom-out; }
+[data-kenburns="pan-left"] { --vf-kb-name: vf-kb-pan-left; }
+[data-kenburns="pan-right"] { --vf-kb-name: vf-kb-pan-right; }
+[data-kenburns="pan-up"] { --vf-kb-name: vf-kb-pan-up; }
+[data-kenburns="pan-down"] { --vf-kb-name: vf-kb-pan-down; }
+[data-kenburns="zoom-in-left"] { --vf-kb-name: vf-kb-zoom-in-left; }
+[data-kenburns="zoom-in-right"] { --vf-kb-name: vf-kb-zoom-in-right; }
+[data-transition="crossfade"] { --vf-tr-in-name: vf-tr-crossfade; }
+[data-transition="fade-black"] { --vf-tr-in-name: vf-tr-fade-black; }
+[data-transition="fade-white"] { --vf-tr-in-name: vf-tr-fade-white; }
+[data-transition="flash"] { --vf-tr-in-name: vf-tr-flash; --vf-tr-ease: cubic-bezier(0.3, 0, 0.55, 1); }
+[data-transition="smoke"] { --vf-tr-in-name: vf-tr-smoke; --vf-tr-ease: cubic-bezier(0.25, 0.4, 0.3, 1); }
+[data-transition="blur"] { --vf-tr-in-name: vf-tr-blur; }
+[data-transition="slide-left"] { --vf-tr-in-name: vf-tr-slide-left; --vf-tr-ease: cubic-bezier(0.22, 1, 0.36, 1); }
+[data-transition="slide-right"] { --vf-tr-in-name: vf-tr-slide-right; --vf-tr-ease: cubic-bezier(0.22, 1, 0.36, 1); }
+[data-transition="slide-up"] { --vf-tr-in-name: vf-tr-slide-up; --vf-tr-ease: cubic-bezier(0.22, 1, 0.36, 1); }
+[data-transition="slide-down"] { --vf-tr-in-name: vf-tr-slide-down; --vf-tr-ease: cubic-bezier(0.22, 1, 0.36, 1); }
+[data-transition="whip-left"] { --vf-tr-in-name: vf-tr-whip-left; --vf-tr-ease: cubic-bezier(0.16, 1, 0.3, 1); }
+[data-transition="whip-right"] { --vf-tr-in-name: vf-tr-whip-right; --vf-tr-ease: cubic-bezier(0.16, 1, 0.3, 1); }
+[data-transition="wipe-left"] { --vf-tr-in-name: vf-tr-wipe-left; --vf-tr-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition="wipe-right"] { --vf-tr-in-name: vf-tr-wipe-right; --vf-tr-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition="wipe-up"] { --vf-tr-in-name: vf-tr-wipe-up; --vf-tr-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition="wipe-down"] { --vf-tr-in-name: vf-tr-wipe-down; --vf-tr-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition="zoom-in"] { --vf-tr-in-name: vf-tr-zoom-in; --vf-tr-ease: cubic-bezier(0.16, 1, 0.3, 1); }
+[data-transition="zoom-out"] { --vf-tr-in-name: vf-tr-zoom-out; --vf-tr-ease: cubic-bezier(0.16, 1, 0.3, 1); }
+[data-transition="circle-open"] { --vf-tr-in-name: vf-tr-circle-open; --vf-tr-ease: cubic-bezier(0.3, 0.6, 0.3, 1); }
+[data-transition-out="fade"] { --vf-tr-out-name: vf-tr-out-fade; }
+[data-transition-out="fade-black"] { --vf-tr-out-name: vf-tr-out-fade-black; }
+[data-transition-out="fade-white"] { --vf-tr-out-name: vf-tr-out-fade-white; }
+[data-transition-out="flash"] { --vf-tr-out-name: vf-tr-out-flash; --vf-tr-out-ease: cubic-bezier(0.45, 0, 0.7, 0.4); }
+[data-transition-out="smoke"] { --vf-tr-out-name: vf-tr-out-smoke; --vf-tr-out-ease: cubic-bezier(0.7, 0, 0.75, 0.6); }
+[data-transition-out="blur"] { --vf-tr-out-name: vf-tr-out-blur; }
+[data-transition-out="slide-left"] { --vf-tr-out-name: vf-tr-out-slide-left; --vf-tr-out-ease: cubic-bezier(0.55, 0.06, 0.68, 0.19); }
+[data-transition-out="slide-right"] { --vf-tr-out-name: vf-tr-out-slide-right; --vf-tr-out-ease: cubic-bezier(0.55, 0.06, 0.68, 0.19); }
+[data-transition-out="slide-up"] { --vf-tr-out-name: vf-tr-out-slide-up; --vf-tr-out-ease: cubic-bezier(0.55, 0.06, 0.68, 0.19); }
+[data-transition-out="slide-down"] { --vf-tr-out-name: vf-tr-out-slide-down; --vf-tr-out-ease: cubic-bezier(0.55, 0.06, 0.68, 0.19); }
+[data-transition-out="wipe-left"] { --vf-tr-out-name: vf-tr-out-wipe-left; --vf-tr-out-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition-out="wipe-right"] { --vf-tr-out-name: vf-tr-out-wipe-right; --vf-tr-out-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition-out="wipe-up"] { --vf-tr-out-name: vf-tr-out-wipe-up; --vf-tr-out-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition-out="wipe-down"] { --vf-tr-out-name: vf-tr-out-wipe-down; --vf-tr-out-ease: cubic-bezier(0.45, 0.05, 0.35, 0.95); }
+[data-transition-out="zoom-in"] { --vf-tr-out-name: vf-tr-out-zoom-in; --vf-tr-out-ease: cubic-bezier(0.5, 0, 0.75, 0.4); }
+[data-transition-out="zoom-out"] { --vf-tr-out-name: vf-tr-out-zoom-out; --vf-tr-out-ease: cubic-bezier(0.5, 0, 0.75, 0.4); }
+[data-transition-out="circle-close"] { --vf-tr-out-name: vf-tr-out-circle-close; --vf-tr-out-ease: cubic-bezier(0.6, 0, 0.7, 0.4); }
+`;
 export function clampTransitionDuration(value) {
     const next = Number(value);
     if (!Number.isFinite(next) || next <= 0)
         return TRANSITION_DEFAULT_DURATION;
     return Math.max(TRANSITION_MIN_DURATION, Math.min(TRANSITION_MAX_DURATION, next));
 }
+// Seconds into the clip at which its exit animation must start so it finishes
+// exactly at the clip's end. Written as the inline --vf-tr-out-delay var.
+export function transitionOutDelaySeconds(layerDurationSeconds, outDurationSeconds) {
+    const layerDuration = Number(layerDurationSeconds);
+    const outDuration = Number(outDurationSeconds);
+    if (!Number.isFinite(layerDuration) || !Number.isFinite(outDuration))
+        return 0;
+    return Math.max(0, Number((layerDuration - outDuration).toFixed(3)));
+}
 export function normalizeTransition(value) {
     if (!value)
         return null;
@@ -168,6 +316,28 @@ export function normalizeTransition(value) {
         duration: raw.duration !== undefined ? clampTransitionDuration(raw.duration) : undefined
     };
 }
+export function normalizeTransitionOut(value) {
+    if (!value)
+        return null;
+    const raw = typeof value === "string" ? { preset: value } : value;
+    if (!TRANSITION_OUT_PRESETS.includes(raw.preset))
+        return null;
+    return {
+        preset: raw.preset,
+        duration: raw.duration !== undefined ? clampTransitionDuration(raw.duration) : undefined
+    };
+}
+// Upgrades stored composition HTML that still carries the V1 transition
+// stylesheet: exact-replaces the legacy block with the current one. If the V1
+// marker is present but the block has drifted, callers' normal marker-guarded
+// injection appends the V2 block AFTER it, which also wins (equal-specificity
+// rules, later source order) — this replace just avoids duplicate blocks in
+// the common case.
+export function upgradeLegacyTransitionCss(html) {
+    if (!html || html.includes(TRANSITION_STYLE_MARKER) || !html.includes("__VF_TRANSITIONS_V1__"))
+        return html;
+    return html.split(LEGACY_TRANSITION_CSS_V1).join(TRANSITION_CSS);
+}
 // ---------------------------------------------------------------------------
 // Animated captions. Same declarative contract as Ken Burns: the caption layer
 // <div> (the element that owns data-start/data-duration) carries
@@ -476,6 +646,10 @@ function timedAttrs(layer) {
         if (transition) {
             attrs.push(`data-transition="${escapeAttr(transition.preset)}"`, `data-transition-duration="${num(clampTransitionDuration(transition.duration ?? TRANSITION_DEFAULT_DURATION))}"`);
         }
+        const transitionOut = normalizeTransitionOut(layer.transitionOut);
+        if (transitionOut) {
+            attrs.push(`data-transition-out="${escapeAttr(transitionOut.preset)}"`, `data-transition-out-duration="${num(clampTransitionDuration(transitionOut.duration ?? TRANSITION_DEFAULT_DURATION))}"`);
+        }
     }
     if (["caption", "text", "shape", "html"].includes(layer.kind)) {
         attrs.push(`data-text-background-style="${escapeAttr(layer.textBackgroundStyle || "plain")}"`, `data-text-background-color="${escapeAttr(layer.background || "#000000")}"`, `data-font-family="${escapeAttr(layer.fontFamily || "TikTok Sans")}"`);
@@ -504,6 +678,13 @@ function layerStyle(layer) {
         if (transition) {
             styles.push(`--vf-tr-dur:${num(clampTransitionDuration(transition.duration ?? TRANSITION_DEFAULT_DURATION))}s`);
         }
+        // Exit transitions additionally need the delay var so the animation window
+        // sits at the clip's tail (duration − out duration).
+        const transitionOut = normalizeTransitionOut(layer.transitionOut);
+        if (transitionOut) {
+            const outDur = clampTransitionDuration(transitionOut.duration ?? TRANSITION_DEFAULT_DURATION);
+            styles.push(`--vf-tr-out-dur:${num(outDur)}s`, `--vf-tr-out-delay:${num(transitionOutDelaySeconds(positiveNumber(layer.duration, 0), outDur))}s`);
+        }
     }
     if (["caption", "text", "shape", "html"].includes(layer.kind)) {
         const fontFamily = layer.fontFamily || "TikTok Sans";

package/dist/src/primitive-registry.js

@@ -8,6 +8,8 @@ import { definePrimitive } from "./primitive-sdk.js";
 import { PrimitiveMediaLambdaService } from "./services/primitive-media-lambda.js";
 import { estimateGhostcutCostUsd, isGhostcutConfigured, pollStatus as pollGhostcutStatus, submitSubtitleRemoval } from "./services/ghostcut.js";
 import { buildSrtFromSegments, defaultSpeechModelFor, inferSpeechProviderForVoice, speechVoiceMismatch } from "./services/speech.js";
+import { buildCaptionCues, cuesFromText } from "./services/captions.js";
+import { CAPTION_ANIMATIONS, CAPTION_STYLE_PRESETS, captionStylePresetById } from "./hyperframes/composition.js";
 import { buildHtmlImageCompositionHtml, buildMediaDedupeCompositionHtml, DEDUPE_DEFAULT_EFFECTS } from "./primitives/hyperframes-media.js";
 const imageProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
 const videoProviderSchema = z.enum(["openai", "gemini", "openrouter"]);
@@ -406,9 +408,58 @@ const sttPayloadSchema = z.preprocess((raw) => {
     source_url: mediaSourceUrlSchema,
     media_type: z.enum(["auto", "video", "audio"]).default("auto"),
     diarize: z.boolean().default(true),
+    // Word-level timings on each segment (animated captions). Real timestamps
+    // come from the openai path (whisper-1); other providers keep segment-level
+    // output and downstream callers estimate word windows.
+    word_timestamps: z.boolean().default(false),
     language: z.string().min(2).max(16).optional(),
     prompt: z.string().min(1).max(2000).optional()
 }));
+// Animated captions from speech: STT with word-level timings, paged into
+// ready-to-apply cue layers. Either transcribe a source_url or page plain text.
+const captionsPayloadSchema = z.preprocess((raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const payload = raw;
+    return {
+        ...payload,
+        source_url: payload.source_url ??
+            payload.source_video_url ??
+            payload.source_audio_url ??
+            payload.source_media_url ??
+            payload.video_url ??
+            payload.audio_url ??
+            payload.url
+    };
+}, z.object({
+    provider: speechProviderSchema.optional(),
+    model: z.string().min(1).optional(),
+    source_url: mediaSourceUrlSchema.optional(),
+    media_type: z.enum(["auto", "video", "audio"]).default("auto"),
+    /** Skip STT entirely: page this script across the window instead. */
+    text: z.string().min(1).max(20_000).optional(),
+    language: z.string().min(2).max(16).optional(),
+    prompt: z.string().min(1).max(2000).optional(),
+    /** Named look: spotlight | karaoke | word-pop | stack-up | neon | bounce. */
+    style: z.string().min(1).max(32).optional(),
+    animation: z.enum(CAPTION_ANIMATIONS).optional(),
+    active_color: z.string().min(1).max(64).optional(),
+    highlight_color: z.string().min(1).max(64).optional(),
+    uppercase: z.boolean().optional(),
+    color: z.string().min(1).max(64).optional(),
+    background: z.string().min(1).max(64).optional(),
+    background_style: z.enum(["plain", "outline", "highlight-solid", "highlight-translucent"]).optional(),
+    font_family: z.string().min(1).max(64).optional(),
+    font_size: z.number().int().min(8).max(200).optional(),
+    max_words_per_cue: z.number().int().min(1).max(8).default(4),
+    /** Shift every cue by this many seconds (where the narration layer starts). */
+    offset_sec: z.number().min(0).max(3600).default(0),
+    /** Text mode window: where the paged script starts and how long it spans. */
+    window_start: z.number().min(0).max(3600).default(0),
+    window_duration: z.number().positive().max(3600).optional()
+}).refine((payload) => Boolean(payload.source_url || payload.text), {
+    message: "Provide source_url (audio/video to transcribe) or text (script to page)."
+}));
 const probeVideoPayloadSchema = z.object({
     source_video_url: mediaSourceUrlSchema
 });
@@ -561,6 +612,7 @@ const PRIMITIVE_BRAINSTORM_PRODUCT_PLACEMENT_ID = "primitive:brainstorm_product_
 const PRIMITIVE_MEDIA_DEDUPE_ID = "primitive:media_dedupe";
 const PRIMITIVE_TTS_ID = "primitive:tts";
 const PRIMITIVE_STT_ID = "primitive:stt";
+const PRIMITIVE_CAPTIONS_ID = "primitive:captions";
 // Gemini inline audio caps out around 20MB; at the 64kbps mono mp3 we extract,
 // that is roughly 40 minutes of speech.
 const MAX_TRANSCRIBE_AUDIO_BYTES = 20 * 1024 * 1024;
@@ -1686,6 +1738,55 @@ const ttsPrimitive = definePrimitive({
         }
     }
 });
+// Shared source→speech-ready-audio loader for the STT-family primitives.
+// Plain audio URLs pass through; videos (and unknown containers) go through
+// the ffmpeg seam, which demuxes and normalizes into a small mono mp3 the
+// speech providers accept.
+async function loadSpeechAudioForPrimitive(ctx, payload) {
+    const sourceKind = payload.media_type === "auto" ? inferSpeechSourceKind(payload.source_url) : payload.media_type;
+    let audioBytes;
+    let audioContentType;
+    let extractionMetadata = null;
+    if (sourceKind === "audio") {
+        ctx.logger.progress(0.1, "Fetching source audio");
+        const response = await fetch(payload.source_url);
+        if (!response.ok) {
+            throw new Error(`Could not fetch source audio (${response.status}).`);
+        }
+        audioBytes = new Uint8Array(await response.arrayBuffer());
+        audioContentType = response.headers.get("content-type")?.split(";")[0]?.trim() || "audio/mpeg";
+    }
+    else {
+        ctx.logger.progress(0.1, "Extracting audio track from source", {
+            executionMode: config.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL ? "lambda" : "local_fallback"
+        });
+        const extracted = await executePrimitiveMediaOperation(ctx, {
+            operation: "video_extract_audio",
+            payload: {
+                source_video_url: payload.source_url,
+                output_format: "mp3",
+                audio_bitrate_kbps: 64
+            },
+            outputKey: "source-audio.mp3"
+        });
+        if (!extracted.publicUrl) {
+            throw new Error("Audio extraction produced no readable audio URL.");
+        }
+        const response = await fetch(extracted.publicUrl);
+        if (!response.ok) {
+            throw new Error(`Could not read extracted audio (${response.status}).`);
+        }
+        audioBytes = new Uint8Array(await response.arrayBuffer());
+        audioContentType = extracted.contentType || "audio/mpeg";
+        extractionMetadata = extracted.metadata ?? null;
+    }
+    if (audioBytes.byteLength > MAX_TRANSCRIBE_AUDIO_BYTES) {
+        const sizeMb = Math.round(audioBytes.byteLength / (1024 * 1024));
+        const maxMb = Math.round(MAX_TRANSCRIBE_AUDIO_BYTES / (1024 * 1024));
+        throw new Error(`Audio is too large to transcribe (${sizeMb}MB > ${maxMb}MB, roughly 40 minutes of speech). Trim the source with /videos/trim or /audio/trim and transcribe in parts.`);
+    }
+    return { audioBytes, audioContentType, extractionMetadata };
+}
 const sttPrimitive = definePrimitive({
     id: PRIMITIVE_STT_ID,
     kind: "stt",
@@ -1699,53 +1800,9 @@ const sttPrimitive = definePrimitive({
     jobs: {
         async run(ctx, input) {
             const payload = sttPayloadSchema.parse(input);
-            const sourceKind = payload.media_type === "auto" ? inferSpeechSourceKind(payload.source_url) : payload.media_type;
-            let audioBytes;
-            let audioContentType;
-            let extractionMetadata = null;
-            if (sourceKind === "audio") {
-                ctx.logger.progress(0.1, "Fetching source audio");
-                const response = await fetch(payload.source_url);
-                if (!response.ok) {
-                    throw new Error(`Could not fetch source audio (${response.status}).`);
-                }
-                audioBytes = new Uint8Array(await response.arrayBuffer());
-                audioContentType = response.headers.get("content-type")?.split(";")[0]?.trim() || "audio/mpeg";
-            }
-            else {
-                // Videos (and unknown extensions) go through the ffmpeg seam: it
-                // demuxes video AND normalizes odd audio containers into a small
-                // mono mp3 the speech providers accept.
-                ctx.logger.progress(0.1, "Extracting audio track from source", {
-                    executionMode: config.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL ? "lambda" : "local_fallback"
-                });
-                const extracted = await executePrimitiveMediaOperation(ctx, {
-                    operation: "video_extract_audio",
-                    payload: {
-                        source_video_url: payload.source_url,
-                        output_format: "mp3",
-                        audio_bitrate_kbps: 64
-                    },
-                    outputKey: "source-audio.mp3"
-                });
-                if (!extracted.publicUrl) {
-                    throw new Error("Audio extraction produced no readable audio URL.");
-                }
-                const response = await fetch(extracted.publicUrl);
-                if (!response.ok) {
-                    throw new Error(`Could not read extracted audio (${response.status}).`);
-                }
-                audioBytes = new Uint8Array(await response.arrayBuffer());
-                audioContentType = extracted.contentType || "audio/mpeg";
-                extractionMetadata = extracted.metadata ?? null;
-            }
-            if (audioBytes.byteLength > MAX_TRANSCRIBE_AUDIO_BYTES) {
-                const sizeMb = Math.round(audioBytes.byteLength / (1024 * 1024));
-                const maxMb = Math.round(MAX_TRANSCRIBE_AUDIO_BYTES / (1024 * 1024));
-                throw new Error(`Audio is too large to transcribe (${sizeMb}MB > ${maxMb}MB, roughly 40 minutes of speech). Trim the source with /videos/trim or /audio/trim and transcribe in parts.`);
-            }
+            const { audioBytes, audioContentType, extractionMetadata } = await loadSpeechAudioForPrimitive(ctx, payload);
             ctx.logger.progress(0.45, "Transcribing speech");
-            const provider = payload.provider ?? "gemini";
+            const provider = payload.provider ?? (payload.word_timestamps ? "openai" : "gemini");
             const model = payload.model ?? defaultSpeechModelFor("stt", provider) ?? "";
             const transcription = await ctx.providers.transcribeSpeech({
                 provider,
@@ -1754,7 +1811,8 @@ const sttPrimitive = definePrimitive({
                 contentType: audioContentType,
                 prompt: payload.prompt,
                 language: payload.language,
-                diarize: payload.diarize
+                diarize: payload.diarize,
+                wordTimestamps: payload.word_timestamps
             });
             ctx.logger.progress(0.85, "Storing transcript artifacts");
             const speakers = [...new Set(transcription.segments.map((segment) => segment.speaker))];
@@ -1802,6 +1860,137 @@ const sttPrimitive = definePrimitive({
         }
     }
 });
+// Speech → animated captions convenience primitive. One job: transcribe the
+// narration WITH word-level timings (openai/whisper-1 real timestamps, other
+// providers estimated), page it into CapCut-style cues, and return the cue
+// list shaped EXACTLY for the editor's `editor_action set_captions` — the
+// output even carries a ready `set_captions_action` object so an agent can
+// pipe it through without any cue math. Composition-agnostic: it never
+// mutates a fork; POST /api/v1/compositions/:forkId/captions is the one-step
+// variant that applies server-side.
+const captionsPrimitive = definePrimitive({
+    id: PRIMITIVE_CAPTIONS_ID,
+    kind: "captions",
+    operations: {
+        run: {
+            description: "Transcribe narration (or page a script) into animated word-by-word caption cues ready for the editor's set_captions action.",
+            inputSchema: captionsPayloadSchema,
+            workflow: "run"
+        }
+    },
+    jobs: {
+        async run(ctx, input) {
+            const payload = captionsPayloadSchema.parse(input);
+            const preset = payload.style
+                ? captionStylePresetById(payload.style)
+                : payload.animation
+                    ? null
+                    : CAPTION_STYLE_PRESETS[0];
+            if (payload.style && !preset) {
+                throw new Error(`Unknown caption style "${payload.style}". Use one of: ${CAPTION_STYLE_PRESETS.map((entry) => entry.id).join(", ")} — or pass animation directly.`);
+            }
+            const animation = payload.animation ?? preset?.animation ?? "highlight-pop";
+            let cues;
+            let wordTimestampSource = "estimated";
+            let transcriptText = null;
+            let transcriptArtifacts = {};
+            if (payload.text?.trim()) {
+                const tokens = payload.text.trim().split(/\s+/).filter(Boolean);
+                const windowDuration = payload.window_duration ?? Math.max(0.4, tokens.length * 0.32);
+                cues = cuesFromText(payload.text, payload.window_start + payload.offset_sec, windowDuration, {
+                    maxWordsPerCue: payload.max_words_per_cue
+                });
+            }
+            else {
+                const { audioBytes, audioContentType } = await loadSpeechAudioForPrimitive(ctx, {
+                    source_url: payload.source_url,
+                    media_type: payload.media_type
+                });
+                ctx.logger.progress(0.45, "Transcribing speech with word timings");
+                // openai first: whisper-1 is the only provider with REAL word-level
+                // timestamps; providerAttempts falls back to the caller's other keys.
+                const provider = payload.provider ?? "openai";
+                const model = payload.model ?? defaultSpeechModelFor("stt", provider) ?? "";
+                const transcription = await ctx.providers.transcribeSpeech({
+                    provider,
+                    model,
+                    audio: audioBytes,
+                    contentType: audioContentType,
+                    prompt: payload.prompt,
+                    language: payload.language,
+                    diarize: false,
+                    wordTimestamps: true
+                });
+                if (!transcription.segments.length) {
+                    throw new Error("Transcription returned no speech segments — the source may be silent.");
+                }
+                transcriptText = transcription.text || null;
+                wordTimestampSource = transcription.segments.some((segment) => segment.words?.length) ? "provider" : "estimated";
+                ctx.logger.progress(0.7, "Paging transcript into caption cues");
+                cues = buildCaptionCues(transcription.segments, {
+                    maxWordsPerCue: payload.max_words_per_cue,
+                    offsetSec: payload.offset_sec
+                });
+                const srt = buildSrtFromSegments(transcription.segments);
+                const storedSrt = srt ? await ctx.storage.putText("transcript.srt", srt, "application/x-subrip; charset=utf-8") : null;
+                if (storedSrt?.url)
+                    transcriptArtifacts.srt_url = storedSrt.url;
+            }
+            if (!cues.length) {
+                throw new Error("No caption cues produced from the source.");
+            }
+            // Style echo in the exact field names editor_action set_captions takes,
+            // so the agent can spread this straight into the action.
+            const styleFields = {
+                ...(preset ? { caption_style: preset.id } : {}),
+                caption_animation: animation,
+                ...(payload.active_color ?? preset?.activeColor ? { caption_active_color: payload.active_color ?? preset?.activeColor } : {}),
+                ...(payload.highlight_color ?? preset?.highlightColor ? { caption_highlight_color: payload.highlight_color ?? preset?.highlightColor } : {}),
+                ...((payload.uppercase ?? preset?.uppercase) !== undefined ? { caption_uppercase: payload.uppercase ?? preset?.uppercase } : {}),
+                ...(payload.color ?? preset?.color ? { color: payload.color ?? preset?.color } : {}),
+                ...(payload.background ?? preset?.background ? { background: payload.background ?? preset?.background } : {}),
+                ...(payload.background_style ?? preset?.textBackgroundStyle ? { background_style: payload.background_style ?? preset?.textBackgroundStyle } : {}),
+                ...(payload.font_family ? { font_family: payload.font_family } : {}),
+                ...(payload.font_size ? { font_size: payload.font_size } : {})
+            };
+            const setCaptionsAction = {
+                action_type: "set_captions",
+                captions: cues,
+                ...styleFields,
+                explanation: "Apply transcribed animated captions."
+            };
+            ctx.logger.progress(0.85, "Storing caption artifacts");
+            const storedCaptions = await ctx.storage.putJson("captions.json", {
+                source_url: payload.source_url ?? null,
+                word_timestamps: wordTimestampSource,
+                style: styleFields,
+                cue_count: cues.length,
+                cues,
+                set_captions_action: setCaptionsAction,
+                ...(transcriptText ? { transcript_text: transcriptText } : {})
+            });
+            const cuesInline = JSON.stringify(cues).length <= 60_000;
+            ctx.logger.progress(1, "Caption cues ready");
+            return {
+                progress: 1,
+                output: {
+                    files: compactUrls([storedCaptions.url, transcriptArtifacts.srt_url]),
+                    primary_file_url: storedCaptions.url,
+                    cue_count: cues.length,
+                    word_timestamps: wordTimestampSource,
+                    ...styleFields,
+                    // The cue list, ready to pass as editor_action set_captions `captions`.
+                    captions: cuesInline ? cues : undefined,
+                    captions_truncated: !cuesInline,
+                    // Fully-formed editor_action arguments — apply verbatim.
+                    set_captions_action: cuesInline ? setCaptionsAction : undefined,
+                    captions_json_url: storedCaptions.url,
+                    transcript: transcriptArtifacts.srt_url ? { srt_url: transcriptArtifacts.srt_url } : undefined
+                }
+            };
+        }
+    }
+});
 const videoProbePrimitive = definePrimitive({
     id: PRIMITIVE_VIDEO_PROBE_ID,
     kind: "video_probe",
@@ -2380,6 +2569,7 @@ class PrimitiveRegistry {
         [audioNormalizePrimitive.id, audioNormalizePrimitive],
         [ttsPrimitive.id, ttsPrimitive],
         [sttPrimitive.id, sttPrimitive],
+        [captionsPrimitive.id, captionsPrimitive],
         [hyperframesRenderPrimitive.id, hyperframesRenderPrimitive],
         [brainstormHooksPrimitive.id, brainstormHooksPrimitive],
         [brainstormAwarenessStagesPrimitive.id, brainstormAwarenessStagesPrimitive],