@scenar/cli 0.0.2

package/src/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/commands/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAMrE,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACtD,OAAO;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,yDAAyD,CAAC;SACtE,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;SAChD,MAAM,CAAC,QAAQ,EAAE,kCAAkC,CAAC;SACpD,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,OAAwB,EAAE,EAAE;QACvD,MAAM,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACP,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,OAAwB;IAExB,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE1C,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM,CAAC,KAAK;YAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACxC,OAAO;IACT,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,IAAI,IAAI,CAAC,CAAC;QACtE,OAAO;IACT,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,MAAM,CAAC,MAAM,CAAC,MAAM,cAAc,IAAI,MAAM,CAAC,CAAC;IACpG,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/src/commands/validate.ts

@@ -0,0 +1,44 @@
+import { Command } from "commander";
+import { loadScenarioYaml } from "../util/load-yaml.js";
+import { validateScenario } from "../validate/scenario-validator.js";
+
+interface ValidateOptions {
+  json?: boolean;
+}
+
+export function registerValidateCommand(program: Command): void {
+  program
+    .command("validate")
+    .description("Validate a scenario YAML file against the proto schema.")
+    .argument("<file>", "path to scenario YAML file")
+    .option("--json", "output validation result as JSON")
+    .action(async (file: string, options: ValidateOptions) => {
+      await runValidate(file, options);
+    });
+}
+
+export async function runValidate(
+  file: string,
+  options: ValidateOptions,
+): Promise<void> {
+  const scenario = await loadScenarioYaml(file);
+  const result = validateScenario(scenario);
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    if (!result.valid) process.exitCode = 1;
+    return;
+  }
+
+  if (result.valid) {
+    process.stdout.write(`\x1b[32m✓\x1b[0m Scenario is valid: ${file}\n`);
+    return;
+  }
+
+  process.stderr.write(`\x1b[31m✗\x1b[0m Scenario has ${result.errors.length} error(s): ${file}\n\n`);
+  for (const error of result.errors) {
+    process.stderr.write(`  \x1b[31m•\x1b[0m ${error.path}: ${error.reason}\n`);
+  }
+  process.stderr.write("\n");
+  process.exitCode = 1;
+}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+export declare function createProgram(): Command;
+export declare function run(argv: string[]): void;
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,aAAa,IAAI,OAAO,CAYvC;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAGxC"}

package/src/index.js

@@ -0,0 +1,18 @@
+import { Command } from "commander";
+import { registerValidateCommand } from "./commands/validate.js";
+import { registerNarrateCommand } from "./commands/narrate.js";
+export function createProgram() {
+    const program = new Command();
+    program
+        .name("scenar")
+        .description("Scenar CLI — validate scenario YAML and generate narration audio.")
+        .version("0.0.1");
+    registerValidateCommand(program);
+    registerNarrateCommand(program);
+    return program;
+}
+export function run(argv) {
+    const program = createProgram();
+    program.parse(argv);
+}
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,QAAQ,CAAC;SACd,WAAW,CAAC,mEAAmE,CAAC;SAChF,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAEhC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,IAAc;IAChC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC"}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { Command } from "commander";
+import { registerValidateCommand } from "./commands/validate.js";
+import { registerNarrateCommand } from "./commands/narrate.js";
+
+export function createProgram(): Command {
+  const program = new Command();
+
+  program
+    .name("scenar")
+    .description("Scenar CLI — validate scenario YAML and generate narration audio.")
+    .version("0.0.1");
+
+  registerValidateCommand(program);
+  registerNarrateCommand(program);
+
+  return program;
+}
+
+export function run(argv: string[]): void {
+  const program = createProgram();
+  program.parse(argv);
+}

package/src/tts/echogarden.d.ts

