reelson 0.7.0

package/skills/reelson-compose/scripts/verify.js

@@ -0,0 +1,190 @@
+/**
+ * `reelson verify`: does each demo still record, and does its video.json still fit?
+ *
+ * Apps change under their demos: a column moves, a URL changes, a step is added. verify
+ * re-records every scenario headless into a scratch folder — the committed recording and
+ * markers.json stay untouched — and checks the new take against video.json: the scenario
+ * ran to the end, every marker a callout or trim uses still exists, every click a zoom or
+ * trim refers to by number is still the same kind of click in the same place, and the plan
+ * (timeline, zoom checks) still holds. `--update` puts a take that passes in place. A demo
+ * with a phone or square take (markers.mobile.json, markers.square.json) gets those
+ * re-recorded and checked too.
+ *
+ *   reelson verify <slug...> | --all [--update]
+ */
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { planSpec } from "./build.js";
+import { readMarkers, RECORD_SCRIPT, readVideoSpec, ReelsonError } from "./project.js";
+import { checkZoom, zoomOverlaps } from "./zooms.js";
+const count = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
+/** A click that moved more than this (CSS px) is probably a different target. */
+const MOVED_PX = 80;
+/** What a re-record changed that video.json relies on. Pure. */
+export function compareRecordings(before, after, spec) {
+    const problems = [];
+    const notes = [];
+    const labels = new Set(after.markers.map((m) => m.label));
+    const trimPoints = ['start', 'end']
+        .map((edge) => [edge, spec.trim?.[edge]])
+        .filter(([, p]) => p !== undefined && typeof p === 'object');
+    // Markers: the ones video.json uses must still be set.
+    for (const c of spec.callouts ?? []) {
+        if (c.marker !== undefined && !labels.has(c.marker)) {
+            problems.push(`callout "${c.text}" is timed from marker "${c.marker}", which the scenario no longer sets`);
+        }
+    }
+    for (const [edge, p] of trimPoints) {
+        if ('marker' in p && !labels.has(p.marker)) {
+            problems.push(`trim.${edge} is tied to marker "${p.marker}", which the scenario no longer sets`);
+        }
+    }
+    if (before) {
+        const old = new Set(before.markers.map((m) => m.label));
+        const added = after.markers.filter((m) => !old.has(m.label)).map((m) => `"${m.label}"`);
+        const removed = before.markers.filter((m) => !labels.has(m.label)).map((m) => `"${m.label}"`);
+        if (added.length)
+            notes.push(`new marker(s) ${added.join(', ')} — no callout uses them yet`);
+        if (removed.length)
+            notes.push(`marker(s) ${removed.join(', ')} are gone`);
+    }
+    // Clicks are referred to by number: the same number must still be the same click.
+    const clicks = after.clicks ?? [];
+    const used = new Map();
+    (spec.zooms ?? []).forEach((z, i) => {
+        if (!z.clicks)
+            return;
+        const [a, b = a] = z.clicks;
+        for (let n = a; n <= b; n++)
+            used.set(n, `zoom ${i + 1}`);
+    });
+    for (const [edge, p] of trimPoints) {
+        if ('click' in p)
+            used.set(p.click, `trim.${edge}`);
+    }
+    for (const [n, user] of [...used].sort((x, y) => x[0] - y[0])) {
+        const now = clicks[n - 1];
+        if (!now) {
+            problems.push(`${user} uses click #${n}, but the new take has ${clicks.length} click(s)`);
+            continue;
+        }
+        const then = before?.clicks?.[n - 1];
+        if (then) {
+            const moved = Math.hypot(now.x - then.x, now.y - then.y);
+            if (now.kind !== then.kind || moved > MOVED_PX) {
+                problems.push(`${user} uses click #${n}: it was a ${then.kind} at ${then.x},${then.y}, now a ${now.kind} at ${now.x},${now.y} — ` +
+                    'a step was probably added or removed before it; renumber the clicks in video.json');
+            }
+        }
+    }
+    if (before?.clicks && before.clicks.length !== clicks.length) {
+        notes.push(`${before.clicks.length} → ${clicks.length} click(s)`);
+    }
+    if (before && (before.transitions?.length ?? 0) !== (after.transitions?.length ?? 0)) {
+        notes.push(`${before.transitions?.length ?? 0} → ${after.transitions?.length ?? 0} hand-off card(s)`);
+    }
+    if (before && Math.abs(after.durationSeconds - before.durationSeconds) > Math.max(3, before.durationSeconds * 0.2)) {
+        notes.push(`length ${before.durationSeconds.toFixed(1)}s → ${after.durationSeconds.toFixed(1)}s`);
+    }
+    return { problems, notes };
+}
+/** The recordings a demo can have: the desktop one, and the takes behind portrait and square. */
+export const TAKES = [
+    { name: 'desktop', suffix: '', flags: [] },
+    { name: 'phone', suffix: '.mobile', flags: ['--mobile'] },
+    { name: 'square', suffix: '.square', flags: ['--square'] },
+];
+/** The takes this demo has (its markers are there): desktop always, phone and square if recorded. */
+export function takesOf(demoDir) {
+    return TAKES.filter((take) => take.suffix === '' || existsSync(resolve(demoDir, `markers${take.suffix}.json`)));
+}
+/** Re-records each take of one demo and checks it; returns the number of problems. */
+export function verify(demoDir, config, options = {}) {
+    const log = options.log ?? console.log;
+    const scenario = resolve(demoDir, 'scenario.ts');
+    if (!existsSync(scenario)) {
+        throw new ReelsonError(`${demoDir} has no scenario.ts`);
+    }
+    let problems = 0;
+    for (const take of takesOf(demoDir)) {
+        problems += verifyTake(demoDir, scenario, take, config, options, log);
+    }
+    return problems;
+}
+function verifyTake(demoDir, scenario, take, config, options, log) {
+    const slug = take.suffix ? `${basename(demoDir)} (${take.name})` : basename(demoDir);
+    const recording = `recording${take.suffix}.mp4`;
+    const markersFile = `markers${take.suffix}.json`;
+    const dir = mkdtempSync(join(tmpdir(), `reelson-verify-${basename(demoDir)}${take.suffix}-`));
+    log(`${slug}: recording…`);
+    const run = spawnSync(process.execPath, [RECORD_SCRIPT, scenario, '--out', dir, ...take.flags], {
+        encoding: 'utf8',
+    });
+    if (run.status !== 0) {
+        const output = `${run.stdout}${run.stderr}`.trim().split('\n').filter((l) => !/^\s+at /.test(l));
+        log(`✗ ${slug}: the scenario failed`);
+        output.slice(-8).forEach((line) => log(`    ${line}`));
+        const failed = resolve(dir, `recording${take.suffix}.failed.mp4`);
+        if (existsSync(failed))
+            log(`    partial take: ${failed}`);
+        return 1;
+    }
+    const after = JSON.parse(readFileSync(resolve(dir, markersFile), 'utf8'));
+    const before = existsSync(resolve(demoDir, markersFile)) ? JSON.parse(readFileSync(resolve(demoDir, markersFile), 'utf8')) : null;
+    const video = readVideoSpec(demoDir);
+    const problems = [];
+    const notes = [];
+    if (!video) {
+        notes.push('no video.json yet — nothing to check against (run `reelson build`)');
+    }
+    else {
+        // As the build uses it: the phone take never zooms; the square one zooms while its clicks
+        // match the desktop take's (video.json numbers them by the desktop clicks).
+        let spec = video;
+        if (take.name === 'phone') {
+            spec = { ...video, zooms: [] };
+        }
+        else if (take.name === 'square' && video.zooms?.length) {
+            const desktop = existsSync(resolve(demoDir, 'markers.json')) ? readMarkers(demoDir) : null;
+            if (desktop && (desktop.clicks?.length ?? 0) !== (after.clicks?.length ?? 0)) {
+                notes.push(`${count(after.clicks?.length ?? 0, 'click')}, the desktop take ${desktop.clicks?.length ?? 0} — the square video leaves out the zooms`);
+                spec = { ...video, zooms: [] };
+            }
+        }
+        const drift = compareRecordings(before, after, spec);
+        problems.push(...drift.problems);
+        notes.push(...drift.notes);
+        try {
+            const plan = planSpec(demoDir, spec, after, config);
+            notes.push(...plan.warnings);
+            const overlaps = zoomOverlaps(plan.zooms);
+            plan.zooms.forEach((z, i) => {
+                for (const p of [...checkZoom(z, plan.clicks, plan.timeline).problems, ...overlaps.filter((o) => o.index === i).map((o) => o.message)]) {
+                    problems.push(`zoom ${i + 1}: ${p}`);
+                }
+            });
+        }
+        catch (error) {
+            problems.push(error.message);
+        }
+    }
+    for (const p of problems)
+        log(`✗ ${slug}: ${p}`);
+    for (const n of notes)
+        log(`! ${slug}: ${n}`);
+    if (!problems.length) {
+        log(`✓ ${slug}: records fine and video.json still fits (${after.durationSeconds.toFixed(1)}s, ${count(after.markers.length, 'marker')}, ${count(after.clicks?.length ?? 0, 'click')})`);
+        if (options.update) {
+            copyFileSync(resolve(dir, recording), resolve(demoDir, recording));
+            copyFileSync(resolve(dir, markersFile), resolve(demoDir, markersFile));
+            log(`  updated ${basename(demoDir)}/${recording} and ${markersFile} — rebuild to use them`);
+        }
+        rmSync(dir, { recursive: true, force: true });
+    }
+    else {
+        log(`  new take kept for a look: ${dir}`);
+    }
+    return problems.length;
+}

