@mineo71/showtime 0.2.1 → 0.4.0

package/src/cli/main.ts

@@ -1,17 +1,68 @@
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { workPaths } from '../paths';
-import { loadScript } from '../script/load';
+import { loadScript, type LoadedScript } from '../script/load';
 import { scriptJsonSchema } from '../script/schema';
-import { formatCheck } from './format';
+import type { TakeEvents } from '../timeline/types';
+import { aspectOf, formatOf } from '../convert';
+import { formatCheck, formatLint } from './format';
 
-const say = (line: string) => process.stdout.write(`${line}\n`);
-const progress = (p: number) => {
-  if (process.stdout.isTTY) process.stdout.write(`\rRendering ${Math.round(p * 100)}%`);
+const say = (line: string): void => {
+  process.stdout.write(`${line}\n`);
 };
+/** With --json, stdout carries exactly one JSON document. */
+const emit = (data: unknown): void => say(JSON.stringify(data, null, 2));
+const progressFor = (json?: boolean) =>
+  json
+    ? undefined
+    : (p: number) => {
+        if (process.stdout.isTTY) process.stdout.write(`\rRendering ${Math.round(p * 100)}%`);
+      };
 
 const { version } = createRequire(import.meta.url)('../../package.json') as { version: string };
 
+const takeSummary = (loaded: LoadedScript, ev: TakeEvents) => ({
+  take: workPaths(loaded).take,
+  durationMs: ev.video.durationMs,
+  steps: ev.steps.length,
+});
+
+interface RenderFlags {
+  out?: string;
+  json?: boolean;
+  aspect: string;
+  format?: string;
+  width?: string;
+  audio: boolean;
+}
+
+/** Validate the output flags up front, before any recording or rendering starts. */
+function renderOptions(o: RenderFlags) {
+  const width = o.width === undefined ? undefined : Number(o.width);
+  if (width !== undefined && !(Number.isInteger(width) && width >= 16 && width <= 3840)) {
+    throw new Error(`--width must be a whole number of pixels between 16 and 3840 (got "${o.width}")`);
+  }
+  return { out: o.out, aspect: aspectOf(o.aspect), format: formatOf(o.out, o.format), width, audio: o.audio };
+}
+
+const withRenderFlags = (c: Command) =>
+  c
+    .option('-o, --out <file>', 'output file (default: <script-name>[-9x16|-1x1].<format> next to the script)')
+    .option('--aspect <ratio>', '16:9, 9:16 or 1:1', '16:9')
+    .option('--format <format>', 'mp4, gif or webp (default: from --out, else mp4)')
+    .option('--width <px>', 'GIF/WebP width (default: 960, 540 or 720 by aspect)')
+    .option('--no-audio', 'leave out narration, music and sounds (narration still paces burned-in subtitles)');
+
+async function render(loaded: LoadedScript, o: RenderFlags) {
+  const { renderDemo } = await import('../pipeline');
+  return renderDemo(loaded, { ...renderOptions(o), onProgress: progressFor(o.json), log: o.json ? undefined : say });
+}
+
+const sayRendered = (r: { video: string; subtitles: string | null }) => {
+  say(`\n✓ ${r.video}`);
+  if (r.subtitles) say(`✓ subtitles: ${r.subtitles}`);
+};
+
 const program = new Command('showtime')
   .description('AI-directed product demo videos: JSON script in, polished MP4 out')
   .version(version);
@@ -21,23 +72,27 @@ program
   .description('download the browsers showTime records with and link the skill into Claude Code and Codex')
   .option('--agent <agent>', 'claude, codex or all', 'all')
   .option('--no-browsers', 'only link the skill')
-  .action(async (o: { agent: string; browsers: boolean }) => {
+  .option('--json', 'print the result as JSON')
+  .action(async (o: { agent: string; browsers: boolean; json?: boolean }) => {
     const { AGENTS, installBrowsers, linkSkill } = await import('../setup');
     const agents = o.agent === 'all' ? AGENTS : AGENTS.filter((a) => a === o.agent);
     if (!agents.length) throw new Error(`--agent must be ${AGENTS.join(', ')} or all`);
     if (o.browsers) {
-      say('Downloading Chromium and the Remotion renderer browser…');
-      await installBrowsers();
+      if (!o.json) say('Downloading Chromium and the Remotion renderer browser…');
+      await installBrowsers({ quiet: o.json });
     }
-    for (const dest of linkSkill(agents)) say(`✓ skill linked: ${dest}`);
+    const links = linkSkill(agents);
+    if (o.json) return emit({ links, browsers: o.browsers });
+    for (const dest of links) say(`✓ skill linked: ${dest}`);
     say('Ready. Ask your agent for a demo, or run `showtime make <script>`.');
   });
 
 program
   .command('schema')
   .description('print the JSON Schema of demo scripts')
+  .option('--json', 'accepted for symmetry; the output is always JSON')
   .action(() => {
-    say(JSON.stringify(scriptJsonSchema(), null, 2));
+    emit(scriptJsonSchema());
   });
 
 program
@@ -49,64 +104,94 @@ program
     const loaded = await loadScript(file);
     const { check } = await import('../runner/check');
     const report = await check(loaded, { headed: o.headed, log: o.json ? undefined : say });
-    say(o.json ? JSON.stringify(report, null, 2) : formatCheck(report));
+    if (o.json) emit(report);
+    else say(formatCheck(report));
     if (!report.ok) process.exitCode = 1;
   });
 
+program
+  .command('lint <script>')
+  .description('flag script problems, and timing problems when a fresh take exists')
+  .option('--json', 'print { issues, timing } as JSON')
+  .action(async (file: string, o: { json?: boolean }) => {
+    const loaded = await loadScript(file);
+    const { lintScript, lintTiming } = await import('../lint');
+    const issues = lintScript(loaded.script);
+    const { loadTake } = await import('../take');
+    const events = await loadTake(loaded).catch(() => null);
+    if (events) {
+      // The timeline as rendered: narration is synthesized (cached) so its holds count.
+      const { timelineFor } = await import('../pipeline');
+      const { timeline } = await timelineFor(loaded, { log: o.json ? undefined : say });
+      issues.push(...lintTiming(timeline, events.steps));
+    }
+    if (o.json) emit({ issues, timing: events !== null });
+    else say(formatLint(issues, events !== null));
+    if (issues.some((i) => i.level === 'warn')) process.exitCode = 1;
+  });
+
 program
   .command('record <script>')
   .description('record a take (raw video + event log) into .showtime/<name>/take')
   .option('--headed', 'show the browser')
   .option('--keep-frames', 'keep the captured JPEG frames')
-  .action(async (file: string, o: { headed?: boolean; keepFrames?: boolean }) => {
+  .option('--json', 'print { take, durationMs, steps } as JSON')
+  .action(async (file: string, o: { headed?: boolean; keepFrames?: boolean; json?: boolean }) => {
     const loaded = await loadScript(file);
     const { record } = await import('../runner/record');
-    const ev = await record(loaded, { headed: o.headed, keepFrames: o.keepFrames, log: say });
-    say(`✓ take: ${(ev.video.durationMs / 1000).toFixed(1)} s, ${ev.steps.length} steps → ${workPaths(loaded).take}`);
+    const ev = await record(loaded, { headed: o.headed, keepFrames: o.keepFrames, log: o.json ? undefined : say });
+    const take = takeSummary(loaded, ev);
+    if (o.json) emit(take);
+    else say(`✓ take: ${(take.durationMs / 1000).toFixed(1)} s, ${take.steps} steps → ${take.take}`);
   });
 
-program
-  .command('render <script>')
-  .description('render the polished video from the last take (no re-recording)')
-  .option('-o, --out <file>', 'output MP4 (default: <script-name>.mp4 next to the script)')
-  .action(async (file: string, o: { out?: string }) => {
-    const loaded = await loadScript(file);
-    const { renderDemo } = await import('../pipeline');
-    const out = await renderDemo(loaded, { out: o.out, onProgress: progress });
-    say(`\n✓ ${out}`);
+withRenderFlags(
+  program.command('render <script>').description('render the polished video from the last take (no re-recording)'),
+)
+  .option('--json', 'print { video, durationMs, subtitles } as JSON')
+  .action(async (file: string, o: RenderFlags) => {
+    renderOptions(o);
+    const result = await render(await loadScript(file), o);
+    if (o.json) emit(result);
+    else sayRendered(result);
   });
 
 program
   .command('frames <script>')
-  .description('render QA stills (intro + one per step) for visual review')
-  .action(async (file: string) => {
-    const loaded = await loadScript(file);
+  .description('render QA stills (intro, one per step, outro) and a contact sheet of them')
+  .option('--aspect <ratio>', '16:9, 9:16 or 1:1', '16:9')
+  .option('--json', 'print { sheet, frames } as JSON')
+  .action(async (file: string, o: { aspect: string; json?: boolean }) => {
+    const aspect = aspectOf(o.aspect);
     const { renderQaFrames } = await import('../pipeline');
-    const files = await renderQaFrames(loaded);
-    say(files.join('\n'));
+    const { sheet, frames } = await renderQaFrames(await loadScript(file), { aspect, log: o.json ? undefined : say });
+    if (o.json) return emit({ sheet, frames });
+    say(`sheet: ${sheet}`);
+    say(frames.join('\n'));
   });
 
-program
-  .command('make <script>')
-  .description('check → record → render')
-  .option('-o, --out <file>', 'output MP4 (default: <script-name>.mp4 next to the script)')
+withRenderFlags(program.command('make <script>').description('check → record → render'))
   .option('--headed', 'show the browser')
-  .action(async (file: string, o: { out?: string; headed?: boolean }) => {
+  .option('--json', 'print { check, take, video } as JSON')
+  .action(async (file: string, o: RenderFlags & { headed?: boolean }) => {
+    renderOptions(o);
     const loaded = await loadScript(file);
+    const log = o.json ? undefined : say;
     const { check } = await import('../runner/check');
     const report = await check(loaded, { headed: o.headed });
     if (!report.ok) {
-      say(formatCheck(report));
+      if (o.json) emit({ check: report });
+      else say(formatCheck(report));
       process.exitCode = 1;
       return;
     }
-    say(`✓ check passed (${report.steps.length} steps)`);
+    log?.(`✓ check passed (${report.steps.length} steps)`);
     const { record } = await import('../runner/record');
-    const ev = await record(loaded, { headed: o.headed, log: say });
-    say(`✓ take: ${(ev.video.durationMs / 1000).toFixed(1)} s`);
-    const { renderDemo } = await import('../pipeline');
-    const out = await renderDemo(loaded, { out: o.out, onProgress: progress });
-    say(`\n✓ ${out}`);
+    const take = takeSummary(loaded, await record(loaded, { headed: o.headed, log }));
+    log?.(`✓ take: ${(take.durationMs / 1000).toFixed(1)} s`);
+    const video = await render(loaded, o);
+    if (o.json) emit({ check: report, take, video });
+    else sayRendered(video);
   });
 
 program.parseAsync().catch((err: Error) => {

package/src/convert.ts

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { run } from './ffmpeg';
+import type { Aspect } from './timeline/types';
+
+export type Format = 'mp4' | 'gif' | 'webp';
+const FORMATS: readonly Format[] = ['mp4', 'gif', 'webp'];
+const ASPECTS: readonly Aspect[] = ['16:9', '9:16', '1:1'];
+
+/** GIF/WebP width when --width is not given. */
+export const ANIMATION_WIDTH: Record<Aspect, number> = { '16:9': 960, '9:16': 540, '1:1': 720 };
+const GIF_FPS = 15;
+const WEBP_FPS = 20;
+const WEBP_QUALITY = 76;
+
+export function aspectOf(flag = '16:9'): Aspect {
+  if (!(ASPECTS as readonly string[]).includes(flag)) throw new Error(`--aspect must be 16:9, 9:16 or 1:1 (got "${flag}")`);
+  return flag as Aspect;
+}
+
+/** The --format flag, else the extension of -o, else mp4. */
+export function formatOf(out?: string, flag?: string): Format {
+  if (flag !== undefined) {
+    if (!(FORMATS as readonly string[]).includes(flag)) throw new Error(`--format must be mp4, gif or webp (got "${flag}")`);
+    return flag as Format;
+  }
+  if (!out) return 'mp4';
+  const ext = path.extname(out).slice(1).toLowerCase();
+  if ((FORMATS as readonly string[]).includes(ext)) return ext as Format;
+  throw new Error(`Cannot tell the format from "${out}": name it .mp4, .gif or .webp, or pass --format`);
+}
+
+/** `<name>.mp4`, `<name>-9x16.mp4`, `<name>-1x1.gif`… next to the script. */
+export function defaultOutput(loaded: { dir: string; name: string }, aspect: Aspect, format: Format): string {
+  const suffix = aspect === '16:9' ? '' : `-${aspect.replace(':', 'x')}`;
+  return path.join(loaded.dir, `${loaded.name}${suffix}.${format}`);
+}
+
+/** An MP4 as a looping GIF with one palette for the whole clip. */
+export async function toGif(src: string, out: string, width: number): Promise<void> {
+  const vf = `fps=${GIF_FPS},scale=${width}:-1:flags=lanczos,split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle`;
+  await run('ffmpeg', ['-v', 'error', '-y', '-i', src, '-vf', vf, '-loop', '0', out]);
+}
+
+/** An MP4 as a looping animated WebP. */
+export async function toWebp(src: string, out: string, width: number): Promise<void> {
+  const vf = `fps=${WEBP_FPS},scale=${width}:-1:flags=lanczos`;
+  await run('ffmpeg', ['-v', 'error', '-y', '-i', src, '-vf', vf, '-c:v', 'libwebp_anim', '-quality', String(WEBP_QUALITY), '-loop', '0', out]);
+}

package/src/ffmpeg.ts

@@ -14,6 +14,21 @@ export function run(cmd: string, args: string[]): Promise<string> {
   });
 }
 
+/** Run a command and collect its binary stdout. */
+export function runBuffer(cmd: string, args: string[]): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const out: Buffer[] = [];
+    let err = '';
+    child.stdout.on('data', (d: Buffer) => out.push(d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', reject);
+    child.on('close', (code) =>
+      code === 0 ? resolve(Buffer.concat(out)) : reject(new Error(`${cmd} exited with ${code}: ${err.trim().slice(-2000)}`)),
+    );
+  });
+}
+
 /** Run a command and stream data into its stdin; `feed` awaits back-pressure through `write`. */
 export function runWithInput(
   cmd: string,
@@ -70,3 +85,9 @@ export async function probeVideo(file: string): Promise<VideoProbe> {
   const j = JSON.parse(out) as { streams: Array<{ width: number; height: number }>; format: { duration: string } };
   return { width: j.streams[0].width, height: j.streams[0].height, durationMs: Math.round(Number(j.format.duration) * 1000) };
 }
+
+/** Whether a media file has an audio stream. */
+export async function hasAudio(file: string): Promise<boolean> {
+  const out = await run('ffprobe', ['-v', 'error', '-select_streams', 'a', '-show_entries', 'stream=index', '-of', 'csv=p=0', file]);
+  return out.trim().length > 0;
+}

package/src/lint.ts

@@ -0,0 +1,128 @@
+import type { Script, Step } from './script/schema';
+import { stepKey } from './timeline/narration';
+import { outputDurationMs, sourceToOutput } from './timeline/timemap';
+import type { StepEvent, Timeline } from './timeline/types';
+
+export interface Issue {
+  rule:
+    | 'caption-length'
+    | 'pause-for-loading'
+    | 'show-ignored'
+    | 'no-intro'
+    | 'caption-too-short'
+    | 'video-length'
+    | 'narration-stretch';
+  level: 'warn' | 'info';
+  /** `scene#step` (1-based), `setup#n`, or `script` */
+  where: string;
+  message: string;
+}
+
+const MAX_CAPTION_WORDS = 6;
+const LOADING_PAUSE_MS = 1500;
+/** Holding the frame this long for a voice is worth a note; twice as long, a warning. */
+const STRETCH_INFO_MS = 1500;
+const STRETCH_WARN_MS = 3000;
+const ACTIONS = new Set<Step['do']>(['click', 'press', 'type', 'select']);
+const TARGETED = new Set<Step['do']>(['click', 'type', 'hover', 'select']);
+
+const words = (text: string) => text.trim().split(/\s+/).filter(Boolean).length;
+const hasTarget = (s: Step) => TARGETED.has(s.do) || (s.do === 'scroll' && s.target !== undefined);
+/** Reading time for a caption: half a second to notice it, a quarter per word, never under 1.2 s. */
+export const readingMs = (text: string) => Math.max(1200, 500 + 250 * words(text));
+
+/** Checks that need only the script. */
+export function lintScript(script: Script): Issue[] {
+  const issues: Issue[] = [];
+  if (!script.meta.title) {
+    issues.push({ rule: 'no-intro', level: 'info', where: 'script', message: 'No meta.title, so the video starts without an intro card.' });
+  }
+  script.setup.forEach((step, i) => {
+    if (step.show) {
+      issues.push({
+        rule: 'show-ignored',
+        level: 'warn',
+        where: `setup#${i + 1}`,
+        message: 'Setup steps run before the camera starts, so their `show` does nothing.',
+      });
+    }
+  });
+  for (const scene of script.scenes) {
+    scene.steps.forEach((step, i) => {
+      const where = `${scene.id}#${i + 1}`;
+      const caption = step.show?.caption;
+      if (caption && words(caption) > MAX_CAPTION_WORDS) {
+        issues.push({
+          rule: 'caption-length',
+          level: 'warn',
+          where,
+          message: `Caption has ${words(caption)} words; keep it to ${MAX_CAPTION_WORDS} or fewer: "${caption}"`,
+        });
+      }
+      const zooms = typeof step.show?.zoom === 'number';
+      if ((zooms || step.show?.spotlight) && !hasTarget(step)) {
+        issues.push({
+          rule: 'show-ignored',
+          level: 'warn',
+          where,
+          message: `\`${step.do}\` has no target, so ${zooms ? 'zoom' : 'spotlight'} does nothing here.`,
+        });
+      }
+      const prev = scene.steps[i - 1];
+      if (step.do === 'pause' && step.ms >= LOADING_PAUSE_MS && prev && ACTIONS.has(prev.do)) {
+        issues.push({
+          rule: 'pause-for-loading',
+          level: 'warn',
+          where,
+          message: 'A long pause right after an action usually waits for loading. Use { "do": "wait", "for": "<what appears>" } so it is sped up.',
+        });
+      }
+    });
+  }
+  return issues;
+}
+
+/** Checks on the edited result: caption reading time and overall length (output time). */
+export function lintTiming(timeline: Timeline, steps: StepEvent[]): Issue[] {
+  const issues: Issue[] = [];
+  for (const c of timeline.captions) {
+    const shown = sourceToOutput(timeline.segments, c.endMs) - sourceToOutput(timeline.segments, c.startMs);
+    const need = readingMs(c.text);
+    if (shown < need) {
+      const step = steps.find((s) => s.startMs === c.startMs);
+      issues.push({
+        rule: 'caption-too-short',
+        level: 'warn',
+        where: step ? `${step.sceneId}#${step.index + 1}` : 'script',
+        // Round shown down and needed up, so the numbers never read as equal.
+        message: `"${c.text}" is on screen for ${(Math.floor(shown / 100) / 10).toFixed(1)} s but needs about ${(Math.ceil(need / 100) / 10).toFixed(1)} s to read. Add show.hold or slow the step down.`,
+      });
+    }
+  }
+  // Each line's holds sit between its step's start and the next narrated step's start.
+  const starts = timeline.narration.map((n) => steps.find((s) => stepKey(s.sceneId, s.index) === n.where)?.startMs ?? Infinity);
+  timeline.narration.forEach((n, i) => {
+    const until = starts[i + 1] ?? Infinity;
+    const held = timeline.segments
+      .filter((s) => s.speed === 0 && s.srcStartMs >= starts[i] && s.srcStartMs < until)
+      .reduce((ms, s) => ms + (s.holdMs ?? 0), 0);
+    if (held > STRETCH_INFO_MS) {
+      issues.push({
+        rule: 'narration-stretch',
+        level: held > STRETCH_WARN_MS ? 'warn' : 'info',
+        where: n.where,
+        message: `"${n.text}" holds the frame for ${(held / 1000).toFixed(1)} s while the voice finishes. Shorten the line or slow the steps.`,
+      });
+    }
+  });
+  const totalMs = (timeline.intro?.durationMs ?? 0) + outputDurationMs(timeline.segments) + (timeline.outro?.durationMs ?? 0);
+  if (totalMs > 60_000) {
+    issues.push({
+      rule: 'video-length',
+      level: totalMs > 120_000 ? 'warn' : 'info',
+      where: 'script',
+      message: `The video runs ${Math.round(totalMs / 1000)} s; pitch demos land best under a minute.`,
+    });
+  }
+  return issues;
+}

package/src/logo.ts

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const TYPES: Record<string, string> = {
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+};
+const MAX_BYTES = 2_000_000;
+
+/** The logo file as a data URI, so timeline.json carries it to the renderer without extra files. */
+export async function logoDataUri(file: string): Promise<string> {
+  const type = TYPES[path.extname(file).toLowerCase()];
+  if (!type) throw new Error(`meta.logo must be an SVG, PNG, JPEG or WebP file: ${file}`);
+  const data = await readFile(file);
+  if (data.length > MAX_BYTES) throw new Error(`meta.logo is larger than 2 MB: ${file}`);
+  return `data:${type};base64,${data.toString('base64')}`;
+}

package/src/paths.ts

@@ -1,15 +1,23 @@
 import path from 'node:path';
 import type { LoadedScript } from './script/load';
+import type { Aspect } from './timeline/types';
 
 export interface WorkPaths {
   root: string;
   check: string;
   take: string;
+  /** a take being recorded; swapped in for `take` only when it succeeds */
+  takeTmp: string;
   rawFrames: string;
   raw: string;
   events: string;
   timeline: string;
   stills: string;
+  /** contact sheet of the stills */
+  sheet: string;
+  /** voice cache and the mixed soundtrack */
+  audio: string;
+  mix: string;
   video: string;
 }
 
@@ -20,11 +28,22 @@ export function workPaths(loaded: LoadedScript): WorkPaths {
     root,
     check: path.join(root, 'check'),
     take,
+    takeTmp: path.join(root, 'take.tmp'),
     rawFrames: path.join(take, 'frames'),
     raw: path.join(take, 'raw.mp4'),
     events: path.join(take, 'events.json'),
     timeline: path.join(root, 'timeline.json'),
     stills: path.join(root, 'frames'),
+    sheet: path.join(root, 'frames', 'sheet.png'),
+    audio: path.join(root, 'audio'),
+    mix: path.join(root, 'audio', 'mix.wav'),
     video: path.join(loaded.dir, `${loaded.name}.mp4`),
   };
 }
+
+/** QA stills of one format: `frames/` for 16:9, `frames-9x16/` and `frames-1x1/` for the crops. */
+export function stillsFor(paths: WorkPaths, aspect: Aspect): { dir: string; sheet: string } {
+  if (aspect === '16:9') return { dir: paths.stills, sheet: paths.sheet };
+  const dir = `${paths.stills}-${aspect.replace(':', 'x')}`;
+  return { dir, sheet: path.join(dir, 'sheet.png') };
+}

package/src/pipeline.ts

@@ -1,38 +1,116 @@
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { workPaths } from './paths';
+import { mixSoundtrack } from './audio/soundtrack';
+import { ensureVoices, type VoiceClip } from './audio/tts';
+import { ANIMATION_WIDTH, defaultOutput, formatOf, toGif, toWebp, type Format } from './convert';
+import { probeVideo } from './ffmpeg';
+import { logoDataUri } from './logo';
+import { stillsFor, workPaths } from './paths';
 import { renderStills, renderVideo } from './render/render';
+import { contactSheet } from './sheet';
 import type { LoadedScript } from './script/load';
 import { loadTake } from './take';
 import { buildTimeline } from './timeline/build';
-import { qaShots } from './timeline/frames';
-import type { TakeEvents, Timeline } from './timeline/types';
+import { introFrames, qaShots } from './timeline/frames';
+import { toSrt } from './timeline/narration';
+import type { Aspect, TakeEvents, Timeline } from './timeline/types';
 
-export async function timelineFor(loaded: LoadedScript): Promise<{ timeline: Timeline; events: TakeEvents }> {
+export interface TimelineOptions {
+  log?: (line: string) => void;
+  aspect?: Aspect;
+  /** false: leave narration out (no synthesis, no holds), for outputs nobody hears */
+  voices?: boolean;
+}
+
+/** The timeline for the last take, with narration synthesized (cached) and its holds in place. */
+export async function timelineFor(
+  loaded: LoadedScript,
+  opts: TimelineOptions = {},
+): Promise<{ timeline: Timeline; events: TakeEvents; clips: Record<string, VoiceClip> }> {
   const events = await loadTake(loaded);
-  const timeline = buildTimeline(loaded.script, events);
+  const clips = opts.voices === false ? {} : await ensureVoices(loaded, { log: opts.log });
+  const { logo } = loaded.script.meta;
+  const timeline = buildTimeline(loaded.script, events, {
+    aspect: opts.aspect,
+    logo: logo ? await logoDataUri(logo) : undefined,
+    voices: Object.fromEntries(Object.entries(clips).map(([where, c]) => [where, c.durationMs])),
+  });
+  await writeTimeline(loaded, timeline);
+  return { timeline, events, clips };
+}
+
+async function writeTimeline(loaded: LoadedScript, timeline: Timeline) {
   const paths = workPaths(loaded);
   await mkdir(paths.root, { recursive: true });
   await writeFile(paths.timeline, JSON.stringify(timeline, null, 2));
-  return { timeline, events };
 }
 
-export async function renderDemo(
-  loaded: LoadedScript,
-  opts: { out?: string; onProgress?: (progress: number) => void } = {},
-): Promise<string> {
-  const { timeline } = await timelineFor(loaded);
+export interface RenderOptions extends TimelineOptions {
+  /** default: `<name>[-9x16|-1x1].<format>` next to the script */
+  out?: string;
+  /** default: from `out`'s extension, else mp4 */
+  format?: Format;
+  /** GIF/WebP width in px */
+  width?: number;
+  onProgress?: (progress: number) => void;
+  /** false: no soundtrack, even with narration, music or sounds */
+  audio?: boolean;
+}
+
+export interface RenderResult {
+  video: string;
+  durationMs: number;
+  /** the .srt written next to an MP4 with narration subtitles */
+  subtitles: string | null;
+}
+
+export async function renderDemo(loaded: LoadedScript, opts: RenderOptions = {}): Promise<RenderResult> {
+  const aspect = opts.aspect ?? '16:9';
+  const format = opts.format ?? formatOf(opts.out);
+  const out = path.resolve(opts.out ?? defaultOutput(loaded, aspect, format));
+  // A silent output (GIF, WebP, --no-audio) only needs the voices to time burned-in subtitles.
+  const silent = format !== 'mp4' || opts.audio === false;
+  const voices = !silent || loaded.script.audio.subtitles === 'burn';
+  const { timeline, clips } = await timelineFor(loaded, { ...opts, voices });
   const paths = workPaths(loaded);
-  const out = path.resolve(opts.out ?? paths.video);
   await mkdir(path.dirname(out), { recursive: true });
-  await renderVideo(timeline, paths.take, out, opts.onProgress);
-  return out;
+
+  if (format !== 'mp4') {
+    // GIF and WebP are cut from a silent MP4 render.
+    const mp4 = path.join(paths.root, `render-${aspect.replace(':', 'x')}.mp4`);
+    await renderVideo(timeline, paths.root, mp4, opts.onProgress);
+    const width = opts.width ?? ANIMATION_WIDTH[aspect];
+    await (format === 'gif' ? toGif(mp4, out, width) : toWebp(mp4, out, width));
+    return { video: out, durationMs: (await probeVideo(mp4)).durationMs, subtitles: null };
+  }
+
+  if (opts.audio !== false) {
+    const src = await mixSoundtrack(loaded, timeline, clips);
+    if (src) {
+      timeline.audio = { src };
+      await writeTimeline(loaded, timeline);
+    }
+  }
+  await renderVideo(timeline, paths.root, out, opts.onProgress);
+  let subtitles: string | null = null;
+  if (timeline.subtitles.length) {
+    subtitles = out.replace(/\.[^./\\]+$/, '') + '.srt';
+    await writeFile(subtitles, toSrt(timeline.subtitles, (introFrames(timeline) * 1000) / timeline.fps));
+  }
+  return { video: out, durationMs: (await probeVideo(out)).durationMs, subtitles };
 }
 
-export async function renderQaFrames(loaded: LoadedScript): Promise<string[]> {
-  const { timeline, events } = await timelineFor(loaded);
+/** QA stills (intro, one per step, outro) and a contact sheet of all of them. */
+export async function renderQaFrames(loaded: LoadedScript, opts: TimelineOptions = {}): Promise<{ sheet: string; frames: string[] }> {
+  const { timeline, events } = await timelineFor(loaded, opts);
   const paths = workPaths(loaded);
-  await rm(paths.stills, { recursive: true, force: true });
-  await mkdir(paths.stills, { recursive: true });
-  return renderStills(timeline, paths.take, paths.stills, qaShots(timeline, events.steps));
+  const stills = stillsFor(paths, timeline.aspect);
+  await rm(stills.dir, { recursive: true, force: true });
+  await mkdir(stills.dir, { recursive: true });
+  const frames = await renderStills(timeline, paths.root, stills.dir, qaShots(timeline, events.steps));
+  const sheet = await contactSheet(
+    frames.map((file) => ({ file, label: path.basename(file, '.png') })),
+    stills.sheet,
+  );
+  return { sheet, frames };
 }