videoclaw 3.0.0-alpha.1

package/dist/video/assemble/transcript.js

@@ -0,0 +1,200 @@
+/**
+ * Transcript loading for the assemble TTS stage (resolves the `load_transcript`
+ * 3b deferral in `tts.ts`).
+ *
+ * Ported from `skills/video-replicator/scripts/generate_tts.py`
+ * (`load_transcript`, `load_edited_transcript`, `get_scene_texts`):
+ *
+ * - Standalone transcript files (from the transcribe pipeline):
+ *   `{ "transcript": { "full_text": ... }, "scene_transcripts": [...] }`
+ * - SEALCAM+-embedded transcripts (from analyze --transcribe):
+ *   `{ "scenes": [{ "scene_number": N, "transcript": { "text": ... } | "..." }] }`
+ * - Editable per-scene overrides (`editable_transcript.json`):
+ *   `{ "scenes": { "1": "text" | [{ "speaker": ..., "text": ... }] } }`
+ *
+ * Multi-voice scenes (an array of `{speaker, text}` segments) are FLATTENED to
+ * a single joined text with a warning — per-speaker multi-voice synthesis is a
+ * separately deferred 3b sub-commit, and a single voice reading every line is
+ * the documented degradation until then.
+ *
+ * The parsing core is pure (takes parsed JSON); only the `*File` wrappers do
+ * I/O. Mirrors the Python's lenient posture: unknown shapes produce an empty
+ * transcript plus a warning rather than throwing.
+ */
+import { readFile } from 'node:fs/promises';
+function sceneTextString(text) {
+    return typeof text === 'string'
+        ? text
+        : text.map((segment) => segment.text ?? '').join(' ');
+}
+function normalizeSceneText(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (Array.isArray(raw)) {
+        return raw
+            .filter((seg) => typeof seg === 'object' && seg !== null)
+            .map((seg) => ({
+            speaker: typeof seg.speaker === 'string' ? seg.speaker : '',
+            text: typeof seg.text === 'string' ? seg.text : '',
+        }));
+    }
+    if (typeof raw === 'object' && raw !== null && 'text' in raw) {
+        const text = raw.text;
+        return typeof text === 'string' ? text : '';
+    }
+    return '';
+}
+/**
+ * Normalize a parsed transcript JSON into {@link LoadedTranscript}. Supports
+ * the standalone and SEALCAM+-embedded shapes; anything else yields an empty
+ * transcript with a warning (mirrors the Python's logged warning).
+ */
+export function parseTranscript(data) {
+    const warnings = [];
+    const obj = (typeof data === 'object' && data !== null ? data : {});
+    // Standalone transcript file (from the transcribe pipeline).
+    if ('transcript' in obj) {
+        const transcript = (obj.transcript ?? {});
+        const fullText = typeof transcript.full_text === 'string' ? transcript.full_text : '';
+        const rawScenes = Array.isArray(obj.scene_transcripts) ? obj.scene_transcripts : [];
+        const sceneTranscripts = rawScenes
+            .filter((s) => typeof s === 'object' && s !== null)
+            .map((s) => {
+            const text = normalizeSceneText(s.text);
+            return {
+                sceneNumber: typeof s.scene_number === 'number' ? s.scene_number : 0,
+                text,
+                hasSpeech: sceneTextString(text).trim().length > 0,
+            };
+        });
+        return { fullText, sceneTranscripts, warnings };
+    }
+    // Embedded in SEALCAM+ analysis (from analyze --transcribe).
+    if (Array.isArray(obj.scenes)) {
+        const sceneTranscripts = obj.scenes
+            .filter((s) => typeof s === 'object' && s !== null)
+            .map((s) => {
+            const text = normalizeSceneText(s.transcript);
+            return {
+                sceneNumber: typeof s.scene_number === 'number' ? s.scene_number : 0,
+                text,
+                hasSpeech: sceneTextString(text).trim().length > 0,
+            };
+        });
+        return {
+            fullText: sceneTranscripts
+                .map((s) => sceneTextString(s.text))
+                .filter((t) => t.length > 0)
+                .join(' '),
+            sceneTranscripts,
+            warnings,
+        };
+    }
+    warnings.push('Could not find transcript data (expected a "transcript" or "scenes" key); using an empty transcript.');
+    return { fullText: '', sceneTranscripts: [], warnings };
+}
+/**
+ * Parse `editable_transcript.json`-style per-scene overrides into a
+ * sceneNumber → text map. Non-numeric scene keys are skipped with a warning
+ * (the Python would have thrown on `int(key)`).
+ */
+export function parseEditedTranscript(data) {
+    const warnings = [];
+    const edits = new Map();
+    const scenes = (typeof data === 'object' && data !== null
+        ? data.scenes
+        : undefined);
+    if (typeof scenes !== 'object' || scenes === null || Array.isArray(scenes)) {
+        return { edits, warnings };
+    }
+    for (const [key, value] of Object.entries(scenes)) {
+        const sceneNumber = Number(key);
+        if (!Number.isInteger(sceneNumber)) {
+            warnings.push(`Edited transcript: skipping non-numeric scene key "${key}".`);
+            continue;
+        }
+        edits.set(sceneNumber, normalizeSceneText(value));
+    }
+    return { edits, warnings };
+}
+/**
+ * Extract per-scene text, applying edits and skips — the Python
+ * `get_scene_texts`. With no per-scene data, the full text becomes a single
+ * scene 1 (the Python fallback).
+ */
+export function sceneTexts(transcript, options = {}) {
+    if (transcript.sceneTranscripts.length === 0) {
+        if (transcript.fullText.trim().length > 0) {
+            return [{ sceneNumber: 1, text: transcript.fullText, edited: false }];
+        }
+        return [];
+    }
+    const result = [];
+    for (const scene of transcript.sceneTranscripts) {
+        if (options.skipScenes?.has(scene.sceneNumber))
+            continue;
+        const override = options.edits?.get(scene.sceneNumber);
+        result.push({
+            sceneNumber: scene.sceneNumber,
+            text: override !== undefined ? override : scene.text,
+            edited: override !== undefined,
+        });
+    }
+    return result;
+}
+/**
+ * Resolve a transcript (plus optional edits) into TTS segments. Multi-voice
+ * scenes are flattened to one joined text with a warning; scenes with no
+ * speech are skipped (the Python's `has_speech`).
+ */
+export function transcriptToTtsSegments(transcript, options = {}) {
+    const warnings = [...transcript.warnings];
+    const segments = [];
+    for (const entry of sceneTexts(transcript, options)) {
+        if (Array.isArray(entry.text) && entry.text.length > 0) {
+            warnings.push(`Scene ${entry.sceneNumber}: multi-voice segments flattened to a single voice (multi-voice synthesis is not implemented yet).`);
+        }
+        const text = sceneTextString(entry.text).trim();
+        if (text.length === 0)
+            continue;
+        segments.push({ sceneIndex: entry.sceneNumber, text });
+    }
+    return { segments, warnings };
+}
+/** Read + parse a transcript file (standalone or SEALCAM+-embedded shape). */
+export async function loadTranscriptFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`loadTranscriptFile: cannot read ${path}: ${error.message}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`loadTranscriptFile: ${path} is not valid JSON: ${error.message}`);
+    }
+    return parseTranscript(data);
+}
+/** Read + parse an editable-transcript overrides file. */
+export async function loadEditedTranscriptFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`loadEditedTranscriptFile: cannot read ${path}: ${error.message}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`loadEditedTranscriptFile: ${path} is not valid JSON: ${error.message}`);
+    }
+    return parseEditedTranscript(data);
+}
+//# sourceMappingURL=transcript.js.map