package/skills/reelson-compose/scripts/verify.ts

@@ -0,0 +1,209 @@
+/**
+ * `reelson verify`: does each demo still record, and does its video.json still fit?
+ *
+ * Apps change under their demos: a column moves, a URL changes, a step is added. verify
+ * re-records every scenario headless into a scratch folder — the committed recording and
+ * markers.json stay untouched — and checks the new take against video.json: the scenario
+ * ran to the end, every marker a callout or trim uses still exists, every click a zoom or
+ * trim refers to by number is still the same kind of click in the same place, and the plan
+ * (timeline, zoom checks) still holds. `--update` puts a take that passes in place. A demo
+ * with a phone or square take (markers.mobile.json, markers.square.json) gets those
+ * re-recorded and checked too.
+ *
+ *   reelson verify <slug...> | --all [--update]
+ */
+import { spawnSync } from 'node:child_process'
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, join, resolve } from 'node:path'
+import type { LoadedConfig } from '../../reelson-record/scripts/config.ts'
+import { planSpec } from './build.ts'
+import { readMarkers, RECORD_SCRIPT, readVideoSpec, ReelsonError } from './project.ts'
+import type { Markers, TrimPoint, VideoSpec } from './timeline.ts'
+import { checkZoom, zoomOverlaps } from './zooms.ts'
+
+export interface Drift {
+    /** video.json no longer fits the new take. */
+    problems: string[]
+    /** Worth knowing, nothing broken. */
+    notes: string[]
+}
+
+const count = (n: number, noun: string): string => `${n} ${noun}${n === 1 ? '' : 's'}`
+
+/** A click that moved more than this (CSS px) is probably a different target. */
+const MOVED_PX = 80
+
+/** What a re-record changed that video.json relies on. Pure. */
+export function compareRecordings(before: Markers | null, after: Markers, spec: VideoSpec): Drift {
+    const problems: string[] = []
+    const notes: string[] = []
+    const labels = new Set(after.markers.map((m) => m.label))
+    const trimPoints = (['start', 'end'] as const)
+        .map((edge) => [edge, spec.trim?.[edge]] as [string, TrimPoint | undefined])
+        .filter(([, p]) => p !== undefined && typeof p === 'object') as [string, Exclude<TrimPoint, number | 'auto'>][]
+
+    // Markers: the ones video.json uses must still be set.
+    for (const c of spec.callouts ?? []) {
+        if (c.marker !== undefined && !labels.has(c.marker)) {
+            problems.push(`callout "${c.text}" is timed from marker "${c.marker}", which the scenario no longer sets`)
+        }
+    }
+    for (const [edge, p] of trimPoints) {
+        if ('marker' in p && !labels.has(p.marker)) {
+            problems.push(`trim.${edge} is tied to marker "${p.marker}", which the scenario no longer sets`)
+        }
+    }
+    if (before) {
+        const old = new Set(before.markers.map((m) => m.label))
+        const added = after.markers.filter((m) => !old.has(m.label)).map((m) => `"${m.label}"`)
+        const removed = before.markers.filter((m) => !labels.has(m.label)).map((m) => `"${m.label}"`)
+        if (added.length) notes.push(`new marker(s) ${added.join(', ')} — no callout uses them yet`)
+        if (removed.length) notes.push(`marker(s) ${removed.join(', ')} are gone`)
+    }
+
+    // Clicks are referred to by number: the same number must still be the same click.
+    const clicks = after.clicks ?? []
+    const used = new Map<number, string>()
+    ;(spec.zooms ?? []).forEach((z, i) => {
+        if (!z.clicks) return
+        const [a, b = a] = z.clicks
+        for (let n = a; n <= b; n++) used.set(n, `zoom ${i + 1}`)
+    })
+    for (const [edge, p] of trimPoints) {
+        if ('click' in p) used.set(p.click, `trim.${edge}`)
+    }
+    for (const [n, user] of [...used].sort((x, y) => x[0] - y[0])) {
+        const now = clicks[n - 1]
+        if (!now) {
+            problems.push(`${user} uses click #${n}, but the new take has ${clicks.length} click(s)`)
+            continue
+        }
+        const then = before?.clicks?.[n - 1]
+        if (then) {
+            const moved = Math.hypot(now.x - then.x, now.y - then.y)
+            if (now.kind !== then.kind || moved > MOVED_PX) {
+                problems.push(
+                    `${user} uses click #${n}: it was a ${then.kind} at ${then.x},${then.y}, now a ${now.kind} at ${now.x},${now.y} — ` +
+                        'a step was probably added or removed before it; renumber the clicks in video.json',
+                )
+            }
+        }
+    }
+    if (before?.clicks && before.clicks.length !== clicks.length) {
+        notes.push(`${before.clicks.length} → ${clicks.length} click(s)`)
+    }
+    if (before && (before.transitions?.length ?? 0) !== (after.transitions?.length ?? 0)) {
+        notes.push(`${before.transitions?.length ?? 0} → ${after.transitions?.length ?? 0} hand-off card(s)`)
+    }
+    if (before && Math.abs(after.durationSeconds - before.durationSeconds) > Math.max(3, before.durationSeconds * 0.2)) {
+        notes.push(`length ${before.durationSeconds.toFixed(1)}s → ${after.durationSeconds.toFixed(1)}s`)
+    }
+
+    return { problems, notes }
+}
+
+export interface VerifyOptions {
+    /** Put a take that passes in place of the committed recording + markers. */
+    update?: boolean
+    log?: (line: string) => void
+}
+
+/** The recordings a demo can have: the desktop one, and the takes behind portrait and square. */
+export const TAKES = [
+    { name: 'desktop', suffix: '', flags: [] as string[] },
+    { name: 'phone', suffix: '.mobile', flags: ['--mobile'] },
+    { name: 'square', suffix: '.square', flags: ['--square'] },
+] as const
+export type Take = (typeof TAKES)[number]
+
+/** The takes this demo has (its markers are there): desktop always, phone and square if recorded. */
+export function takesOf(demoDir: string): Take[] {
+    return TAKES.filter((take) => take.suffix === '' || existsSync(resolve(demoDir, `markers${take.suffix}.json`)))
+}
+
+/** Re-records each take of one demo and checks it; returns the number of problems. */
+export function verify(demoDir: string, config: LoadedConfig, options: VerifyOptions = {}): number {
+    const log = options.log ?? console.log
+    const scenario = resolve(demoDir, 'scenario.ts')
+    if (!existsSync(scenario)) {
+        throw new ReelsonError(`${demoDir} has no scenario.ts`)
+    }
+    let problems = 0
+    for (const take of takesOf(demoDir)) {
+        problems += verifyTake(demoDir, scenario, take, config, options, log)
+    }
+    return problems
+}
+
+function verifyTake(demoDir: string, scenario: string, take: Take, config: LoadedConfig, options: VerifyOptions, log: (line: string) => void): number {
+    const slug = take.suffix ? `${basename(demoDir)} (${take.name})` : basename(demoDir)
+    const recording = `recording${take.suffix}.mp4`
+    const markersFile = `markers${take.suffix}.json`
+    const dir = mkdtempSync(join(tmpdir(), `reelson-verify-${basename(demoDir)}${take.suffix}-`))
+    log(`${slug}: recording…`)
+    const run = spawnSync(process.execPath, [RECORD_SCRIPT, scenario, '--out', dir, ...take.flags], {
+        encoding: 'utf8',
+    })
+    if (run.status !== 0) {
+        const output = `${run.stdout}${run.stderr}`.trim().split('\n').filter((l) => !/^\s+at /.test(l))
+        log(`✗ ${slug}: the scenario failed`)
+        output.slice(-8).forEach((line) => log(`    ${line}`))
+        const failed = resolve(dir, `recording${take.suffix}.failed.mp4`)
+        if (existsSync(failed)) log(`    partial take: ${failed}`)
+        return 1
+    }
+
+    const after = JSON.parse(readFileSync(resolve(dir, markersFile), 'utf8')) as Markers
+    const before = existsSync(resolve(demoDir, markersFile)) ? (JSON.parse(readFileSync(resolve(demoDir, markersFile), 'utf8')) as Markers) : null
+    const video = readVideoSpec(demoDir)
+    const problems: string[] = []
+    const notes: string[] = []
+    if (!video) {
+        notes.push('no video.json yet — nothing to check against (run `reelson build`)')
+    } else {
+        // As the build uses it: the phone take never zooms; the square one zooms while its clicks
+        // match the desktop take's (video.json numbers them by the desktop clicks).
+        let spec = video
+        if (take.name === 'phone') {
+            spec = { ...video, zooms: [] }
+        } else if (take.name === 'square' && video.zooms?.length) {
+            const desktop = existsSync(resolve(demoDir, 'markers.json')) ? readMarkers(demoDir) : null
+            if (desktop && (desktop.clicks?.length ?? 0) !== (after.clicks?.length ?? 0)) {
+                notes.push(`${count(after.clicks?.length ?? 0, 'click')}, the desktop take ${desktop.clicks?.length ?? 0} — the square video leaves out the zooms`)
+                spec = { ...video, zooms: [] }
+            }
+        }
+        const drift = compareRecordings(before, after, spec)
+        problems.push(...drift.problems)
+        notes.push(...drift.notes)
+        try {
+            const plan = planSpec(demoDir, spec, after, config)
+            notes.push(...plan.warnings)
+            const overlaps = zoomOverlaps(plan.zooms)
+            plan.zooms.forEach((z, i) => {
+                for (const p of [...checkZoom(z, plan.clicks, plan.timeline).problems, ...overlaps.filter((o) => o.index === i).map((o) => o.message)]) {
+                    problems.push(`zoom ${i + 1}: ${p}`)
+                }
+            })
+        } catch (error) {
+            problems.push((error as Error).message)
+        }
+    }
+
+    for (const p of problems) log(`✗ ${slug}: ${p}`)
+    for (const n of notes) log(`! ${slug}: ${n}`)
+    if (!problems.length) {
+        log(`✓ ${slug}: records fine and video.json still fits (${after.durationSeconds.toFixed(1)}s, ${count(after.markers.length, 'marker')}, ${count(after.clicks?.length ?? 0, 'click')})`)
+        if (options.update) {
+            copyFileSync(resolve(dir, recording), resolve(demoDir, recording))
+            copyFileSync(resolve(dir, markersFile), resolve(demoDir, markersFile))
+            log(`  updated ${basename(demoDir)}/${recording} and ${markersFile} — rebuild to use them`)
+        }
+        rmSync(dir, { recursive: true, force: true })
+    } else {
+        log(`  new take kept for a look: ${dir}`)
+    }
+
+    return problems.length
+}

