@mineo71/showtime 0.3.0 → 0.4.0

package/src/lint.ts

@@ -1,9 +1,17 @@
 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';
+  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;
@@ -12,6 +20,9 @@ export interface Issue {
 
 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']);
 
@@ -88,6 +99,22 @@ export function lintTiming(timeline: Timeline, steps: StepEvent[]): Issue[] {
       });
     }
   }
+  // 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({

package/src/paths.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import type { LoadedScript } from './script/load';
+import type { Aspect } from './timeline/types';
 
 export interface WorkPaths {
   root: string;
@@ -14,6 +15,9 @@ export interface WorkPaths {
   stills: string;
   /** contact sheet of the stills */
   sheet: string;
+  /** voice cache and the mixed soundtrack */
+  audio: string;
+  mix: string;
   video: string;
 }
 
@@ -31,6 +35,15 @@ export function workPaths(loaded: LoadedScript): WorkPaths {
     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,47 +1,116 @@
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+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 { workPaths } from './paths';
+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 clips = opts.voices === false ? {} : await ensureVoices(loaded, { log: opts.log });
   const { logo } = loaded.script.meta;
-  const timeline = buildTimeline(loaded.script, events, { logo: logo ? await logoDataUri(logo) : undefined });
+  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 };
 }
 
 /** QA stills (intro, one per step, outro) and a contact sheet of all of them. */
-export async function renderQaFrames(loaded: LoadedScript): Promise<{ sheet: string; frames: string[] }> {
-  const { timeline, events } = await timelineFor(loaded);
+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 });
-  const frames = await 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') })),
-    paths.sheet,
+    stills.sheet,
   );
   return { sheet, frames };
 }

package/src/render/remotion/Intro.tsx

@@ -20,7 +20,7 @@ export const Intro: FC<{ timeline: Timeline; frame: number }> = ({ timeline: t,
         textAlign: 'center',
       }}
     >
-      <div style={{ opacity: Math.min(enter, exit), transform: `scale(${0.94 + 0.06 * enter})` }}>
+      <div style={{ maxWidth: '86%', opacity: Math.min(enter, exit), transform: `scale(${0.94 + 0.06 * enter})` }}>
         <Logo src={t.logo} />
         <div style={{ fontSize: 88, fontWeight: 800, letterSpacing: -1.5 }}>{t.intro?.title}</div>
         {t.intro?.subtitle ? <div style={{ marginTop: 18, fontSize: 36, opacity: 0.75 }}>{t.intro.subtitle}</div> : null}

package/src/render/remotion/Outro.tsx

@@ -11,7 +11,7 @@ export const Outro: FC<{ timeline: Timeline; frame: number }> = ({ timeline: t,
     <AbsoluteFill
       style={{ background: t.style.background, fontFamily: t.style.font, alignItems: 'center', justifyContent: 'center', color: '#fff', textAlign: 'center' }}
     >
-      <div style={{ opacity: enter, transform: `translateY(${(1 - enter) * 24}px)` }}>
+      <div style={{ maxWidth: '86%', opacity: enter, transform: `translateY(${(1 - enter) * 24}px)` }}>
         <Logo src={t.logo} />
         <div style={{ fontSize: 80, fontWeight: 800, letterSpacing: -1.5 }}>{o?.title}</div>
         {o?.subtitle ? <div style={{ marginTop: 18, fontSize: 34, opacity: 0.75 }}>{o.subtitle}</div> : null}

package/src/render/remotion/Overlays.tsx

@@ -1,5 +1,6 @@
-import type { FC } from 'react';
+import type { CSSProperties, FC } from 'react';
 import { ripplesAt } from '../../timeline/cursor';
+import { CAPTION_FADE_MS, SPOTLIGHT_FADE_MS } from '../../timeline/fades';
 import { clamp, easeOutCubic } from '../../timeline/math';
 import type { Timeline } from '../../timeline/types';
 
@@ -25,7 +26,7 @@ export const Spotlights: FC<LayerProps> = ({ timeline, srcMs }) => (
             boxShadow: '0 0 0 9999px rgba(2, 6, 23, 0.55)',
             outline: `3px solid ${timeline.style.accent}`,
             outlineOffset: 2,
-            opacity: envelope(srcMs, s.startMs, s.endMs, 250),
+            opacity: envelope(srcMs, s.startMs, s.endMs, SPOTLIGHT_FADE_MS),
           }}
         />
       ))}