@@ -0,0 +1,18 @@
+import type { TtsProvider } from "./types.js";
+/**
+ * Checks whether the `echogarden` package is available at runtime.
+ * Returns `true` if it can be imported, `false` otherwise.
+ */
+export declare function isEchogardenAvailable(): Promise<boolean>;
+/**
+ * TTS provider backed by Echogarden — a TypeScript-native, offline
+ * speech toolkit. Requires no API keys or network access.
+ *
+ * Echogarden is an **optional peer dependency** (GPL v3 licensed).
+ * Users must install it explicitly: `pnpm add echogarden`.
+ *
+ * Uses dynamic import to avoid compile-time type coupling to the
+ * optional dependency.
+ */
+export declare function createEchogardenProvider(): TtsProvider;
+//# sourceMappingURL=echogarden.d.ts.map

package/src/tts/echogarden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echogarden.d.ts","sourceRoot":"","sources":["../../../src/tts/echogarden.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAyB,MAAM,YAAY,CAAC;AAErE;;;GAGG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,IAAI,WAAW,CAmCtD"}

package/src/tts/echogarden.js

@@ -0,0 +1,54 @@
+/**
+ * Checks whether the `echogarden` package is available at runtime.
+ * Returns `true` if it can be imported, `false` otherwise.
+ */
+export async function isEchogardenAvailable() {
+    try {
+        await import("echogarden");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * TTS provider backed by Echogarden — a TypeScript-native, offline
+ * speech toolkit. Requires no API keys or network access.
+ *
+ * Echogarden is an **optional peer dependency** (GPL v3 licensed).
+ * Users must install it explicitly: `pnpm add echogarden`.
+ *
+ * Uses dynamic import to avoid compile-time type coupling to the
+ * optional dependency.
+ */
+export function createEchogardenProvider() {
+    return {
+        name: "echogarden",
+        async synthesize(text, options) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let echogarden;
+            try {
+                echogarden = await import("echogarden");
+            }
+            catch {
+                throw new Error("Echogarden is not installed. Install it with:\n\n" +
+                    "  pnpm add echogarden\n\n" +
+                    "Or use a different TTS provider: --tts edge-tts, --tts openai");
+            }
+            const result = await echogarden.synthesize(text, {
+                engine: "vits",
+                voice: options.voice,
+            });
+            const rawAudio = result.audio;
+            const sampleRate = rawAudio.sampleRate ?? 22050;
+            const samples = rawAudio.audioChannels?.[0]?.length ?? 0;
+            const durationMs = Math.round((samples / sampleRate) * 1000);
+            const mp3Bytes = await echogarden.encodeRawAudioToMp3(rawAudio);
+            return {
+                audio: Buffer.from(mp3Bytes),
+                durationMs,
+            };
+        },
+    };
+}
+//# sourceMappingURL=echogarden.js.map

package/src/tts/echogarden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"echogarden.js","sourceRoot":"","sources":["../../../src/tts/echogarden.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO;QACL,IAAI,EAAE,YAAY;QAElB,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,OAAmB;YAChD,8DAA8D;YAC9D,IAAI,UAAe,CAAC;YACpB,IAAI,CAAC;gBACH,UAAU,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CACb,mDAAmD;oBACnD,2BAA2B;oBAC3B,+DAA+D,CAChE,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,IAAI,EAAE;gBAC/C,MAAM,EAAE,MAAM;gBACd,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC,CAAC;YAEH,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC;YAC9B,MAAM,UAAU,GAAW,QAAQ,CAAC,UAAU,IAAI,KAAK,CAAC;YACxD,MAAM,OAAO,GAAW,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;YACjE,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;YAE7D,MAAM,QAAQ,GAAe,MAAM,UAAU,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YAE5E,OAAO;gBACL,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAC5B,UAAU;aACX,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/src/tts/echogarden.ts

@@ -0,0 +1,61 @@
+import type { TtsProvider, TtsOptions, TtsResult } from "./types.js";
+
+/**
+ * Checks whether the `echogarden` package is available at runtime.
+ * Returns `true` if it can be imported, `false` otherwise.
+ */
+export async function isEchogardenAvailable(): Promise<boolean> {
+  try {
+    await import("echogarden");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * TTS provider backed by Echogarden — a TypeScript-native, offline
+ * speech toolkit. Requires no API keys or network access.
+ *
+ * Echogarden is an **optional peer dependency** (GPL v3 licensed).
+ * Users must install it explicitly: `pnpm add echogarden`.
+ *
+ * Uses dynamic import to avoid compile-time type coupling to the
+ * optional dependency.
+ */
+export function createEchogardenProvider(): TtsProvider {
+  return {
+    name: "echogarden",
+
+    async synthesize(text: string, options: TtsOptions): Promise<TtsResult> {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let echogarden: any;
+      try {
+        echogarden = await import("echogarden");
+      } catch {
+        throw new Error(
+          "Echogarden is not installed. Install it with:\n\n" +
+          "  pnpm add echogarden\n\n" +
+          "Or use a different TTS provider: --tts edge-tts, --tts openai",
+        );
+      }
+
+      const result = await echogarden.synthesize(text, {
+        engine: "vits",
+        voice: options.voice,
+      });
+
+      const rawAudio = result.audio;
+      const sampleRate: number = rawAudio.sampleRate ?? 22050;
+      const samples: number = rawAudio.audioChannels?.[0]?.length ?? 0;
+      const durationMs = Math.round((samples / sampleRate) * 1000);
+
+      const mp3Bytes: Uint8Array = await echogarden.encodeRawAudioToMp3(rawAudio);
+
+      return {
+        audio: Buffer.from(mp3Bytes),
+        durationMs,
+      };
+    },
+  };
+}

package/src/tts/edge-tts.d.ts

@@ -0,0 +1,19 @@
+import type { TtsProvider } from "./types.js";
+/**
+ * Checks whether the `edge-tts-universal` package is available at runtime.
+ * Returns `true` if it can be imported, `false` otherwise.
+ */
+export declare function isEdgeTtsAvailable(): Promise<boolean>;
+/**
+ * TTS provider backed by Microsoft Edge TTS via `edge-tts-universal`.
+ * Free, requires no API keys, but needs network access.
+ *
+ * `edge-tts-universal` is an **optional peer dependency** (AGPL-3.0 licensed).
+ * Users must install it explicitly: `pnpm add edge-tts-universal`.
+ *
+ * Duration is extracted from word-boundary subtitle metadata returned by
+ * the service. Falls back to a bitrate-based estimate when metadata is
+ * unavailable — same approach proven in Stigmer's narration pipeline.
+ */
+export declare function createEdgeTtsProvider(): TtsProvider;
+//# sourceMappingURL=edge-tts.d.ts.map

package/src/tts/edge-tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-tts.d.ts","sourceRoot":"","sources":["../../../src/tts/edge-tts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAyB,MAAM,YAAY,CAAC;AAUrE;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,WAAW,CAsCnD"}

package/src/tts/edge-tts.js

@@ -0,0 +1,63 @@
+const DEFAULT_VOICE = "en-US-AndrewMultilingualNeural";
+/**
+ * Edge TTS outputs mono MP3 at 48 kbps. Used as a fallback when
+ * subtitle metadata is unavailable for precise duration.
+ */
+const EDGE_TTS_BITRATE_KBPS = 48;
+/**
+ * Checks whether the `edge-tts-universal` package is available at runtime.
+ * Returns `true` if it can be imported, `false` otherwise.
+ */
+export async function isEdgeTtsAvailable() {
+    try {
+        await import("edge-tts-universal");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * TTS provider backed by Microsoft Edge TTS via `edge-tts-universal`.
+ * Free, requires no API keys, but needs network access.
+ *
+ * `edge-tts-universal` is an **optional peer dependency** (AGPL-3.0 licensed).
+ * Users must install it explicitly: `pnpm add edge-tts-universal`.
+ *
+ * Duration is extracted from word-boundary subtitle metadata returned by
+ * the service. Falls back to a bitrate-based estimate when metadata is
+ * unavailable — same approach proven in Stigmer's narration pipeline.
+ */
+export function createEdgeTtsProvider() {
+    return {
+        name: "edge-tts",
+        async synthesize(text, options) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let EdgeTTS;
+            try {
+                const mod = await import("edge-tts-universal");
+                EdgeTTS = mod.EdgeTTS;
+            }
+            catch {
+                throw new Error("edge-tts-universal is not installed. Install it with:\n\n" +
+                    "  pnpm add edge-tts-universal\n\n" +
+                    "Or use a different TTS provider: --tts echogarden, --tts openai");
+            }
+            const voice = options.voice ?? DEFAULT_VOICE;
+            const tts = new EdgeTTS(text, voice);
+            const result = await tts.synthesize();
+            const audioBuffer = Buffer.from(await result.audio.arrayBuffer());
+            let durationMs = 0;
+            if (result.subtitle.length > 0) {
+                const last = result.subtitle[result.subtitle.length - 1];
+                // offset and duration are in 100-nanosecond units
+                durationMs = Math.ceil((last.offset + last.duration) / 10_000);
+            }
+            if (durationMs === 0 && audioBuffer.length > 0) {
+                durationMs = Math.ceil((audioBuffer.length * 8) / EDGE_TTS_BITRATE_KBPS);
+            }
+            return { audio: audioBuffer, durationMs };
+        },
+    };
+}
+//# sourceMappingURL=edge-tts.js.map

package/src/tts/edge-tts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-tts.js","sourceRoot":"","sources":["../../../src/tts/edge-tts.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAAG,gCAAgC,CAAC;AAEvD;;;GAGG;AACH,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,IAAI,EAAE,UAAU;QAEhB,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,OAAmB;YAChD,8DAA8D;YAC9D,IAAI,OAAY,CAAC;YACjB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;gBAC/C,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CACb,2DAA2D;oBACzD,mCAAmC;oBACnC,iEAAiE,CACpE,CAAC;YACJ,CAAC;YAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC;YAC7C,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,UAAU,EAAE,CAAC;YAEtC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;YAElE,IAAI,UAAU,GAAG,CAAC,CAAC;YACnB,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBACzD,kDAAkD;gBAClD,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC;YACjE,CAAC;YAED,IAAI,UAAU,KAAK,CAAC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC/C,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC;YAC3E,CAAC;YAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/src/tts/edge-tts.ts

@@ -0,0 +1,73 @@
+import type { TtsProvider, TtsOptions, TtsResult } from "./types.js";
+
+const DEFAULT_VOICE = "en-US-AndrewMultilingualNeural";
+
+/**
+ * Edge TTS outputs mono MP3 at 48 kbps. Used as a fallback when
+ * subtitle metadata is unavailable for precise duration.
+ */
+const EDGE_TTS_BITRATE_KBPS = 48;
+
+/**
+ * Checks whether the `edge-tts-universal` package is available at runtime.
+ * Returns `true` if it can be imported, `false` otherwise.
+ */
+export async function isEdgeTtsAvailable(): Promise<boolean> {
+  try {
+    await import("edge-tts-universal");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * TTS provider backed by Microsoft Edge TTS via `edge-tts-universal`.
+ * Free, requires no API keys, but needs network access.
+ *
+ * `edge-tts-universal` is an **optional peer dependency** (AGPL-3.0 licensed).
+ * Users must install it explicitly: `pnpm add edge-tts-universal`.
+ *
+ * Duration is extracted from word-boundary subtitle metadata returned by
+ * the service. Falls back to a bitrate-based estimate when metadata is
+ * unavailable — same approach proven in Stigmer's narration pipeline.
+ */
+export function createEdgeTtsProvider(): TtsProvider {
+  return {
+    name: "edge-tts",
+
+    async synthesize(text: string, options: TtsOptions): Promise<TtsResult> {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let EdgeTTS: any;
+      try {
+        const mod = await import("edge-tts-universal");
+        EdgeTTS = mod.EdgeTTS;
+      } catch {
+        throw new Error(
+          "edge-tts-universal is not installed. Install it with:\n\n" +
+            "  pnpm add edge-tts-universal\n\n" +
+            "Or use a different TTS provider: --tts echogarden, --tts openai",
+        );
+      }
+
+      const voice = options.voice ?? DEFAULT_VOICE;
+      const tts = new EdgeTTS(text, voice);
+      const result = await tts.synthesize();
+
+      const audioBuffer = Buffer.from(await result.audio.arrayBuffer());
+
+      let durationMs = 0;
+      if (result.subtitle.length > 0) {
+        const last = result.subtitle[result.subtitle.length - 1];
+        // offset and duration are in 100-nanosecond units
+        durationMs = Math.ceil((last.offset + last.duration) / 10_000);
+      }
+
+      if (durationMs === 0 && audioBuffer.length > 0) {
+        durationMs = Math.ceil((audioBuffer.length * 8) / EDGE_TTS_BITRATE_KBPS);
+      }
+
+      return { audio: audioBuffer, durationMs };
+    },
+  };
+}

package/src/tts/openai.d.ts

@@ -0,0 +1,7 @@
+import type { TtsProvider } from "./types.js";
+/**
+ * TTS provider backed by OpenAI's text-to-speech API.
+ * Requires the `OPENAI_API_KEY` environment variable.
+ */
+export declare function createOpenAIProvider(): TtsProvider;
+//# sourceMappingURL=openai.d.ts.map

package/src/tts/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/tts/openai.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAyB,MAAM,YAAY,CAAC;AAMrE;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,CA8ClD"}

package/src/tts/openai.js

@@ -0,0 +1,54 @@
+const OPENAI_TTS_URL = "https://api.openai.com/v1/audio/speech";
+const DEFAULT_MODEL = "tts-1";
+const DEFAULT_VOICE = "alloy";
+/**
+ * TTS provider backed by OpenAI's text-to-speech API.
+ * Requires the `OPENAI_API_KEY` environment variable.
+ */
+export function createOpenAIProvider() {
+    return {
+        name: "openai",
+        async synthesize(text, options) {
+            const apiKey = process.env["OPENAI_API_KEY"];
+            if (!apiKey) {
+                throw new Error("OPENAI_API_KEY environment variable is not set.\n\n" +
+                    "Set it before running narrate:\n" +
+                    "  export OPENAI_API_KEY=sk-...\n\n" +
+                    "Or use a different TTS provider: --tts echogarden");
+            }
+            const voice = options.voice ?? DEFAULT_VOICE;
+            const response = await fetch(OPENAI_TTS_URL, {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: DEFAULT_MODEL,
+                    input: text,
+                    voice,
+                    response_format: "mp3",
+                }),
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                throw new Error(`OpenAI TTS API error (${response.status}): ${body}`);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            const audio = Buffer.from(arrayBuffer);
+            const durationMs = estimateMp3DurationMs(audio);
+            return { audio, durationMs };
+        },
+    };
+}
+/**
+ * Rough MP3 duration estimate from file size and assumed bitrate.
+ * OpenAI tts-1 defaults to ~64 kbps MP3 output. This is a fallback
+ * when precise duration parsing isn't available.
+ */
+function estimateMp3DurationMs(mp3) {
+    const ASSUMED_BITRATE_KBPS = 64;
+    const bytes = mp3.byteLength;
+    return Math.round((bytes * 8) / ASSUMED_BITRATE_KBPS);
+}
+//# sourceMappingURL=openai.js.map

package/src/tts/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../../src/tts/openai.ts"],"names":[],"mappings":"AAEA,MAAM,cAAc,GAAG,wCAAwC,CAAC;AAChE,MAAM,aAAa,GAAG,OAAO,CAAC;AAC9B,MAAM,aAAa,GAAG,OAAO,CAAC;AAE9B;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,IAAI,EAAE,QAAQ;QAEd,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,OAAmB;YAChD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CACb,qDAAqD;oBACrD,kCAAkC;oBAClC,oCAAoC;oBACpC,mDAAmD,CACpD,CAAC;YACJ,CAAC;YAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC;YAE7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,cAAc,EAAE;gBAC3C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,eAAe,EAAE,UAAU,MAAM,EAAE;oBACnC,cAAc,EAAE,kBAAkB;iBACnC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,KAAK,EAAE,aAAa;oBACpB,KAAK,EAAE,IAAI;oBACX,KAAK;oBACL,eAAe,EAAE,KAAK;iBACvB,CAAC;aACH,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACb,yBAAyB,QAAQ,CAAC,MAAM,MAAM,IAAI,EAAE,CACrD,CAAC;YACJ,CAAC;YAED,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC;YACjD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAEvC,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;YAEhD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAC/B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,GAAW;IACxC,MAAM,oBAAoB,GAAG,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;IAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC;AACxD,CAAC"}

package/src/tts/openai.ts

@@ -0,0 +1,68 @@
+import type { TtsProvider, TtsOptions, TtsResult } from "./types.js";
+
+const OPENAI_TTS_URL = "https://api.openai.com/v1/audio/speech";
+const DEFAULT_MODEL = "tts-1";
+const DEFAULT_VOICE = "alloy";
+
+/**
+ * TTS provider backed by OpenAI's text-to-speech API.
+ * Requires the `OPENAI_API_KEY` environment variable.
+ */
+export function createOpenAIProvider(): TtsProvider {
+  return {
+    name: "openai",
+
+    async synthesize(text: string, options: TtsOptions): Promise<TtsResult> {
+      const apiKey = process.env["OPENAI_API_KEY"];
+      if (!apiKey) {
+        throw new Error(
+          "OPENAI_API_KEY environment variable is not set.\n\n" +
+          "Set it before running narrate:\n" +
+          "  export OPENAI_API_KEY=sk-...\n\n" +
+          "Or use a different TTS provider: --tts echogarden",
+        );
+      }
+
+      const voice = options.voice ?? DEFAULT_VOICE;
+
+      const response = await fetch(OPENAI_TTS_URL, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model: DEFAULT_MODEL,
+          input: text,
+          voice,
+          response_format: "mp3",
+        }),
+      });
+
+      if (!response.ok) {
+        const body = await response.text();
+        throw new Error(
+          `OpenAI TTS API error (${response.status}): ${body}`,
+        );
+      }
+
+      const arrayBuffer = await response.arrayBuffer();
+      const audio = Buffer.from(arrayBuffer);
+
+      const durationMs = estimateMp3DurationMs(audio);
+
+      return { audio, durationMs };
+    },
+  };
+}
+
+/**
+ * Rough MP3 duration estimate from file size and assumed bitrate.
+ * OpenAI tts-1 defaults to ~64 kbps MP3 output. This is a fallback
+ * when precise duration parsing isn't available.
+ */
+function estimateMp3DurationMs(mp3: Buffer): number {
+  const ASSUMED_BITRATE_KBPS = 64;
+  const bytes = mp3.byteLength;
+  return Math.round((bytes * 8) / ASSUMED_BITRATE_KBPS);
+}

package/src/tts/resolve-provider.d.ts

@@ -0,0 +1,11 @@
+import type { TtsProvider } from "./types.js";
+export type TtsProviderName = "echogarden" | "edge-tts" | "openai";
+/**
+ * Resolve a TTS provider by name.
+ *
+ * When `providerName` is `"echogarden"` (the default), verifies
+ * the optional peer dependency is installed before returning it.
+ * Falls back to a clear error message guiding the user.
+ */
+export declare function resolveProvider(providerName: string): Promise<TtsProvider>;
+//# sourceMappingURL=resolve-provider.d.ts.map

package/src/tts/resolve-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-provider.d.ts","sourceRoot":"","sources":["../../../src/tts/resolve-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,CAAC;AAQnE;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAwChF"}

package/src/tts/resolve-provider.js

@@ -0,0 +1,47 @@
+import { createEchogardenProvider, isEchogardenAvailable } from "./echogarden.js";
+import { createEdgeTtsProvider, isEdgeTtsAvailable } from "./edge-tts.js";
+import { createOpenAIProvider } from "./openai.js";
+const KNOWN_PROVIDERS = new Set([
+    "echogarden",
+    "edge-tts",
+    "openai",
+]);
+/**
+ * Resolve a TTS provider by name.
+ *
+ * When `providerName` is `"echogarden"` (the default), verifies
+ * the optional peer dependency is installed before returning it.
+ * Falls back to a clear error message guiding the user.
+ */
+export async function resolveProvider(providerName) {
+    if (!KNOWN_PROVIDERS.has(providerName)) {
+        throw new Error(`Unknown TTS provider: "${providerName}". ` +
+            `Supported providers: ${[...KNOWN_PROVIDERS].join(", ")}.`);
+    }
+    if (providerName === "openai") {
+        return createOpenAIProvider();
+    }
+    if (providerName === "edge-tts") {
+        const available = await isEdgeTtsAvailable();
+        if (!available) {
+            throw new Error("edge-tts-universal is not installed. To use free online TTS:\n\n" +
+                "  pnpm add edge-tts-universal\n\n" +
+                "Or use a different provider:\n\n" +
+                "  scenar narrate <file> --tts echogarden   (offline, pnpm add echogarden)\n" +
+                "  scenar narrate <file> --tts openai        (requires OPENAI_API_KEY)");
+        }
+        return createEdgeTtsProvider();
+    }
+    const available = await isEchogardenAvailable();
+    if (!available) {
+        throw new Error("Echogarden is not installed. To use free offline TTS:\n\n" +
+            "  pnpm add echogarden\n\n" +
+            "Or use free online TTS (requires network):\n\n" +
+            "  scenar narrate <file> --tts edge-tts\n" +
+            "  pnpm add edge-tts-universal\n\n" +
+            "Or use OpenAI TTS (requires API key):\n\n" +
+            "  scenar narrate <file> --tts openai");
+    }
+    return createEchogardenProvider();
+}
+//# sourceMappingURL=resolve-provider.js.map

package/src/tts/resolve-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-provider.js","sourceRoot":"","sources":["../../../src/tts/resolve-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAInD,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAkB;IACpE,YAAY;IACZ,UAAU;IACV,QAAQ;CACT,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,YAAoB;IACxD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,0BAA0B,YAAY,KAAK;YAC3C,wBAAwB,CAAC,GAAG,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC3D,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,oBAAoB,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,YAAY,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,SAAS,GAAG,MAAM,kBAAkB,EAAE,CAAC;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,kEAAkE;gBAClE,mCAAmC;gBACnC,kCAAkC;gBAClC,6EAA6E;gBAC7E,uEAAuE,CACxE,CAAC;QACJ,CAAC;QACD,OAAO,qBAAqB,EAAE,CAAC;IACjC,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,qBAAqB,EAAE,CAAC;IAChD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,2DAA2D;YAC3D,2BAA2B;YAC3B,gDAAgD;YAChD,0CAA0C;YAC1C,mCAAmC;YACnC,2CAA2C;YAC3C,sCAAsC,CACvC,CAAC;IACJ,CAAC;IAED,OAAO,wBAAwB,EAAE,CAAC;AACpC,CAAC"}