@vibeframe/cli 0.53.0 → 0.54.0

package/dist/commands/_shared/tts-resolve.js

@@ -0,0 +1,89 @@
+/**
+ * @module _shared/tts-resolve
+ *
+ * One-stop factory for picking a TTS provider at runtime. Used by every
+ * scene-authoring path that turns text into narration audio (currently
+ * `executeSceneAdd`; `script-to-video --format scenes` follows in C5+).
+ *
+ * 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.
+ *     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
+ * `{ success, audioBuffer, error?, characterCount? }` result.
+ */
+import { ElevenLabsProvider, KokoroProvider } from "@vibeframe/ai-providers";
+import { hasApiKey } from "../../utils/api-key.js";
+import { getApiKey } from "../../utils/api-key.js";
+/**
+ * Resolve a TTS provider preference into a callable + metadata.
+ *
+ * Resolution policy:
+ *   - `"elevenlabs"`: requires `ELEVENLABS_API_KEY`. Throws an `ApiKeyError`-style
+ *     error via {@link getApiKey} (consumed by `requireApiKey`/`exitWithError`).
+ *   - `"kokoro"`: always available (local). No key check.
+ *   - `"auto"` (or `undefined`): if `ELEVENLABS_API_KEY` is set, picks
+ *     ElevenLabs; otherwise falls back to Kokoro.
+ */
+export async function resolveTtsProvider(preferred = "auto") {
+    const choice = preferred === "auto"
+        ? (hasApiKey("ELEVENLABS_API_KEY") ? "elevenlabs" : "kokoro")
+        : preferred;
+    if (choice === "elevenlabs") {
+        return buildElevenLabs();
+    }
+    return buildKokoro();
+}
+async function buildElevenLabs() {
+    const key = await getApiKey("ELEVENLABS_API_KEY", "ElevenLabs");
+    if (!key) {
+        throw new TtsKeyMissingError("elevenlabs");
+    }
+    const provider = new ElevenLabsProvider();
+    await provider.initialize({ apiKey: key });
+    const call = async (text, opts) => provider.textToSpeech(text, {
+        voiceId: opts?.voice,
+        speed: opts?.speed,
+    });
+    return { provider: "elevenlabs", audioExtension: "mp3", call };
+}
+async function buildKokoro() {
+    const provider = new KokoroProvider();
+    // No-op initialize — Kokoro doesn't take a config but we keep parity with
+    // the AIProvider lifecycle for future audit checks.
+    await provider.initialize({});
+    const call = async (text, opts) => provider.textToSpeech(text, {
+        voice: opts?.voice,
+        speed: opts?.speed,
+        onProgress: opts?.onProgress,
+    });
+    return { provider: "kokoro", audioExtension: "wav", call };
+}
+/**
+ * Thrown when the caller asked for a specific provider whose key/runtime is
+ * unavailable. Carries the provider id so the caller can format a clean
+ * `usageError`/`exitWithError`.
+ */
+export class TtsKeyMissingError extends Error {
+    provider;
+    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.`);
+        this.provider = provider;
+        this.name = "TtsKeyMissingError";
+    }
+}
+/** Validate a free-form `--tts <value>` against {@link TtsProviderName}. */
+export function parseTtsProviderName(value) {
+    if (!value)
+        return "auto";
+    if (value === "auto" || value === "elevenlabs" || value === "kokoro") {
+        return value;
+    }
+    throw new Error(`Invalid --tts: ${value}. Valid: auto, elevenlabs, kokoro.`);
+}
+//# sourceMappingURL=tts-resolve.js.map

package/dist/commands/_shared/tts-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-resolve.js","sourceRoot":"","sources":["../../../src/commands/_shared/tts-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AA0CnD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,YAA6B,MAAM;IAEnC,MAAM,MAAM,GAAG,SAAS,KAAK,MAAM;QACjC,CAAC,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC7D,CAAC,CAAC,SAAS,CAAC;IAEd,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;QAC5B,OAAO,eAAe,EAAE,CAAC;IAC3B,CAAC;IACD,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAED,KAAK,UAAU,eAAe;IAC5B,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,oBAAoB,EAAE,YAAY,CAAC,CAAC;IAChE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAC1C,MAAM,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAgB,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAC7C,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE;QAC1B,OAAO,EAAE,IAAI,EAAE,KAAK;QACpB,KAAK,EAAE,IAAI,EAAE,KAAK;KACnB,CAAC,CAAC;IACL,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,KAAK,UAAU,WAAW;IACxB,MAAM,QAAQ,GAAG,IAAI,cAAc,EAAE,CAAC;IACtC,0EAA0E;IAC1E,oDAAoD;IACpD,MAAM,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAgB,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAC7C,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,IAAI,EAAE,KAAK;QAClB,KAAK,EAAE,IAAI,EAAE,KAAK;QAClB,UAAU,EAAE,IAAI,EAAE,UAAU;KAC7B,CAAC,CAAC;IACL,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACf;IAA5B,YAA4B,QAA6B;QACvD,KAAK,CACH,QAAQ,KAAK,YAAY;YACvB,CAAC,CAAC,+IAA+I;YACjJ,CAAC,CAAC,YAAY,QAAQ,kBAAkB,CAC3C,CAAC;QALwB,aAAQ,GAAR,QAAQ,CAAqB;QAMvD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,UAAU,oBAAoB,CAAC,KAAyB;IAC5D,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,YAAY,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,IAAI,KAAK,CACb,kBAAkB,KAAK,oCAAoC,CAC5D,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,6 @@
+/**
+ * Unit tests for the TTS router. The actual provider classes are mocked at
+ * the module level so we can drive resolution outcomes deterministically.
+ */
+export {};
+//# sourceMappingURL=tts-resolve.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tts-resolve.test.d.ts","sourceRoot":"","sources":["../../../src/commands/_shared/tts-resolve.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/commands/_shared/tts-resolve.test.js

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for the TTS router. The actual provider classes are mocked at
+ * the module level so we can drive resolution outcomes deterministically.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+// vi.mock factories are hoisted above imports — so any references must come
+// from vi.hoisted (which is also hoisted) rather than module-scope variables.
+const mocks = vi.hoisted(() => {
+    return {
+        elevenLabsTextToSpeech: vi.fn(),
+        elevenLabsInitialize: vi.fn(),
+        kokoroTextToSpeech: vi.fn(),
+        kokoroInitialize: vi.fn(),
+        hasApiKey: vi.fn(),
+        getApiKey: vi.fn(),
+    };
+});
+vi.mock("@vibeframe/ai-providers", () => ({
+    ElevenLabsProvider: class {
+        initialize = mocks.elevenLabsInitialize;
+        textToSpeech = mocks.elevenLabsTextToSpeech;
+    },
+    KokoroProvider: class {
+        initialize = mocks.kokoroInitialize;
+        textToSpeech = mocks.kokoroTextToSpeech;
+    },
+}));
+vi.mock("../../utils/api-key.js", () => ({
+    hasApiKey: (...args) => mocks.hasApiKey(...args),
+    getApiKey: (...args) => mocks.getApiKey(...args),
+}));
+const { elevenLabsTextToSpeech, elevenLabsInitialize, kokoroTextToSpeech, kokoroInitialize, hasApiKey, getApiKey, } = mocks;
+import { parseTtsProviderName, resolveTtsProvider, TtsKeyMissingError, } from "./tts-resolve.js";
+describe("parseTtsProviderName", () => {
+    it("defaults to auto when undefined or empty", () => {
+        expect(parseTtsProviderName(undefined)).toBe("auto");
+        expect(parseTtsProviderName("")).toBe("auto");
+    });
+    it("accepts the three valid values", () => {
+        expect(parseTtsProviderName("auto")).toBe("auto");
+        expect(parseTtsProviderName("elevenlabs")).toBe("elevenlabs");
+        expect(parseTtsProviderName("kokoro")).toBe("kokoro");
+    });
+    it("throws for unknown providers", () => {
+        expect(() => parseTtsProviderName("openai")).toThrow(/Invalid --tts/);
+        expect(() => parseTtsProviderName("KOKORO")).toThrow(/Invalid --tts/);
+    });
+});
+describe("resolveTtsProvider", () => {
+    beforeEach(() => {
+        elevenLabsTextToSpeech.mockReset();
+        elevenLabsInitialize.mockReset();
+        kokoroTextToSpeech.mockReset();
+        kokoroInitialize.mockReset();
+        hasApiKey.mockReset();
+        getApiKey.mockReset();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe("auto", () => {
+        it("picks ElevenLabs when ELEVENLABS_API_KEY is set", async () => {
+            hasApiKey.mockReturnValue(true);
+            getApiKey.mockResolvedValue("sk-test");
+            const r = await resolveTtsProvider("auto");
+            expect(r.provider).toBe("elevenlabs");
+            expect(r.audioExtension).toBe("mp3");
+            expect(hasApiKey).toHaveBeenCalledWith("ELEVENLABS_API_KEY");
+            expect(elevenLabsInitialize).toHaveBeenCalledWith({ apiKey: "sk-test" });
+        });
+        it("falls back to Kokoro when ELEVENLABS_API_KEY is unset", async () => {
+            hasApiKey.mockReturnValue(false);
+            const r = await resolveTtsProvider("auto");
+            expect(r.provider).toBe("kokoro");
+            expect(r.audioExtension).toBe("wav");
+            expect(kokoroInitialize).toHaveBeenCalled();
+            expect(getApiKey).not.toHaveBeenCalled();
+        });
+        it("treats undefined preferred the same as auto", async () => {
+            hasApiKey.mockReturnValue(false);
+            const r = await resolveTtsProvider();
+            expect(r.provider).toBe("kokoro");
+        });
+    });
+    describe("explicit elevenlabs", () => {
+        it("uses ElevenLabs when key is present", async () => {
+            getApiKey.mockResolvedValue("sk-real");
+            const r = await resolveTtsProvider("elevenlabs");
+            expect(r.provider).toBe("elevenlabs");
+            expect(elevenLabsInitialize).toHaveBeenCalledWith({ apiKey: "sk-real" });
+        });
+        it("throws TtsKeyMissingError when key is absent", async () => {
+            getApiKey.mockResolvedValue(undefined);
+            await expect(resolveTtsProvider("elevenlabs")).rejects.toBeInstanceOf(TtsKeyMissingError);
+            expect(kokoroInitialize).not.toHaveBeenCalled();
+        });
+    });
+    describe("explicit kokoro", () => {
+        it("uses Kokoro without checking any key", async () => {
+            const r = await resolveTtsProvider("kokoro");
+            expect(r.provider).toBe("kokoro");
+            expect(r.audioExtension).toBe("wav");
+            expect(kokoroInitialize).toHaveBeenCalled();
+            expect(getApiKey).not.toHaveBeenCalled();
+            expect(hasApiKey).not.toHaveBeenCalled();
+        });
+    });
+    describe("call dispatch", () => {
+        it("forwards voice + speed to ElevenLabs as voiceId/speed", async () => {
+            hasApiKey.mockReturnValue(true);
+            getApiKey.mockResolvedValue("sk-test");
+            elevenLabsTextToSpeech.mockResolvedValue({ success: true, audioBuffer: Buffer.from("x") });
+            const r = await resolveTtsProvider("elevenlabs");
+            await r.call("Hello.", { voice: "rachel", speed: 1.1 });
+            expect(elevenLabsTextToSpeech).toHaveBeenCalledWith("Hello.", {
+                voiceId: "rachel",
+                speed: 1.1,
+            });
+        });
+        it("forwards voice + speed + onProgress to Kokoro", async () => {
+            kokoroTextToSpeech.mockResolvedValue({ success: true, audioBuffer: Buffer.from("y") });
+            const r = await resolveTtsProvider("kokoro");
+            const onProgress = vi.fn();
+            await r.call("Hello.", { voice: "af_heart", speed: 1.0, onProgress });
+            expect(kokoroTextToSpeech).toHaveBeenCalledWith("Hello.", {
+                voice: "af_heart",
+                speed: 1.0,
+                onProgress,
+            });
+        });
+    });
+});
+describe("TtsKeyMissingError", () => {
+    it("provides actionable elevenlabs message", () => {
+        const err = new TtsKeyMissingError("elevenlabs");
+        expect(err.message).toMatch(/ELEVENLABS_API_KEY/);
+        expect(err.message).toMatch(/--tts kokoro/);
+        expect(err.provider).toBe("elevenlabs");
+    });
+    it("is identifiable via instanceof", () => {
+        const err = new TtsKeyMissingError("elevenlabs");
+        expect(err).toBeInstanceOf(TtsKeyMissingError);
+        expect(err).toBeInstanceOf(Error);
+        expect(err.name).toBe("TtsKeyMissingError");
+    });
+});
+//# sourceMappingURL=tts-resolve.test.js.map

package/dist/commands/_shared/tts-resolve.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-resolve.test.js","sourceRoot":"","sources":["../../../src/commands/_shared/tts-resolve.test.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAEzE,4EAA4E;AAC5E,8EAA8E;AAC9E,MAAM,KAAK,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;IAC5B,OAAO;QACL,sBAAsB,EAAE,EAAE,CAAC,EAAE,EAAE;QAC/B,oBAAoB,EAAE,EAAE,CAAC,EAAE,EAAE;QAC7B,kBAAkB,EAAE,EAAE,CAAC,EAAE,EAAE;QAC3B,gBAAgB,EAAE,EAAE,CAAC,EAAE,EAAE;QACzB,SAAS,EAAE,EAAE,CAAC,EAAE,EAAE;QAClB,SAAS,EAAE,EAAE,CAAC,EAAE,EAAE;KACnB,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,IAAI,CAAC,yBAAyB,EAAE,GAAG,EAAE,CAAC,CAAC;IACxC,kBAAkB,EAAE;QAClB,UAAU,GAAG,KAAK,CAAC,oBAAoB,CAAC;QACxC,YAAY,GAAG,KAAK,CAAC,sBAAsB,CAAC;KAC7C;IACD,cAAc,EAAE;QACd,UAAU,GAAG,KAAK,CAAC,gBAAgB,CAAC;QACpC,YAAY,GAAG,KAAK,CAAC,kBAAkB,CAAC;KACzC;CACF,CAAC,CAAC,CAAC;AAEJ,EAAE,CAAC,IAAI,CAAC,wBAAwB,EAAE,GAAG,EAAE,CAAC,CAAC;IACvC,SAAS,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IAC3D,SAAS,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;CAC5D,CAAC,CAAC,CAAC;AAEJ,MAAM,EACJ,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,SAAS,GACV,GAAG,KAAK,CAAC;AAEV,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,CAAC,oBAAoB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,MAAM,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC9D,MAAM,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,UAAU,CAAC,GAAG,EAAE;QACd,sBAAsB,CAAC,SAAS,EAAE,CAAC;QACnC,oBAAoB,CAAC,SAAS,EAAE,CAAC;QACjC,kBAAkB,CAAC,SAAS,EAAE,CAAC;QAC/B,gBAAgB,CAAC,SAAS,EAAE,CAAC;QAC7B,SAAS,CAAC,SAAS,EAAE,CAAC;QACtB,SAAS,CAAC,SAAS,EAAE,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,eAAe,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE;QACpB,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;YAC/D,SAAS,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;YAChC,SAAS,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YAEvC,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;YAE3C,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACtC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrC,MAAM,CAAC,SAAS,CAAC,CAAC,oBAAoB,CAAC,oBAAoB,CAAC,CAAC;YAC7D,MAAM,CAAC,oBAAoB,CAAC,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QAC3E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;YACrE,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;YAEjC,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;YAE3C,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAClC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrC,MAAM,CAAC,gBAAgB,CAAC,CAAC,gBAAgB,EAAE,CAAC;YAC5C,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;QAC3C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;YAC3D,SAAS,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;YAEjC,MAAM,CAAC,GAAG,MAAM,kBAAkB,EAAE,CAAC;YAErC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;QACnC,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;YACnD,SAAS,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YAEvC,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,YAAY,CAAC,CAAC;YAEjD,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACtC,MAAM,CAAC,oBAAoB,CAAC,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QAC3E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;YAC5D,SAAS,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YAEvC,MAAM,MAAM,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,CACnE,kBAAkB,CACnB,CAAC;YACF,MAAM,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;QAClD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;QAC/B,EAAE,CAAC,sCAAsC,EAAE,KAAK,IAAI,EAAE;YACpD,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAE7C,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAClC,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrC,MAAM,CAAC,gBAAgB,CAAC,CAAC,gBAAgB,EAAE,CAAC;YAC5C,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;YACzC,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC;QAC3C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;QAC7B,EAAE,CAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;YACrE,SAAS,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;YAChC,SAAS,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACvC,sBAAsB,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAE3F,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,YAAY,CAAC,CAAC;YACjD,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YAExD,MAAM,CAAC,sBAAsB,CAAC,CAAC,oBAAoB,CAAC,QAAQ,EAAE;gBAC5D,OAAO,EAAE,QAAQ;gBACjB,KAAK,EAAE,GAAG;aACX,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;YAC7D,kBAAkB,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAEvF,MAAM,CAAC,GAAG,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAC7C,MAAM,UAAU,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC;YAEtE,MAAM,CAAC,kBAAkB,CAAC,CAAC,oBAAoB,CAAC,QAAQ,EAAE;gBACxD,KAAK,EAAE,UAAU;gBACjB,KAAK,EAAE,GAAG;gBACV,UAAU;aACX,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,GAAG,GAAG,IAAI,kBAAkB,CAAC,YAAY,CAAC,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,GAAG,GAAG,IAAI,kBAAkB,CAAC,YAAY,CAAC,CAAC;QACjD,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,kBAAkB,CAAC,CAAC;QAC/C,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/commands/scene.d.ts

@@ -14,6 +14,7 @@
  *   - render    [C4, this commit] — render scene project to MP4/WebM/MOV
  */
 import { Command } from "commander";
+import { type TtsProviderName } from "./_shared/tts-resolve.js";
 import { type ScenePreset } from "./_shared/scene-html-emit.js";
 export declare const sceneCommand: Command;
 export interface SceneAddOptions {
@@ -21,6 +22,14 @@ export interface SceneAddOptions {
     preset: ScenePreset;
     /** Narration text. If the value is an existing file path, its content is used. */
     narration?: string;
+    /**
+     * Path to an existing narration audio file (.wav/.mp3). When provided,
+     * skips TTS entirely and copies the file into the project's `assets/`.
+     * Compatible with `npx hyperframes tts`, `say`, or any other external
+     * synthesis tool. The transcript is still generated unless
+     * `skipTranscribe` is set.
+     */
+    narrationFile?: string;
     /** Explicit duration in seconds. Overrides narration-derived duration. */
     duration?: number;
     /** Image generation prompt. */
@@ -33,12 +42,21 @@ export interface SceneAddOptions {
     insertInto?: string;
     /** "gemini" | "openai". */
     imageProvider?: string;
-    /** ElevenLabs voice id/name. */
+    /** TTS provider preference. Defaults to `"auto"` (ElevenLabs if key set, else Kokoro). */
+    tts?: TtsProviderName;
+    /** Voice id (ElevenLabs name/id, or Kokoro id like `af_heart`). */
     voice?: string;
     /** When true, skip TTS even if narration is provided. */
     skipAudio?: boolean;
     /** When true, skip image generation even if visuals is provided. */
     skipImage?: boolean;
+    /**
+     * When true, skip the Whisper word-level transcribe step that would
+     * otherwise emit `assets/transcript-<id>.json`.
+     */
+    skipTranscribe?: boolean;
+    /** BCP-47 language hint forwarded to Whisper (e.g. `"en"`, `"ko"`). */
+    transcribeLanguage?: string;
     /** Overwrite existing compositions/scene-<id>.html. */
     force?: boolean;
     /** Progress sink (CLI spinner / agent stream). */
@@ -54,6 +72,14 @@ export interface SceneAddResult {
     rootPath: string;
     audioPath?: string;
     imagePath?: string;
+    /**
+     * Project-relative path to `assets/transcript-<id>.json` when Whisper
+     * word-level transcribe ran. `undefined` when skipped or when the audio
+     * source produced no narration text to transcribe.
+     */
+    transcriptPath?: string;
+    /** Number of word entries emitted into the transcript JSON. */
+    transcriptWordCount?: number;
     error?: string;
 }
 export declare function executeSceneAdd(opts: SceneAddOptions): Promise<SceneAddResult>;

package/dist/commands/scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../src/commands/scene.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC,OAAO,EAOL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AA8CtC,eAAO,MAAM,YAAY,SAkByC,CAAC;AAoLnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAwCD,wBAAsB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAuKpF"}
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../../src/commands/scene.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,EAOL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AA8CtC,eAAO,MAAM,YAAY,SAkByC,CAAC;AAoMnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAwCD,wBAAsB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAuPpF"}

package/dist/commands/scene.js

@@ -15,12 +15,13 @@
  */
 import { Command } from "commander";
 import { basename, resolve, relative, dirname } from "node:path";
-import { mkdir, readFile, writeFile, access } from "node:fs/promises";
+import { mkdir, readFile, writeFile, access, copyFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import chalk from "chalk";
 import ora from "ora";
 import { parse as yamlParse } from "yaml";
-import { ElevenLabsProvider, GeminiProvider, OpenAIImageProvider, } from "@vibeframe/ai-providers";
+import { GeminiProvider, OpenAIImageProvider, WhisperProvider, } from "@vibeframe/ai-providers";
+import { resolveTtsProvider, TtsKeyMissingError, parseTtsProviderName, } from "./_shared/tts-resolve.js";
 import { scaffoldSceneProject, aspectToDims, } from "./_shared/scene-project.js";
 import { emitSceneHtml, insertClipIntoRoot, nextSceneStart, readRootDims, slugifySceneName, SCENE_PRESETS, } from "./_shared/scene-html-emit.js";
 import { runProjectLint, rootExists, } from "./_shared/scene-lint.js";
@@ -136,6 +137,7 @@ sceneCommand
     .argument("<name>", "Scene name (slugified into the composition id)")
     .option("--style <preset>", `Style preset: ${SCENE_PRESETS.join(", ")}`, "simple")
     .option("--narration <text>", "Narration text (or path to a .txt file). Drives TTS + scene duration.")
+    .option("--narration-file <path>", "Existing narration audio file (.wav/.mp3). Skips TTS — useful with hyperframes tts, Mac say, or other external tools.")
     .option("-d, --duration <sec>", "Explicit scene duration in seconds (overrides narration audio)")
     .option("--visuals <prompt>", "Image prompt — generates assets/scene-<id>.png via the configured image provider")
     .option("--headline <text>", "Visible headline (defaults to the humanised scene name)")
@@ -143,9 +145,12 @@ sceneCommand
     .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("--voice <id>", "ElevenLabs voice id or name")
+    .option("--tts <provider>", "TTS provider: auto, elevenlabs, kokoro (default auto — picks ElevenLabs when key set, else Kokoro local)", "auto")
+    .option("--voice <id>", "Voice id (ElevenLabs name/id, or Kokoro id like af_heart, am_michael)")
     .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("--no-transcribe", "Skip Whisper word-level transcribe step (no transcript-<id>.json emitted)")
+    .option("--transcribe-language <code>", "BCP-47 language code passed to Whisper (e.g. en, ko)")
     .option("--force", "Overwrite an existing compositions/scene-<id>.html")
     .option("--dry-run", "Preview parameters without writing files or calling APIs")
     .action(async (name, options) => {
@@ -153,6 +158,13 @@ sceneCommand
         options.style = validatePreset(options.style);
     if (options.duration !== undefined)
         options.duration = validateDuration(options.duration);
+    let tts;
+    try {
+        tts = parseTtsProviderName(options.tts);
+    }
+    catch (error) {
+        exitWithError(usageError(error instanceof Error ? error.message : String(error)));
+    }
     if (options.dryRun) {
         const id = slugifySceneName(name);
         outputResult({
@@ -170,6 +182,7 @@ sceneCommand
                 project: options.project,
                 insertInto: options.insertInto,
                 imageProvider: options.imageProvider,
+                tts,
                 audio: options.audio, // commander sets `audio: false` when --no-audio is passed
                 image: options.image,
             },
@@ -182,6 +195,7 @@ sceneCommand
             name,
             preset: options.style,
             narration: options.narration,
+            narrationFile: options.narrationFile,
             duration: options.duration,
             visuals: options.visuals,
             headline: options.headline,
@@ -189,9 +203,12 @@ sceneCommand
             projectDir: options.project,
             insertInto: options.insertInto,
             imageProvider: options.imageProvider,
+            tts,
             voice: options.voice,
             skipAudio: options.audio === false,
             skipImage: options.image === false,
+            skipTranscribe: options.transcribe === false,
+            transcribeLanguage: options.transcribeLanguage,
             force: !!options.force,
             onProgress: (msg) => {
                 if (spinner)
@@ -218,6 +235,8 @@ sceneCommand
             console.log(chalk.green("  +"), result.audioPath);
         if (result.imagePath)
             console.log(chalk.green("  +"), result.imagePath);
+        if (result.transcriptPath)
+            console.log(chalk.green("  +"), result.transcriptPath);
         console.log(chalk.yellow("  ~"), result.rootPath, chalk.dim("(updated)"));
         console.log();
         console.log(chalk.bold.cyan("Composition"));
@@ -325,19 +344,53 @@ export async function executeSceneAdd(opts) {
     let audioRelPath;
     let audioAbsPath;
     let narrationDuration;
-    if (narrationText && !opts.skipAudio) {
-        const elevenlabsKey = await getApiKey("ELEVENLABS_API_KEY", "ElevenLabs");
-        if (!elevenlabsKey) {
-            return errResult("ElevenLabs API key required for --narration. Set ELEVENLABS_API_KEY, run 'vibe setup', or pass --no-audio.");
+    if (opts.narrationFile && !opts.skipAudio) {
+        // External wav/mp3: skip TTS, copy file into the project's assets/ dir.
+        const sourceAbs = resolve(opts.narrationFile);
+        if (!(await pathExists(sourceAbs))) {
+            return errResult(`Narration file not found: ${sourceAbs}`);
+        }
+        const ext = (sourceAbs.match(/\.([a-z0-9]+)$/i)?.[1] ?? "wav").toLowerCase();
+        if (ext !== "wav" && ext !== "mp3") {
+            return errResult(`Unsupported narration file extension: .${ext}. Use .wav or .mp3.`);
+        }
+        audioRelPath = `assets/narration-${id}.${ext}`;
+        audioAbsPath = resolve(projectDir, audioRelPath);
+        await mkdir(dirname(audioAbsPath), { recursive: true });
+        await copyFile(sourceAbs, audioAbsPath);
+        try {
+            narrationDuration = await getAudioDuration(audioAbsPath);
+        }
+        catch {
+            narrationDuration = undefined;
         }
-        opts.onProgress?.("Generating narration with ElevenLabs...");
-        const elevenlabs = new ElevenLabsProvider();
-        await elevenlabs.initialize({ apiKey: elevenlabsKey });
-        const tts = await elevenlabs.textToSpeech(narrationText, { voiceId: opts.voice });
+    }
+    else if (narrationText && !opts.skipAudio) {
+        let resolution;
+        try {
+            resolution = await resolveTtsProvider(opts.tts ?? "auto");
+        }
+        catch (error) {
+            if (error instanceof TtsKeyMissingError) {
+                return errResult(error.message);
+            }
+            throw error;
+        }
+        opts.onProgress?.(resolution.provider === "kokoro"
+            ? "Generating narration with Kokoro (local — first run downloads ~330MB)..."
+            : "Generating narration with ElevenLabs...");
+        const tts = await resolution.call(narrationText, {
+            voice: opts.voice,
+            onProgress: (event) => {
+                if (event.status === "progress" && typeof event.progress === "number") {
+                    opts.onProgress?.(`Kokoro model: ${event.file ?? ""} ${Math.round(event.progress)}%`);
+                }
+            },
+        });
         if (!tts.success || !tts.audioBuffer) {
-            return errResult(`ElevenLabs TTS failed: ${tts.error ?? "unknown error"}`);
+            return errResult(`${resolution.provider} TTS failed: ${tts.error ?? "unknown error"}`);
         }
-        audioRelPath = `assets/narration-${id}.mp3`;
+        audioRelPath = `assets/narration-${id}.${resolution.audioExtension}`;
         audioAbsPath = resolve(projectDir, audioRelPath);
         await mkdir(dirname(audioAbsPath), { recursive: true });
         await writeFile(audioAbsPath, tts.audioBuffer);
@@ -348,6 +401,47 @@ export async function executeSceneAdd(opts) {
             narrationDuration = undefined;
         }
     }
+    // -- Whisper word-level transcribe --------------------------------------
+    // Auto-runs whenever we have audio + an OpenAI key. The transcript JSON
+    // mirrors the Hyperframes shape so a future emitSceneHtml (C5) can drive
+    // GSAP word-sync from it. Failure is non-fatal — narration still plays,
+    // we just lose word-level animation timing.
+    let transcriptRelPath;
+    let transcriptWordCount;
+    let transcriptWords;
+    if (audioAbsPath && !opts.skipTranscribe) {
+        const whisperKey = await getApiKey("OPENAI_API_KEY", "OpenAI");
+        if (!whisperKey) {
+            opts.onProgress?.("Skipping transcribe (OPENAI_API_KEY not set — narration plays but word-sync unavailable)");
+        }
+        else {
+            opts.onProgress?.("Transcribing narration (Whisper word-level)...");
+            try {
+                const whisper = new WhisperProvider();
+                await whisper.initialize({ apiKey: whisperKey });
+                const audioBytes = await readFile(audioAbsPath);
+                const audioBlob = new Blob([new Uint8Array(audioBytes)]);
+                const transcript = await whisper.transcribe(audioBlob, undefined, {
+                    granularity: "word",
+                    language: opts.transcribeLanguage,
+                });
+                if (transcript.status === "completed" && transcript.words?.length) {
+                    transcriptRelPath = `assets/transcript-${id}.json`;
+                    const transcriptAbs = resolve(projectDir, transcriptRelPath);
+                    await writeFile(transcriptAbs, JSON.stringify(transcript.words, null, 2), "utf-8");
+                    transcriptWordCount = transcript.words.length;
+                    transcriptWords = transcript.words.map((w) => ({ text: w.text, start: w.start, end: w.end }));
+                }
+                else if (transcript.status === "failed") {
+                    opts.onProgress?.(`Transcribe failed: ${transcript.error ?? "unknown error"}`);
+                }
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                opts.onProgress?.(`Transcribe failed: ${msg}`);
+            }
+        }
+    }
     // -- Asset generation: backdrop image -----------------------------------
     let imageRelPath;
     let imageAbsPath;
@@ -424,6 +518,7 @@ export async function executeSceneAdd(opts) {
         kicker: opts.kicker,
         imagePath: imageRelPath,
         audioPath: audioRelPath,
+        transcript: transcriptWords,
     });
     await mkdir(dirname(scenePath), { recursive: true });
     await writeFile(scenePath, sceneHtml, "utf-8");
@@ -432,6 +527,7 @@ export async function executeSceneAdd(opts) {
     const start = nextSceneStart(rootHtmlBefore);
     const updated = insertClipIntoRoot(rootHtmlBefore, { id, start, duration });
     await writeFile(rootPath, updated, "utf-8");
+    const transcriptAbsPath = transcriptRelPath ? resolve(projectDir, transcriptRelPath) : undefined;
     return {
         success: true,
         id,
@@ -442,6 +538,8 @@ export async function executeSceneAdd(opts) {
         rootPath: relative(process.cwd(), rootPath) || rootPath,
         audioPath: audioAbsPath ? (relative(process.cwd(), audioAbsPath) || audioAbsPath) : undefined,
         imagePath: imageAbsPath ? (relative(process.cwd(), imageAbsPath) || imageAbsPath) : undefined,
+        transcriptPath: transcriptAbsPath ? (relative(process.cwd(), transcriptAbsPath) || transcriptAbsPath) : undefined,
+        transcriptWordCount,
     };
 }
 // ---------------------------------------------------------------------------