videoclaw 3.0.0-alpha.1

package/src/video/assemble/transcript.ts

@@ -0,0 +1,240 @@
+/**
+ * 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';
+import type { TtsSegment } from './tts.js';
+
+export interface MultiVoiceSegment {
+  speaker: string;
+  text: string;
+}
+
+/** A scene's narration: plain text, or multi-voice speaker segments. */
+export type SceneText = string | MultiVoiceSegment[];
+
+export interface SceneTranscript {
+  sceneNumber: number;
+  text: SceneText;
+  hasSpeech: boolean;
+}
+
+export interface LoadedTranscript {
+  fullText: string;
+  sceneTranscripts: SceneTranscript[];
+  warnings: string[];
+}
+
+function sceneTextString(text: SceneText): string {
+  return typeof text === 'string'
+    ? text
+    : text.map((segment) => segment.text ?? '').join(' ');
+}
+
+function normalizeSceneText(raw: unknown): SceneText {
+  if (typeof raw === 'string') return raw;
+  if (Array.isArray(raw)) {
+    return raw
+      .filter((seg): seg is { speaker?: unknown; text?: unknown } => 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 as { text?: unknown }).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: unknown): LoadedTranscript {
+  const warnings: string[] = [];
+  const obj = (typeof data === 'object' && data !== null ? data : {}) as Record<string, unknown>;
+
+  // Standalone transcript file (from the transcribe pipeline).
+  if ('transcript' in obj) {
+    const transcript = (obj.transcript ?? {}) as Record<string, unknown>;
+    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): s is Record<string, unknown> => 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): s is Record<string, unknown> => 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: unknown): { edits: Map<number, SceneText>; warnings: string[] } {
+  const warnings: string[] = [];
+  const edits = new Map<number, SceneText>();
+  const scenes = (typeof data === 'object' && data !== null
+    ? (data as Record<string, unknown>).scenes
+    : undefined) as Record<string, unknown> | 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 };
+}
+
+export interface SceneTextEntry {
+  sceneNumber: number;
+  text: SceneText;
+  edited: boolean;
+}
+
+/**
+ * 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: LoadedTranscript,
+  options: { edits?: Map<number, SceneText>; skipScenes?: Set<number> } = {},
+): SceneTextEntry[] {
+  if (transcript.sceneTranscripts.length === 0) {
+    if (transcript.fullText.trim().length > 0) {
+      return [{ sceneNumber: 1, text: transcript.fullText, edited: false }];
+    }
+    return [];
+  }
+  const result: SceneTextEntry[] = [];
+  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: LoadedTranscript,
+  options: { edits?: Map<number, SceneText>; skipScenes?: Set<number> } = {},
+): { segments: TtsSegment[]; warnings: string[] } {
+  const warnings = [...transcript.warnings];
+  const segments: TtsSegment[] = [];
+  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: string): Promise<LoadedTranscript> {
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (error) {
+    throw new Error(`loadTranscriptFile: cannot read ${path}: ${(error as Error).message}`);
+  }
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`loadTranscriptFile: ${path} is not valid JSON: ${(error as Error).message}`);
+  }
+  return parseTranscript(data);
+}
+
+/** Read + parse an editable-transcript overrides file. */
+export async function loadEditedTranscriptFile(
+  path: string,
+): Promise<{ edits: Map<number, SceneText>; warnings: string[] }> {
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (error) {
+    throw new Error(`loadEditedTranscriptFile: cannot read ${path}: ${(error as Error).message}`);
+  }
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`loadEditedTranscriptFile: ${path} is not valid JSON: ${(error as Error).message}`);
+  }
+  return parseEditedTranscript(data);
+}

package/src/video/assemble/tts-elevenlabs.ts

@@ -0,0 +1,182 @@
+/**
+ * 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;
+
+/** 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 function resolveApiKey(explicit?: string): string {
+  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: SynthesizeSpeechInput): Promise<Uint8Array> {
+  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: Record<string, unknown> = {
+    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?: string): Promise<ElevenLabsVoice[]> {
+  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()) as { voices?: ElevenLabsVoice[] };
+  return data.voices ?? [];
+}
+
+/** List available TTS models (mirrors the Python `list_models`). */
+export async function listModels(apiKey?: string): Promise<ElevenLabsModel[]> {
+  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 as ElevenLabsModel[]) : [];
+}
+
+async function safeReadText(resp: Response): Promise<string> {
+  try {
+    return await resp.text();
+  } catch {
+    return '';
+  }
+}

package/src/video/assemble/tts.ts

@@ -0,0 +1,227 @@
+/**
+ * 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,
+  type VoiceSettings,
+} from './tts-elevenlabs.js';
+import {
+  validateOutputFormat,
+  DEFAULT_OUTPUT_FORMAT,
+  sceneAudioFilename,
+  type OutputFormat,
+} from './audio-utils.js';
+import { ffprobeDuration } from './ffmpeg.js';
+import { loadTranscriptFile, loadEditedTranscriptFile, transcriptToTtsSegments } from './transcript.js';
+import { planNarrationConcat, runNarrationConcat } from './audio-concat.js';
+import type { AssembleManifestEntry } from './types.js';
+
+/** Filename of the combined narration track (always mp3, see audio-concat.ts). */
+export 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 async function generateTts(input: TtsInput): Promise<TtsResult> {
+  const outputFormat: 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: 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: TtsSceneOutput[] = [];
+  const manifest: AssembleManifestEntry[] = [];
+
+  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: TtsInput,
+): Promise<{ segments: TtsSegment[]; warnings: string[] }> {
+  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: [] as string[] };
+    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`.');
+}

package/src/video/assemble/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared types for the `vclaw video assemble` post-execution stage.
+ *
+ * Sub-slice 3a establishes only the structural surface. The actual
+ * TTS / PDF / title-card / slide-animation / music / stitch logic lands
+ * in sub-slices 3b–3h. No video/audio I/O lives here yet.
+ */
+import type { VideoProjectWorkspace } from '../workspace.js';
+import type { AssembleMediaQcReport } from './media-qc.js';
+
+export interface AssembleInput {
+  workspace: VideoProjectWorkspace;
+  /** Path to the brand-profile.json for the active presenter (Slice 2 output). */
+  brandProfilePath?: string;
+  /** Optional override of FFmpeg path. Defaults to `ffmpeg` on PATH. */
+  ffmpegBin?: string;
+  /** Dry run produces the report but skips actual generation. */
+  dryRun?: boolean;
+  /**
+   * Clip-stitch mode. When set, the body segments are the per-scene rendered
+   * clips `vclaw video execute` downloads to `outputs/scene-<i>.mp4` (NOT
+   * animated slides). Each clip's native audio (incl. omni-flash voice) is
+   * kept; the background-music bed is the only optional extra layer; no TTS
+   * narration and no dialogue/sfx auto-layers are added.
+   */
+  fromRenderedClips?: boolean;
+}
+
+export interface AssembleManifestEntry {
+  kind: 'narration' | 'music' | 'title-card' | 'slide-animation' | 'rendered-clip' | 'final-video';
+  path: string;
+  durationMs: number;
+  sceneIndex?: number;
+  sizeBytes: number;
+  generator: string;
+}
+
+export interface AssembleResult {
+  status: 'complete' | 'partial' | 'dry-run';
+  outputPath: string;
+  manifest: AssembleManifestEntry[];
+  events: string[];
+  warnings: string[];
+  qc?: AssembleMediaQcReport;
+}