package/dist/video/assemble/transcript.js.map

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

package/dist/video/assemble/tts-elevenlabs.d.ts

@@ -0,0 +1,52 @@
+export declare const ELEVENLABS_API_BASE = "https://api.elevenlabs.io";
+export declare const DEFAULT_MODEL_ID = "eleven_flash_v2_5";
+export declare const DEFAULT_STABILITY = 0.5;
+export declare const DEFAULT_SIMILARITY_BOOST = 0.75;
+/** voice_settings object sent in the TTS request body. */
+export interface VoiceSettings {
+    stability: number;
+    similarity_boost: number;
+    /** Style exaggeration 0.0-1.0 (default 0). */
+    style: number;
+    /** Boost similarity to original voice (default true). */
+    use_speaker_boost: boolean;
+}
+export interface SynthesizeSpeechInput {
+    voiceId: string;
+    text: string;
+    modelId?: string;
+    voiceSettings: VoiceSettings;
+    outputFormat: string;
+    /** Speech speed; only sent when != 1.0 (matches Python behavior). */
+    speed?: number;
+    /** Read from ELEVENLABS_API_KEY when omitted. */
+    apiKey?: string;
+}
+export interface ElevenLabsVoice {
+    voice_id: string;
+    name?: string;
+    [key: string]: unknown;
+}
+export interface ElevenLabsModel {
+    model_id: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Resolve the API key from the explicit input or the environment.
+ * Throws `env_var_missing` if absent.
+ */
+export declare function resolveApiKey(explicit?: string): string;
+/**
+ * Synthesize speech for a single block of text. Returns the raw audio bytes
+ * (mp3 / pcm / etc. per `outputFormat`).
+ */
+export declare function synthesizeSpeech(input: SynthesizeSpeechInput): Promise<Uint8Array>;
+/**
+ * List available voices. Tries the v2 endpoint first, falling back to v1
+ * (mirrors the Python `list_voices`).
+ */
+export declare function listVoices(apiKey?: string): Promise<ElevenLabsVoice[]>;
+/** List available TTS models (mirrors the Python `list_models`). */
+export declare function listModels(apiKey?: string): Promise<ElevenLabsModel[]>;
+//# sourceMappingURL=tts-elevenlabs.d.ts.map

package/dist/video/assemble/tts-elevenlabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-elevenlabs.d.ts","sourceRoot":"","sources":["../../../src/video/assemble/tts-elevenlabs.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AACpD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CA6CxF;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAuB5E;AAED,oEAAoE;AACpE,wBAAsB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAgB5E"}

package/dist/video/assemble/tts-elevenlabs.js

@@ -0,0 +1,118 @@
+/**
+ * ElevenLabs TTS adapter (fetch-based).
+ *
+ * Ported from `skills/video-replicator/scripts/generate_tts.py`:
+ *  - API base:           https://api.elevenlabs.io
+ *  - auth header:        xi-api-key: <ELEVENLABS_API_KEY>
+ *  - core TTS call:      POST /v1/text-to-speech/{voice_id}
+ *                          ?output_format=<fmt>
+ *                          body { text, model_id, voice_settings }
+ *                          Accept: audio/mpeg -> returns raw audio bytes
+ *  - list voices:        GET  /v2/voices?page_size=100  (fallback /v1/voices)
+ *  - list models:        GET  /v1/models
+ *
+ * This adapter covers only the basic text->speech + listing surface
+ * (sub-slice 3b.2). The dialogue / with-timestamps / speech-to-speech
+ * variants from the Python source are intentionally NOT ported here yet —
+ * see TODOs in `tts.ts`.
+ */
+import { VclawError } from '../errors.js';
+export const ELEVENLABS_API_BASE = 'https://api.elevenlabs.io';
+export const DEFAULT_MODEL_ID = 'eleven_flash_v2_5';
+export const DEFAULT_STABILITY = 0.5;
+export const DEFAULT_SIMILARITY_BOOST = 0.75;
+/**
+ * Resolve the API key from the explicit input or the environment.
+ * Throws `env_var_missing` if absent.
+ */
+export function resolveApiKey(explicit) {
+    const key = explicit ?? process.env.ELEVENLABS_API_KEY;
+    if (!key) {
+        throw new VclawError('env_var_missing', 'ELEVENLABS_API_KEY is not set. Export it (e.g. `export ELEVENLABS_API_KEY=sk_...`) before running TTS.', { envVar: 'ELEVENLABS_API_KEY' });
+    }
+    return key;
+}
+/**
+ * Synthesize speech for a single block of text. Returns the raw audio bytes
+ * (mp3 / pcm / etc. per `outputFormat`).
+ */
+export async function synthesizeSpeech(input) {
+    const apiKey = resolveApiKey(input.apiKey);
+    const modelId = input.modelId ?? DEFAULT_MODEL_ID;
+    if (!input.text.trim()) {
+        throw new VclawError('tts_failed', 'Cannot synthesize empty text.', {
+            voiceId: input.voiceId,
+        });
+    }
+    const url = new URL(`${ELEVENLABS_API_BASE}/v1/text-to-speech/${encodeURIComponent(input.voiceId)}`);
+    url.searchParams.set('output_format', input.outputFormat);
+    const body = {
+        text: input.text,
+        model_id: modelId,
+        voice_settings: input.voiceSettings,
+    };
+    if (input.speed !== undefined && input.speed !== 1.0) {
+        body.speed = input.speed;
+    }
+    const resp = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            'xi-api-key': apiKey,
+            'Content-Type': 'application/json',
+            Accept: 'audio/mpeg',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const detail = await safeReadText(resp);
+        throw new VclawError('tts_failed', `ElevenLabs TTS request failed: ${resp.status} ${resp.statusText}`, { status: resp.status, voiceId: input.voiceId, detail: detail.slice(0, 300) });
+    }
+    const buf = await resp.arrayBuffer();
+    return new Uint8Array(buf);
+}
+/**
+ * List available voices. Tries the v2 endpoint first, falling back to v1
+ * (mirrors the Python `list_voices`).
+ */
+export async function listVoices(apiKey) {
+    const key = resolveApiKey(apiKey);
+    let resp = await fetch(`${ELEVENLABS_API_BASE}/v2/voices?page_size=100`, {
+        method: 'GET',
+        headers: { 'xi-api-key': key },
+    });
+    if (!resp.ok) {
+        resp = await fetch(`${ELEVENLABS_API_BASE}/v1/voices`, {
+            method: 'GET',
+            headers: { 'xi-api-key': key },
+        });
+    }
+    if (!resp.ok) {
+        const detail = await safeReadText(resp);
+        throw new VclawError('tts_failed', `ElevenLabs list-voices request failed: ${resp.status} ${resp.statusText}`, { status: resp.status, detail: detail.slice(0, 300) });
+    }
+    const data = (await resp.json());
+    return data.voices ?? [];
+}
+/** List available TTS models (mirrors the Python `list_models`). */
+export async function listModels(apiKey) {
+    const key = resolveApiKey(apiKey);
+    const resp = await fetch(`${ELEVENLABS_API_BASE}/v1/models`, {
+        method: 'GET',
+        headers: { 'xi-api-key': key },
+    });
+    if (!resp.ok) {
+        const detail = await safeReadText(resp);
+        throw new VclawError('tts_failed', `ElevenLabs list-models request failed: ${resp.status} ${resp.statusText}`, { status: resp.status, detail: detail.slice(0, 300) });
+    }
+    const data = await resp.json();
+    return Array.isArray(data) ? data : [];
+}
+async function safeReadText(resp) {
+    try {
+        return await resp.text();
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=tts-elevenlabs.js.map

package/dist/video/assemble/tts-elevenlabs.js.map

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

package/dist/video/assemble/tts.d.ts

@@ -0,0 +1,79 @@
+import type { AssembleManifestEntry } from './types.js';
+/** Filename of the combined narration track (always mp3, see audio-concat.ts). */
+export declare const COMBINED_NARRATION_FILENAME = "narration-combined.mp3";
+/** A single narration segment: one scene's text. */
+export interface TtsSegment {
+    /** 1-based scene index, used for filenames + manifest ordering. */
+    sceneIndex: number;
+    text: string;
+}
+export interface TtsInput {
+    /**
+     * Path to a transcript JSON file (per-scene narration). Standalone and
+     * SEALCAM+-embedded shapes are supported — see `transcript.ts`.
+     */
+    transcriptPath?: string;
+    /** Optional editable-transcript per-scene overrides (editable_transcript.json). */
+    transcriptEditsPath?: string;
+    /** Inline segments, used instead of `transcriptPath` when provided. */
+    segments?: TtsSegment[];
+    voiceId: string;
+    modelId?: string;
+    stability?: number;
+    similarityBoost?: number;
+    style?: number;
+    speed?: number;
+    /** Boost similarity to original voice (default true). */
+    speakerBoost?: boolean;
+    outputFormat?: string;
+    /** Directory to write per-scene + combined audio into. */
+    outputDir: string;
+    /** Read from ELEVENLABS_API_KEY when omitted. */
+    apiKey?: string;
+    /** Skip provider calls and file writes; report intended actions only. */
+    dryRun?: boolean;
+    /** Optional override of ffprobe path for duration probing. */
+    ffprobeBin?: string;
+    /**
+     * Concatenate the per-scene audio into a single narration track
+     * ({@link COMBINED_NARRATION_FILENAME} in `outputDir`). Default off.
+     */
+    combine?: boolean;
+    /**
+     * With `combine`: pad each scene's audio with trailing silence to its scene
+     * duration so the combined track stays aligned to the slide timeline.
+     */
+    padToDuration?: boolean;
+    /** Target per-scene on-screen durations, seconds (in scene order). */
+    sceneDurationsSec?: number[];
+    /** Optional override of ffmpeg path for the combined-track concat. */
+    ffmpegBin?: string;
+}
+export interface TtsSceneOutput {
+    sceneIndex: number;
+    path: string;
+    durationMs: number;
+    sizeBytes: number;
+}
+export interface TtsResult {
+    status: 'complete' | 'dry-run';
+    /** Per-scene audio file paths. */
+    scenes: TtsSceneOutput[];
+    /** Path to the combined narration track (set when `combine` is on). */
+    combinedPath?: string;
+    manifest: AssembleManifestEntry[];
+    /** Advisory notes (e.g. multi-voice scenes flattened to a single voice). */
+    warnings: string[];
+}
+/**
+ * Generate per-scene narration audio from a transcript or inline segments.
+ *
+ * TODO(3b later sub-commits):
+ *  - conductor / sync-to-slides: re-time slides to narration (the inverse of
+ *    `padToDuration`; `narration-fit.ts` plans this but the baker is unwired).
+ *  - bake-narration / speech-to-speech (swap) subcommands.
+ *  - per-speaker multi-voice synthesis (multi-voice scenes currently flatten
+ *    to one voice — see `transcript.ts`).
+ */
+export declare function generateTts(input: TtsInput): Promise<TtsResult>;
+//# sourceMappingURL=tts.d.ts.map

package/dist/video/assemble/tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.d.ts","sourceRoot":"","sources":["../../../src/video/assemble/tts.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,kFAAkF;AAClF,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAEpE,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,kCAAkC;IAClC,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CA0FrE"}

package/dist/video/assemble/tts.js

@@ -0,0 +1,131 @@
+/**
+ * Public TTS entrypoint for the assemble stage (sub-slice 3b).
+ *
+ * Source of truth: `skills/video-replicator/scripts/generate_tts.py`.
+ *
+ * Wires the text->speech path through the ElevenLabs adapter, with
+ * transcript-file loading (`transcript.ts` — standalone + SEALCAM+-embedded
+ * shapes, editable per-scene overrides) and the optional combined narration
+ * track (`audio-concat.ts` — concat with per-scene silence padding to slide
+ * durations). The remaining Python behaviors are deferred to later 3b
+ * sub-commits and explicitly marked TODO below.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { synthesizeSpeech, DEFAULT_MODEL_ID, DEFAULT_STABILITY, DEFAULT_SIMILARITY_BOOST, } from './tts-elevenlabs.js';
+import { validateOutputFormat, DEFAULT_OUTPUT_FORMAT, sceneAudioFilename, } from './audio-utils.js';
+import { ffprobeDuration } from './ffmpeg.js';
+import { loadTranscriptFile, loadEditedTranscriptFile, transcriptToTtsSegments } from './transcript.js';
+import { planNarrationConcat, runNarrationConcat } from './audio-concat.js';
+/** Filename of the combined narration track (always mp3, see audio-concat.ts). */
+export const COMBINED_NARRATION_FILENAME = 'narration-combined.mp3';
+/**
+ * Generate per-scene narration audio from a transcript or inline segments.
+ *
+ * TODO(3b later sub-commits):
+ *  - conductor / sync-to-slides: re-time slides to narration (the inverse of
+ *    `padToDuration`; `narration-fit.ts` plans this but the baker is unwired).
+ *  - bake-narration / speech-to-speech (swap) subcommands.
+ *  - per-speaker multi-voice synthesis (multi-voice scenes currently flatten
+ *    to one voice — see `transcript.ts`).
+ */
+export async function generateTts(input) {
+    const outputFormat = validateOutputFormat(input.outputFormat ?? DEFAULT_OUTPUT_FORMAT);
+    const { segments, warnings } = await resolveSegments(input);
+    const combinedPath = input.combine
+        ? join(input.outputDir, COMBINED_NARRATION_FILENAME)
+        : undefined;
+    const voiceSettings = {
+        stability: input.stability ?? DEFAULT_STABILITY,
+        similarity_boost: input.similarityBoost ?? DEFAULT_SIMILARITY_BOOST,
+        style: input.style ?? 0.0,
+        use_speaker_boost: input.speakerBoost ?? true,
+    };
+    const modelId = input.modelId ?? DEFAULT_MODEL_ID;
+    if (input.dryRun) {
+        return {
+            status: 'dry-run',
+            scenes: segments.map((s) => ({
+                sceneIndex: s.sceneIndex,
+                path: join(input.outputDir, sceneAudioFilename(s.sceneIndex, outputFormat)),
+                durationMs: 0,
+                sizeBytes: 0,
+            })),
+            ...(combinedPath ? { combinedPath } : {}),
+            manifest: [],
+            warnings,
+        };
+    }
+    await mkdir(input.outputDir, { recursive: true });
+    const scenes = [];
+    const manifest = [];
+    for (const segment of segments) {
+        const bytes = await synthesizeSpeech({
+            voiceId: input.voiceId,
+            text: segment.text,
+            modelId,
+            voiceSettings,
+            outputFormat,
+            speed: input.speed,
+            apiKey: input.apiKey,
+        });
+        const filename = sceneAudioFilename(segment.sceneIndex, outputFormat);
+        const path = join(input.outputDir, filename);
+        await writeFile(path, bytes);
+        const durationMs = await ffprobeDuration(path, { ffprobeBin: input.ffprobeBin });
+        scenes.push({ sceneIndex: segment.sceneIndex, path, durationMs, sizeBytes: bytes.byteLength });
+        manifest.push({
+            kind: 'narration',
+            path,
+            durationMs,
+            sceneIndex: segment.sceneIndex,
+            sizeBytes: bytes.byteLength,
+            generator: `elevenlabs:${modelId}`,
+        });
+    }
+    if (combinedPath) {
+        const plan = planNarrationConcat({
+            files: scenes.map((s) => s.path),
+            output: combinedPath,
+            tempDir: join(input.outputDir, 'concat-tmp'),
+            padToDuration: input.padToDuration,
+            actualDurationsSec: scenes.map((s) => s.durationMs / 1000),
+            sceneDurationsSec: input.sceneDurationsSec,
+        });
+        await runNarrationConcat(plan, { ffmpegBin: input.ffmpegBin });
+        const combinedDurationMs = await ffprobeDuration(combinedPath, { ffprobeBin: input.ffprobeBin });
+        manifest.push({
+            kind: 'narration',
+            path: combinedPath,
+            durationMs: combinedDurationMs,
+            sizeBytes: 0,
+            generator: 'ffmpeg:concat',
+        });
+    }
+    return {
+        status: 'complete',
+        scenes,
+        ...(combinedPath ? { combinedPath } : {}),
+        manifest,
+        warnings,
+    };
+}
+async function resolveSegments(input) {
+    if (input.segments && input.segments.length > 0) {
+        return { segments: input.segments, warnings: [] };
+    }
+    if (input.transcriptPath) {
+        const transcript = await loadTranscriptFile(input.transcriptPath);
+        const editsResult = input.transcriptEditsPath
+            ? await loadEditedTranscriptFile(input.transcriptEditsPath)
+            : { edits: undefined, warnings: [] };
+        const resolved = transcriptToTtsSegments(transcript, { edits: editsResult.edits });
+        const warnings = [...editsResult.warnings, ...resolved.warnings];
+        if (resolved.segments.length === 0) {
+            throw new Error(`generateTts: transcript ${input.transcriptPath} contains no scenes with speech.`);
+        }
+        return { segments: resolved.segments, warnings };
+    }
+    throw new Error('generateTts: provide either `segments` or `transcriptPath`.');
+}
+//# sourceMappingURL=tts.js.map

package/dist/video/assemble/tts.js.map

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