@mevdragon/vidfarm-devcli 0.11.0 → 0.13.0

package/dist/src/primitive-registry.js

@@ -7,7 +7,9 @@ import { config } from "./config.js";
 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 } from "./services/speech.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"]);
@@ -376,6 +378,15 @@ const ttsPayloadSchema = z.preprocess((raw) => {
     voice: z.string().min(1).max(120).optional(),
     instructions: z.string().min(1).max(4000).optional(),
     output_format: z.enum(["mp3", "wav"]).default("mp3")
+}).superRefine((value, ctx) => {
+    // Reject an explicit provider/voice contradiction at enqueue (400) instead
+    // of queueing a job that can only fail at the provider.
+    if (!value.provider || !value.voice)
+        return;
+    const mismatch = speechVoiceMismatch({ provider: value.provider, model: value.model, voice: value.voice });
+    if (mismatch) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["voice"], message: mismatch });
+    }
 }));
 const sttPayloadSchema = z.preprocess((raw) => {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
@@ -397,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
 });
@@ -552,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;
@@ -1630,7 +1691,9 @@ const ttsPrimitive = definePrimitive({
         async run(ctx, input) {
             const payload = ttsPayloadSchema.parse(input);
             ctx.logger.progress(0.12, "Generating speech audio");
-            const provider = payload.provider ?? "openai";
+            // A bare voice preset implies its provider ("Puck" → gemini) — blindly
+            // defaulting to openai would guarantee a cross-family voice failure.
+            const provider = payload.provider ?? inferSpeechProviderForVoice(payload.voice) ?? "openai";
             const model = payload.model ?? defaultSpeechModelFor("tts", provider) ?? "";
             const generated = await ctx.providers.generateSpeech({
                 provider,
@@ -1675,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",
@@ -1688,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,
@@ -1743,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))];
@@ -1791,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",
@@ -2369,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],

package/dist/src/services/captions.js

@@ -0,0 +1,123 @@
+// Turns a transcript into animated-caption cues. Shared by the devcli
+// `captions` command group, the /editor chat agent's set_captions action, and
+// any server surface that wants captions from STT output. Pure — no network,
+// no filesystem — so it is safe to import from the devcli.
+//
+// A "cue" is one caption layer on the timeline: a short run of words shown
+// together (CapCut-style pages of ~3-5 words), with per-word windows relative
+// to the cue start driving the animation. Word timings come from the provider
+// when available (openai whisper-1) and are char-weight estimated inside each
+// segment otherwise (gemini estimates, hand-typed text) — see
+// estimateCaptionWords.
+import { estimateCaptionWords } from "../hyperframes/composition.js";
+const CUE_TAIL_SEC = 0.12;
+const MIN_WORD_SPAN_SEC = 0.05;
+/** Flattens transcript segments into absolute-timed words, estimating windows
+ * for segments the provider left word-less (or entirely time-less — those
+ * distribute across fallbackDurationSec). */
+export function transcriptWordTimeline(segments, fallbackDurationSec) {
+    const words = [];
+    const timeless = segments.filter((segment) => typeof segment.start_sec !== "number");
+    for (const segment of segments) {
+        if (segment.words?.length) {
+            words.push(...segment.words.map((word) => ({ ...word, text: word.text.trim() })).filter((word) => word.text));
+            continue;
+        }
+        let base;
+        let span;
+        if (typeof segment.start_sec === "number") {
+            base = segment.start_sec;
+            span = typeof segment.end_sec === "number" && segment.end_sec > segment.start_sec
+                ? segment.end_sec - segment.start_sec
+                : 0;
+        }
+        else {
+            // No timings at all (plain-text providers): spread the blob across the
+            // caller-provided window so captions still land somewhere sensible.
+            base = 0;
+            span = Number.isFinite(fallbackDurationSec) && fallbackDurationSec > 0 && timeless.length
+                ? fallbackDurationSec / timeless.length
+                : 0;
+            if (timeless.length > 1) {
+                base = (span || 0) * timeless.indexOf(segment);
+            }
+        }
+        const estimated = estimateCaptionWords(segment.text, span);
+        words.push(...estimated.map((word) => ({
+            text: word.text,
+            start_sec: base + word.start,
+            end_sec: base + word.end
+        })));
+    }
+    return words
+        .filter((word) => Number.isFinite(word.start_sec) && Number.isFinite(word.end_sec) && word.end_sec > word.start_sec)
+        .sort((a, b) => a.start_sec - b.start_sec);
+}
+export function buildCaptionCues(segments, options) {
+    const words = transcriptWordTimeline(segments, options?.fallbackDurationSec);
+    return cuesFromWordTimeline(words, options);
+}
+export function cuesFromWordTimeline(words, options) {
+    const maxWords = Math.max(1, Math.round(options?.maxWordsPerCue ?? 4));
+    const maxDuration = Math.max(0.4, options?.maxCueDurationSec ?? 2.6);
+    const gapBreak = Math.max(0.15, options?.gapBreakSec ?? 0.6);
+    const offset = Number.isFinite(options?.offsetSec) ? options?.offsetSec : 0;
+    const cues = [];
+    let bucket = [];
+    const flush = () => {
+        if (!bucket.length)
+            return;
+        const start = bucket[0].start_sec;
+        const end = bucket[bucket.length - 1].end_sec + CUE_TAIL_SEC;
+        cues.push({
+            text: bucket.map((word) => word.text).join(" "),
+            start: round3(start + offset),
+            duration: round3(Math.max(MIN_WORD_SPAN_SEC * bucket.length, end - start)),
+            words: bucket.map((word) => ({
+                text: word.text,
+                start: round3(Math.max(0, word.start_sec - start)),
+                end: round3(Math.max(word.start_sec - start + MIN_WORD_SPAN_SEC, word.end_sec - start))
+            }))
+        });
+        bucket = [];
+    };
+    for (const word of words) {
+        if (bucket.length) {
+            const cueStart = bucket[0].start_sec;
+            const previous = bucket[bucket.length - 1];
+            const silence = word.start_sec - previous.end_sec;
+            const wouldRun = word.end_sec - cueStart;
+            const sentenceBreak = /[.!?…]["')\]]?$/.test(previous.text);
+            if (bucket.length >= maxWords || silence > gapBreak || wouldRun > maxDuration || sentenceBreak) {
+                flush();
+            }
+        }
+        bucket.push(word);
+    }
+    flush();
+    // Clamp each cue against the next so consecutive caption layers never
+    // overlap on the shared track (one-clip-per-(track,time) invariant).
+    for (let index = 0; index < cues.length - 1; index += 1) {
+        const cue = cues[index];
+        const next = cues[index + 1];
+        const maxEnd = next.start - 0.02;
+        if (cue.start + cue.duration > maxEnd) {
+            cue.duration = round3(Math.max(MIN_WORD_SPAN_SEC, maxEnd - cue.start));
+        }
+    }
+    return cues.filter((cue) => cue.duration > 0);
+}
+/** Cues straight from plain text spread across a window — the no-transcript
+ * path (AI-authored captions, manual cue text). */
+export function cuesFromText(text, startSec, durationSec, options) {
+    const words = estimateCaptionWords(text, durationSec).map((word) => ({
+        text: word.text,
+        start_sec: startSec + word.start,
+        end_sec: startSec + word.end
+    }));
+    return cuesFromWordTimeline(words, options);
+}
+function round3(value) {
+    return Number(value.toFixed(3));
+}
+//# sourceMappingURL=captions.js.map

package/dist/src/services/hyperframes.js

@@ -13,7 +13,7 @@ import ffprobeStatic from "ffprobe-static";
 import { parseHTML } from "linkedom";
 import { config } from "../config.js";
 import { devErrorFields, devLog } from "../lib/dev-log.js";
-import { KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, buildHyperframeCompositionHtml } from "../hyperframes/composition.js";
+import { CAPTION_ANIM_CSS, CAPTION_STYLE_MARKER, KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, TRANSITION_ADJACENCY_EPSILON, TRANSITION_CSS, TRANSITION_PRESETS, TRANSITION_STYLE_MARKER, buildHyperframeCompositionHtml, clampTransitionDuration } from "../hyperframes/composition.js";
 import { applyMarkupUsd } from "./billing-pricing.js";
 // The scene-annotation pass reuses the clip library's controlled vocabulary and
 // embedding-text recipe verbatim so a source scene's clip-match query is
@@ -2296,6 +2296,102 @@ function compositionHasCoverageGap(intervals, total, minGap = 0.2) {
     }
     return cursor < total - minGap;
 }
+// Scene transitions: the INCOMING clip carries data-transition and its vf-tr-*
+// animation plays over the clip's first data-transition-duration seconds — the
+// render engine's CSS adapter scrubs that on its own. What the render engine
+// canNOT do is keep the OUTGOING clip on screen beneath it (visibility is
+// derived strictly from data-start/data-duration), so materialize the overlap
+// here: extend the previous same-track butt-cut clip's data-duration by the
+// transition length. The granted extension is recorded in data-transition-hold
+// so the pass is idempotent and self-healing — every run first restores each
+// clip's nominal duration (duration - hold), then re-grants from the current
+// set of [data-transition] clips (so removed/retimed transitions shrink their
+// neighbor back). Stored drafts stay butt-cut; only publish/render output
+// carries the overlap. The preview runtime applies the same window live.
+function materializeTransitionOverlaps(document) {
+    const clips = [];
+    for (const el of Array.from(document.querySelectorAll("[data-start]"))) {
+        if (el.hasAttribute("data-composition-id"))
+            continue;
+        const start = Number.parseFloat(el.getAttribute("data-start") || "");
+        const duration = Number.parseFloat(el.getAttribute("data-duration") || "");
+        if (!Number.isFinite(start) || !Number.isFinite(duration) || duration <= 0)
+            continue;
+        const priorHold = Number.parseFloat(el.getAttribute("data-transition-hold") || "");
+        const hold = Number.isFinite(priorHold) && priorHold > 0 ? Math.min(priorHold, duration) : 0;
+        clips.push({
+            el,
+            track: Number.parseInt(el.getAttribute("data-track-index") || "0", 10) || 0,
+            start,
+            nominal: duration - hold,
+            hold: 0
+        });
+    }
+    if (!clips.length)
+        return;
+    for (const clip of clips) {
+        const transitionEl = clip.el;
+        const preset = transitionEl.getAttribute("data-transition");
+        if (!preset)
+            continue;
+        if (!TRANSITION_PRESETS.includes(preset)) {
+            // Unknown preset would render as a permanently-paused animation with no
+            // keyframes — harmless — but drop it so agents get clean state back.
+            transitionEl.removeAttribute("data-transition");
+            transitionEl.removeAttribute("data-transition-duration");
+            continue;
+        }
+        const tagName = transitionEl.tagName?.toLowerCase?.() ?? "";
+        if (tagName === "audio") {
+            transitionEl.removeAttribute("data-transition");
+            transitionEl.removeAttribute("data-transition-duration");
+            continue;
+        }
+        // The animation cannot outlast its own clip.
+        const duration = Math.min(clampTransitionDuration(transitionEl.getAttribute("data-transition-duration")), clip.nominal);
+        const durationValue = Number(duration.toFixed(3));
+        transitionEl.setAttribute("data-transition-duration", String(durationValue));
+        // Keep the inline var (which drives animation-duration) in lockstep, same
+        // as the --vf-kb-dur re-derivation above.
+        const styleValue = transitionEl.getAttribute("style") || "";
+        const durDecl = `--vf-tr-dur:${durationValue}s`;
+        const nextStyle = /(^|;)\s*--vf-tr-dur\s*:[^;]*/i.test(styleValue)
+            ? styleValue.replace(/(^|;)\s*--vf-tr-dur\s*:[^;]*/i, (_match, lead) => `${lead}${durDecl}`)
+            : styleValue.length === 0 || styleValue.endsWith(";")
+                ? `${styleValue}${durDecl}`
+                : `${styleValue};${durDecl}`;
+        if (nextStyle !== styleValue)
+            transitionEl.setAttribute("style", nextStyle);
+        // Grant the hold to the clip this one cuts away from: same track, nominal
+        // end at (within epsilon of) this clip's start.
+        for (const candidate of clips) {
+            if (candidate === clip || candidate.track !== clip.track)
+                continue;
+            if (Math.abs(candidate.start + candidate.nominal - clip.start) > TRANSITION_ADJACENCY_EPSILON)
+                continue;
+            const candidateTag = candidate.el.tagName?.toLowerCase?.() ?? "";
+            if (candidateTag === "audio")
+                continue;
+            candidate.hold = Math.max(candidate.hold, duration);
+        }
+    }
+    for (const clip of clips) {
+        const nextDuration = Number((clip.nominal + clip.hold).toFixed(3));
+        const currentDuration = Number.parseFloat(clip.el.getAttribute("data-duration") || "");
+        if (currentDuration !== nextDuration) {
+            clip.el.setAttribute("data-duration", String(nextDuration));
+        }
+        if (clip.el.hasAttribute("data-end")) {
+            clip.el.setAttribute("data-end", String(Number((clip.start + nextDuration).toFixed(3))));
+        }
+        if (clip.hold > 0) {
+            clip.el.setAttribute("data-transition-hold", String(Number(clip.hold.toFixed(3))));
+        }
+        else {
+            clip.el.removeAttribute("data-transition-hold");
+        }
+    }
+}
 export function normalizePublishHtml(html) {
     const { document } = parseHTML(html);
     // Coverage gaps: any interval of the timeline with no active canvas-filling
@@ -2412,6 +2508,22 @@ export function normalizePublishHtml(html) {
         styleEl.textContent = KEN_BURNS_CSS;
         (document.head ?? document.documentElement)?.appendChild(styleEl);
     }
+    // Animated captions: word windows are stored relative to the layer start
+    // (inline animation-delay/duration on each [data-cap-word]), so retimes need
+    // no re-derivation — but the shared vf-cap-* keyframes stylesheet must
+    // travel with compositions stored before the builder embedded it, or every
+    // word renders in its resting state.
+    if (document.querySelector("[data-caption-animation]") && !html.includes(CAPTION_STYLE_MARKER)) {
+        const styleEl = document.createElement("style");
+        styleEl.textContent = CAPTION_ANIM_CSS;
+        (document.head ?? document.documentElement)?.appendChild(styleEl);
+    }
+    materializeTransitionOverlaps(document);
+    if (document.querySelector("[data-transition]") && !html.includes(TRANSITION_STYLE_MARKER)) {
+        const styleEl = document.createElement("style");
+        styleEl.textContent = TRANSITION_CSS;
+        (document.head ?? document.documentElement)?.appendChild(styleEl);
+    }
     // Editor sessions occasionally leave inline style attributes with double
     // quotes inside CSS values (font-family: "TikTok Sans"). When serialized into
     // an HTML attribute, those quotes become &quot; entities. The render lambda

package/dist/src/services/provider-errors.js

@@ -7,6 +7,9 @@ export class ProviderKeyUnavailableError extends Error {
 }
 export class ProviderAuthError extends Error {
 }
+/** A TTS voice preset that belongs to a different provider family — user input error, never retryable. */
+export class SpeechVoiceMismatchError extends Error {
+}
 export class ProviderQuotaExceededError extends Error {
 }
 export class ProviderWaitExceededError extends Error {