@@ -55,23 +56,19 @@ export const Ripples: FC<LayerProps> = ({ timeline, srcMs }) => (
   </>
 );
 
-/** `top` is where a top caption's box starts (output px); bottom captions sit at a fixed inset. */
-export const Captions: FC<LayerProps & { top: number }> = ({ timeline, srcMs, top }) => {
+/** Where an overlay row sits: an inset from the top or bottom, or a band (top + height / top + bottom). */
+type Place = Pick<CSSProperties, 'top' | 'bottom' | 'height' | 'alignItems'>;
+
+const row = (place: Place): CSSProperties => ({ position: 'absolute', left: 0, right: 0, display: 'flex', justifyContent: 'center', ...place });
+
+/** The active caption, placed at `top` or `bottom` by its position. */
+export const Captions: FC<LayerProps & { top: Place; bottom: Place; fontSize: number }> = ({ timeline, srcMs, top, bottom, fontSize }) => {
   const active = timeline.captions.filter((c) => srcMs >= c.startMs && srcMs <= c.endMs);
   const c = active[active.length - 1];
   if (!c) return null;
-  const o = envelope(srcMs, c.startMs, c.endMs, 220);
+  const o = envelope(srcMs, c.startMs, c.endMs, CAPTION_FADE_MS);
   return (
-    <div
-      style={{
-        position: 'absolute',
-        left: 0,
-        right: 0,
-        ...(c.position === 'top' ? { top } : { bottom: Math.round(timeline.output.height * 0.075) }),
-        display: 'flex',
-        justifyContent: 'center',
-      }}
-    >
+    <div style={row(c.position === 'top' ? top : bottom)}>
       <div
         style={{
           maxWidth: '70%',
@@ -80,7 +77,7 @@ export const Captions: FC<LayerProps & { top: number }> = ({ timeline, srcMs, to
           background: 'rgba(15, 23, 42, 0.9)',
           color: '#fff',
           fontFamily: timeline.style.font,
-          fontSize: 36,
+          fontSize,
           fontWeight: 600,
           lineHeight: 1.25,
           textAlign: 'center',
@@ -94,3 +91,30 @@ export const Captions: FC<LayerProps & { top: number }> = ({ timeline, srcMs, to
     </div>
   );
 };
+
+/** Burned-in narration subtitles. `videoMs` is output time from the start of the video. */
+export const Subtitles: FC<{ timeline: Timeline; videoMs: number; place: Place; fontSize: number }> = ({ timeline, videoMs, place, fontSize }) => {
+  if (!timeline.subtitlesBurned) return null;
+  const c = timeline.subtitles.find((s) => videoMs >= s.startMs && videoMs < s.endMs);
+  if (!c) return null;
+  return (
+    <div style={row(place)}>
+      <div
+        style={{
+          maxWidth: '80%',
+          padding: '10px 24px',
+          borderRadius: 12,
+          background: 'rgba(0, 0, 0, 0.72)',
+          color: '#fff',
+          fontFamily: timeline.style.font,
+          fontSize,
+          fontWeight: 500,
+          lineHeight: 1.35,
+          textAlign: 'center',
+        }}
+      >
+        {c.text}
+      </div>
+    </div>
+  );
+};

package/src/render/remotion/ShowtimeVideo.tsx

@@ -1,20 +1,28 @@
 import type { FC } from 'react';
-import { AbsoluteFill, Easing, interpolate, OffthreadVideo, Sequence, staticFile, useCurrentFrame } from 'remotion';
+import { AbsoluteFill, Easing, Freeze, Html5Audio, interpolate, OffthreadVideo, Sequence, staticFile, useCurrentFrame } from 'remotion';
 import { cameraAt, cameraTransform } from '../../timeline/camera';
 import { introFrames, segmentPlan, sourceMsAtFrame, videoEndFrame } from '../../timeline/frames';
-import { BROWSER_BAR, windowLayout } from '../../timeline/layout';
+import { BROWSER_BAR, viewLayout } from '../../timeline/layout';
 import type { Timeline } from '../../timeline/types';
 import { BrowserBar } from './BrowserBar';
 import { Cursor } from './Cursor';
 import { Intro } from './Intro';
 import { Outro } from './Outro';
-import { Captions, Ripples, Spotlights } from './Overlays';
+import { Captions, Ripples, Spotlights, Subtitles } from './Overlays';
 
 export type ShowtimeVideoProps = { timeline: Timeline };
 
 const SHADOW = '0 30px 80px rgba(0, 0, 0, 0.45), 0 8px 24px rgba(0, 0, 0, 0.25)';
 
-export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
+/** The soundtrack plays across every frame; the picture switches between cards and the take. */
+export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => (
+  <>
+    {t.audio ? <Html5Audio src={staticFile(t.audio.src)} /> : null}
+    <Picture timeline={t} />
+  </>
+);
+
+const Picture: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
   const frame = useCurrentFrame();
   const intro = introFrames(t);
   if (frame < intro) return <Intro timeline={t} frame={frame} />;
@@ -22,9 +30,15 @@ export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
   if (t.outro && frame >= end) return <Outro timeline={t} frame={frame - end} />;
 
   const src = sourceMsAtFrame(t, frame) ?? 0;
-  const win = windowLayout(t.output, t.stage, t.style.padding, t.chrome ? BROWSER_BAR : 0);
+  const win = viewLayout(t.output, t.stage, t.style.padding, t.chrome ? BROWSER_BAR : 0, t.aspect);
   const cam = cameraAt(t.camera, src);
-  const k = win.width / t.stage.width;
+  const { content } = win;
+  const k = content.width / t.stage.width;
+  const H = t.output.height;
+  // 9:16 puts captions and subtitles in the bands above and below the window; the others overlay it.
+  const bands = t.aspect === '9:16';
+  const above = { top: 0, height: win.y - win.bar, alignItems: 'center' } as const;
+  const below = { top: win.y + win.height, bottom: 0, alignItems: 'center' } as const;
   // After an intro card the window rises into place instead of cutting in.
   const enter = intro
     ? interpolate(frame - intro, [0, 16], [0, 1], { extrapolateLeft: 'clamp', extrapolateRight: 'clamp', easing: Easing.out(Easing.cubic) })
@@ -56,23 +70,28 @@ export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
               position: 'absolute',
               left: 0,
               top: 0,
-              width: win.width,
-              height: win.height,
+              width: content.width,
+              height: content.height,
               transformOrigin: '0 0',
-              transform: cameraTransform(cam, win.width, win.height),
+              transform: cameraTransform(cam, win.width, win.height, content),
             }}
           >
-            {segmentPlan(t).map((p) => (
-              <Sequence key={p.fromFrame} from={p.fromFrame} durationInFrames={p.durationInFrames} layout="none">
+            {segmentPlan(t).map((p) => {
+              const video = (
                 <OffthreadVideo
                   src={staticFile(t.video.src)}
                   trimBefore={p.trimBefore}
-                  playbackRate={p.speed}
+                  playbackRate={p.speed || 1}
                   muted
-                  style={{ position: 'absolute', left: 0, top: 0, width: win.width, height: win.height }}
+                  style={{ position: 'absolute', left: 0, top: 0, width: content.width, height: content.height }}
                 />
-              </Sequence>
-            ))}
+              );
+              return (
+                <Sequence key={p.fromFrame} from={p.fromFrame} durationInFrames={p.durationInFrames} layout="none">
+                  {p.speed === 0 ? <Freeze frame={0}>{video}</Freeze> : video}
+                </Sequence>
+              );
+            })}
             <div
               style={{
                 position: 'absolute',
@@ -92,7 +111,19 @@ export const ShowtimeVideo: FC<ShowtimeVideoProps> = ({ timeline: t }) => {
         </div>
       </div>
       <div style={{ opacity: leave }}>
-        <Captions timeline={t} srcMs={src} top={win.y + Math.round(t.output.height * 0.03)} />
+        <Captions
+          timeline={t}
+          srcMs={src}
+          top={bands ? above : { top: win.y + Math.round(H * 0.03) }}
+          bottom={bands ? below : { bottom: Math.round(H * 0.075) }}
+          fontSize={bands ? 46 : 36}
+        />
+        <Subtitles
+          timeline={t}
+          videoMs={((frame - intro) * 1000) / t.fps}
+          place={bands ? below : { bottom: Math.round(H * 0.06) }}
+          fontSize={bands ? 40 : 34}
+        />
       </div>
     </AbsoluteFill>
   );

package/src/render/render.ts

@@ -8,7 +8,7 @@ import type { Timeline } from '../timeline/types';
 const ENTRY = fileURLToPath(new URL('./remotion/index.ts', import.meta.url));
 const COMPOSITION_ID = 'ShowtimeVideo';
 
-/** Bundle the composition with the take directory as public dir, so the raw video is staticFile('raw.mp4'). */
+/** Bundle the composition with `.showtime/<name>/` as public dir: the take is staticFile('take/raw.mp4'). */
 async function prepare(timeline: Timeline, publicDir: string) {
   const serveUrl = await bundle({ entryPoint: ENTRY, publicDir, symlinkPublicDir: true });
   const inputProps = { timeline };

package/src/runner/events.ts

@@ -6,6 +6,8 @@ export class EventLog {
   readonly moves: Move[] = [];
   readonly clicks: Click[] = [];
   readonly idle: Interval[] = [];
+  /** keystroke times of human-paced typing */
+  readonly keys: number[] = [];
 
   constructor(private readonly t0: number = Date.now()) {}
 

package/src/runner/record.ts

@@ -102,6 +102,7 @@ export async function record(loaded: LoadedScript, opts: RecordOptions = {}): Pr
         moves: shot.log.moves,
         clicks: shot.log.clicks,
         idle: shot.log.idle,
+        keys: shot.log.keys,
       };
       await writeFile(path.join(tmp, 'events.json'), JSON.stringify(events, null, 2));
       if (!opts.keepFrames) await rm(frames, { recursive: true, force: true });

package/src/runner/steps.ts

@@ -193,6 +193,7 @@ async function typeText(ctx: StepContext, text: string, pace: 'human' | 'fast' |
   const rand = rng(text);
   for (const ch of text) {
     await ctx.page.keyboard.type(ch);
+    ctx.log.keys.push(ctx.log.now());
     await sleep(typeof pace === 'number' ? pace : 45 + rand() * 65);
   }
 }

package/src/script/config.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
-import { formatIssues, MetaSchema, ScriptError, StyleSchema } from './schema';
+import { AudioSchema, formatIssues, MetaSchema, ScriptError, StyleSchema } from './schema';
 
 export const CONFIG_FILE = 'showtime.config.json';
 
@@ -11,11 +11,17 @@ type Json = Record<string, unknown>;
 export interface BrandConfig {
   style?: Json;
   meta?: Json;
+  audio?: Json;
 }
 
 // Validated on its own so mistakes are blamed on this file; the raw values are what get merged.
 const ConfigSchema = z
-  .object({ $schema: z.string().optional(), style: StyleSchema.partial().optional(), meta: MetaSchema.partial().optional() })
+  .object({
+    $schema: z.string().optional(),
+    style: StyleSchema.partial().optional(),
+    meta: MetaSchema.partial().optional(),
+    audio: AudioSchema.partial().optional(),
+  })
   .strict();
 
 /** The nearest showtime.config.json from `dir` upward, or null. */
@@ -27,7 +33,7 @@ export function findConfig(dir: string): string | null {
   }
 }
 
-/** Read a brand file; paths inside it (meta.logo) resolve against its folder. */
+/** Read a brand file; paths inside it (meta.logo, audio.music.file) resolve against its folder. */
 export async function readConfig(file: string): Promise<BrandConfig> {
   let raw: unknown;
   try {
@@ -37,8 +43,9 @@ export async function readConfig(file: string): Promise<BrandConfig> {
   }
   const parsed = ConfigSchema.safeParse(raw);
   if (!parsed.success) throw new ScriptError(`Invalid ${file}:\n${formatIssues(parsed.error.issues)}`);
-  const { style, meta } = raw as BrandConfig;
-  return { style, meta: withLogoFrom(meta, path.dirname(file)) };
+  const { style, meta, audio } = raw as BrandConfig;
+  const dir = path.dirname(file);
+  return { style, meta: withLogoFrom(meta, dir), audio: withMusicFrom(audio, dir) };
 }
 
 /** meta with `logo` made absolute against `dir` (when it is a string). */
@@ -47,12 +54,21 @@ export function withLogoFrom(meta: Json | undefined, dir: string): Json | undefi
   return { ...meta, logo: path.resolve(dir, meta.logo) };
 }
 
+/** audio with `music.file` made absolute against `dir` (when it is a string). */
+export function withMusicFrom(audio: Json | undefined, dir: string): Json | undefined {
+  const music = audio?.music;
+  if (!isObject(music) || typeof music.file !== 'string') return audio;
+  return { ...audio, music: { ...music, file: path.resolve(dir, music.file) } };
+}
+
 const isObject = (v: unknown): v is Json => typeof v === 'object' && v !== null && !Array.isArray(v);
 
-/** Brand defaults under the raw script: the script wins key by key in `style` and `meta`. */
+/** Brand defaults under the raw script: the script wins key by key in `style`, `meta` and `audio`. */
 export function applyConfig(config: BrandConfig, raw: Json): Json {
   const merged: Json = { ...raw };
-  if (config.style) merged.style = isObject(raw.style) ? { ...config.style, ...raw.style } : (raw.style ?? config.style);
-  if (config.meta) merged.meta = isObject(raw.meta) ? { ...config.meta, ...raw.meta } : (raw.meta ?? config.meta);
+  for (const key of ['style', 'meta', 'audio'] as const) {
+    const defaults = config[key];
+    if (defaults) merged[key] = isObject(raw[key]) ? { ...defaults, ...raw[key] } : (raw[key] ?? defaults);
+  }
   return merged;
 }

package/src/script/load.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { applyConfig, findConfig, readConfig, withLogoFrom } from './config';
+import { applyConfig, findConfig, readConfig, withLogoFrom, withMusicFrom } from './config';
 import { parseScript, ScriptError, type Script } from './schema';
 
 export interface LoadedScript {
@@ -32,10 +32,13 @@ export async function loadScript(file: string): Promise<LoadedScript> {
   if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
     const own = raw as Record<string, unknown>;
     if (own.meta && typeof own.meta === 'object') own.meta = withLogoFrom(own.meta as Record<string, unknown>, dir);
+    if (own.audio && typeof own.audio === 'object') own.audio = withMusicFrom(own.audio as Record<string, unknown>, dir);
     if (config) raw = applyConfig(await readConfig(config), own);
   }
   const script = parseScript(raw, scriptPath);
   if (script.meta.logo && !existsSync(script.meta.logo)) throw new ScriptError(`meta.logo not found: ${script.meta.logo}`);
+  const music = script.audio.music?.file;
+  if (music && !existsSync(music)) throw new ScriptError(`audio.music.file not found: ${music}`);
   if (script.app.storageState) {
     script.app.storageState = path.resolve(dir, script.app.storageState);
     if (!existsSync(script.app.storageState)) {

package/src/script/schema.ts

@@ -15,6 +15,11 @@ export const ShowSchema = z
     spotlight: z.boolean().optional().describe('Dim everything except the target'),
     hold: z.number().int().min(0).max(30_000).optional().describe('Extra real-time ms after the step'),
     speed: z.number().min(0.25).max(16).optional().describe('Playback speed for this step'),
+    say: z
+      .string()
+      .min(1)
+      .optional()
+      .describe('Narration spoken from the start of this step; the video waits for it before the next narrated step'),
   })
   .strict();
 
@@ -146,6 +151,51 @@ export const MetaSchema = z
   })
   .strict();
 
+export const VoiceSchema = z
+  .object({
+    engine: z
+      .enum(['system', 'openai', 'elevenlabs', 'command'])
+      .default('system')
+      .describe('system: macOS say / Linux espeak-ng; openai and elevenlabs read OPENAI_API_KEY / ELEVENLABS_API_KEY'),
+    name: z.string().min(1).optional().describe('Voice name (system, openai) or voice id (elevenlabs)'),
+    speed: z.number().min(0.5).max(2).default(1),
+    model: z.string().min(1).optional().describe('openai: gpt-4o-mini-tts by default; elevenlabs: eleven_multilingual_v2'),
+    instructions: z.string().min(1).optional().describe('openai only: how to speak, e.g. "warm and confident"'),
+    command: z
+      .string()
+      .min(1)
+      .optional()
+      .describe('command engine: shell command that reads the text on stdin and writes audio to {out}'),
+  })
+  .strict()
+  .superRefine((v, ctx) => {
+    if (v.engine === 'elevenlabs' && !v.name) {
+      ctx.addIssue({ code: 'custom', path: ['name'], message: 'elevenlabs needs a voice id in "name"' });
+    }
+    if (v.engine === 'command' && !v.command) {
+      ctx.addIssue({ code: 'custom', path: ['command'], message: 'the command engine needs "command"' });
+    }
+  });
+
+export const AudioSchema = z
+  .object({
+    voice: VoiceSchema.prefault({}).describe('Text-to-speech for show.say'),
+    music: z
+      .object({
+        file: z.string().min(1).describe('Audio file, relative to the file that names it'),
+        volume: z.number().min(0).max(1).default(0.25),
+      })
+      .strict()
+      .optional()
+      .describe('Music bed under the whole video; ducks while the voice speaks'),
+    sounds: z.boolean().default(false).describe('Click and keystroke sounds'),
+    subtitles: z
+      .enum(['off', 'file', 'burn'])
+      .default('file')
+      .describe('Narration subtitles: an .srt next to the video (file), also drawn on the video (burn), or none'),
+  })
+  .strict();
+
 export const SceneSchema = z
   .object({
     id: z.string().regex(/^[A-Za-z0-9_-]+$/, 'scene id may contain letters, digits, "-" and "_"'),
@@ -162,6 +212,7 @@ export const ScriptSchema = z
     hooks: HooksSchema.prefault({}),
     setup: z.array(StepSchema).default([]),
     style: StyleSchema.prefault({}),
+    audio: AudioSchema.prefault({}),
     scenes: z.array(SceneSchema).min(1),
   })
   .strict()
@@ -182,6 +233,8 @@ export type Show = z.output<typeof ShowSchema>;
 export type Style = z.output<typeof StyleSchema>;
 export type Hook = z.output<typeof HookSchema>;
 export type Mock = z.output<typeof MockSchema>;
+export type Audio = z.output<typeof AudioSchema>;
+export type Voice = z.output<typeof VoiceSchema>;
 
 export class ScriptError extends Error {
   constructor(message: string) {