@mevdragon/vidfarm-devcli 0.11.0 → 0.12.0

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 {

package/dist/src/services/providers.js

@@ -5,8 +5,8 @@ import { createId } from "../lib/ids.js";
 import { addSeconds } from "../lib/time.js";
 import { ServerlessProviderKeyService } from "./serverless-provider-keys.js";
 import sharp from "sharp";
-import { ProviderAuthError, ProviderKeyUnavailableError, ProviderLeaseTimeoutError, ProviderQuotaExceededError, ProviderRateLimitError, ProviderTransientError, ProviderWaitExceededError, conciseProviderDetails, parseRetryAfterSeconds, rateLimitOrQuotaError } from "./provider-errors.js";
-import { SUPPORTED_STT_MODELS, SUPPORTED_TTS_MODELS, defaultSpeechModelFor, generateSpeechWithKey, inferSpeechContentType, transcribeSpeechWithKey } from "./speech.js";
+import { ProviderAuthError, ProviderKeyUnavailableError, ProviderLeaseTimeoutError, ProviderQuotaExceededError, ProviderRateLimitError, ProviderTransientError, ProviderWaitExceededError, SpeechVoiceMismatchError, conciseProviderDetails, parseRetryAfterSeconds, rateLimitOrQuotaError } from "./provider-errors.js";
+import { SUPPORTED_STT_MODELS, SUPPORTED_TTS_MODELS, defaultSpeechModelFor, generateSpeechWithKey, inferSpeechContentType, speechVoiceFamilyFor, speechVoiceMismatch, transcribeSpeechWithKey } from "./speech.js";
 export { ProviderAuthError, ProviderKeyUnavailableError, ProviderLeaseTimeoutError, ProviderQuotaExceededError, ProviderRateLimitError, ProviderTransientError, ProviderWaitExceededError } from "./provider-errors.js";
 const SUPPORTED_TEXT_MODELS = {
     openai: new Set(["gpt-5.4"]),
@@ -542,7 +542,9 @@ export class ProviderService {
         }
     }
     async generateSpeech(input) {
-        const attempts = await providerAttempts({
+        // Provider fallback must stay voice-aware: a Gemini preset routed to an
+        // OpenAI key (or the reverse) would 400 opaquely at the provider.
+        const attempts = (await providerAttempts({
             providerKeyService: this.serverlessProviderKeys,
             customerId: input.customerId,
             capability: "tts",
@@ -550,7 +552,11 @@ export class ProviderService {
             requestedModel: input.model,
             supportedModels: SUPPORTED_TTS_MODELS,
             defaultModelForProvider: (provider) => defaultSpeechModelFor("tts", provider)
-        });
+        })).filter((attempt) => !speechVoiceMismatch({ provider: attempt.provider, model: attempt.model, voice: input.voice }));
+        if (!attempts.length) {
+            throw new SpeechVoiceMismatchError(speechVoiceMismatch({ provider: input.provider, model: input.model, voice: input.voice }) ??
+                `Voice "${input.voice}" needs a ${speechVoiceFamilyFor(input.provider, input.model) === "gemini" ? "Gemini-family (gemini, or openrouter with a Gemini TTS model)" : "OpenAI-family (openai)"} provider key, but none is configured. Save a compatible key or pick a different voice.`);
+        }
         const retryDeadlineMs = providerLeaseRetryDeadlineMs();
         for (;;) {
             let lastError = null;

package/dist/src/services/speech.js

@@ -9,7 +9,7 @@
 // is an audio-native LLM, so we ask for speaker-attributed JSON segments in one
 // call. OpenAI/OpenRouter transcription endpoints return plain text only and
 // degrade to a single unlabeled segment.
-import { ProviderAuthError, rateLimitOrQuotaError } from "./provider-errors.js";
+import { ProviderAuthError, SpeechVoiceMismatchError, rateLimitOrQuotaError } from "./provider-errors.js";
 export const SUPPORTED_TTS_MODELS = {
     openrouter: new Set(["google/gemini-3.1-flash-tts-preview"]),
     gemini: new Set(["gemini-3.1-flash-tts-preview", "gemini-2.5-flash-preview-tts"]),
@@ -18,25 +18,109 @@ export const SUPPORTED_TTS_MODELS = {
 export const SUPPORTED_STT_MODELS = {
     openrouter: new Set(["openai/gpt-4o-mini-transcribe"]),
     gemini: new Set(["gemini-3.1-flash-lite-preview", "gemini-2.5-flash-lite"]),
-    openai: new Set(["gpt-4o-mini-transcribe-2025-12-15"])
+    openai: new Set(["gpt-4o-mini-transcribe-2025-12-15", "whisper-1"])
 };
+// The only STT model that returns real word-level timestamps
+// (verbose_json + timestamp_granularities). Word-timestamp requests on the
+// openai path are routed here regardless of the configured chat-grade model.
+export const OPENAI_WORD_TIMESTAMP_STT_MODEL = "whisper-1";
 export function defaultSpeechModelFor(kind, provider) {
     return kind === "tts" ? SUPPORTED_TTS_MODELS[provider]?.values().next().value : SUPPORTED_STT_MODELS[provider]?.values().next().value;
 }
+// Known TTS voice presets, in the exact casing each provider accepts (OpenAI is
+// lowercase; Gemini prebuilt voices are case-sensitive TitleCase). These lists
+// exist to guard, not to gate: a voice that clearly belongs to the OTHER family
+// is rejected with an actionable message (the provider would 400 opaquely), a
+// known voice has its casing normalized, and an UNKNOWN voice passes through
+// untouched so new provider presets keep working without a code change.
+export const OPENAI_TTS_VOICES = [
+    "alloy", "ash", "ballad", "cedar", "coral", "echo", "fable", "marin", "nova", "onyx", "sage", "shimmer", "verse"
+];
+export const GEMINI_TTS_VOICES = [
+    "Achernar", "Achird", "Algenib", "Algieba", "Alnilam", "Aoede", "Autonoe", "Callirrhoe", "Charon", "Despina",
+    "Enceladus", "Erinome", "Fenrir", "Gacrux", "Iapetus", "Kore", "Laomedeia", "Leda", "Orus", "Puck",
+    "Pulcherrima", "Rasalgethi", "Sadachbia", "Sadaltager", "Schedar", "Sulafat", "Umbriel", "Vindemiatrix", "Zephyr", "Zubenelgenubi"
+];
+const OPENAI_VOICES_BY_KEY = new Map(OPENAI_TTS_VOICES.map((voice) => [voice.toLowerCase(), voice]));
+const GEMINI_VOICES_BY_KEY = new Map(GEMINI_TTS_VOICES.map((voice) => [voice.toLowerCase(), voice]));
+/** Which voice family a provider/model pair expects; openrouter follows its (typically Gemini) TTS model. */
+export function speechVoiceFamilyFor(provider, model) {
+    if (provider === "gemini") {
+        return "gemini";
+    }
+    if (provider === "openrouter") {
+        const resolvedModel = model?.trim() || defaultSpeechModelFor("tts", provider) || "";
+        return /gemini/i.test(resolvedModel) ? "gemini" : "openai";
+    }
+    return "openai";
+}
+/** Which provider a bare voice preset implies (null when the name is not a known preset). */
+export function inferSpeechProviderForVoice(voice) {
+    const key = voice?.trim().toLowerCase();
+    if (!key) {
+        return null;
+    }
+    if (OPENAI_VOICES_BY_KEY.has(key)) {
+        return "openai";
+    }
+    if (GEMINI_VOICES_BY_KEY.has(key)) {
+        return "gemini";
+    }
+    return null;
+}
+/** Actionable mismatch message when the voice belongs to the other provider family, else null (usable). */
+export function speechVoiceMismatch(input) {
+    const key = input.voice?.trim().toLowerCase();
+    if (!key) {
+        return null;
+    }
+    const family = speechVoiceFamilyFor(input.provider, input.model);
+    if ((family === "gemini" ? GEMINI_VOICES_BY_KEY : OPENAI_VOICES_BY_KEY).has(key)) {
+        return null;
+    }
+    const foreign = (family === "gemini" ? OPENAI_VOICES_BY_KEY : GEMINI_VOICES_BY_KEY).get(key);
+    if (!foreign) {
+        return null;
+    }
+    return family === "gemini"
+        ? `Voice "${foreign}" is an OpenAI preset, but provider ${input.provider} expects a Gemini voice (e.g. Kore, Puck, Charon). Pick a Gemini voice or set provider to "openai".`
+        : `Voice "${foreign}" is a Gemini preset, but provider ${input.provider} expects an OpenAI voice (e.g. alloy, ash, coral). Pick an OpenAI voice or set provider to "gemini".`;
+}
+/** Canonicalize a requested voice for the target provider/model (casing fixed, cross-family presets rejected). */
+export function resolveSpeechVoice(input) {
+    const raw = input.voice?.trim();
+    if (!raw) {
+        return undefined;
+    }
+    const mismatch = speechVoiceMismatch(input);
+    if (mismatch) {
+        throw new SpeechVoiceMismatchError(mismatch);
+    }
+    const family = speechVoiceFamilyFor(input.provider, input.model);
+    return (family === "gemini" ? GEMINI_VOICES_BY_KEY : OPENAI_VOICES_BY_KEY).get(raw.toLowerCase()) ?? raw;
+}
 /** Generate speech audio with a raw provider key. Voice style rides on `instructions`. */
 export async function generateSpeechWithKey(input) {
+    const voice = resolveSpeechVoice(input);
     return input.provider === "gemini"
-        ? callGeminiSpeechGeneration(input)
+        ? callGeminiSpeechGeneration({ ...input, voice })
         : callOpenAICompatibleSpeechGeneration({
             ...input,
+            voice,
             provider: input.provider === "openrouter" ? "openrouter" : "openai"
         });
 }
-/** Transcribe speech audio with a raw provider key; diarizes on the Gemini path. */
+/** Transcribe speech audio with a raw provider key; diarizes on the Gemini path.
+ * wordTimestamps requests word-level timings — honored only on the openai path
+ * (routed to whisper-1 verbose_json); other providers return their usual
+ * segment-level output and callers estimate word windows from text. */
 export async function transcribeSpeechWithKey(input) {
     if (input.provider === "gemini") {
         return callGeminiSpeechTranscription(input);
     }
+    if (input.provider === "openai" && input.wordTimestamps) {
+        return callOpenAIVerboseSpeechTranscription(input);
+    }
     const plain = input.provider === "openrouter"
         ? await callOpenRouterSpeechTranscription(input)
         : await callOpenAISpeechTranscription(input);
@@ -201,6 +285,84 @@ async function callOpenAISpeechTranscription(input) {
         }
     };
 }
+// whisper-1 verbose_json: the one provider path with real (non-estimated) word
+// timestamps. Returns timed segments with their word windows attached, ready
+// for animated-caption cue building.
+async function callOpenAIVerboseSpeechTranscription(input) {
+    const contentType = input.contentType ?? "audio/mpeg";
+    const model = /^whisper/i.test(input.model) ? input.model : OPENAI_WORD_TIMESTAMP_STT_MODEL;
+    const form = new FormData();
+    form.set("file", new Blob([Buffer.from(input.audio)], { type: contentType }), `audio.${audioExtensionFromContentType(contentType)}`);
+    form.set("model", model);
+    form.set("response_format", "verbose_json");
+    form.append("timestamp_granularities[]", "word");
+    form.append("timestamp_granularities[]", "segment");
+    if (input.prompt) {
+        form.set("prompt", input.prompt);
+    }
+    if (input.language) {
+        form.set("language", input.language);
+    }
+    const response = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${input.apiKey}`
+        },
+        body: form
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new ProviderAuthError("openai authentication failed");
+    }
+    if (response.status === 429) {
+        throw await rateLimitOrQuotaError("openai", response);
+    }
+    if (!response.ok) {
+        const details = await response.text();
+        throw new Error(`openai transcription returned ${response.status}${details ? `: ${details}` : ""}`);
+    }
+    const data = await response.json();
+    const words = Array.isArray(data.words)
+        ? data.words
+            .map((entry) => ({
+            text: String(entry.word ?? "").trim(),
+            start_sec: Number(entry.start),
+            end_sec: Number(entry.end)
+        }))
+            .filter((word) => word.text && Number.isFinite(word.start_sec) && Number.isFinite(word.end_sec) && word.end_sec > word.start_sec)
+        : [];
+    const rawSegments = Array.isArray(data.segments) ? data.segments : [];
+    const segments = [];
+    for (const entry of rawSegments) {
+        const start = Number(entry.start);
+        const end = Number(entry.end);
+        const text = String(entry.text ?? "").trim();
+        if (!text || !Number.isFinite(start) || !Number.isFinite(end))
+            continue;
+        const segmentWords = words.filter((word) => word.start_sec >= start - 0.05 && word.start_sec < end + 0.05);
+        segments.push({
+            speaker: "speaker_1",
+            start_sec: start,
+            end_sec: end,
+            text,
+            words: segmentWords.length ? segmentWords : undefined
+        });
+    }
+    const text = String(data.text ?? "").trim();
+    if (!segments.length && text) {
+        segments.push({ speaker: "speaker_1", start_sec: null, end_sec: null, text, words: words.length ? words : undefined });
+    }
+    return {
+        text,
+        language: typeof data.language === "string" && data.language.trim() ? data.language.trim() : input.language?.trim() || null,
+        segments,
+        diarization: "none",
+        usage: {
+            inputTokens: Number(data.usage?.input_tokens ?? 0),
+            outputTokens: Number(data.usage?.output_tokens ?? 0),
+            costUsd: Number(data.usage?.cost ?? 0)
+        }
+    };
+}
 async function callOpenRouterSpeechTranscription(input) {
     const response = await fetch("https://openrouter.ai/api/v1/audio/transcriptions", {
         method: "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {