recordable 0.1.0

package/dist/video/stitch.js

@@ -0,0 +1,111 @@
+import { writeFileSync } from "node:fs";
+import { join as joinPath } from "node:path";
+import { getDuration, runFfmpeg } from "../ffmpeg.js";
+import { moveFile } from "../fs.js";
+/** Stitch `segs` into `out`, choosing move / join / cross-fade automatically. */
+export async function stitch(segs, cfg, log, out, tmpDir) {
+    const hasFades = segs.some((s) => s.fadeIn > 0 || s.fadeOut > 0);
+    if (hasFades) {
+        await stitchWithFades(segs, cfg, log, out);
+    }
+    else if (segs.length === 1) {
+        moveFile(segs[0].path, out);
+    }
+    else {
+        await join(segs, cfg, log, out, tmpDir);
+    }
+}
+/** Concatenate segments into one file. Stream-copies (lossless, fast) when the
+ *  segments are compatible; falls back to a re-encode if they aren't. */
+async function join(segments, cfg, log, out, tmpDir) {
+    const listFile = joinPath(tmpDir, "concat.txt");
+    const list = segments
+        .map((s) => `file '${s.path.replace(/'/g, "'\\''")}'`)
+        .join("\n");
+    writeFileSync(listFile, list + "\n");
+    const base = ["-y", "-f", "concat", "-safe", "0", "-i", listFile];
+    try {
+        await runFfmpeg([...base, "-c", "copy", out]);
+        log("Record", `joined ${segments.length} segments`);
+    }
+    catch {
+        await runFfmpeg([
+            ...base,
+            "-c:v",
+            cfg.videoCodec,
+            "-preset",
+            cfg.videoPreset,
+            "-crf",
+            String(cfg.videoCrf),
+            out,
+        ]);
+        log("Record", `joined ${segments.length} segments (re-encoded)`);
+    }
+}
+/**
+ * Stitch segments into one file with cross-fade transitions. Builds a single
+ * `filter_complex` that, walking left to right, `xfade`s across every cross-fade
+ * boundary and `concat`s across hard cuts, then fades from/to black at the very
+ * ends when the edge clip asked for it.
+ *
+ * A cross-fade of duration `d` *overlaps* the two pieces by `d` (the outgoing
+ * tail dissolves into the incoming head), so the timeline shortens by `d` at each
+ * such boundary — tracked in `accDur` to place the next `xfade` offset.
+ * Re-encodes throughout, since xfade can't stream-copy.
+ */
+async function stitchWithFades(segs, cfg, log, out) {
+    const n = segs.length;
+    const dur = await Promise.all(segs.map((s) => getDuration(s.path)));
+    // The outer ends have no neighbour to dissolve with, so an edge clip's fade
+    // there is a fade against black; interior boundaries cross-fade two pieces.
+    const startBlack = Math.min(segs[0].fadeIn, dur[0]);
+    const endBlack = Math.min(segs[n - 1].fadeOut, dur[n - 1]);
+    const boundary = (i) => segs[i].fadeOut || segs[i + 1].fadeIn || 0;
+    // 1. Pre-process each input: relabel [i:v] → [vi], baking in the black fades.
+    const parts = [];
+    for (let i = 0; i < n; i++) {
+        const f = [];
+        if (i === 0 && startBlack > 0)
+            f.push(`fade=t=in:st=0:d=${startBlack.toFixed(3)}`);
+        if (i === n - 1 && endBlack > 0)
+            f.push(`fade=t=out:st=${(dur[i] - endBlack).toFixed(3)}:d=${endBlack.toFixed(3)}`);
+        parts.push(`[${i}:v]${f.length ? f.join(",") : "null"}[v${i}]`);
+    }
+    // 2. Fold the inputs together left to right, xfade or concat per boundary.
+    let acc = "v0";
+    let accDur = dur[0];
+    for (let i = 1; i < n; i++) {
+        const lbl = `x${i}`;
+        const d = boundary(i - 1);
+        if (d > 0) {
+            const dd = Math.min(d, accDur, dur[i]);
+            const offset = Math.max(0, accDur - dd);
+            parts.push(`[${acc}][v${i}]xfade=transition=fade:duration=${dd.toFixed(3)}:offset=${offset.toFixed(3)}[${lbl}]`);
+            accDur += dur[i] - dd;
+        }
+        else {
+            parts.push(`[${acc}][v${i}]concat=n=2:v=1:a=0[${lbl}]`);
+            accDur += dur[i];
+        }
+        acc = lbl;
+    }
+    await runFfmpeg([
+        "-y",
+        ...segs.flatMap((s) => ["-i", s.path]),
+        "-filter_complex",
+        parts.join(";"),
+        "-map",
+        `[${acc}]`,
+        "-c:v",
+        cfg.videoCodec,
+        "-preset",
+        cfg.videoPreset,
+        "-crf",
+        String(cfg.videoCrf),
+        "-pix_fmt",
+        "yuv420p",
+        out,
+    ]);
+    log("Record", `joined ${n} segments (cross-faded)`);
+}
+//# sourceMappingURL=stitch.js.map

package/dist/video/stitch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stitch.js","sourceRoot":"","sources":["../../src/video/stitch.ts"],"names":[],"mappings":"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"}

package/dist/voiceover/alignment.d.ts

@@ -0,0 +1,14 @@
+import type { Alignment } from "./types.js";
+/** The raw alignment block as returned by ElevenLabs (either key casing). */
+export interface ElevenLabsAlignment {
+    characters?: string[];
+    character_start_times_seconds?: number[];
+    character_end_times_seconds?: number[];
+    characterStartTimesSeconds?: number[];
+    characterEndTimesSeconds?: number[];
+}
+/** Normalise a raw ElevenLabs alignment to ms-based {@link Alignment}. */
+export declare function normalizeAlignment(raw: ElevenLabsAlignment): Alignment;
+/** Clip duration implied by an alignment: the last character's end time (ms). */
+export declare function alignmentDurationMs(a: Alignment): number;
+//# sourceMappingURL=alignment.d.ts.map

package/dist/voiceover/alignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.d.ts","sourceRoot":"","sources":["../../src/voiceover/alignment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQ5C,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,6BAA6B,CAAC,EAAE,MAAM,EAAE,CAAC;IACzC,2BAA2B,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvC,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;IACtC,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;CACrC;AAKD,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,CAOtE;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAExD"}

package/dist/voiceover/alignment.js

@@ -0,0 +1,13 @@
+const toMs = (secs) => secs.map((s) => Math.round(s * 1000));
+/** Normalise a raw ElevenLabs alignment to ms-based {@link Alignment}. */
+export function normalizeAlignment(raw) {
+    const chars = raw.characters ?? [];
+    const startSecs = raw.character_start_times_seconds ?? raw.characterStartTimesSeconds ?? [];
+    const endSecs = raw.character_end_times_seconds ?? raw.characterEndTimesSeconds ?? [];
+    return { chars, startMs: toMs(startSecs), endMs: toMs(endSecs) };
+}
+/** Clip duration implied by an alignment: the last character's end time (ms). */
+export function alignmentDurationMs(a) {
+    return a.endMs.length ? a.endMs[a.endMs.length - 1] : 0;
+}
+//# sourceMappingURL=alignment.js.map

package/dist/voiceover/alignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.js","sourceRoot":"","sources":["../../src/voiceover/alignment.ts"],"names":[],"mappings":"AAkBA,MAAM,IAAI,GAAG,CAAC,IAAc,EAAY,EAAE,CACxC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAExC,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB,CAAC,GAAwB;IACzD,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC;IACnC,MAAM,SAAS,GACb,GAAG,CAAC,6BAA6B,IAAI,GAAG,CAAC,0BAA0B,IAAI,EAAE,CAAC;IAC5E,MAAM,OAAO,GACX,GAAG,CAAC,2BAA2B,IAAI,GAAG,CAAC,wBAAwB,IAAI,EAAE,CAAC;IACxE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;AACnE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,mBAAmB,CAAC,CAAY;IAC9C,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/voiceover/cache.d.ts

@@ -0,0 +1,22 @@
+import { type TTSResult } from "./types.js";
+/** The inputs that fully determine a synthesis result. */
+export interface CacheKeyParts {
+    provider: string;
+    voiceId: string;
+    modelId?: string;
+    voiceSettings?: Record<string, number>;
+    format?: string;
+    text: string;
+}
+/** Stable hash of everything that affects the audio — order-independent. */
+export declare function cacheKey(parts: CacheKeyParts): string;
+/** A directory-backed cache of {@link TTSResult}s, keyed by {@link cacheKey}. */
+export declare class FileCache {
+    private readonly dir;
+    constructor(dir: string);
+    /** Cached result for `key`, or null on a miss. */
+    get(key: string): TTSResult | null;
+    /** Store `result` under `key` (audio file + JSON sidecar). */
+    put(key: string, result: TTSResult): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/voiceover/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/voiceover/cache.ts"],"names":[],"mappings":"AAGA,OAAO,EAA0B,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AASpE,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAcrD;AASD,iFAAiF;AACjF,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,MAAM;IAExC,kDAAkD;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAclC,8DAA8D;IAC9D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;CAa1C"}

package/dist/voiceover/cache.js

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { extFor } from "./types.js";
+/** Stable hash of everything that affects the audio — order-independent. */
+export function cacheKey(parts) {
+    const settings = parts.voiceSettings ?? {};
+    const sorted = {};
+    for (const k of Object.keys(settings).sort())
+        sorted[k] = settings[k];
+    const canonical = JSON.stringify({
+        provider: parts.provider,
+        voiceId: parts.voiceId,
+        modelId: parts.modelId ?? "",
+        voiceSettings: sorted,
+        format: parts.format ?? "",
+        text: parts.text,
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/** A directory-backed cache of {@link TTSResult}s, keyed by {@link cacheKey}. */
+export class FileCache {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** Cached result for `key`, or null on a miss. */
+    get(key) {
+        const metaPath = join(this.dir, `${key}.json`);
+        if (!existsSync(metaPath))
+            return null;
+        const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+        const audioPath = join(this.dir, `${key}.${extFor(meta.format)}`);
+        if (!existsSync(audioPath))
+            return null;
+        return {
+            audio: readFileSync(audioPath),
+            format: meta.format,
+            durationMs: meta.durationMs,
+            alignment: meta.alignment,
+        };
+    }
+    /** Store `result` under `key` (audio file + JSON sidecar). */
+    put(key, result) {
+        mkdirSync(this.dir, { recursive: true });
+        writeFileSync(join(this.dir, `${key}.${extFor(result.format)}`), result.audio);
+        const meta = {
+            format: result.format,
+            durationMs: result.durationMs,
+            alignment: result.alignment,
+        };
+        writeFileSync(join(this.dir, `${key}.json`), JSON.stringify(meta));
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/voiceover/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/voiceover/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAkC,MAAM,YAAY,CAAC;AAmBpE,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,KAAoB;IAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC;IAC3C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAEtE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAC/B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;QAC5B,aAAa,EAAE,MAAM;QACrB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;QAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC,CAAC;IACH,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AASD,iFAAiF;AACjF,MAAM,OAAO,SAAS;IACS;IAA7B,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAE5C,kDAAkD;IAClD,GAAG,CAAC,GAAW;QACb,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;QAC/C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAc,CAAC;QACrE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,OAAO;YACL,KAAK,EAAE,YAAY,CAAC,SAAS,CAAC;YAC9B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,GAAG,CAAC,GAAW,EAAE,MAAiB;QAChC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,aAAa,CACX,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EACjD,MAAM,CAAC,KAAK,CACb,CAAC;QACF,MAAM,IAAI,GAAc;YACtB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC;QACF,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,CAAC;CACF"}

package/dist/voiceover/compile.d.ts

@@ -0,0 +1,35 @@
+import type { Action } from "../actions.js";
+import type { RecordableConfig, VoiceoverConfig } from "../config.js";
+import { type Logger } from "../logger.js";
+import { type TTSProvider } from "./types.js";
+/** Everything the compiler needs that isn't in the document itself. */
+export interface CompileOptions {
+    /** Synthesis backend. Omit to build an `ElevenLabsProvider` from the voiceover
+     *  config; pass one (e.g. `MockTTSProvider`) to synthesize offline. */
+    provider?: TTSProvider;
+    /** Directory the generated (committable) audio assets are written to. */
+    assetsDir: string;
+    /** Voiceover settings (provider/voice/model). Falls back to document frontmatter. */
+    voiceover?: VoiceoverConfig;
+    /** Config merged over frontmatter (e.g. CLI flags). `actionDelay` is always forced to 0. */
+    configOverride?: RecordableConfig;
+    /** Gitignored timing cache. Default: `<assetsDir>/.cache`. */
+    cacheDir?: string;
+    /** Where overrun / drift warnings go. Default: the universal `[Recordable]` warn logger. */
+    warn?: (message: string) => void;
+    /** Progress logger for synthesis/cache events. Omit for silent (progress is opt-in);
+     *  pass the host's logger to surface the whole voiceover flow. */
+    log?: Logger;
+}
+/** The compiled artifact: a runnable script plus the audio files it references. */
+export interface CompiledScript {
+    config: RecordableConfig;
+    actions: Action[];
+    /** Paths of every audio asset written, in document order (deduped by content). */
+    assets: string[];
+}
+/** Compile a Markdown document into a runnable core script plus generated audio.
+ *  Paragraphs become synthesized clips with computed waits; fenced blocks between
+ *  them are narrative-level pauses. `actionDelay` is forced to 0 to keep timing exact. */
+export declare function compileMarkdown(md: string, options: CompileOptions): Promise<CompiledScript>;
+//# sourceMappingURL=compile.d.ts.map

package/dist/voiceover/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/voiceover/compile.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEtE,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AASzD,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAStE,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B;2EACuE;IACvE,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;sEACkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kFAAkF;IAClF,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAwLD;;0FAE0F;AAC1F,wBAAsB,eAAe,CACnC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAgDzB"}

package/dist/voiceover/compile.js

@@ -0,0 +1,194 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseMarkdown } from "../formats/markdown/parse.js";
+import { truncate } from "../utils.js";
+import { createLogger } from "../logger.js";
+import { actionDurationMs } from "../timing.js";
+import { cacheKey, FileCache } from "./cache.js";
+import { ElevenLabsProvider, DEFAULT_MODEL, DEFAULT_FORMAT, } from "./elevenlabs.js";
+import { MockTTSProvider } from "./mock.js";
+import { extFor } from "./types.js";
+/** First-character index of the word containing `offset` (scan back to whitespace). */
+function wordStart(text, offset) {
+    let i = Math.min(offset, text.length);
+    while (i > 0 && !/\s/.test(text[i - 1]))
+        i--;
+    return i;
+}
+/** Timeline position (ms) of a marker: the start of its enclosing word, or the
+ *  clip end for a trailing marker clamped past the last char. */
+function markerFireMs(offset, narration, alignment, durationMs) {
+    if (offset >= alignment.startMs.length)
+        return durationMs;
+    const w = wordStart(narration, offset);
+    return alignment.startMs[w] ?? durationMs;
+}
+/** A marker as the author wrote it, e.g. `click("#signInBtn")` — for diagnostics. */
+function markerLabel(step) {
+    const arg = (step.target ?? step.path ?? "");
+    return arg ? `${step.action}("${arg}")` : `${step.action}()`;
+}
+/** The narrated word a marker is anchored to (or "the end" for a trailing one). */
+function wordAt(narration, offset) {
+    if (offset >= narration.length)
+        return "the end";
+    const word = narration.slice(wordStart(narration, offset)).match(/^\S+/);
+    return word ? `"${word[0]}"` : "the end";
+}
+/** Cache/asset key for a block — narration is already the stripped, audible text.
+ *  Model/format default to the same values the provider applies, so the key
+ *  captures what was actually synthesized (else changing the default would serve
+ *  stale audio, and naming the default explicitly would force a needless re-run). */
+function keyFor(narration, vo) {
+    return cacheKey({
+        provider: vo?.provider ?? "mock",
+        voiceId: vo?.voiceId ?? "",
+        modelId: vo?.modelId ?? DEFAULT_MODEL,
+        voiceSettings: vo?.voiceSettings,
+        format: vo?.format ?? DEFAULT_FORMAT,
+        text: narration,
+    });
+}
+/** Synthesize one paragraph (cache-first) → its `audio()` clip, a `wait`/action
+ *  pair per marker, and a tail `wait` so the voiceover finishes. */
+async function compileNarration(block, opts) {
+    const { narration, markers } = block;
+    const key = keyFor(narration, opts.voiceover);
+    const preview = truncate(narration);
+    let result = opts.cache.get(key);
+    if (result) {
+        opts.log("Voice", `cache hit   "${preview}"`);
+    }
+    else {
+        // A miss means a real synthesis — for a network provider, an external API call.
+        opts.log("Voice", `synthesize  "${preview}" via ${opts.providerName}`);
+        result = await opts.provider.synthesize(narration, {
+            format: opts.voiceover?.format,
+        });
+        opts.cache.put(key, result);
+        const kb = (result.audio.length / 1024).toFixed(0);
+        opts.log("Voice", `generated   "${preview}" (${Math.round(result.durationMs)}ms, ${kb} KB)`);
+    }
+    const asset = join(opts.assetsDir, `${key}.${extFor(result.format)}`);
+    mkdirSync(opts.assetsDir, { recursive: true });
+    writeFileSync(asset, result.audio);
+    const actions = [{ action: "audio", path: asset, wait: false }];
+    const alignment = result.alignment ?? {
+        chars: [],
+        startMs: [],
+        endMs: [],
+    };
+    let elapsed = 0;
+    let prevOffset = -1;
+    for (const m of markers) {
+        const fire = markerFireMs(m.offset, narration, alignment, result.durationMs);
+        const gap = Math.round(fire - elapsed);
+        if (gap > 0) {
+            actions.push({ action: "wait", ms: gap });
+            elapsed += gap;
+        }
+        else if (gap < 0) {
+            // The action can't land on its word: earlier actions in this paragraph
+            // (their cursor travel, typing, inserts) already ran `-gap`ms past it, so
+            // this one and everything after it lag. Point at the exact spot and say why.
+            const stacked = m.offset === prevOffset;
+            const cause = stacked
+                ? `it shares a spot in the narration with the action before it`
+                : `the actions before it overrun by that much`;
+            const fix = stacked
+                ? `move ${markerLabel(m.step)} to the word it actually describes, or add narration between the two`
+                : `add words before it, space the actions out, or move it into a fenced block (no audio)`;
+            opts.warn(`Voiceover timing — ${markerLabel(m.step)} can't start on ${wordAt(narration, m.offset)} ` +
+                `(paragraph "${preview}"): ${cause}, so it and the rest lag ${-gap}ms. Fix: ${fix}.`);
+        }
+        actions.push(m.step);
+        elapsed += await actionDurationMs(m.step, opts.cfg);
+        prevOffset = m.offset;
+    }
+    // Let the narration finish before the next block begins.
+    const tail = Math.round(result.durationMs - elapsed);
+    if (tail > 0)
+        actions.push({ action: "wait", ms: tail });
+    return { actions, asset };
+}
+/** Apply env defaults to a voiceover block — frontmatter always wins. The env
+ *  vars let many files share a provider/voice/model without repeating it; a file
+ *  stays fully reproducible by spelling the values out. No-op without a block. */
+function withEnvDefaults(vo) {
+    if (!vo)
+        return vo;
+    return {
+        ...vo,
+        provider: vo.provider || process.env.RECORDABLE_TTS_PROVIDER || "elevenlabs",
+        voiceId: vo.voiceId || process.env.RECORDABLE_VOICE_ID || "",
+        modelId: vo.modelId ?? process.env.RECORDABLE_MODEL_ID,
+    };
+}
+/** Pick the synthesis backend: an explicit provider, else the one named by the
+ *  voiceover config. `mock` is silent/offline; ElevenLabs requires an API key
+ *  (config `apiKey`, else `ELEVENLABS_API_KEY`) — without one we throw, since a
+ *  voiceover run with no key can't do anything useful. */
+function resolveProvider(provider, voiceover) {
+    if (provider)
+        return provider;
+    if (!voiceover) {
+        throw new Error("compileMarkdown: no `voiceover` frontmatter and no `provider` — add a voiceover block or pass a provider.");
+    }
+    if (voiceover.provider === "mock")
+        return new MockTTSProvider();
+    const hasKey = voiceover.apiKey ?? process.env.ELEVENLABS_API_KEY;
+    if (!hasKey) {
+        throw new Error("Voiceover: ElevenLabs needs an API key — set ELEVENLABS_API_KEY (e.g. in a .env beside " +
+            "the document) or `voiceover.apiKey`, or use RECORDABLE_TTS_PROVIDER=mock for silent audio.");
+    }
+    const voiceId = voiceover.voiceId;
+    if (!voiceId) {
+        throw new Error("Voiceover: ElevenLabs needs a voice — set RECORDABLE_VOICE_ID (e.g. in a .env beside " +
+            "the document) or `voiceover.voiceId`.");
+    }
+    return new ElevenLabsProvider({ ...voiceover, voiceId });
+}
+/** Compile a Markdown document into a runnable core script plus generated audio.
+ *  Paragraphs become synthesized clips with computed waits; fenced blocks between
+ *  them are narrative-level pauses. `actionDelay` is forced to 0 to keep timing exact. */
+export async function compileMarkdown(md, options) {
+    const parsed = parseMarkdown(md);
+    // Progress is opt-in (silent default); warnings always surface.
+    const log = options.log ?? createLogger(() => true);
+    const warn = options.warn ?? options.log?.warn ?? createLogger(() => false).warn;
+    const voiceover = withEnvDefaults(options.voiceover ?? parsed.voiceover);
+    const provider = resolveProvider(options.provider, voiceover);
+    const providerName = provider.constructor?.name?.replace(/(TTS)?Provider$/, "").toLowerCase() ||
+        "provider";
+    const cache = new FileCache(options.cacheDir ?? join(options.assetsDir, ".cache"));
+    const config = {
+        ...parsed.config,
+        ...options.configOverride,
+        actionDelay: 0,
+    };
+    const actions = [];
+    const assets = [];
+    const narrationCount = parsed.blocks.filter((b) => b.type !== "actions").length;
+    log("Voice", `compiling ${narrationCount} narration block(s) → ${providerName}`);
+    for (const block of parsed.blocks) {
+        if (block.type === "actions") {
+            actions.push(...block.actions); // a fenced pause: actions run sequentially, no audio
+            continue;
+        }
+        const compiled = await compileNarration(block, {
+            provider,
+            assetsDir: options.assetsDir,
+            voiceover,
+            cache,
+            cfg: config,
+            warn,
+            log,
+            providerName,
+        });
+        actions.push(...compiled.actions);
+        assets.push(compiled.asset);
+    }
+    log.success("Voice", `done — compiled ${assets.length} clip(s)`);
+    return { config, actions, assets };
+}
+//# sourceMappingURL=compile.js.map

package/dist/voiceover/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../../src/voiceover/compile.ts"],"names":[],"mappings":"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"}

package/dist/voiceover/elevenlabs.d.ts

@@ -0,0 +1,16 @@
+import type { VoiceoverConfig } from "../config.js";
+import type { SynthOptions, TTSProvider, TTSResult } from "./types.js";
+export declare const DEFAULT_MODEL = "eleven_multilingual_v2";
+export declare const DEFAULT_FORMAT = "mp3_44100_128";
+export interface ElevenLabsOptions extends VoiceoverConfig {
+    /** Required here — resolved from config/env before the provider is built. */
+    voiceId: string;
+}
+export declare class ElevenLabsProvider implements TTSProvider {
+    private readonly cfg;
+    constructor(cfg: ElevenLabsOptions);
+    synthesize(text: string, opts?: SynthOptions): Promise<TTSResult>;
+    /** The raw network call — isolated so everything around it stays testable. */
+    private _synthesize;
+}
+//# sourceMappingURL=elevenlabs.d.ts.map

package/dist/voiceover/elevenlabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elevenlabs.d.ts","sourceRoot":"","sources":["../../src/voiceover/elevenlabs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAOpD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAUvE,eAAO,MAAM,aAAa,2BAA2B,CAAC;AACtD,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAG9C,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,kBAAmB,YAAW,WAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,iBAAiB;IAE7C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,SAAS,CAAC;IAK3E,8EAA8E;YAChE,WAAW;CAyD1B"}

package/dist/voiceover/elevenlabs.js

@@ -0,0 +1,66 @@
+import { RecordableError } from "../errors.js";
+import { alignmentDurationMs, normalizeAlignment, } from "./alignment.js";
+// ─── ElevenLabs provider ─────────────────────────────────────────────────────
+//
+// The first TTS implementation. The SDK is an optionalDependency, loaded with a
+// dynamic import only on this path, so a core record-JSON install never pulls it
+// in. Caching lives one level up in the compiler (keyed by the same inputs);
+// this provider just turns text into audio. Network calls run in the user's
+// terminal (secret + connectivity).
+export const DEFAULT_MODEL = "eleven_multilingual_v2";
+export const DEFAULT_FORMAT = "mp3_44100_128";
+const PACKAGE = "@elevenlabs/elevenlabs-js";
+export class ElevenLabsProvider {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async synthesize(text, opts = {}) {
+        const format = opts.format ?? this.cfg.format ?? DEFAULT_FORMAT;
+        return this._synthesize(text, format);
+    }
+    /** The raw network call — isolated so everything around it stays testable. */
+    async _synthesize(text, format) {
+        const apiKey = this.cfg.apiKey ?? process.env.ELEVENLABS_API_KEY;
+        if (!apiKey) {
+            throw new Error("ElevenLabs: no API key — set ELEVENLABS_API_KEY (or voiceover.apiKey)");
+        }
+        // Non-literal specifier so tsc doesn't try to resolve the optional dep; it's
+        // present only when the voiceover add-on path is actually used.
+        let mod;
+        try {
+            mod = await import(PACKAGE);
+        }
+        catch {
+            throw new Error(`ElevenLabs: the "${PACKAGE}" package is not installed — ` +
+                `add it to use voiceover (it is an optional dependency)`);
+        }
+        const ElevenLabsClient = mod.ElevenLabsClient ?? mod.default?.ElevenLabsClient ?? mod.default;
+        const client = new ElevenLabsClient({ apiKey });
+        let res;
+        try {
+            res = await client.textToSpeech.convertWithTimestamps(this.cfg.voiceId, {
+                text,
+                modelId: this.cfg.modelId ?? DEFAULT_MODEL,
+                voiceSettings: this.cfg.voiceSettings,
+                outputFormat: format,
+            });
+        }
+        catch (e) {
+            throw new RecordableError("TTS_FAILED", `ElevenLabs synthesis failed: ${e.message}`, { cause: e });
+        }
+        // Response is the object directly in current SDKs, `.data`-wrapped in older.
+        // Audio field is `audioBase64` (camelCase SDK) / `audio_base64` (raw REST).
+        const data = res?.data ?? res;
+        const audioBase64 = data.audioBase64 ?? data.audio_base64 ?? data.audio;
+        if (!audioBase64)
+            throw new RecordableError("TTS_FAILED", "ElevenLabs returned no audio in its response");
+        const audio = Buffer.from(audioBase64, "base64");
+        const alignment = data.alignment
+            ? normalizeAlignment(data.alignment)
+            : undefined;
+        const durationMs = alignment ? alignmentDurationMs(alignment) : 0;
+        return { audio, format, durationMs, alignment };
+    }
+}
+//# sourceMappingURL=elevenlabs.js.map

package/dist/voiceover/elevenlabs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elevenlabs.js","sourceRoot":"","sources":["../../src/voiceover/elevenlabs.ts"],"names":[],"mappings":"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"}

package/dist/voiceover/index.d.ts

@@ -0,0 +1,7 @@
+export type { Alignment, TTSResult, TTSProvider, SynthOptions, } from "./types.js";
+export { normalizeAlignment, alignmentDurationMs, type ElevenLabsAlignment, } from "./alignment.js";
+export { cacheKey, FileCache, type CacheKeyParts } from "./cache.js";
+export { ElevenLabsProvider, type ElevenLabsOptions } from "./elevenlabs.js";
+export { MockTTSProvider, silentWav, type MockOptions } from "./mock.js";
+export { compileMarkdown, type CompileOptions, type CompiledScript, } from "./compile.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/voiceover/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voiceover/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC"}

package/dist/voiceover/index.js

@@ -0,0 +1,8 @@
+// The optional voiceover add-on. Imports core; core never imports this. Pulls in
+// the ElevenLabs SDK (an optional dependency) only when actually used.
+export { normalizeAlignment, alignmentDurationMs, } from "./alignment.js";
+export { cacheKey, FileCache } from "./cache.js";
+export { ElevenLabsProvider } from "./elevenlabs.js";
+export { MockTTSProvider, silentWav } from "./mock.js";
+export { compileMarkdown, } from "./compile.js";
+//# sourceMappingURL=index.js.map

package/dist/voiceover/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/voiceover/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,uEAAuE;AAQvE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,GAEpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAsB,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAA0B,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,SAAS,EAAoB,MAAM,WAAW,CAAC;AACzE,OAAO,EACL,eAAe,GAGhB,MAAM,cAAc,CAAC"}

package/dist/voiceover/mock.d.ts

@@ -0,0 +1,15 @@
+import type { SynthOptions, TTSProvider, TTSResult } from "./types.js";
+export interface MockOptions {
+    /** Synthetic speaking rate: ms of audio per character. Default 55. */
+    msPerChar?: number;
+    /** WAV sample rate; lower keeps the silent buffer small. Default 8000. */
+    sampleRate?: number;
+}
+export declare class MockTTSProvider implements TTSProvider {
+    private readonly opts;
+    constructor(opts?: MockOptions);
+    synthesize(text: string, _opts?: SynthOptions): Promise<TTSResult>;
+}
+/** Build a valid silent 16-bit mono WAV of `durationMs` — ffmpeg-compatible. */
+export declare function silentWav(durationMs: number, sampleRate?: number): Buffer;
+//# sourceMappingURL=mock.d.ts.map