package/skills/reelson-compose/scripts/voice.js

@@ -0,0 +1,178 @@
+/**
+ * Voice-over: each callout spoken as it appears (video.json "voice": true).
+ *
+ * Lines are spoken by a text-to-speech provider (demo.config.json `voice.provider`: OpenAI,
+ * ElevenLabs, a local Piper voice or any local command — see tts.ts), trimmed of the silence
+ * around them and cached in <demo>/voice/<hash>.mp3 — the hash covers the words and every
+ * setting that changes the sound, so a line is only made once and a re-render never calls the
+ * provider. `reelson voice <slug>` (and `render`) make the missing lines; the build (sync)
+ * mixes whatever is cached into one track per version (landscape, portrait, square: each has
+ * its own timing), and says what is missing.
+ *
+ * What is spoken: a callout's `say` (false: nothing), else its text; plus video.json
+ * `voice.intro` over the intro, when given.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { ReelsonError } from "./project.js";
+import { round } from "./timeline.js";
+import { missingSetup, providerDefaults, speak } from "./tts.js";
+/** A line starts this long after its callout appears (the pill is read, then heard). */
+const LEAD_IN = 0.25;
+/** The voice settings for a video, or null when it has no voice-over. */
+export function voiceSettings(spec, config) {
+    if (!spec.voice) {
+        return null;
+    }
+    const own = typeof spec.voice === 'object' ? spec.voice : {};
+    const project = config.voice;
+    const provider = own.provider ?? project.provider;
+    // A video switching provider starts from that provider's defaults, not the project's voice.
+    const same = provider === project.provider;
+    const defaults = providerDefaults(provider, config.language);
+    return {
+        provider,
+        model: own.model ?? (same ? project.model : undefined) ?? defaults.model,
+        voice: own.voice ?? (same ? project.voice : undefined) ?? defaults.voice,
+        instructions: own.instructions ?? project.instructions,
+        ...((own.speed ?? project.speed) !== undefined ? { speed: own.speed ?? project.speed } : {}),
+        language: config.language,
+        ...(same && project.baseURL ? { baseURL: project.baseURL } : {}),
+        ...(same && project.command ? { command: project.command } : {}),
+        ...(same && project.options ? { options: project.options } : {}),
+        lufs: project.lufs,
+    };
+}
+/** Everything spoken in this video, in order, timed to `t`. Pure. */
+export function voiceLines(t, spec, settings) {
+    const intro = typeof spec.voice === 'object' ? spec.voice.intro : undefined;
+    const spoken = [
+        ...(intro ? [{ at: round(t.intro.start + 0.4), text: intro, intro: true }] : []),
+        ...t.callouts.map((c) => ({ at: round(c.at + LEAD_IN), text: lineOf(c) })),
+    ].filter((l) => l.text);
+    return spoken.map((line, i) => ({
+        ...line,
+        file: `${lineHash(line.text, settings)}.mp3`,
+        // The intro line runs until the recording comes in; a step's, until the next line.
+        until: round(i === 0 && intro ? t.clipStart + 0.6 : (spoken[i + 1]?.at ?? t.clipEnd)),
+    }));
+}
+/** Bumped when the post-processing (the trim) changes, so cached lines are made again. */
+const CACHE_VERSION = 2;
+/** The cache name of a line: everything that changes how it sounds (not the loudness: the mix sets it). */
+export function lineHash(text, s) {
+    const { lufs: _, ...sound } = s;
+    return createHash('sha1')
+        .update(JSON.stringify([CACHE_VERSION, sound, text]))
+        .digest('hex')
+        .slice(0, 16);
+}
+/** What a callout says (its `say`, else its text); '' when it is silent. */
+function lineOf(c) {
+    return c.say === false ? '' : (c.say || c.text).trim();
+}
+/**
+ * For the timeline: seconds from a callout appearing until its cached line is done (the lead-in
+ * plus the line); 0 when it is silent or not spoken yet.
+ */
+export function spokenLength(settings, cacheDir) {
+    const lengths = new Map();
+    return (c) => {
+        const text = lineOf(c);
+        const file = resolve(cacheDir, `${lineHash(text, settings)}.mp3`);
+        if (!text || !existsSync(file)) {
+            return 0;
+        }
+        if (!lengths.has(file)) {
+            lengths.set(file, lengthOf(file));
+        }
+        return round(LEAD_IN + lengths.get(file));
+    };
+}
+/** Every line the video would speak, without a timeline (for fetching). */
+export function spokenTexts(spec, callouts) {
+    const intro = typeof spec.voice === 'object' ? spec.voice.intro : undefined;
+    return [intro, ...callouts.map(lineOf)].filter((t) => !!t);
+}
+/**
+ * Speaks the lines missing from `cacheDir` (see tts.ts). Returns how many it made.
+ * Throws a ReelsonError when the provider cannot speak here (only when something is missing).
+ */
+export async function fetchLines(texts, settings, cacheDir, log) {
+    const missing = [...new Set(texts)].filter((text) => !existsSync(resolve(cacheDir, `${lineHash(text, settings)}.mp3`)));
+    if (!missing.length) {
+        return 0;
+    }
+    const problem = missingSetup(settings);
+    if (problem) {
+        throw new ReelsonError(`voice-over: ${missing.length} line(s) to speak with ${settings.provider} and ${problem} (or turn "voice" off in video.json)`);
+    }
+    mkdirSync(cacheDir, { recursive: true });
+    const scratch = mkdtempSync(join(tmpdir(), 'reelson-voice-'));
+    try {
+        for (const text of missing) {
+            const raw = resolve(scratch, settings.provider === 'openai' || settings.provider === 'elevenlabs' ? 'line.mp3' : 'line.wav');
+            rmSync(raw, { force: true });
+            await speak(text, settings, raw);
+            trimInto(raw, resolve(cacheDir, `${lineHash(text, settings)}.mp3`));
+            log(`  voice: spoke "${text}" (${settings.provider})`);
+        }
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    return missing.length;
+}
+/** The silence around a line, cut (a breath of it kept) and saved as mp3. */
+const TRIM = 'silenceremove=start_periods=1:start_threshold=-50dB:start_silence=0.05';
+function trimInto(raw, target) {
+    const run = spawnSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', raw, '-af', `${TRIM},areverse,${TRIM},areverse`, '-ar', '48000', '-c:a', 'libmp3lame', '-q:a', '2', target], { stdio: 'inherit' });
+    if (run.status !== 0 || !existsSync(target)) {
+        throw new ReelsonError(`ffmpeg could not read the spoken line ${raw}`);
+    }
+}
+/** Seconds of audio in `file` (ffprobe). */
+function lengthOf(file) {
+    const probe = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', file], { encoding: 'utf8' });
+    return Number.parseFloat(probe.stdout.trim()) || 0;
+}
+/**
+ * Mixes the cached lines into one track as long as the video (`target`, m4a). Returns false
+ * when none is cached. Warns about missing lines and an intro line that outlasts the intro.
+ */
+export function renderVoiceTrack(lines, settings, cacheDir, total, target, log) {
+    const cached = lines.filter((l) => existsSync(resolve(cacheDir, l.file)));
+    const missing = lines.length - cached.length;
+    if (missing) {
+        log(`  warning: voice-over: ${missing} line(s) not spoken yet — run \`reelson voice <slug>\` (render does it for you)`);
+    }
+    if (!cached.length) {
+        return false;
+    }
+    for (const line of cached.filter((l) => l.intro)) {
+        const length = lengthOf(resolve(cacheDir, line.file));
+        if (line.at + length > line.until + 0.05) {
+            log(`  warning: voice-over: "${line.text}" (${length.toFixed(1)}s) runs ${(line.at + length - line.until).toFixed(1)}s into the recording — shorten \`voice.intro\``);
+        }
+    }
+    const key = JSON.stringify({ lines: cached.map((l) => [l.at, l.file]), total, lufs: settings.lufs, v: 2 });
+    const stamp = `${target}.key`;
+    if (existsSync(target) && existsSync(stamp) && readFileSync(stamp, 'utf8') === key) {
+        return true;
+    }
+    const inputs = cached.flatMap((l) => ['-i', resolve(cacheDir, l.file)]);
+    const delayed = cached.map((l, i) => `[${i}:a]aresample=48000,adelay=${Math.round(l.at * 1000)}:all=1[v${i}]`).join(';');
+    // 0.1 s past the video: AAC's encoder padding would otherwise leave the track a frame or
+    // two short of its slot. loudnorm works at 192 kHz, hence the resample back.
+    const mix = `${delayed};${cached.map((_, i) => `[v${i}]`).join('')}amix=inputs=${cached.length}:normalize=0,` +
+        `loudnorm=I=${settings.lufs}:TP=-1.5:LRA=11,aresample=48000,apad,atrim=0:${round(total + 0.1)}[out]`;
+    const render = spawnSync('ffmpeg', ['-y', '-loglevel', 'error', ...inputs, '-filter_complex', mix, '-map', '[out]', '-c:a', 'aac', '-b:a', '160k', target], { stdio: 'inherit' });
+    if (render.status !== 0) {
+        throw new ReelsonError('ffmpeg could not mix the voice-over');
+    }
+    writeFileSync(stamp, key);
+    return true;
+}