@vibeframe/cli 0.112.1 → 0.113.0

package/dist/commands/_shared/project-config.d.ts

@@ -4,7 +4,7 @@ export declare const LEGACY_VIBE_PROJECT_FILENAME = "vibe.project.yaml";
 export type CompositionEngine = "hyperframes";
 export type ProjectImageProvider = "openai" | "gemini" | "grok" | null;
 export type ProjectVideoProvider = "seedance" | "grok" | "kling" | "runway" | "veo" | null;
-export type ProjectNarrationProvider = "elevenlabs" | "kokoro" | null;
+export type ProjectNarrationProvider = "elevenlabs" | "openai" | "kokoro" | null;
 export type ProjectComposerProvider = "claude" | "openai" | "gemini" | null;
 export type ProjectQuality = "draft" | "standard" | "high";
 export interface VibeProjectConfigV1 {

package/dist/commands/_shared/scene-build.d.ts

@@ -12,7 +12,7 @@
  * Idempotent: assets that already exist on disk are reused unless `force`.
  *
  * Scope held tight for v0.60:
- *   - TTS via `resolveTtsProvider` (ElevenLabs / Kokoro auto-fallback)
+ *   - TTS via `resolveTtsProvider` (ElevenLabs / OpenAI / Kokoro auto-fallback)
  *   - T2I via OpenAI, Gemini, or Grok
  *   - No Whisper transcribe step (compose handles its own)
  *   - No root `index.html` synthesis — driver expects the project to

package/dist/commands/_shared/scene-project.d.ts

@@ -45,7 +45,7 @@ export interface VibeProjectConfig {
     /** Default providers per capability. `null` means "auto-resolve from env". */
     providers: {
         image: "openai" | "gemini" | "grok" | null;
-        tts: "elevenlabs" | "kokoro" | null;
+        tts: "elevenlabs" | "openai" | "kokoro" | null;
         transcribe: "whisper" | null;
     };
     /** Cost ceiling for `vibe remix` runs in this project. 0 disables. */

package/dist/commands/_shared/tts-resolve.d.ts

@@ -8,18 +8,21 @@
  * Routes between:
  *   - **ElevenLabs** — cloud, API-key gated, paid (~$0.02/scene). Default
  *     when `ELEVENLABS_API_KEY` is set.
- *   - **Kokoro** — local Apache 2.0 model, free, ~330MB first-call download.
+ *   - **OpenAI** — cloud gpt-4o-mini-tts, cheap (~$0.015/min of audio).
+ *     Default when only `OPENAI_API_KEY` is set — the common Claude Desktop
+ *     case where one key already covers backdrop images.
+ *   - **Kokoro** — local Apache 2.0 model, free, ~90MB first-call download.
  *     The fallback for key-less users.
  *
  * The router exposes a uniform `TtsCallable` shape so call sites don't have
- * to branch on provider id. Both providers already return the same
+ * to branch on provider id. All providers already return the same
  * `{ success, audioBuffer, error?, characterCount? }` result.
  */
 import type { KokoroLoadEvent } from "@vibeframe/ai-providers";
 /** TTS providers VibeFrame can route to. `"auto"` picks based on key availability. */
-export type TtsProviderName = "auto" | "elevenlabs" | "kokoro";
+export type TtsProviderName = "auto" | "elevenlabs" | "openai" | "kokoro";
 /** Concrete provider id surfaced in result metadata. Never `"auto"`. */
-export type ResolvedTtsProvider = "elevenlabs" | "kokoro";
+export type ResolvedTtsProvider = "elevenlabs" | "openai" | "kokoro";
 /** Options accepted by every {@link TtsCallable}. Subset of provider-specific options. */
 export interface TtsCallOptions {
     /**
@@ -56,10 +59,11 @@ export interface TtsResolution {
  * Resolution policy:
  *   - `"elevenlabs"`: requires `ELEVENLABS_API_KEY`. Throws an `ApiKeyError`-style
  *     error via {@link getApiKey} (consumed by `requireApiKey`/`exitWithError`).
+ *   - `"openai"`: requires `OPENAI_API_KEY`.
  *   - `"kokoro"`: always available (local). No key check.
- *   - `"auto"` (or `undefined`): if an ElevenLabs key is configured in
- *     project/user config.yaml, .env, or process env, picks ElevenLabs;
- *     otherwise falls back to Kokoro.
+ *   - `"auto"` (or `undefined`): ElevenLabs key configured → ElevenLabs
+ *     (preserves pre-0.113 behavior — a dedicated TTS key signals intent);
+ *     else OpenAI key configured → OpenAI; else Kokoro.
  */
 export declare function resolveTtsProvider(preferred?: TtsProviderName): Promise<TtsResolution>;
 /**

package/dist/index.js

@@ -7066,8 +7066,8 @@ var init_api_keys = __esm({
       envVar: "OPENAI_API_KEY",
       label: "OpenAI",
       showInSetup: true,
-      setupDescription: "gpt-image-2 image gen ($, default since v0.56), Whisper transcribe, Agent",
-      envExampleComment: "OpenAI API Key (Whisper transcription, gpt-image-2 \u2014 default text-to-image since v0.56)",
+      setupDescription: "gpt-image-2 image gen ($, default since v0.56), gpt-4o-mini-tts narration, Whisper transcribe, Agent",
+      envExampleComment: "OpenAI API Key (Whisper transcription, gpt-4o-mini-tts narration, gpt-image-2 \u2014 default text-to-image since v0.56)",
       envExampleUrl: "https://platform.openai.com/api-keys",
       keyFormat: { prefix: /^sk-/, example: "sk-..." }
     });
@@ -9174,8 +9174,8 @@ var init_openai = __esm({
       id: "openai",
       label: "OpenAI",
       apiKey: "openai",
-      kinds: ["llm", "image", "transcription"],
-      resolverPriority: { image: 1 },
+      kinds: ["llm", "image", "transcription", "speech"],
+      resolverPriority: { image: 1, speech: 2 },
       commandsUnlocked: [
         "agent -p openai",
         "generate image -p openai",
@@ -11597,16 +11597,19 @@ var init_elevenlabs = __esm({
 });
 
 // ../ai-providers/dist/kokoro/KokoroProvider.js
-async function loadKokoroFactory() {
+async function loadKokoroRuntime() {
   if (factoryOverride)
-    return factoryOverride;
+    return { factory: factoryOverride, device: "cpu" };
   try {
     const mod = await import("kokoro-js");
-    return mod.KokoroTTS;
+    return { factory: mod.KokoroTTS, device: "cpu" };
   } catch (err) {
-    const fallback2 = await loadKokoroFromWorkspace();
-    if (fallback2)
-      return fallback2;
+    const workspace = await loadKokoroFromWorkspace();
+    if (workspace)
+      return { factory: workspace, device: "cpu" };
+    const bundled = await loadBundledKokoroRuntime();
+    if (bundled)
+      return bundled;
     throw mapKokoroImportError(err);
   }
 }
@@ -11626,10 +11629,51 @@ async function loadKokoroFromWorkspace(baseDir = process.cwd()) {
     return null;
   }
 }
+async function loadBundledKokoroRuntime(runtimeDir = process.env.VIBE_KOKORO_RUNTIME) {
+  const base = runtimeDir?.trim();
+  if (!base)
+    return null;
+  try {
+    const { readFile: readFile56, writeFile: writeFile61, mkdir: mkdir31 } = await import("node:fs/promises");
+    const { join: join30, resolve: resolve86 } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const { homedir: homedir8 } = await import("node:os");
+    const transformersDir = resolve86(base, "node_modules", "@huggingface", "transformers");
+    const ortDistDir = resolve86(base, "node_modules", "onnxruntime-web", "dist");
+    const transformers = await import(pathToFileURL(join30(transformersDir, "dist", "transformers.web.js")).href);
+    const cacheRoot = join30(homedir8(), ".cache", "vibeframe", "models");
+    transformers.env.allowLocalModels = false;
+    transformers.env.useCustomCache = true;
+    transformers.env.customCache = {
+      async match(key) {
+        try {
+          return new Response(await readFile56(join30(cacheRoot, encodeURIComponent(String(key)))));
+        } catch {
+          return void 0;
+        }
+      },
+      async put(key, response) {
+        try {
+          const buf = Buffer.from(await response.arrayBuffer());
+          await mkdir31(cacheRoot, { recursive: true });
+          await writeFile61(join30(cacheRoot, encodeURIComponent(String(key))), buf);
+        } catch {
+        }
+      }
+    };
+    transformers.env.backends.onnx.wasm.wasmPaths = pathToFileURL(ortDistDir + "/").href;
+    const factory = await loadKokoroFromWorkspace(base);
+    if (!factory)
+      return null;
+    return { factory, device: "cpu" };
+  } catch {
+    return null;
+  }
+}
 function mapKokoroImportError(err) {
   const code = err instanceof Error && "code" in err ? err.code : void 0;
   if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
-    return new Error("Local Kokoro TTS is unavailable: optional dependency kokoro-js is not installed (its native dependencies may have failed to build on this platform). Install it with `npm i kokoro-js` \u2014 run it inside your workspace folder when using the Claude Desktop extension \u2014 or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
+    return new Error("Local Kokoro TTS is unavailable: kokoro-js could not be loaded from the npm install, the workspace node_modules, or the bundled extension runtime. Set OPENAI_API_KEY or ELEVENLABS_API_KEY to use a cloud voice instead (ttsProvider: openai / elevenlabs), or install the engine locally with `npm i kokoro-js` in your workspace folder.");
   }
   return err instanceof Error ? err : new Error(String(err));
 }
@@ -11637,10 +11681,12 @@ function loadModel(progress) {
   if (modelPromise)
     return modelPromise;
   modelPromise = (async () => {
-    const factory = await loadKokoroFactory();
-    return factory.from_pretrained(KOKORO_MODEL_ID, {
+    const runtime = await loadKokoroRuntime();
+    const override = process.env.VIBE_ONNX_DEVICE;
+    const device = override === "cpu" || override === "wasm" ? override : runtime.device;
+    return runtime.factory.from_pretrained(KOKORO_MODEL_ID, {
       dtype: "q8",
-      device: "cpu",
+      device,
       progress_callback: progress ? (raw) => progress(normaliseEvent(raw)) : void 0
     });
   })().catch((err) => {
@@ -11724,7 +11770,7 @@ var init_kokoro = __esm({
       label: "Kokoro (local)",
       apiKey: null,
       kinds: ["speech"],
-      resolverPriority: { speech: 2 }
+      resolverPriority: { speech: 3 }
     });
   }
 });
@@ -11996,12 +12042,119 @@ var init_openai_image = __esm({
   }
 });
 
+// ../ai-providers/dist/openai-tts/OpenAiTtsProvider.js
+var OPENAI_TTS_VOICES, DEFAULT_VOICE, DEFAULT_MODEL2, TTS_429_MAX_RETRIES2, TTS_429_RETRY_DELAY_MS2, OpenAiTtsProvider, openaiTtsProvider;
+var init_OpenAiTtsProvider = __esm({
+  "../ai-providers/dist/openai-tts/OpenAiTtsProvider.js"() {
+    "use strict";
+    OPENAI_TTS_VOICES = [
+      "alloy",
+      "ash",
+      "ballad",
+      "cedar",
+      "coral",
+      "echo",
+      "fable",
+      "marin",
+      "nova",
+      "onyx",
+      "sage",
+      "shimmer",
+      "verse"
+    ];
+    DEFAULT_VOICE = "marin";
+    DEFAULT_MODEL2 = "gpt-4o-mini-tts";
+    TTS_429_MAX_RETRIES2 = 1;
+    TTS_429_RETRY_DELAY_MS2 = 2e3;
+    OpenAiTtsProvider = class {
+      constructor() {
+        this.id = "openai";
+        this.name = "OpenAI TTS";
+        this.description = "OpenAI cloud text-to-speech (gpt-4o-mini-tts)";
+        this.capabilities = ["text-to-speech"];
+        this.isAvailable = true;
+        this.baseUrl = "https://api.openai.com/v1";
+      }
+      async initialize(config2) {
+        this.apiKey = config2.apiKey;
+        if (config2.baseUrl) {
+          this.baseUrl = config2.baseUrl;
+        }
+      }
+      isConfigured() {
+        return !!this.apiKey;
+      }
+      async textToSpeech(text, options = {}) {
+        if (!this.apiKey) {
+          return { success: false, error: "OpenAI API key not configured" };
+        }
+        const voice = (options.voice ?? DEFAULT_VOICE).toLowerCase();
+        if (!OPENAI_TTS_VOICES.includes(voice)) {
+          return {
+            success: false,
+            error: `Unknown OpenAI voice "${options.voice}". Available voices: ${OPENAI_TTS_VOICES.join(", ")}.`
+          };
+        }
+        try {
+          let response;
+          for (let attempt = 0; ; attempt++) {
+            response = await fetch(`${this.baseUrl}/audio/speech`, {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json"
+              },
+              body: JSON.stringify({
+                model: options.model ?? DEFAULT_MODEL2,
+                input: text,
+                voice,
+                response_format: "mp3",
+                ...options.speed !== void 0 && { speed: options.speed },
+                ...options.instructions !== void 0 && { instructions: options.instructions }
+              })
+            });
+            if (response.status === 429 && attempt < TTS_429_MAX_RETRIES2) {
+              await new Promise((resolveDelay) => setTimeout(resolveDelay, TTS_429_RETRY_DELAY_MS2 * (attempt + 1)));
+              continue;
+            }
+            break;
+          }
+          if (!response.ok) {
+            const error = await response.text();
+            return { success: false, error: `OpenAI TTS failed: ${error}` };
+          }
+          const arrayBuffer = await response.arrayBuffer();
+          return {
+            success: true,
+            audioBuffer: Buffer.from(arrayBuffer),
+            characterCount: text.length
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: error instanceof Error ? error.message : "Unknown error"
+          };
+        }
+      }
+    };
+    openaiTtsProvider = new OpenAiTtsProvider();
+  }
+});
+
+// ../ai-providers/dist/openai-tts/index.js
+var init_openai_tts = __esm({
+  "../ai-providers/dist/openai-tts/index.js"() {
+    "use strict";
+    init_OpenAiTtsProvider();
+  }
+});
+
 // ../ai-providers/dist/runway/RunwayProvider.js
-var DEFAULT_MODEL2, RunwayProvider, runwayProvider;
+var DEFAULT_MODEL3, RunwayProvider, runwayProvider;
 var init_RunwayProvider = __esm({
   "../ai-providers/dist/runway/RunwayProvider.js"() {
     "use strict";
-    DEFAULT_MODEL2 = "gen4.5";
+    DEFAULT_MODEL3 = "gen4.5";
     RunwayProvider = class _RunwayProvider {
       constructor() {
         this.id = "runway";
@@ -12044,7 +12197,7 @@ var init_RunwayProvider = __esm({
             "1:1": "960:960"
           };
           const apiRatio = ratioMap[options?.aspectRatio || "16:9"] || "1280:720";
-          const model = options?.model || DEFAULT_MODEL2;
+          const model = options?.model || DEFAULT_MODEL3;
           if (!options?.referenceImage && model !== "gen4.5") {
             return {
               id: "",
@@ -12306,11 +12459,11 @@ var init_runway = __esm({
 
 // ../ai-providers/dist/kling/KlingProvider.js
 import { createHmac } from "node:crypto";
-var DEFAULT_MODEL3, STD_MODE_MODELS, KlingProvider, klingProvider;
+var DEFAULT_MODEL4, STD_MODE_MODELS, KlingProvider, klingProvider;
 var init_KlingProvider = __esm({
   "../ai-providers/dist/kling/KlingProvider.js"() {
     "use strict";
-    DEFAULT_MODEL3 = "kling-v2-5-turbo";
+    DEFAULT_MODEL4 = "kling-v2-5-turbo";
     STD_MODE_MODELS = ["kling-v2-5-turbo", "kling-v2-6", "kling-v3", "kling-v3-omni"];
     KlingProvider = class {
       constructor() {
@@ -12373,7 +12526,7 @@ var init_KlingProvider = __esm({
         }
         try {
           const token = this.generateToken();
-          const model = options?.model || DEFAULT_MODEL3;
+          const model = options?.model || DEFAULT_MODEL4;
           let mode = options?.mode || "std";
           if (!STD_MODE_MODELS.includes(model) && mode === "std") {
             mode = "pro";
@@ -12744,11 +12897,11 @@ var init_kling = __esm({
 });
 
 // ../ai-providers/dist/grok/GrokProvider.js
-var DEFAULT_MODEL4, GrokProvider, grokProvider;
+var DEFAULT_MODEL5, GrokProvider, grokProvider;
 var init_GrokProvider = __esm({
   "../ai-providers/dist/grok/GrokProvider.js"() {
     "use strict";
-    DEFAULT_MODEL4 = "grok-imagine-video";
+    DEFAULT_MODEL5 = "grok-imagine-video";
     GrokProvider = class {
       constructor() {
         this.id = "grok";
@@ -12915,7 +13068,7 @@ var init_GrokProvider = __esm({
         try {
           const duration = Math.round(Math.min(15, Math.max(1, options?.duration || 5)));
           const body = {
-            model: DEFAULT_MODEL4,
+            model: DEFAULT_MODEL5,
             prompt: prompt3,
             duration,
             aspect_ratio: options?.aspectRatio || "16:9"
@@ -18122,9 +18275,11 @@ __export(dist_exports2, {
   KOKORO_MODEL_ID: () => KOKORO_MODEL_ID,
   KlingProvider: () => KlingProvider,
   KokoroProvider: () => KokoroProvider,
+  OPENAI_TTS_VOICES: () => OPENAI_TTS_VOICES,
   OllamaProvider: () => OllamaProvider,
   OpenAIImageProvider: () => OpenAIImageProvider,
   OpenAIProvider: () => OpenAIProvider,
+  OpenAiTtsProvider: () => OpenAiTtsProvider,
   ReplicateProvider: () => ReplicateProvider,
   RunwayProvider: () => RunwayProvider,
   WhisperProvider: () => WhisperProvider,
@@ -18148,9 +18303,12 @@ __export(dist_exports2, {
   isGeminiTextModelAlias: () => isGeminiTextModelAlias,
   klingProvider: () => klingProvider,
   kokoroProvider: () => kokoroProvider,
+  loadBundledKokoroRuntime: () => loadBundledKokoroRuntime,
+  loadKokoroFromWorkspace: () => loadKokoroFromWorkspace,
   ollamaProvider: () => ollamaProvider,
   openaiImageProvider: () => openaiImageProvider,
   openaiProvider: () => openaiProvider,
+  openaiTtsProvider: () => openaiTtsProvider,
   providerRegistry: () => providerRegistry,
   replicateProvider: () => replicateProvider,
   resolveGeminiTextModel: () => resolveGeminiTextModel,
@@ -18173,6 +18331,7 @@ var init_dist2 = __esm({
     init_elevenlabs();
     init_kokoro();
     init_openai_image();
+    init_openai_tts();
     init_runway();
     init_kling();
     init_grok();
@@ -26347,10 +26506,22 @@ var init_api_key = __esm({
 
 // src/commands/_shared/tts-resolve.ts
 async function resolveTtsProvider(preferred = "auto") {
-  const choice = preferred === "auto" ? await getConfiguredApiKey("ELEVENLABS_API_KEY") ? "elevenlabs" : "kokoro" : preferred;
+  let choice = preferred;
+  if (choice === "auto") {
+    if (await getConfiguredApiKey("ELEVENLABS_API_KEY")) {
+      choice = "elevenlabs";
+    } else if (await getConfiguredApiKey("OPENAI_API_KEY")) {
+      choice = "openai";
+    } else {
+      choice = "kokoro";
+    }
+  }
   if (choice === "elevenlabs") {
     return buildElevenLabs();
   }
+  if (choice === "openai") {
+    return buildOpenAi();
+  }
   return buildKokoro();
 }
 async function buildElevenLabs() {
@@ -26366,6 +26537,19 @@ async function buildElevenLabs() {
   });
   return { provider: "elevenlabs", audioExtension: "mp3", call };
 }
+async function buildOpenAi() {
+  const key = await getApiKey("OPENAI_API_KEY", "OpenAI");
+  if (!key) {
+    throw new TtsKeyMissingError("openai");
+  }
+  const provider = new OpenAiTtsProvider();
+  await provider.initialize({ apiKey: key });
+  const call = async (text, opts) => provider.textToSpeech(text, {
+    voice: opts?.voice,
+    speed: opts?.speed
+  });
+  return { provider: "openai", audioExtension: "mp3", call };
+}
 async function buildKokoro() {
   const provider = new KokoroProvider();
   await provider.initialize({});
@@ -26378,11 +26562,11 @@ async function buildKokoro() {
 }
 function parseTtsProviderName(value) {
   if (!value) return "auto";
-  if (value === "auto" || value === "elevenlabs" || value === "kokoro") {
+  if (value === "auto" || value === "elevenlabs" || value === "openai" || value === "kokoro") {
     return value;
   }
   throw new Error(
-    `Invalid --tts: ${value}. Valid: auto, elevenlabs, kokoro.`
+    `Invalid --tts: ${value}. Valid: auto, elevenlabs, openai, kokoro.`
   );
 }
 var TtsKeyMissingError;
@@ -26394,7 +26578,7 @@ var init_tts_resolve = __esm({
     TtsKeyMissingError = class extends Error {
       constructor(provider) {
         super(
-          provider === "elevenlabs" ? "ElevenLabs API key required (ELEVENLABS_API_KEY). Run 'vibe setup', set ELEVENLABS_API_KEY in .env, or pass --tts kokoro for local synthesis." : `Provider ${provider} is unavailable.`
+          provider === "elevenlabs" ? "ElevenLabs API key required (ELEVENLABS_API_KEY). Run 'vibe setup', set ELEVENLABS_API_KEY in .env, or pass --tts kokoro for local synthesis." : provider === "openai" ? "OpenAI API key required (OPENAI_API_KEY). Run 'vibe setup', set OPENAI_API_KEY in .env, or pass --tts kokoro for local synthesis." : `Provider ${provider} is unavailable.`
         );
         this.provider = provider;
         this.name = "TtsKeyMissingError";
@@ -31013,7 +31197,7 @@ async function executeSceneAdd(opts) {
       throw error;
     }
     opts.onProgress?.(
-      resolution.provider === "kokoro" ? "Generating narration with Kokoro (local \u2014 first run downloads ~330MB)..." : "Generating narration with ElevenLabs..."
+      resolution.provider === "kokoro" ? "Generating narration with Kokoro (local \u2014 first run downloads a ~90MB model)..." : resolution.provider === "openai" ? "Generating narration with OpenAI (gpt-4o-mini-tts)..." : "Generating narration with ElevenLabs..."
     );
     const tts = await resolution.call(narrationText, {
       voice: opts.voice,
@@ -31536,9 +31720,9 @@ Run 'vibe schema scene.<command>' for structured parameter info.`
       "Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider"
     ).option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option(
       "--tts <provider>",
-      "TTS provider: auto, elevenlabs, kokoro (default auto \u2014 picks ElevenLabs when key set, else Kokoro local)",
+      "TTS provider: auto, elevenlabs, openai, kokoro (default auto \u2014 ElevenLabs key > OpenAI key > Kokoro local)",
       "auto"
-    ).option("--voice <id>", "Voice id (ElevenLabs name/id, or Kokoro id like af_heart, am_michael)").option(
+    ).option("--voice <id>", "Voice id (ElevenLabs name/id, OpenAI voice like marin, or Kokoro id like af_heart)").option(
       "--no-audio",
       "Skip TTS even when --narration is provided (useful for tests/agent dry runs)"
     ).option("--no-image", "Skip image generation even when --visuals is provided").option(
@@ -59619,13 +59803,13 @@ async function createBuildPlan(opts) {
     const backdropCue = backdropPrompt ?? backdropReference?.raw;
     const videoCue = videoPrompt ?? videoReference?.raw;
     const musicCue = musicPrompt ?? musicReference?.raw;
-    const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : 0;
+    const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : resolved.narration.resolved === "openai" ? OPENAI_NARRATION_COST_USD : 0;
     const narrationCache = narrationText && !narrationReference ? narrationCacheDescriptor({
       beatId: beat.id,
       cue: narrationText,
       provider: resolved.narration.resolved,
       voice,
-      ext: resolved.narration.resolved === "elevenlabs" ? "mp3" : "wav"
+      ext: resolved.narration.resolved === "kokoro" ? "wav" : "mp3"
     }) : null;
     const backdropCache = augmentedBackdropPrompt && !backdropReference ? backdropCacheDescriptor({
       beatId: beat.id,
@@ -60043,17 +60227,20 @@ function providerInput(opts) {
 async function resolveNarrationProvider(input, projectDir) {
   const requested = input.value.toLowerCase();
   const hasElevenLabs = Boolean(await getApiKeyFromConfig("elevenlabs", { cwd: projectDir }));
-  const resolved = requested === "elevenlabs" ? "elevenlabs" : requested === "kokoro" ? "kokoro" : hasElevenLabs ? "elevenlabs" : "kokoro";
+  const hasOpenAi = Boolean(await getApiKeyFromConfig("openai", { cwd: projectDir }));
+  const resolved = requested === "elevenlabs" ? "elevenlabs" : requested === "openai" ? "openai" : requested === "kokoro" ? "kokoro" : hasElevenLabs ? "elevenlabs" : hasOpenAi ? "openai" : "kokoro";
+  const requiresKey = resolved !== "kokoro";
+  const hasKey = resolved === "elevenlabs" ? hasElevenLabs : resolved === "openai" ? hasOpenAi : true;
   return {
     kind: "narration",
     requested: input.requested,
     resolved,
     source: input.source,
-    requiresKey: resolved === "elevenlabs",
-    configured: resolved !== "elevenlabs" || hasElevenLabs,
-    ...resolved === "elevenlabs" ? { configKey: "elevenlabs" } : {},
-    ...resolved === "elevenlabs" && !hasElevenLabs ? { missingKey: providerEnvVar("elevenlabs") } : {},
-    retryWith: resolved === "elevenlabs" && !hasElevenLabs ? ["vibe setup --full"] : []
+    requiresKey,
+    configured: hasKey,
+    ...requiresKey ? { configKey: resolved } : {},
+    ...requiresKey && !hasKey ? { missingKey: providerEnvVar(resolved) } : {},
+    retryWith: requiresKey && !hasKey ? ["vibe setup --full"] : []
   };
 }
 async function keyedProviderResolution(opts, projectDir) {
@@ -60149,7 +60336,7 @@ function loadPlanEnv(projectDir) {
     dir = dirname21(dir);
   }
 }
-var import_dotenv3, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
+var import_dotenv3, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, OPENAI_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
 var init_build_plan = __esm({
   "src/commands/_shared/build-plan.ts"() {
     "use strict";
@@ -60167,6 +60354,7 @@ var init_build_plan = __esm({
     VIDEO_COST_USD = 5;
     MUSIC_COST_USD = 0.5;
     ELEVENLABS_NARRATION_COST_USD = 0.05;
+    OPENAI_NARRATION_COST_USD = 0.01;
     COMPOSE_COST_USD = 0.06;
     SUPPORTED_BUILD_IMAGE_PROVIDERS = ["openai", "gemini", "grok"];
   }
@@ -67930,8 +68118,9 @@ function planBuildElicitation(args) {
       description: "Which TTS engine narrates the video?",
       enum: [...NARRATION_CHOICES],
       enumNames: [
-        "Kokoro \u2014 free, runs locally on this machine",
-        "ElevenLabs \u2014 cloud TTS, uses your ElevenLabs credits"
+        "Kokoro \u2014 free, runs on this machine (first use downloads a ~90 MB voice model; slower)",
+        "OpenAI \u2014 fast cloud voice, uses your OpenAI API key (~$0.02 per video)",
+        "ElevenLabs \u2014 premium cloud voices, uses your ElevenLabs credits"
       ]
     };
     required.push("narration");
@@ -67987,7 +68176,7 @@ var NARRATION_CHOICES, BACKDROP_CHOICES;
 var init_elicit = __esm({
   "src/tools/_shared/elicit.ts"() {
     "use strict";
-    NARRATION_CHOICES = ["kokoro", "elevenlabs"];
+    NARRATION_CHOICES = ["kokoro", "openai", "elevenlabs"];
     BACKDROP_CHOICES = ["skip", "openai"];
   }
 });
@@ -68465,7 +68654,9 @@ var init_scene2 = __esm({
       skipVideo: external_exports.boolean().optional().describe("Skip video generation for every beat (use existing MP4 assets if present)."),
       skipMusic: external_exports.boolean().optional().describe("Skip music generation for every beat (use existing audio assets if present)."),
       skipRender: external_exports.boolean().optional().describe("Stop after compose \u2014 produces compositions/*.html but no final MP4."),
-      ttsProvider: external_exports.enum(["auto", "elevenlabs", "kokoro"]).optional().describe("TTS provider override. Default 'auto'."),
+      ttsProvider: external_exports.enum(["auto", "elevenlabs", "openai", "kokoro"]).optional().describe(
+        "TTS provider override. Default 'auto' (elevenlabs key > openai key > local kokoro)."
+      ),
       voice: external_exports.string().optional().describe("TTS voice id (provider-specific)."),
       imageProvider: external_exports.enum(["openai"]).optional().describe("Image provider for backdrops. Default 'openai' (gpt-image-2)."),
       videoProvider: external_exports.enum(["seedance", "grok", "kling", "runway", "veo"]).optional().describe("Video provider for per-beat video cues. Default seedance."),
@@ -70320,7 +70511,7 @@ var init_storyboard2 = __esm({
         skipBackdrop: external_exports.boolean().optional().describe("Don't include backdrop image generation in the plan."),
         skipVideo: external_exports.boolean().optional().describe("Don't include video generation in the plan."),
         skipMusic: external_exports.boolean().optional().describe("Don't include music generation in the plan."),
-        ttsProvider: external_exports.enum(["auto", "elevenlabs", "kokoro"]).optional().describe("TTS provider override."),
+        ttsProvider: external_exports.enum(["auto", "elevenlabs", "openai", "kokoro"]).optional().describe("TTS provider override."),
         voice: external_exports.string().optional().describe("Voice id."),
         imageProvider: external_exports.string().optional().describe("Image provider override."),
         imageQuality: external_exports.enum(["standard", "hd"]).optional().describe("Image quality override."),
@@ -73436,7 +73627,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.112.1",
+  version: "0.113.0",
   description: "VibeFrame CLI - agentic video workflow runtime",
   private: false,
   license: "MIT",
@@ -83439,13 +83630,13 @@ init_output();
 import { resolve as resolve61 } from "node:path";
 var VALID_STAGES = ["assets", "compose", "sync", "render", "all"];
 var VALID_MODES = ["agent", "batch", "auto"];
-var VALID_TTS_PROVIDERS = ["auto", "elevenlabs", "kokoro"];
+var VALID_TTS_PROVIDERS = ["auto", "elevenlabs", "openai", "kokoro"];
 var VALID_IMAGE_PROVIDERS = ["openai", "gemini", "grok"];
 var VALID_VIDEO_PROVIDERS = ["seedance", "grok", "kling", "runway", "veo"];
 var VALID_MUSIC_PROVIDERS = ["elevenlabs", "replicate"];
 var VALID_COMPOSERS = ["claude", "openai", "gemini"];
 var VALID_IMAGE_QUALITIES = ["standard", "hd"];
-var planCommand = new Command("plan").description("Read STORYBOARD.md and show build plan, costs, missing cues, and provider needs").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Stage to plan: ${VALID_STAGES.join("|")}`, "all").option("--beat <id>", "Restrict the plan to one beat").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--skip-narration", "Don't include narration generation in the plan").option("--skip-backdrop", "Don't include backdrop image generation in the plan").option("--skip-video", "Don't include video generation in the plan").option("--skip-music", "Don't include music generation in the plan").option("--tts <provider>", "TTS provider: auto|elevenlabs|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS.join("|")}`).option("--quality <q>", "Image quality: standard|hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--force", "Plan regeneration even when outputs already exist").option("--max-cost <usd>", "Fail if estimated cost exceeds this USD cap").action(async (projectDirArg, options) => {
+var planCommand = new Command("plan").description("Read STORYBOARD.md and show build plan, costs, missing cues, and provider needs").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Stage to plan: ${VALID_STAGES.join("|")}`, "all").option("--beat <id>", "Restrict the plan to one beat").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--skip-narration", "Don't include narration generation in the plan").option("--skip-backdrop", "Don't include backdrop image generation in the plan").option("--skip-video", "Don't include video generation in the plan").option("--skip-music", "Don't include music generation in the plan").option("--tts <provider>", "TTS provider: auto|elevenlabs|openai|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS.join("|")}`).option("--quality <q>", "Image quality: standard|hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--force", "Plan regeneration even when outputs already exist").option("--max-cost <usd>", "Fail if estimated cost exceeds this USD cap").action(async (projectDirArg, options) => {
   const startedAt = Date.now();
   const stage = String(options.stage ?? "all");
   if (!VALID_STAGES.includes(stage)) {
@@ -83636,7 +83827,7 @@ var VALID_STAGES2 = ["assets", "compose", "sync", "render", "all"];
 var VALID_IMAGE_PROVIDERS2 = ["openai", "gemini", "grok"];
 var VALID_VIDEO_PROVIDERS2 = ["seedance", "grok", "kling", "runway", "veo"];
 var VALID_MUSIC_PROVIDERS2 = ["elevenlabs", "replicate"];
-var buildCommand = new Command("build").description("Build a VibeFrame video project from STORYBOARD.md").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Build stage: ${VALID_STAGES2.join("|")}`, "all").option("--beat <id>", "Restrict asset/compose work to one beat id").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--effort <level>", "Compose effort tier (batch mode only): low|medium|high", "medium").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--max-cost <usd>", "Fail before provider spend when estimated cost exceeds this USD cap").option("--skip-narration", "Don't dispatch TTS even when beats declare narration cues").option("--skip-backdrop", "Don't dispatch image-gen even when beats declare backdrop cues").option("--skip-video", "Don't dispatch video generation even when beats declare video cues").option("--skip-music", "Don't dispatch music generation even when beats declare music cues").option("--skip-render", "Compose only \u2014 don't render to MP4").option("--tts <provider>", "TTS provider: auto|elevenlabs|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS2.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS2.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS2.join("|")}`).option("--quality <q>", "Image quality: standard|hd", "hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536", "1536x1024").option("--force", "Re-dispatch primitives even when assets already exist").option("--dry-run", "Preview parameters without dispatching").addHelpText(
+var buildCommand = new Command("build").description("Build a VibeFrame video project from STORYBOARD.md").argument("[project-dir]", "Video project directory", ".").option("--stage <stage>", `Build stage: ${VALID_STAGES2.join("|")}`, "all").option("--beat <id>", "Restrict asset/compose work to one beat id").option("--mode <mode>", "Build mode: agent|batch|auto", "auto").option("--effort <level>", "Compose effort tier (batch mode only): low|medium|high", "medium").option("--composer <provider>", "Batch composer: claude|openai|gemini").option("--max-cost <usd>", "Fail before provider spend when estimated cost exceeds this USD cap").option("--skip-narration", "Don't dispatch TTS even when beats declare narration cues").option("--skip-backdrop", "Don't dispatch image-gen even when beats declare backdrop cues").option("--skip-video", "Don't dispatch video generation even when beats declare video cues").option("--skip-music", "Don't dispatch music generation even when beats declare music cues").option("--skip-render", "Compose only \u2014 don't render to MP4").option("--tts <provider>", "TTS provider: auto|elevenlabs|openai|kokoro").option("--voice <id>", "Voice id").option("--image-provider <name>", `Image provider: ${VALID_IMAGE_PROVIDERS2.join("|")}`).option("--video-provider <name>", `Video provider: ${VALID_VIDEO_PROVIDERS2.join("|")}`).option("--music-provider <name>", `Music provider: ${VALID_MUSIC_PROVIDERS2.join("|")}`).option("--quality <q>", "Image quality: standard|hd", "hd").option("--image-size <s>", "Image size: 1024x1024|1536x1024|1024x1536", "1536x1024").option("--force", "Re-dispatch primitives even when assets already exist").option("--dry-run", "Preview parameters without dispatching").addHelpText(
   "after",
   `
 Examples:

package/dist/tools/_shared/elicit.d.ts

@@ -11,7 +11,7 @@ import type { ElicitForm } from "../adapters/mcp.js";
 /** The subset of build args that drive the question set. */
 export interface BuildChoiceArgs {
     stage?: "assets" | "compose" | "sync" | "render" | "all";
-    ttsProvider?: "auto" | "elevenlabs" | "kokoro";
+    ttsProvider?: "auto" | "elevenlabs" | "openai" | "kokoro";
     skipNarration?: boolean;
     skipBackdrop?: boolean;
     imageProvider?: string;

package/dist/tools/manifest/index.js

@@ -191,8 +191,8 @@ var init_api_keys = __esm({
       envVar: "OPENAI_API_KEY",
       label: "OpenAI",
       showInSetup: true,
-      setupDescription: "gpt-image-2 image gen ($, default since v0.56), Whisper transcribe, Agent",
-      envExampleComment: "OpenAI API Key (Whisper transcription, gpt-image-2 \u2014 default text-to-image since v0.56)",
+      setupDescription: "gpt-image-2 image gen ($, default since v0.56), gpt-4o-mini-tts narration, Whisper transcribe, Agent",
+      envExampleComment: "OpenAI API Key (Whisper transcription, gpt-4o-mini-tts narration, gpt-image-2 \u2014 default text-to-image since v0.56)",
       envExampleUrl: "https://platform.openai.com/api-keys",
       keyFormat: { prefix: /^sk-/, example: "sk-..." }
     });
@@ -2299,8 +2299,8 @@ var init_openai = __esm({
       id: "openai",
       label: "OpenAI",
       apiKey: "openai",
-      kinds: ["llm", "image", "transcription"],
-      resolverPriority: { image: 1 },
+      kinds: ["llm", "image", "transcription", "speech"],
+      resolverPriority: { image: 1, speech: 2 },
       commandsUnlocked: [
         "agent -p openai",
         "generate image -p openai",
@@ -4722,16 +4722,19 @@ var init_elevenlabs = __esm({
 });
 
 // ../ai-providers/dist/kokoro/KokoroProvider.js
-async function loadKokoroFactory() {
+async function loadKokoroRuntime() {
   if (factoryOverride)
-    return factoryOverride;
+    return { factory: factoryOverride, device: "cpu" };
   try {
     const mod = await import("kokoro-js");
-    return mod.KokoroTTS;
+    return { factory: mod.KokoroTTS, device: "cpu" };
   } catch (err) {
-    const fallback2 = await loadKokoroFromWorkspace();
-    if (fallback2)
-      return fallback2;
+    const workspace = await loadKokoroFromWorkspace();
+    if (workspace)
+      return { factory: workspace, device: "cpu" };
+    const bundled = await loadBundledKokoroRuntime();
+    if (bundled)
+      return bundled;
     throw mapKokoroImportError(err);
   }
 }
@@ -4751,10 +4754,51 @@ async function loadKokoroFromWorkspace(baseDir = process.cwd()) {
     return null;
   }
 }
+async function loadBundledKokoroRuntime(runtimeDir = process.env.VIBE_KOKORO_RUNTIME) {
+  const base = runtimeDir?.trim();
+  if (!base)
+    return null;
+  try {
+    const { readFile: readFile45, writeFile: writeFile51, mkdir: mkdir26 } = await import("node:fs/promises");
+    const { join: join27, resolve: resolve66 } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const { homedir: homedir6 } = await import("node:os");
+    const transformersDir = resolve66(base, "node_modules", "@huggingface", "transformers");
+    const ortDistDir = resolve66(base, "node_modules", "onnxruntime-web", "dist");
+    const transformers = await import(pathToFileURL(join27(transformersDir, "dist", "transformers.web.js")).href);
+    const cacheRoot = join27(homedir6(), ".cache", "vibeframe", "models");
+    transformers.env.allowLocalModels = false;
+    transformers.env.useCustomCache = true;
+    transformers.env.customCache = {
+      async match(key) {
+        try {
+          return new Response(await readFile45(join27(cacheRoot, encodeURIComponent(String(key)))));
+        } catch {
+          return void 0;
+        }
+      },
+      async put(key, response) {
+        try {
+          const buf = Buffer.from(await response.arrayBuffer());
+          await mkdir26(cacheRoot, { recursive: true });
+          await writeFile51(join27(cacheRoot, encodeURIComponent(String(key))), buf);
+        } catch {
+        }
+      }
+    };
+    transformers.env.backends.onnx.wasm.wasmPaths = pathToFileURL(ortDistDir + "/").href;
+    const factory = await loadKokoroFromWorkspace(base);
+    if (!factory)
+      return null;
+    return { factory, device: "cpu" };
+  } catch {
+    return null;
+  }
+}
 function mapKokoroImportError(err) {
   const code = err instanceof Error && "code" in err ? err.code : void 0;
   if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
-    return new Error("Local Kokoro TTS is unavailable: optional dependency kokoro-js is not installed (its native dependencies may have failed to build on this platform). Install it with `npm i kokoro-js` \u2014 run it inside your workspace folder when using the Claude Desktop extension \u2014 or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
+    return new Error("Local Kokoro TTS is unavailable: kokoro-js could not be loaded from the npm install, the workspace node_modules, or the bundled extension runtime. Set OPENAI_API_KEY or ELEVENLABS_API_KEY to use a cloud voice instead (ttsProvider: openai / elevenlabs), or install the engine locally with `npm i kokoro-js` in your workspace folder.");
   }
   return err instanceof Error ? err : new Error(String(err));
 }
@@ -4762,10 +4806,12 @@ function loadModel(progress) {
   if (modelPromise)
     return modelPromise;
   modelPromise = (async () => {
-    const factory = await loadKokoroFactory();
-    return factory.from_pretrained(KOKORO_MODEL_ID, {
+    const runtime = await loadKokoroRuntime();
+    const override = process.env.VIBE_ONNX_DEVICE;
+    const device = override === "cpu" || override === "wasm" ? override : runtime.device;
+    return runtime.factory.from_pretrained(KOKORO_MODEL_ID, {
       dtype: "q8",
-      device: "cpu",
+      device,
       progress_callback: progress ? (raw) => progress(normaliseEvent(raw)) : void 0
     });
   })().catch((err) => {
@@ -4849,7 +4895,7 @@ var init_kokoro = __esm({
       label: "Kokoro (local)",
       apiKey: null,
       kinds: ["speech"],
-      resolverPriority: { speech: 2 }
+      resolverPriority: { speech: 3 }
     });
   }
 });
@@ -5121,12 +5167,119 @@ var init_openai_image = __esm({
   }
 });
 
+// ../ai-providers/dist/openai-tts/OpenAiTtsProvider.js
+var OPENAI_TTS_VOICES, DEFAULT_VOICE, DEFAULT_MODEL2, TTS_429_MAX_RETRIES2, TTS_429_RETRY_DELAY_MS2, OpenAiTtsProvider, openaiTtsProvider;
+var init_OpenAiTtsProvider = __esm({
+  "../ai-providers/dist/openai-tts/OpenAiTtsProvider.js"() {
+    "use strict";
+    OPENAI_TTS_VOICES = [
+      "alloy",
+      "ash",
+      "ballad",
+      "cedar",
+      "coral",
+      "echo",
+      "fable",
+      "marin",
+      "nova",
+      "onyx",
+      "sage",
+      "shimmer",
+      "verse"
+    ];
+    DEFAULT_VOICE = "marin";
+    DEFAULT_MODEL2 = "gpt-4o-mini-tts";
+    TTS_429_MAX_RETRIES2 = 1;
+    TTS_429_RETRY_DELAY_MS2 = 2e3;
+    OpenAiTtsProvider = class {
+      constructor() {
+        this.id = "openai";
+        this.name = "OpenAI TTS";
+        this.description = "OpenAI cloud text-to-speech (gpt-4o-mini-tts)";
+        this.capabilities = ["text-to-speech"];
+        this.isAvailable = true;
+        this.baseUrl = "https://api.openai.com/v1";
+      }
+      async initialize(config2) {
+        this.apiKey = config2.apiKey;
+        if (config2.baseUrl) {
+          this.baseUrl = config2.baseUrl;
+        }
+      }
+      isConfigured() {
+        return !!this.apiKey;
+      }
+      async textToSpeech(text, options = {}) {
+        if (!this.apiKey) {
+          return { success: false, error: "OpenAI API key not configured" };
+        }
+        const voice = (options.voice ?? DEFAULT_VOICE).toLowerCase();
+        if (!OPENAI_TTS_VOICES.includes(voice)) {
+          return {
+            success: false,
+            error: `Unknown OpenAI voice "${options.voice}". Available voices: ${OPENAI_TTS_VOICES.join(", ")}.`
+          };
+        }
+        try {
+          let response;
+          for (let attempt = 0; ; attempt++) {
+            response = await fetch(`${this.baseUrl}/audio/speech`, {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json"
+              },
+              body: JSON.stringify({
+                model: options.model ?? DEFAULT_MODEL2,
+                input: text,
+                voice,
+                response_format: "mp3",
+                ...options.speed !== void 0 && { speed: options.speed },
+                ...options.instructions !== void 0 && { instructions: options.instructions }
+              })
+            });
+            if (response.status === 429 && attempt < TTS_429_MAX_RETRIES2) {
+              await new Promise((resolveDelay) => setTimeout(resolveDelay, TTS_429_RETRY_DELAY_MS2 * (attempt + 1)));
+              continue;
+            }
+            break;
+          }
+          if (!response.ok) {
+            const error = await response.text();
+            return { success: false, error: `OpenAI TTS failed: ${error}` };
+          }
+          const arrayBuffer = await response.arrayBuffer();
+          return {
+            success: true,
+            audioBuffer: Buffer.from(arrayBuffer),
+            characterCount: text.length
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: error instanceof Error ? error.message : "Unknown error"
+          };
+        }
+      }
+    };
+    openaiTtsProvider = new OpenAiTtsProvider();
+  }
+});
+
+// ../ai-providers/dist/openai-tts/index.js
+var init_openai_tts = __esm({
+  "../ai-providers/dist/openai-tts/index.js"() {
+    "use strict";
+    init_OpenAiTtsProvider();
+  }
+});
+
 // ../ai-providers/dist/runway/RunwayProvider.js
-var DEFAULT_MODEL2, RunwayProvider, runwayProvider;
+var DEFAULT_MODEL3, RunwayProvider, runwayProvider;
 var init_RunwayProvider = __esm({
   "../ai-providers/dist/runway/RunwayProvider.js"() {
     "use strict";
-    DEFAULT_MODEL2 = "gen4.5";
+    DEFAULT_MODEL3 = "gen4.5";
     RunwayProvider = class _RunwayProvider {
       constructor() {
         this.id = "runway";
@@ -5169,7 +5322,7 @@ var init_RunwayProvider = __esm({
             "1:1": "960:960"
           };
           const apiRatio = ratioMap[options?.aspectRatio || "16:9"] || "1280:720";
-          const model = options?.model || DEFAULT_MODEL2;
+          const model = options?.model || DEFAULT_MODEL3;
           if (!options?.referenceImage && model !== "gen4.5") {
             return {
               id: "",
@@ -5431,11 +5584,11 @@ var init_runway = __esm({
 
 // ../ai-providers/dist/kling/KlingProvider.js
 import { createHmac } from "node:crypto";
-var DEFAULT_MODEL3, STD_MODE_MODELS, KlingProvider, klingProvider;
+var DEFAULT_MODEL4, STD_MODE_MODELS, KlingProvider, klingProvider;
 var init_KlingProvider = __esm({
   "../ai-providers/dist/kling/KlingProvider.js"() {
     "use strict";
-    DEFAULT_MODEL3 = "kling-v2-5-turbo";
+    DEFAULT_MODEL4 = "kling-v2-5-turbo";
     STD_MODE_MODELS = ["kling-v2-5-turbo", "kling-v2-6", "kling-v3", "kling-v3-omni"];
     KlingProvider = class {
       constructor() {
@@ -5498,7 +5651,7 @@ var init_KlingProvider = __esm({
         }
         try {
           const token = this.generateToken();
-          const model = options?.model || DEFAULT_MODEL3;
+          const model = options?.model || DEFAULT_MODEL4;
           let mode = options?.mode || "std";
           if (!STD_MODE_MODELS.includes(model) && mode === "std") {
             mode = "pro";
@@ -5869,11 +6022,11 @@ var init_kling = __esm({
 });
 
 // ../ai-providers/dist/grok/GrokProvider.js
-var DEFAULT_MODEL4, GrokProvider, grokProvider;
+var DEFAULT_MODEL5, GrokProvider, grokProvider;
 var init_GrokProvider = __esm({
   "../ai-providers/dist/grok/GrokProvider.js"() {
     "use strict";
-    DEFAULT_MODEL4 = "grok-imagine-video";
+    DEFAULT_MODEL5 = "grok-imagine-video";
     GrokProvider = class {
       constructor() {
         this.id = "grok";
@@ -6040,7 +6193,7 @@ var init_GrokProvider = __esm({
         try {
           const duration = Math.round(Math.min(15, Math.max(1, options?.duration || 5)));
           const body = {
-            model: DEFAULT_MODEL4,
+            model: DEFAULT_MODEL5,
             prompt: prompt3,
             duration,
             aspect_ratio: options?.aspectRatio || "16:9"
@@ -11247,9 +11400,11 @@ __export(dist_exports2, {
   KOKORO_MODEL_ID: () => KOKORO_MODEL_ID,
   KlingProvider: () => KlingProvider,
   KokoroProvider: () => KokoroProvider,
+  OPENAI_TTS_VOICES: () => OPENAI_TTS_VOICES,
   OllamaProvider: () => OllamaProvider,
   OpenAIImageProvider: () => OpenAIImageProvider,
   OpenAIProvider: () => OpenAIProvider,
+  OpenAiTtsProvider: () => OpenAiTtsProvider,
   ReplicateProvider: () => ReplicateProvider,
   RunwayProvider: () => RunwayProvider,
   WhisperProvider: () => WhisperProvider,
@@ -11273,9 +11428,12 @@ __export(dist_exports2, {
   isGeminiTextModelAlias: () => isGeminiTextModelAlias,
   klingProvider: () => klingProvider,
   kokoroProvider: () => kokoroProvider,
+  loadBundledKokoroRuntime: () => loadBundledKokoroRuntime,
+  loadKokoroFromWorkspace: () => loadKokoroFromWorkspace,
   ollamaProvider: () => ollamaProvider,
   openaiImageProvider: () => openaiImageProvider,
   openaiProvider: () => openaiProvider,
+  openaiTtsProvider: () => openaiTtsProvider,
   providerRegistry: () => providerRegistry,
   replicateProvider: () => replicateProvider,
   resolveGeminiTextModel: () => resolveGeminiTextModel,
@@ -11298,6 +11456,7 @@ var init_dist2 = __esm({
     init_elevenlabs();
     init_kokoro();
     init_openai_image();
+    init_openai_tts();
     init_runway();
     init_kling();
     init_grok();
@@ -28713,10 +28872,22 @@ var init_esm = __esm({
 
 // src/commands/_shared/tts-resolve.ts
 async function resolveTtsProvider(preferred = "auto") {
-  const choice = preferred === "auto" ? await getConfiguredApiKey("ELEVENLABS_API_KEY") ? "elevenlabs" : "kokoro" : preferred;
+  let choice = preferred;
+  if (choice === "auto") {
+    if (await getConfiguredApiKey("ELEVENLABS_API_KEY")) {
+      choice = "elevenlabs";
+    } else if (await getConfiguredApiKey("OPENAI_API_KEY")) {
+      choice = "openai";
+    } else {
+      choice = "kokoro";
+    }
+  }
   if (choice === "elevenlabs") {
     return buildElevenLabs();
   }
+  if (choice === "openai") {
+    return buildOpenAi();
+  }
   return buildKokoro();
 }
 async function buildElevenLabs() {
@@ -28732,6 +28903,19 @@ async function buildElevenLabs() {
   });
   return { provider: "elevenlabs", audioExtension: "mp3", call };
 }
+async function buildOpenAi() {
+  const key = await getApiKey("OPENAI_API_KEY", "OpenAI");
+  if (!key) {
+    throw new TtsKeyMissingError("openai");
+  }
+  const provider = new OpenAiTtsProvider();
+  await provider.initialize({ apiKey: key });
+  const call = async (text, opts) => provider.textToSpeech(text, {
+    voice: opts?.voice,
+    speed: opts?.speed
+  });
+  return { provider: "openai", audioExtension: "mp3", call };
+}
 async function buildKokoro() {
   const provider = new KokoroProvider();
   await provider.initialize({});
@@ -28744,11 +28928,11 @@ async function buildKokoro() {
 }
 function parseTtsProviderName(value) {
   if (!value) return "auto";
-  if (value === "auto" || value === "elevenlabs" || value === "kokoro") {
+  if (value === "auto" || value === "elevenlabs" || value === "openai" || value === "kokoro") {
     return value;
   }
   throw new Error(
-    `Invalid --tts: ${value}. Valid: auto, elevenlabs, kokoro.`
+    `Invalid --tts: ${value}. Valid: auto, elevenlabs, openai, kokoro.`
   );
 }
 var TtsKeyMissingError;
@@ -28760,7 +28944,7 @@ var init_tts_resolve = __esm({
     TtsKeyMissingError = class extends Error {
       constructor(provider) {
         super(
-          provider === "elevenlabs" ? "ElevenLabs API key required (ELEVENLABS_API_KEY). Run 'vibe setup', set ELEVENLABS_API_KEY in .env, or pass --tts kokoro for local synthesis." : `Provider ${provider} is unavailable.`
+          provider === "elevenlabs" ? "ElevenLabs API key required (ELEVENLABS_API_KEY). Run 'vibe setup', set ELEVENLABS_API_KEY in .env, or pass --tts kokoro for local synthesis." : provider === "openai" ? "OpenAI API key required (OPENAI_API_KEY). Run 'vibe setup', set OPENAI_API_KEY in .env, or pass --tts kokoro for local synthesis." : `Provider ${provider} is unavailable.`
         );
         this.provider = provider;
         this.name = "TtsKeyMissingError";
@@ -32801,13 +32985,13 @@ async function createBuildPlan(opts) {
     const backdropCue = backdropPrompt ?? backdropReference?.raw;
     const videoCue = videoPrompt ?? videoReference?.raw;
     const musicCue = musicPrompt ?? musicReference?.raw;
-    const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : 0;
+    const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : resolved.narration.resolved === "openai" ? OPENAI_NARRATION_COST_USD : 0;
     const narrationCache = narrationText && !narrationReference ? narrationCacheDescriptor({
       beatId: beat.id,
       cue: narrationText,
       provider: resolved.narration.resolved,
       voice,
-      ext: resolved.narration.resolved === "elevenlabs" ? "mp3" : "wav"
+      ext: resolved.narration.resolved === "kokoro" ? "wav" : "mp3"
     }) : null;
     const backdropCache = augmentedBackdropPrompt && !backdropReference ? backdropCacheDescriptor({
       beatId: beat.id,
@@ -33225,17 +33409,20 @@ function providerInput(opts) {
 async function resolveNarrationProvider(input, projectDir) {
   const requested = input.value.toLowerCase();
   const hasElevenLabs = Boolean(await getApiKeyFromConfig("elevenlabs", { cwd: projectDir }));
-  const resolved = requested === "elevenlabs" ? "elevenlabs" : requested === "kokoro" ? "kokoro" : hasElevenLabs ? "elevenlabs" : "kokoro";
+  const hasOpenAi = Boolean(await getApiKeyFromConfig("openai", { cwd: projectDir }));
+  const resolved = requested === "elevenlabs" ? "elevenlabs" : requested === "openai" ? "openai" : requested === "kokoro" ? "kokoro" : hasElevenLabs ? "elevenlabs" : hasOpenAi ? "openai" : "kokoro";
+  const requiresKey = resolved !== "kokoro";
+  const hasKey = resolved === "elevenlabs" ? hasElevenLabs : resolved === "openai" ? hasOpenAi : true;
   return {
     kind: "narration",
     requested: input.requested,
     resolved,
     source: input.source,
-    requiresKey: resolved === "elevenlabs",
-    configured: resolved !== "elevenlabs" || hasElevenLabs,
-    ...resolved === "elevenlabs" ? { configKey: "elevenlabs" } : {},
-    ...resolved === "elevenlabs" && !hasElevenLabs ? { missingKey: providerEnvVar("elevenlabs") } : {},
-    retryWith: resolved === "elevenlabs" && !hasElevenLabs ? ["vibe setup --full"] : []
+    requiresKey,
+    configured: hasKey,
+    ...requiresKey ? { configKey: resolved } : {},
+    ...requiresKey && !hasKey ? { missingKey: providerEnvVar(resolved) } : {},
+    retryWith: requiresKey && !hasKey ? ["vibe setup --full"] : []
   };
 }
 async function keyedProviderResolution(opts, projectDir) {
@@ -33331,7 +33518,7 @@ function loadPlanEnv(projectDir) {
     dir = dirname9(dir);
   }
 }
-var import_dotenv2, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
+var import_dotenv2, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, OPENAI_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
 var init_build_plan = __esm({
   "src/commands/_shared/build-plan.ts"() {
     "use strict";
@@ -33349,6 +33536,7 @@ var init_build_plan = __esm({
     VIDEO_COST_USD = 5;
     MUSIC_COST_USD = 0.5;
     ELEVENLABS_NARRATION_COST_USD = 0.05;
+    OPENAI_NARRATION_COST_USD = 0.01;
     COMPOSE_COST_USD = 0.06;
     SUPPORTED_BUILD_IMAGE_PROVIDERS = ["openai", "gemini", "grok"];
   }
@@ -51379,7 +51567,7 @@ function pickOutputPath(data) {
 }
 
 // src/tools/_shared/elicit.ts
-var NARRATION_CHOICES = ["kokoro", "elevenlabs"];
+var NARRATION_CHOICES = ["kokoro", "openai", "elevenlabs"];
 var BACKDROP_CHOICES = ["skip", "openai"];
 function planBuildElicitation(args) {
   const assetsWillRun = args.stage === void 0 || args.stage === "all" || args.stage === "assets";
@@ -51394,8 +51582,9 @@ function planBuildElicitation(args) {
       description: "Which TTS engine narrates the video?",
       enum: [...NARRATION_CHOICES],
       enumNames: [
-        "Kokoro \u2014 free, runs locally on this machine",
-        "ElevenLabs \u2014 cloud TTS, uses your ElevenLabs credits"
+        "Kokoro \u2014 free, runs on this machine (first use downloads a ~90 MB voice model; slower)",
+        "OpenAI \u2014 fast cloud voice, uses your OpenAI API key (~$0.02 per video)",
+        "ElevenLabs \u2014 premium cloud voices, uses your ElevenLabs credits"
       ]
     };
     required.push("narration");
@@ -52600,9 +52789,9 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
   "Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider"
 ).option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option(
   "--tts <provider>",
-  "TTS provider: auto, elevenlabs, kokoro (default auto \u2014 picks ElevenLabs when key set, else Kokoro local)",
+  "TTS provider: auto, elevenlabs, openai, kokoro (default auto \u2014 ElevenLabs key > OpenAI key > Kokoro local)",
   "auto"
-).option("--voice <id>", "Voice id (ElevenLabs name/id, or Kokoro id like af_heart, am_michael)").option(
+).option("--voice <id>", "Voice id (ElevenLabs name/id, OpenAI voice like marin, or Kokoro id like af_heart)").option(
   "--no-audio",
   "Skip TTS even when --narration is provided (useful for tests/agent dry runs)"
 ).option("--no-image", "Skip image generation even when --visuals is provided").option(
@@ -52863,7 +53052,7 @@ async function executeSceneAdd(opts) {
       throw error;
     }
     opts.onProgress?.(
-      resolution.provider === "kokoro" ? "Generating narration with Kokoro (local \u2014 first run downloads ~330MB)..." : "Generating narration with ElevenLabs..."
+      resolution.provider === "kokoro" ? "Generating narration with Kokoro (local \u2014 first run downloads a ~90MB model)..." : resolution.provider === "openai" ? "Generating narration with OpenAI (gpt-4o-mini-tts)..." : "Generating narration with ElevenLabs..."
     );
     const tts = await resolution.call(narrationText, {
       voice: opts.voice,
@@ -53623,7 +53812,9 @@ var sceneBuildSchema = external_exports.object({
   skipVideo: external_exports.boolean().optional().describe("Skip video generation for every beat (use existing MP4 assets if present)."),
   skipMusic: external_exports.boolean().optional().describe("Skip music generation for every beat (use existing audio assets if present)."),
   skipRender: external_exports.boolean().optional().describe("Stop after compose \u2014 produces compositions/*.html but no final MP4."),
-  ttsProvider: external_exports.enum(["auto", "elevenlabs", "kokoro"]).optional().describe("TTS provider override. Default 'auto'."),
+  ttsProvider: external_exports.enum(["auto", "elevenlabs", "openai", "kokoro"]).optional().describe(
+    "TTS provider override. Default 'auto' (elevenlabs key > openai key > local kokoro)."
+  ),
   voice: external_exports.string().optional().describe("TTS voice id (provider-specific)."),
   imageProvider: external_exports.enum(["openai"]).optional().describe("Image provider for backdrops. Default 'openai' (gpt-image-2)."),
   videoProvider: external_exports.enum(["seedance", "grok", "kling", "runway", "veo"]).optional().describe("Video provider for per-beat video cues. Default seedance."),
@@ -57461,7 +57652,7 @@ var planTool = defineTool({
     skipBackdrop: external_exports.boolean().optional().describe("Don't include backdrop image generation in the plan."),
     skipVideo: external_exports.boolean().optional().describe("Don't include video generation in the plan."),
     skipMusic: external_exports.boolean().optional().describe("Don't include music generation in the plan."),
-    ttsProvider: external_exports.enum(["auto", "elevenlabs", "kokoro"]).optional().describe("TTS provider override."),
+    ttsProvider: external_exports.enum(["auto", "elevenlabs", "openai", "kokoro"]).optional().describe("TTS provider override."),
     voice: external_exports.string().optional().describe("Voice id."),
     imageProvider: external_exports.string().optional().describe("Image provider override."),
     imageQuality: external_exports.enum(["standard", "hd"]).optional().describe("Image quality override."),

package/dist/tools/manifest/scene.d.ts

@@ -145,7 +145,7 @@ export declare const sceneBuildTool: import("../define-tool.js").ToolDefinition<
     skipVideo: z.ZodOptional<z.ZodBoolean>;
     skipMusic: z.ZodOptional<z.ZodBoolean>;
     skipRender: z.ZodOptional<z.ZodBoolean>;
-    ttsProvider: z.ZodOptional<z.ZodEnum<["auto", "elevenlabs", "kokoro"]>>;
+    ttsProvider: z.ZodOptional<z.ZodEnum<["auto", "elevenlabs", "openai", "kokoro"]>>;
     voice: z.ZodOptional<z.ZodString>;
     imageProvider: z.ZodOptional<z.ZodEnum<["openai"]>>;
     videoProvider: z.ZodOptional<z.ZodEnum<["seedance", "grok", "kling", "runway", "veo"]>>;
@@ -167,7 +167,7 @@ export declare const sceneBuildTool: import("../define-tool.js").ToolDefinition<
     skipBackdrop?: boolean | undefined;
     skipRender?: boolean | undefined;
     imageProvider?: "openai" | undefined;
-    ttsProvider?: "elevenlabs" | "auto" | "kokoro" | undefined;
+    ttsProvider?: "openai" | "elevenlabs" | "auto" | "kokoro" | undefined;
     skipVideo?: boolean | undefined;
     skipMusic?: boolean | undefined;
     videoProvider?: "grok" | "seedance" | "kling" | "runway" | "veo" | undefined;
@@ -188,7 +188,7 @@ export declare const sceneBuildTool: import("../define-tool.js").ToolDefinition<
     skipBackdrop?: boolean | undefined;
     skipRender?: boolean | undefined;
     imageProvider?: "openai" | undefined;
-    ttsProvider?: "elevenlabs" | "auto" | "kokoro" | undefined;
+    ttsProvider?: "openai" | "elevenlabs" | "auto" | "kokoro" | undefined;
     skipVideo?: boolean | undefined;
     skipMusic?: boolean | undefined;
     videoProvider?: "grok" | "seedance" | "kling" | "runway" | "veo" | undefined;

package/dist/tools/manifest/storyboard.d.ts

@@ -87,7 +87,7 @@ export declare const planTool: import("../define-tool.js").ToolDefinition<z.ZodO
     skipBackdrop: z.ZodOptional<z.ZodBoolean>;
     skipVideo: z.ZodOptional<z.ZodBoolean>;
     skipMusic: z.ZodOptional<z.ZodBoolean>;
-    ttsProvider: z.ZodOptional<z.ZodEnum<["auto", "elevenlabs", "kokoro"]>>;
+    ttsProvider: z.ZodOptional<z.ZodEnum<["auto", "elevenlabs", "openai", "kokoro"]>>;
     voice: z.ZodOptional<z.ZodString>;
     imageProvider: z.ZodOptional<z.ZodString>;
     imageQuality: z.ZodOptional<z.ZodEnum<["standard", "hd"]>>;
@@ -107,7 +107,7 @@ export declare const planTool: import("../define-tool.js").ToolDefinition<z.ZodO
     skipNarration?: boolean | undefined;
     skipBackdrop?: boolean | undefined;
     imageProvider?: string | undefined;
-    ttsProvider?: "elevenlabs" | "auto" | "kokoro" | undefined;
+    ttsProvider?: "openai" | "elevenlabs" | "auto" | "kokoro" | undefined;
     skipVideo?: boolean | undefined;
     skipMusic?: boolean | undefined;
     videoProvider?: "grok" | "seedance" | "kling" | "runway" | "veo" | undefined;
@@ -125,7 +125,7 @@ export declare const planTool: import("../define-tool.js").ToolDefinition<z.ZodO
     skipNarration?: boolean | undefined;
     skipBackdrop?: boolean | undefined;
     imageProvider?: string | undefined;
-    ttsProvider?: "elevenlabs" | "auto" | "kokoro" | undefined;
+    ttsProvider?: "openai" | "elevenlabs" | "auto" | "kokoro" | undefined;
     skipVideo?: boolean | undefined;
     skipMusic?: boolean | undefined;
     videoProvider?: "grok" | "seedance" | "kling" | "runway" | "veo" | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.112.1",
+  "version": "0.113.0",
   "description": "VibeFrame CLI - agentic video workflow runtime",
   "private": false,
   "license": "MIT",
@@ -83,8 +83,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/ai-providers": "0.112.1",
-    "@vibeframe/core": "0.112.1"
+    "@vibeframe/ai-providers": "0.113.0",
+    "@vibeframe/core": "0.113.0"
   },
   "engines": {
     "node": ">=20"