@tandryukha/aidemo 0.8.0

package/src/util.ts

@@ -0,0 +1,171 @@
+import { promises as fs, createWriteStream, type WriteStream } from "node:fs";
+import { dirname } from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// Optional native log tee: when a command sets a log file, everything emitted
+// through log/step/ok/fail is mirrored (ANSI-stripped) into logs/<cmd>.log as
+// well as stderr. This makes `aidemo record` self-log without a fragile
+// `| tee record.log` (which also masks the exit code — see the CLI docs).
+let logStream: WriteStream | null = null;
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/** Mirror all subsequent log output into `path` (truncating it). Best-effort. */
+export function setLogFile(path: string): void {
+  try {
+    logStream = createWriteStream(path, { flags: "w" });
+    logStream.on("error", () => (logStream = null));
+  } catch {
+    logStream = null;
+  }
+}
+
+/** Flush and close the log file, if any. Await before process.exit(). */
+export async function closeLogFile(): Promise<void> {
+  const s = logStream;
+  logStream = null;
+  if (!s) return;
+  await new Promise<void>((res) => s.end(res));
+}
+
+/** A per-job log sink receiving every ANSI-stripped emitted chunk. */
+export type LogSink = (clean: string) => void;
+const logSinks = new AsyncLocalStorage<LogSink[]>();
+
+/**
+ * Run `fn` with additional log sinks that receive everything emitted through
+ * log/step/ok/fail — scoped to fn's async chain, so concurrent runs (MCP jobs
+ * vs. sync tool calls) don't interleave each other's log files. The CLI's
+ * setLogFile singleton is unaffected. Composes with any sinks already active
+ * (additive, not a replace) so a stage nested inside a composite command
+ * (e.g. the `render` job's voice/record/captions/compose sub-stages) still
+ * feeds the outer command's log/ring buffer while ALSO getting its own sink.
+ * Known blind spot: a line emitted from a detached event-loop callback (not
+ * awaited inside fn) misses the sinks and goes to stderr only.
+ */
+export function withLogSinks<T>(sinks: LogSink[], fn: () => Promise<T>): Promise<T> {
+  const outer = logSinks.getStore();
+  return logSinks.run(outer ? [...outer, ...sinks] : sinks, fn);
+}
+
+/**
+ * Tee subsequent log/step/ok/fail output into a freshly truncated file at
+ * `path`, composed with whatever log sinks (or the CLI's global log file) are
+ * already active. Used so a stage driven from inside a composite command —
+ * CLI `render`; the MCP `render` job — still refreshes its OWN stable
+ * logs/<stage>.log, not just the composite command's log. Fixes stale
+ * `logs/<command>.log` lines fooling log-watchers into probing half-written
+ * output (a poller sees an old `✓ final video → …` line from a previous
+ * standalone `compose` run while the current `render` is still composing).
+ */
+export async function teeStageLog<T>(path: string, fn: () => Promise<T>): Promise<T> {
+  const stream = createWriteStream(path, { flags: "w" });
+  stream.on("error", () => {});
+  try {
+    return await withLogSinks([(s) => void stream.write(s)], fn);
+  } finally {
+    await new Promise<void>((res) => stream.end(res));
+  }
+}
+
+/**
+ * Per-scene progress hooks, shared by every stage that loops over scenes
+ * (voice, captions, compose, and record's own RecordOptions) — the MCP job
+ * model wires these into job.currentScene/scenesTotal/scenesDone so pollers
+ * get structured progress instead of only a log tail.
+ */
+export interface SceneProgress {
+  onSceneStart?: (sceneId: string, index: number, total: number) => void;
+  onSceneComplete?: (sceneId: string, index: number, total: number) => void;
+}
+
+/** Thrown when a run is canceled via an AbortSignal (e.g. MCP job_cancel). */
+export class CanceledError extends Error {
+  constructor(msg = "canceled") {
+    super(msg);
+    this.name = "CanceledError";
+  }
+}
+
+function emit(s: string): void {
+  process.stderr.write(s);
+  const clean = s.replace(ANSI_RE, "");
+  logStream?.write(clean);
+  const extra = logSinks.getStore();
+  if (extra) {
+    for (const sink of extra) {
+      try {
+        sink(clean);
+      } catch {
+        // a broken sink must never break a pipeline stage
+      }
+    }
+  }
+}
+
+export function log(msg: string): void {
+  emit(`  ${msg}\n`);
+}
+
+export function step(msg: string): void {
+  emit(`\n▶ ${msg}\n`);
+}
+
+export function ok(msg: string): void {
+  emit(`  ✓ ${msg}\n`);
+}
+
+/** Emit a failure line (also captured in the log file). */
+export function fail(msg: string): void {
+  emit(`\n✗ ${msg}\n`);
+}
+
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((r) => setTimeout(r, ms));
+
+/** easeInOutCubic — smooth acceleration/deceleration for cursor motion. */
+export function easeInOutCubic(t: number): number {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+
+/** easeOutCubic — fast start, soft landing (the "snappy" scroll feel). */
+export function easeOutCubic(t: number): number {
+  return 1 - Math.pow(1 - t, 3);
+}
+
+/** easeInOutSine — gentle drift for long cinematic scrolls. */
+export function easeInOutSine(t: number): number {
+  return -(Math.cos(Math.PI * t) - 1) / 2;
+}
+
+export async function ensureDir(path: string): Promise<void> {
+  await fs.mkdir(path, { recursive: true });
+}
+
+export async function writeJson(path: string, data: unknown): Promise<void> {
+  await ensureDir(dirname(path));
+  await fs.writeFile(path, JSON.stringify(data, null, 2) + "\n");
+}
+
+export async function readJson<T = unknown>(path: string): Promise<T> {
+  return JSON.parse(await fs.readFile(path, "utf8")) as T;
+}
+
+export async function exists(path: string): Promise<boolean> {
+  try {
+    await fs.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Format milliseconds as an SRT timestamp: HH:MM:SS,mmm */
+export function srtTime(ms: number): string {
+  const clamped = Math.max(0, ms);
+  const h = Math.floor(clamped / 3_600_000);
+  const m = Math.floor((clamped % 3_600_000) / 60_000);
+  const s = Math.floor((clamped % 60_000) / 1000);
+  const millis = Math.floor(clamped % 1000);
+  const pad = (n: number, w = 2) => String(n).padStart(w, "0");
+  return `${pad(h)}:${pad(m)}:${pad(s)},${pad(millis, 3)}`;
+}

package/src/variants.ts

@@ -0,0 +1,117 @@
+import { resolve } from "node:path";
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { Project } from "./project.js";
+import { generateVoice } from "./voice.js";
+import { record, type RecordOptions } from "./recorder.js";
+import { generateCaptions, generateCaptionsOffline } from "./captions.js";
+import { compose } from "./compose.js";
+import { captionsAutoOffline } from "./config.js";
+import { readJson, log, ok, step } from "./util.js";
+
+/**
+ * Personalized demo variants — one storyboard, N per-prospect/segment renders.
+ *
+ * `aidemo render <dir> --variants variants.json` where variants.json is:
+ *   [ { "name": "acme", "params": { "customer": "Acme" } }, ... ]
+ *
+ * Each variant renders as an ISOLATED project under
+ * <dir>/output/variants/<name>/ — it seeds its own copy of the storyboard and
+ * runs the full pipeline (voice → record → captions → compose) with its params,
+ * so a param that changes narration/urls/typed text produces a genuinely
+ * different take. Sequential and simple; voice hashing dedupes unchanged scenes
+ * within a variant.
+ */
+
+const VariantSchema = z.object({
+  name: z
+    .string()
+    .regex(
+      /^[A-Za-z0-9._-]+$/,
+      "variant name must be a filesystem-safe dir name (A-Z a-z 0-9 . _ -)"
+    ),
+  params: z.record(z.string(), z.string()).default({}),
+});
+export type Variant = z.infer<typeof VariantSchema>;
+
+const VariantsFileSchema = z.array(VariantSchema).min(1);
+
+/** Read + validate a variants matrix file. */
+export async function loadVariants(path: string): Promise<Variant[]> {
+  const abs = resolve(path);
+  const raw = await readJson<unknown>(abs);
+  const parsed = VariantsFileSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(
+      `Invalid variants file ${abs}:\n${parsed.error.issues
+        .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
+        .join("\n")}\nExpected: [{ "name": "acme", "params": { "k": "v" } }, ...]`
+    );
+  }
+  const seen = new Set<string>();
+  for (const v of parsed.data) {
+    if (seen.has(v.name)) {
+      throw new Error(`duplicate variant name "${v.name}" in ${abs}`);
+    }
+    seen.add(v.name);
+  }
+  return parsed.data;
+}
+
+export interface RenderVariantsOptions {
+  /** Chrome record options shared by every variant. */
+  record?: Pick<RecordOptions, "profileDir" | "headed" | "capture">;
+  /** Re-synthesize narration even if unchanged. */
+  forceVoice?: boolean;
+}
+
+export interface VariantResult {
+  name: string;
+  dir: string;
+  output: string;
+  params: Record<string, string>;
+}
+
+/**
+ * Render every variant. NOTE: a variant renders relative to its own isolated
+ * dir, so storyboards that reference LOCAL asset paths (e.g. a music `track`)
+ * should use absolute paths — relative ones resolve against the variant dir.
+ */
+export async function renderVariants(
+  parentDir: string,
+  variants: Variant[],
+  opts: RenderVariantsOptions = {}
+): Promise<VariantResult[]> {
+  const parent = new Project(parentDir);
+  const storyboardRaw = await fs.readFile(parent.storyboardPath, "utf8");
+
+  const results: VariantResult[] = [];
+  for (const [i, v] of variants.entries()) {
+    step(`Variant ${i + 1}/${variants.length}: "${v.name}"`);
+    const variantDir = parent.p("output", "variants", v.name);
+    const project = new Project(variantDir);
+    await project.ensureDirs();
+    // Seed the storyboard so the variant is a fully self-contained project.
+    await fs.writeFile(project.storyboardPath, storyboardRaw);
+
+    // Explicit variant params win (and are typo-guarded) + get persisted.
+    const storyboard = await project.loadStoryboard({ params: v.params });
+    await generateVoice(project, storyboard, { force: opts.forceVoice });
+    await record(project, storyboard, { ...(opts.record ?? {}) });
+    if (captionsAutoOffline()) {
+      log("local TTS and no STT endpoint/key — deriving captions offline");
+      await generateCaptionsOffline(project, storyboard);
+    } else {
+      await generateCaptions(project, storyboard);
+    }
+    await compose(project, storyboard);
+    ok(`variant "${v.name}" → ${project.outputPath}`);
+    results.push({
+      name: v.name,
+      dir: variantDir,
+      output: project.outputPath,
+      params: v.params,
+    });
+  }
+  return results;
+}

package/src/voice-local.ts

@@ -0,0 +1,230 @@
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import type { VoicePlan } from "./types.js";
+import type { VoiceProvider } from "./voice.js";
+import {
+  KOKORO_MODEL_ID,
+  KOKORO_VOICE,
+  kokoroDtype,
+  ttsModelCacheDir,
+} from "./config.js";
+import { runFfmpeg } from "./ffmpeg.js";
+import { exists, log } from "./util.js";
+
+/**
+ * In-process TTS: Kokoro-82M ONNX on CPU via kokoro-js — no server, no key.
+ * kokoro-js is deliberately NOT in package.json (it drags in ~400 MB of
+ * onnxruntime); it's an opt-in install, imported lazily through non-literal
+ * specifiers so typecheck and every non-local run never touch it.
+ */
+const KOKORO_PKG: string = "kokoro-js";
+const TRANSFORMERS_PKG: string = "@huggingface/transformers";
+
+interface KokoroTtsCtor {
+  prototype: unknown;
+  from_pretrained(
+    modelId: string,
+    opts: { dtype: string; device: string }
+  ): Promise<KokoroTts>;
+}
+
+interface KokoroModules {
+  KokoroTTS: KokoroTtsCtor;
+  /** transformers.js env — cacheDir/allowRemoteModels knobs. */
+  hfEnv: { cacheDir: string; allowRemoteModels: boolean };
+}
+
+interface KokoroTts {
+  voices: Record<string, { name: string }>;
+  model?: { dispose(): Promise<void> };
+  generate(
+    text: string,
+    opts: { voice: string; speed: number }
+  ): Promise<{ toWav(): ArrayBuffer }>;
+}
+
+/**
+ * Resolve kokoro-js from the engine's own node_modules, then from the
+ * consumer's cwd (an npx-installed engine lives in the npx cache, so a
+ * `npm install kokoro-js` in the consumer repo is only reachable via cwd).
+ * @huggingface/transformers is resolved relative to wherever kokoro-js was
+ * found — it's kokoro-js's own dependency, needed only to steer its cache.
+ */
+async function loadKokoro(): Promise<KokoroModules> {
+  const attempts: Array<() => Promise<KokoroModules>> = [
+    async () => ({
+      KokoroTTS: (await import(KOKORO_PKG)).KokoroTTS,
+      hfEnv: (await import(TRANSFORMERS_PKG)).env,
+    }),
+    async () => {
+      const req = createRequire(join(process.cwd(), "package.json"));
+      const kokoroPath = req.resolve(KOKORO_PKG);
+      const sibling = createRequire(kokoroPath);
+      return {
+        KokoroTTS: (await import(pathToFileURL(kokoroPath).href)).KokoroTTS,
+        hfEnv: (await import(pathToFileURL(sibling.resolve(TRANSFORMERS_PKG)).href)).env,
+      };
+    },
+  ];
+  for (const attempt of attempts) {
+    try {
+      return await attempt();
+    } catch {
+      // try the next resolution root
+    }
+  }
+  throw new Error(
+    `AIDEMO_TTS_PROVIDER=local needs the optional kokoro-js package (not bundled — ` +
+      `it installs ~400 MB of onnxruntime). Run: npm install kokoro-js ` +
+      `(in the engine checkout, or in the repo you run aidemo from), then retry.`
+  );
+}
+
+/** True if kokoro-js resolves from the engine or the consumer cwd (no heavy import). */
+export function localTtsInstalled(): boolean {
+  for (const from of [import.meta.url, pathToFileURL(join(process.cwd(), "package.json")).href]) {
+    try {
+      createRequire(from).resolve(KOKORO_PKG);
+      return true;
+    } catch {
+      // not resolvable from this root
+    }
+  }
+  return false;
+}
+
+/** Doctor's view of the local provider: installed? model cached where, how big? */
+export async function localTtsStatus(): Promise<{
+  installed: boolean;
+  dtype: string;
+  cacheDir: string;
+  modelDir: string;
+  modelCached: boolean;
+  cacheSizeMB: number | null;
+}> {
+  const cacheDir = ttsModelCacheDir();
+  const modelDir = join(cacheDir, KOKORO_MODEL_ID);
+  const modelCached = await exists(join(modelDir, "onnx"));
+  return {
+    installed: localTtsInstalled(),
+    dtype: kokoroDtype(),
+    cacheDir,
+    modelDir,
+    modelCached,
+    cacheSizeMB: modelCached ? await dirSizeMB(modelDir) : null,
+  };
+}
+
+async function dirSizeMB(dir: string): Promise<number> {
+  let bytes = 0;
+  const walk = async (d: string): Promise<void> => {
+    for (const e of await fs.readdir(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) await walk(p);
+      else bytes += (await fs.stat(p)).size;
+    }
+  };
+  await walk(dir).catch(() => {});
+  return Math.round(bytes / 1e6);
+}
+
+/**
+ * The voice table is a static getter on the prototype (it doesn't need a
+ * loaded model) — reading it there lets a wrong voiceId fail BEFORE the
+ * ~90 MB first-run model download. Best-effort: null falls back to the
+ * post-load instance check.
+ */
+function staticVoices(KokoroTTS: KokoroTtsCtor): Record<string, unknown> | null {
+  try {
+    const get = Object.getOwnPropertyDescriptor(KokoroTTS.prototype, "voices")?.get;
+    const voices = get?.call(Object.create(KokoroTTS.prototype as object));
+    return voices && typeof voices === "object" ? voices : null;
+  } catch {
+    return null;
+  }
+}
+
+export class LocalVoiceProvider implements VoiceProvider {
+  private mods: Promise<KokoroModules> | null = null;
+  private tts: Promise<KokoroTts> | null = null;
+  private warnedInstructions = false;
+
+  private modules(): Promise<KokoroModules> {
+    return (this.mods ??= loadKokoro());
+  }
+
+  private load(): Promise<KokoroTts> {
+    return (this.tts ??= (async () => {
+      const { KokoroTTS, hfEnv } = await this.modules();
+      hfEnv.cacheDir = ttsModelCacheDir();
+      // Same switch the Python HF stack honors — proves air-gapped runs work.
+      if (process.env.HF_HUB_OFFLINE === "1") hfEnv.allowRemoteModels = false;
+      const dtype = kokoroDtype();
+      if (!(await localTtsStatus()).modelCached) {
+        log(
+          `downloading ${KOKORO_MODEL_ID} (${dtype}) from huggingface.co → ` +
+            `${hfEnv.cacheDir} — first run only, cached after`
+        );
+      }
+      return KokoroTTS.from_pretrained(KOKORO_MODEL_ID, { dtype, device: "cpu" });
+    })());
+  }
+
+  async synthesize({ text, plan }: { text: string; plan: VoicePlan }): Promise<Buffer> {
+    if (plan.instructions && !this.warnedInstructions) {
+      this.warnedInstructions = true;
+      log(
+        "⚠ voice.instructions is a gpt-4o-mini-tts steering prompt — the local Kokoro provider ignores it"
+      );
+    }
+    // "marin" is the schema default (an OpenAI voice name); anything else the
+    // author chose deliberately and must be a Kokoro voice id. Validate here,
+    // not in kokoro-js — its own validation console.tables to stdout, which
+    // the MCP server reserves for JSON-RPC.
+    const voiceId = plan.voiceId === "marin" ? KOKORO_VOICE() : plan.voiceId;
+    const voices =
+      staticVoices((await this.modules()).KokoroTTS) ?? (await this.load()).voices;
+    if (!(voiceId in voices)) {
+      throw new Error(
+        `"${voiceId}" is not a Kokoro voice — the local provider has: ` +
+          `${Object.keys(voices).join(", ")}. Set the storyboard's voice.voiceId ` +
+          `(e.g. af_heart) or AIDEMO_KOKORO_VOICE.`
+      );
+    }
+    const tts = await this.load();
+    const audio = await tts.generate(text, {
+      voice: voiceId,
+      // Storyboards allow 0.5–2, matching Kokoro's usable range — pass through.
+      speed: plan.speed ?? 1,
+    });
+    return wavToMp3(Buffer.from(await audio.toWav()));
+  }
+
+  /** Release the ONNX session — onnxruntime aborts noisily if the process
+   *  exits (especially process.exit) while a session is still alive. */
+  async dispose(): Promise<void> {
+    if (!this.tts) return;
+    const tts = await this.tts.catch(() => null);
+    await tts?.model?.dispose().catch(() => {});
+    this.tts = null;
+  }
+}
+
+/** Kokoro emits WAV; sceneAudioPath is .mp3 and downstream assumes it — transcode. */
+async function wavToMp3(wav: Buffer): Promise<Buffer> {
+  const base = join(tmpdir(), `aidemo-tts-${randomBytes(6).toString("hex")}`);
+  const wavPath = `${base}.wav`;
+  const mp3Path = `${base}.mp3`;
+  try {
+    await fs.writeFile(wavPath, wav);
+    await runFfmpeg(["-i", wavPath, "-codec:a", "libmp3lame", "-q:a", "2", mp3Path]);
+    return await fs.readFile(mp3Path);
+  } finally {
+    await fs.rm(wavPath, { force: true });
+    await fs.rm(mp3Path, { force: true });
+  }
+}