retake-demos 0.2.2 → 0.3.0

package/dist/pace.js

@@ -0,0 +1,99 @@
+/**
+ * Idle compression: the app's dead time, shortened at render.
+ *
+ * The take's own timeline is the honest signal — a waitFor or navigate step
+ * records exactly how long the viewer sat looking at nothing changing. Each
+ * such stretch is shown as ~keepSeconds: the real start at 1×, then the rest
+ * fast-forwarded. The author's `wait` steps are pacing and are never touched;
+ * scene holds stay exactly as written.
+ *
+ * Implemented as a pre-pass: the source video is re-cut into a warped source
+ * and every clock in the take (timeline, trim, duration) is remapped through
+ * the same piecewise-linear warp, so captions, camera keys and stills land
+ * where they always did — the rest of the render pipeline never knows.
+ */
+import path from "node:path";
+/** The app made the viewer wait: show the start, fast-forward the rest. */
+const WAITING = new Set(["waitFor", "navigate"]);
+/** Only stretches meaningfully longer than what we would keep are worth a cut. */
+const SLACK = 0.6;
+/** Typing is not dead time — it is the person speaking — so it keeps its
+    start AND its finish at real speed and only accelerates the middle. Every
+    keystroke is a round-trip to the browser (~57ms whatever `delay` says), so
+    a real sentence costs five seconds nobody watches. */
+const TYPE_BUDGET = 2.4;
+const TYPE_HEAD = 0.8;
+const TYPE_TAIL = 0.7;
+/** Plan the warp: 1× everywhere except the tail of each long app-wait and the
+    middle of each long typing run. */
+export function planIdle(take, keepSeconds) {
+    const segs = [];
+    for (const e of take.timeline) {
+        if (!e.ok)
+            continue;
+        const dur = e.end - e.start;
+        if (WAITING.has(e.action)) {
+            if (dur < keepSeconds + SLACK)
+                continue;
+            // Head at real speed, tail fast-forwarded into the remaining budget.
+            const head = keepSeconds * 0.6;
+            const shownTail = keepSeconds * 0.4;
+            segs.push({ from: e.start + head, to: e.end, rate: (dur - head) / shownTail });
+        }
+        else if (e.action === "type" || e.action === "fill") {
+            if (dur < TYPE_BUDGET + SLACK)
+                continue;
+            const middle = dur - TYPE_HEAD - TYPE_TAIL;
+            const shownMiddle = Math.max(0.3, TYPE_BUDGET - TYPE_HEAD - TYPE_TAIL);
+            segs.push({ from: e.start + TYPE_HEAD, to: e.end - TYPE_TAIL, rate: middle / shownMiddle });
+        }
+    }
+    return segs.sort((a, b) => a.from - b.from);
+}
+/** Source time → warped time. */
+export function warpTime(segs, t) {
+    let out = t;
+    for (const s of segs) {
+        if (t <= s.from)
+            break;
+        const inSeg = Math.min(t, s.to) - s.from;
+        out -= inSeg - inSeg / s.rate;
+    }
+    return out;
+}
+/** The take with every clock remapped. */
+export function warpTake(take, segs) {
+    const w = (t) => warpTime(segs, t);
+    return {
+        ...take,
+        trimBefore: w(take.trimBefore),
+        duration: w(take.duration),
+        timeline: take.timeline.map((e) => ({ ...e, start: w(e.start), end: w(e.end) })),
+    };
+}
+/** ffmpeg args to cut the raw source into the warped source. */
+export function warpFilterArgs(src, segs, duration, out) {
+    // Alternating 1× and fast segments covering [0, duration].
+    const pieces = [];
+    let cur = 0;
+    for (const s of segs) {
+        if (s.from > cur)
+            pieces.push({ a: cur, b: s.from, rate: 1 });
+        pieces.push({ a: s.from, b: s.to, rate: s.rate });
+        cur = s.to;
+    }
+    if (cur < duration)
+        pieces.push({ a: cur, b: duration, rate: 1 });
+    const graph = pieces.map((p, i) => `[0:v]trim=start=${p.a.toFixed(3)}:end=${p.b.toFixed(3)},setpts=(PTS-STARTPTS)/${p.rate.toFixed(4)}[s${i}]`).join(";") +
+        ";" + pieces.map((_, i) => `[s${i}]`).join("") + `concat=n=${pieces.length}:v=1:a=0[out]`;
+    return ["-i", path.resolve(src), "-filter_complex", graph, "-map", "[out]", "-an", out];
+}
+/** Human line for the proof log. */
+export function describeIdle(take, segs) {
+    return segs.map((s) => {
+        const e = take.timeline.find((x) => x.start <= s.from && x.end >= s.to);
+        const real = e ? e.end - e.start : s.to - s.from;
+        const shown = real - (s.to - s.from) + (s.to - s.from) / s.rate;
+        return `${e ? e.summary.slice(0, 52) : "wait"}: ${real.toFixed(1)}s shown as ${shown.toFixed(1)}s`;
+    });
+}

package/dist/presets.js

@@ -8,7 +8,7 @@ export const PRESETS = {
         name: "draft",
         width: 960, height: 540, scale: 1, fps: 15, crf: 0,
         gif: false, layout: "band", cameraZoom: 1.2,
-        cursorSize: 36, captionFontSize: 24, bandHeight: 76,
+        cursorSize: 36, captionFontSize: 24, bandHeight: 76, bandFit: "text",
         encoder: "videotoolbox", master: false,
         description: "Fastest. Same layout as the final at a quarter of the pixels — for iterating, never for shipping.",
     },
@@ -16,7 +16,7 @@ export const PRESETS = {
         name: "preview-fast",
         width: 1920, height: 1080, scale: 2, fps: 24, crf: 0,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
         encoder: "videotoolbox", master: false,
         description: "Same framing as post, hardware-encoded MP4 only. For checking timing and framing fast.",
     },
@@ -24,7 +24,7 @@ export const PRESETS = {
         name: "proof-fast",
         width: 960, height: 720, scale: 1, fps: 24, crf: 24,
         gif: false, layout: "band", cameraZoom: 1.2,
-        cursorSize: 40, captionFontSize: 26, bandHeight: 84,
+        cursorSize: 40, captionFontSize: 26, bandHeight: 84, bandFit: "text",
         encoder: "videotoolbox", master: false,
         description: "Small, quick internal check.",
     },
@@ -32,7 +32,7 @@ export const PRESETS = {
         name: "post-landscape",
         width: 1920, height: 1080, scale: 2, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
         encoder: "x264", master: true,
         description: "1080p, 30fps, CRF 17. The general-purpose demo. GIF on request.",
     },
@@ -41,25 +41,25 @@ export const PRESETS = {
         /* The page area is the canvas minus the caption band, so the file really
            is 1080×1080 — a square preset that produced 1080×1210 got letterboxed
            by every feed. Landscape keeps its full-height page on purpose. */
-        width: 1080, height: 950, scale: 1.6, fps: 30, crf: 17,
+        width: 1080, height: 960, scale: 1.6, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 60, captionFontSize: 40, bandHeight: 130,
+        cursorSize: 60, captionFontSize: 36, bandHeight: 120, bandFit: "fill",
         encoder: "x264", master: true,
-        description: "A true 1080×1080 (page 1080×950 + caption band), feed-friendly.",
+        description: "A true 1080×1080 (page 1080×960 + a fixed 120px caption band), feed-friendly.",
     },
     "post-vertical": {
         name: "post-vertical",
-        width: 1080, height: 1750, scale: 2, fps: 30, crf: 17,
+        width: 1080, height: 1800, scale: 2, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.3,
-        cursorSize: 60, captionFontSize: 44, bandHeight: 170,
+        cursorSize: 60, captionFontSize: 40, bandHeight: 120, bandFit: "fill",
         encoder: "x264", master: true,
-        description: "A true 1080×1920 (page 1080×1750 + caption band) for shorts/reels. Narrow-column apps suit it best.",
+        description: "A true 1080×1920 (page 1080×1800 + a fixed 120px caption band) for shorts/reels. Narrow-column apps suit it best.",
     },
     "docs-gif": {
         name: "docs-gif",
         width: 1440, height: 900, scale: 1.5, fps: 24, crf: 20,
         gif: { width: 900, fps: 15 }, layout: "band", cameraZoom: 1.2,
-        cursorSize: 48, captionFontSize: 32, bandHeight: 100,
+        cursorSize: 48, captionFontSize: 32, bandHeight: 100, bandFit: "text",
         encoder: "x264", master: false,
         description: "README/docs GIF, 900px wide.",
     },
@@ -67,7 +67,7 @@ export const PRESETS = {
         name: "master",
         width: 1920, height: 1080, scale: 2, fps: 30, crf: 12,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
         encoder: "x264", master: true,
         description: "Highest quality, slowest. Archive/source render.",
     },

package/dist/record.js

@@ -191,6 +191,10 @@ export async function record(m, opts) {
     const stateFresh = !!statePath && fs.existsSync(statePath) && (Date.now() - fs.statSync(statePath).mtimeMs) / 3.6e6 < (m.auth?.maxAgeHours ?? 72);
     if (statePath)
         log(stateFresh ? `auth: reusing session ${path.relative(process.cwd(), statePath)}` : `auth: no fresh session — running setup to sign in`);
+    // No session and nothing that could create one: stop here rather than record
+    // a logged-out take that passes every check.
+    if (statePath && !stateFresh && !(m.auth?.setup?.length))
+        throw new Error(`no fresh session at ${path.relative(process.cwd(), statePath)} and no auth.setup to sign in with — run \`retake signin ${path.relative(process.cwd(), path.join(opts.manifestDir, m.name + ".yaml"))}\` and log in once by hand, or add the sign-in steps under auth.setup`);
     const context = await browser.newContext({
         viewport: size,
         colorScheme: m.colorScheme,
@@ -332,6 +336,10 @@ export async function record(m, opts) {
         if (statePath && !stateFresh && authOk) {
             fs.mkdirSync(path.dirname(statePath), { recursive: true });
             await context.storageState({ path: statePath });
+            try {
+                fs.chmodSync(statePath, 0o600);
+            }
+            catch { /* windows */ }
             log(`auth: saved session → ${path.relative(process.cwd(), statePath)}`);
         }
         else if (statePath && !stateFresh) {
@@ -366,6 +374,15 @@ export async function record(m, opts) {
                 end: 0,
                 ok: true,
             };
+            if (step.action === "callout") {
+                // Resolve the box now; the ring itself is drawn at render time.
+                const target = step.selector ?? step.at;
+                const c = await resolvePoint(page, target, step.timeout ?? 10_000);
+                const half = typeof target === "string" || !("x" in target)
+                    ? await page.locator((typeof target === "string" ? target : target.selector)).first().evaluate((el) => { const r = el.getBoundingClientRect(); return { w: r.width, h: r.height }; }).catch(() => ({ w: 48, h: 48 }))
+                    : { w: 48, h: 48 };
+                entry.callout = { box: { x: c.x - half.w / 2, y: c.y - half.h / 2, width: half.w, height: half.h }, label: step.label, ms: step.ms };
+            }
             if (step.action === "scene") {
                 entry.label = step.label;
                 entry.caption = step.caption;
@@ -481,10 +498,18 @@ export async function record(m, opts) {
     // calibrated to within ~0.2s of the first video frame on a warm route). The
     // real file length is authoritative for the end.
     const trimBefore = sec(setupEnd - t0);
-    const duration = video ? videoDuration(video) : sec(endMs - t0);
+    // The recording keeps rolling while the browser is torn down, so the raw
+    // video always has a tail of nothing after the last step. The take ends
+    // where the demo ends (plus a breath), never where the recorder stopped —
+    // otherwise every video ships with dead seconds at the end.
+    const GRACE = 0.4;
+    const videoSec = video ? videoDuration(video) : sec(endMs - t0);
     const last = timeline.at(-1);
-    if (last && Math.abs(duration - last.end) > 3) {
-        log(`note: video is ${duration.toFixed(1)}s but the last step ended at ${last.end.toFixed(1)}s — check anchoring`);
+    const duration = last && videoSec > last.end + GRACE + 0.1 ? last.end + GRACE : videoSec;
+    if (last && duration < videoSec - 0.05)
+        log(`trim: ${(videoSec - duration).toFixed(1)}s of tail after the last step dropped`);
+    if (last && videoSec < last.end - 0.5) {
+        log(`note: video is ${videoSec.toFixed(1)}s but the last step ended at ${last.end.toFixed(1)}s — check anchoring`);
     }
     const finishedAt = new Date().toISOString();
     const take = {
@@ -615,7 +640,7 @@ async function runStep(rec, page, step, m, ctx) {
             await rec.click(step.selector, { timeout, zoom: step.zoom });
             break;
         case "type":
-            await rec.type(step.selector, expandEnv(step.text), { delay: step.delay ?? 70, clear: step.clear, timeout });
+            await rec.type(step.selector, expandEnv(step.text), { delay: step.delay ?? (m.typing === "brisk" ? 22 : 70), clear: step.clear, timeout });
             break;
         case "fill":
             await rec.fill(step.selector, expandEnv(step.text), { timeout });
@@ -695,6 +720,11 @@ async function runStep(rec, page, step, m, ctx) {
         case "stub":
             await ctx.stub({ url: step.url, method: step.method, status: step.status ?? 200, json: step.json, from: step.from, contentType: "application/json; charset=utf-8" });
             break;
+        case "callout":
+            // The box was resolved in the caller; on camera this is a hold while
+            // the (render-time) ring has the viewer's eye.
+            await page.waitForTimeout(step.ms / m.speed);
+            break;
         case "scene":
             // A marker only. Its timestamp is the point of the step.
             break;
@@ -743,6 +773,8 @@ export function describe(step) {
             return `evaluate (${step.script.length} chars)`;
         case "stub":
             return `stub ${step.method ? step.method + " " : ""}${step.url}`;
+        case "callout":
+            return `callout ${step.selector ?? pointName(step.at)}${step.label ? ` “${step.label}”` : ""}`;
         case "scene":
             return `scene: ${step.label}`;
     }

package/dist/render.js

@@ -18,9 +18,13 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import { execFileSync, spawnSync } from "node:child_process";
 import { capSecondsFor } from "./record.js";
+import { bandHeightFor, maxCharsFor, wrap } from "./captions.js";
+import { renderCard, renderCalloutOverlay, renderTitledCover } from "./cards.js";
+import { describeIdle, planIdle, warpFilterArgs, warpTake } from "./pace.js";
+import { DEFAULT_VOICE, audioSeconds, synthesize } from "./voice.js";
 import { createRequire } from "node:module";
 import { chromium } from "playwright";
-import { resolve } from "./manifest.js";
+import { expandEnv, resolve } from "./manifest.js";
 /** What the render depends on: the raw take + everything in the manifest that
     shapes the picture. Same hash → same output → skip. */
 export function renderHash(m, take) {
@@ -28,7 +32,14 @@ export function renderHash(m, take) {
     const src = take.video && fs.existsSync(take.video) ? fs.statSync(take.video) : null;
     const h = createHash("sha1");
     const merged = applyManifest(m, take);
-    h.update(JSON.stringify({ q, tempo: m.tempo, cap: m.captions, theme: m.theme, camera: m.camera, gif: m.outputs.gif, thumb: m.outputs.thumbnail, stills: m.outputs.stills, video: src ? [src.size, Math.round(src.mtimeMs)] : null, tl: merged.timeline.map((t) => [t.start, t.end, t.label, t.caption, t.holdMs, t.camera]), trim: [merged.trimBefore, merged.duration] }));
+    h.update(JSON.stringify({ q, tempo: m.tempo, cap: m.captions, theme: m.theme, camera: m.camera, cards: [m.intro, m.outro], idle: m.compressIdle, vo: m.voiceover, music: m.music ? [m.music, (() => { try {
+                const f = typeof m.music === "string" ? m.music : m.music.file;
+                const st = fs.statSync(path.resolve(f));
+                return [st.size, Math.round(st.mtimeMs)];
+            }
+            catch {
+                return null;
+            } })()] : null, gif: m.outputs.gif, thumb: m.outputs.thumbnail, stills: m.outputs.stills, video: src ? [src.size, Math.round(src.mtimeMs)] : null, tl: merged.timeline.map((t) => [t.start, t.end, t.label, t.caption, t.holdMs, t.camera, t.callout]), trim: [merged.trimBefore, merged.duration] }));
     return h.digest("hex").slice(0, 12);
 }
 const require = createRequire(import.meta.url);
@@ -79,38 +90,6 @@ export function probe(file) {
     };
 }
 export const videoDuration = (file) => probe(file).duration;
-/** Word-wrap long captions; two-line captions break near the middle so no
-    word is left orphaned on the second line. */
-function wrap(text, max) {
-    if (text.length <= max)
-        return text;
-    const words = text.split(/\s+/);
-    if (text.length <= max * 2) {
-        let best = 1, bestDiff = Infinity;
-        for (let i = 1; i < words.length; i++) {
-            const a = words.slice(0, i).join(" ").length;
-            const b = words.slice(i).join(" ").length;
-            if (a <= max && b <= max && Math.abs(a - b) < bestDiff) {
-                best = i;
-                bestDiff = Math.abs(a - b);
-            }
-        }
-        return words.slice(0, best).join(" ") + "\n" + words.slice(best).join(" ");
-    }
-    const out = [];
-    let line = "";
-    for (const w of words) {
-        if (line && (line + " " + w).length > max) {
-            out.push(line);
-            line = w;
-        }
-        else
-            line = line ? line + " " + w : w;
-    }
-    if (line)
-        out.push(line);
-    return out.join("\n");
-}
 /** ffmpeg drawtext needs a few characters escaped inside the filter graph. */
 function esc(s) {
     return s.replace(/\\/g, "\\\\").replace(/'/g, "\u2019").replace(/:/g, "\\:").replace(/%/g, "\\%").replace(/,/g, "\\,");
@@ -296,6 +275,21 @@ export async function render(m, take, outDir, opts = {}) {
     }
     // Captions, holds, camera zooms and trim come from the manifest as it is now.
     take = applyManifest(m, take);
+    // Idle compression: re-cut the source so the app's dead waits are shown
+    // short, and remap every clock in the take through the same warp.
+    let idleLines = [];
+    if (m.compressIdle && take.video) {
+        const keep = m.compressIdle === true ? 1.5 : m.compressIdle.keepSeconds;
+        const segs = planIdle(take, keep);
+        if (segs.length) {
+            const paced = path.join(outDir, ".paced.mp4");
+            ff([...warpFilterArgs(take.video, segs, take.duration, paced).slice(0, -1), "-r", String(resolve(m).fps), "-c:v", "libx264", "-crf", "14", "-preset", "veryfast", "-pix_fmt", "yuv420p", paced], log);
+            idleLines = describeIdle(take, segs);
+            for (const l of idleLines)
+                log?.(`idle: ${l}`);
+            take = { ...warpTake(take, segs), video: paced };
+        }
+    }
     // Tempo: the source is cut in its own time (-ss/-t below), then every
     // clock downstream — captions, camera keys, stills — runs in output time.
     const srcTake = take;
@@ -316,7 +310,7 @@ export async function render(m, take, outDir, opts = {}) {
         const to = sc[i + 1] ? sc[i + 1].start : take.duration;
         take = { ...take, trimBefore: from, duration: to };
     }
-    const src = path.resolve(srcVideo);
+    const src = path.resolve(take.video ?? srcVideo); // take.video may be the idle-warped re-cut
     // Source (recorded viewport) vs canvas (preset output). They differ when a
     // narrow app was recorded at its own aspect and gets centred on the canvas.
     const SW = take.quality?.width ?? q.viewport.width;
@@ -344,13 +338,17 @@ export async function render(m, take, outDir, opts = {}) {
     let frameInput = null;
     let geom = null;
     const capSize = q.captions ? q.captions.fontSize : 0;
+    // One band height for the whole take, from its captions (see captions.ts).
+    const bandH = bandHeightFor(q, W, captionWindows(take).map((w) => w.text), H);
     if (layout === "band") {
-        // Site fills the frame; caption strip below it.
-        filters.push(`pad=${W}:${H + q.bandHeight}:0:0:color=${bg}`);
-        capY = `${H}+${q.bandHeight / 2}-th/2`;
+        // Site fills the frame; caption strip below it — none at all if captions are off.
+        if (bandH) {
+            filters.push(`pad=${W}:${H + bandH}:0:0:color=${bg}`);
+            capY = `${H}+${bandH / 2}-th/2`;
+        }
     }
     else if (layout === "card") {
-        geom = cardGeometry(W, H, SW, SH, q.bandHeight);
+        geom = cardGeometry(W, H, SW, SH, bandH);
         frameInput = path.join(outDir, ".frame.png");
         await renderCardFrame(frameInput, W, H, geom, bg);
         filters.push(`scale=${geom.vw}:${geom.vh}:flags=lanczos`, `pad=${W}:${H}:${geom.vx}:${geom.vy}:color=${bg}`);
@@ -364,16 +362,40 @@ export async function render(m, take, outDir, opts = {}) {
     filters.push("format=yuv420p");
     const captionFilters = [];
     if (q.captions && layout !== "none") {
-        const maxChars = Math.max(28, Math.round((W / capSize) * 1.55));
+        const maxChars = maxCharsFor(W, capSize);
         for (const w of captionWindows(take)) {
             captionFilters.push(`drawtext=${font}text='${esc(wrap(w.text, maxChars))}':fontsize=${capSize}:fontcolor=${capColor}${capBox}:line_spacing=${Math.round(capSize * 0.25)}` +
                 `:x=(w-tw)/2:y=${capY}:enable='between(t,${w.from.toFixed(2)},${w.to.toFixed(2)})'`);
         }
     }
-    const graph = frameInput
-        ? `[0:v]${filters.join(",")}[v];[v][1:v]overlay=0:0:format=auto${captionFilters.length ? "," + captionFilters.join(",") : ""}[out]`
-        : `[0:v]${[...filters, ...captionFilters].join(",")}[out]`;
-    const inputs = ["-ss", srcTake.trimBefore.toFixed(3), "-t", (srcTake.duration - srcTake.trimBefore).toFixed(3), "-i", src, ...(frameInput ? ["-i", frameInput] : [])];
+    // Callouts: recorded boxes become animated overlays, applied in SOURCE
+    // coordinates (before the camera filter) so a moving camera carries them.
+    const callouts = take.timeline.filter((e) => e.callout && e.ok);
+    const calloutInputs = [];
+    let preCam = "";
+    if (callouts.length && !o.scene && !frameInput) {
+        const camIdx = cam.filter ? filters.indexOf(cam.filter) : filters.length;
+        const before = filters.slice(0, camIdx), after = filters.slice(camIdx);
+        let label = "b0";
+        let g = `[0:v]${before.join(",")}[${label}]`;
+        for (let i = 0; i < callouts.length; i++) {
+            const e = callouts[i];
+            const from = Math.max(0, e.start - take.trimBefore);
+            const webm = await renderCalloutOverlay(ffmpegBin(), outDir, i, e.callout, SW, SH, fps, Math.max(15, Math.round(q.captions ? q.captions.fontSize * 0.55 : 20)), ink);
+            calloutInputs.push(webm);
+            const inIdx = 1 + (frameInput ? 1 : 0) + i;
+            const next = `b${i + 1}`;
+            g += `;[${inIdx}:v]setpts=PTS+${from.toFixed(3)}/TB[c${i}];[${label}][c${i}]overlay=0:0:eof_action=pass[${next}]`;
+            label = next;
+        }
+        preCam = `${g};[${label}]${after.length ? after.join(",") : "null"}`;
+    }
+    const graph = preCam
+        ? `${preCam}${captionFilters.length ? "," + captionFilters.join(",") : ""}[out]`
+        : frameInput
+            ? `[0:v]${filters.join(",")}[v];[v][1:v]overlay=0:0:format=auto${captionFilters.length ? "," + captionFilters.join(",") : ""}[out]`
+            : `[0:v]${[...filters, ...captionFilters].join(",")}[out]`;
+    const inputs = ["-ss", srcTake.trimBefore.toFixed(3), "-t", (srcTake.duration - srcTake.trimBefore).toFixed(3), "-i", src, ...(frameInput ? ["-i", frameInput] : []), ...calloutInputs.flatMap((f) => ["-c:v", "libvpx-vp9", "-i", f])];
     const compose = ["-filter_complex", graph, "-map", "[out]", "-r", String(fps), "-an", "-pix_fmt", "yuv420p", "-movflags", "+faststart"];
     const x264 = (crf, preset) => ["-c:v", "libx264", "-crf", String(crf), "-preset", preset];
     // Hardware encode is a macOS thing; elsewhere the "fast" presets are a fast x264.
@@ -401,6 +423,98 @@ export async function render(m, take, outDir, opts = {}) {
     }
     if (frameInput)
         fs.rmSync(frameInput, { force: true });
+    for (const f of calloutInputs)
+        fs.rmSync(f, { force: true });
+    // Title cards: rendered at the finished frame size, spliced on. The intro's
+    // settled frame becomes cover.png — the poster.
+    let cover;
+    if ((m.intro || m.outro) && !o.scene) {
+        const dims = probe(mp4);
+        const segs = [];
+        if (m.intro) {
+            const c = await renderCard(ffmpegBin(), outDir, "intro", m.intro, dims.width, dims.height, fps, q.theme);
+            segs.push(c.mp4);
+            cover = c.cover;
+        }
+        segs.push(mp4);
+        if (m.outro)
+            segs.push((await renderCard(ffmpegBin(), outDir, "outro", m.outro, dims.width, dims.height, fps, q.theme)).mp4);
+        if (segs.length > 1) {
+            const joined = path.join(outDir, ".joined.mp4");
+            ff([...segs.flatMap((f) => ["-i", f]), "-filter_complex", `${segs.map((_, i) => `[${i}:v]`).join("")}concat=n=${segs.length}:v=1:a=0[out]`, "-map", "[out]", "-r", String(fps), "-pix_fmt", "yuv420p", "-movflags", "+faststart", "-an", ...x264(q.crf, "medium"), joined], log);
+            fs.renameSync(joined, mp4);
+            for (const f of segs)
+                if (f !== mp4)
+                    fs.rmSync(f, { force: true });
+        }
+        mark("cards");
+    }
+    // Audio: the music bed and/or the captions read aloud, mixed in one pass.
+    // The deliverable gets it; the master stays a clean video-only source.
+    if ((m.music || m.voiceover) && !o.scene) {
+        const dur = probe(mp4).duration;
+        // Cards shift every scene: narration is placed in FINAL time.
+        const introShift = m.intro ? m.intro.ms / 1000 : 0;
+        const audioIn = [];
+        const chains = [];
+        const mixIns = [];
+        let idx = 1; // 0 is the video
+        if (m.music) {
+            const spec = typeof m.music === "string" ? { file: m.music, gainDb: -14, fadeOutMs: 1800 } : m.music;
+            const musicFile = path.resolve(expandEnv(spec.file));
+            if (!fs.existsSync(musicFile))
+                throw new Error(`music: no such file ${musicFile} — the track ships inside the video, so it must be one the person may use (CC0 or licensed)`);
+            const fadeStart = Math.max(0, dur - spec.fadeOutMs / 1000);
+            // Ducked a step further when a voice speaks over it.
+            const gain = spec.gainDb - (m.voiceover ? 7 : 0);
+            audioIn.push("-stream_loop", "-1", "-i", musicFile);
+            chains.push(`[${idx}:a]volume=${gain}dB,afade=t=in:st=0:d=0.6,afade=t=out:st=${fadeStart.toFixed(2)}:d=${(spec.fadeOutMs / 1000).toFixed(2)}[mus]`);
+            mixIns.push("[mus]");
+            idx++;
+        }
+        if (m.voiceover) {
+            const spec = m.voiceover === true ? { voice: DEFAULT_VOICE, gainDb: 0, script: undefined, fragments: true } : m.voiceover;
+            if (spec.script) {
+                // One script, one performance: prosody carries across the whole
+                // video the way a person reads. Starts after the title card.
+                const clip = path.join(outDir, ".vo-0.mp3");
+                synthesize(spec.script, spec.voice, clip);
+                const spoken = audioSeconds(ffmpegBin(), clip);
+                if (spoken > dur - introShift + 0.5)
+                    log?.(`voiceover: the script reads ${spoken.toFixed(1)}s but there are ${(dur - introShift).toFixed(1)}s of video after the title card — cut the script or lengthen the scenes, then re-render`);
+                audioIn.push("-i", clip);
+                chains.push(`[${idx}:a]volume=${spec.gainDb}dB,adelay=${Math.round(introShift * 1000)}:all=1[vo0]`);
+                mixIns.push("[vo0]");
+                idx++;
+            }
+            else {
+                // Explicitly-asked-for fragments: one clip per caption. Known to
+                // reset prosody at every line; the schema refuses it by default.
+                const wins = captionWindows(take);
+                for (let i = 0; i < wins.length; i++) {
+                    const w = wins[i];
+                    const clip = path.join(outDir, `.vo-${i}.mp3`);
+                    synthesize(w.text, spec.voice, clip);
+                    const spoken = audioSeconds(ffmpegBin(), clip);
+                    const at = w.from + introShift;
+                    if (spoken > w.to - w.from + 0.4)
+                        log?.(`voiceover: “${w.text.slice(0, 40)}…” runs ${spoken.toFixed(1)}s but its scene holds ${(w.to - w.from).toFixed(1)}s — lengthen the scene's holdMs or trailing wait and re-render`);
+                    audioIn.push("-i", clip);
+                    chains.push(`[${idx}:a]volume=${spec.gainDb}dB,adelay=${Math.round(at * 1000)}:all=1[vo${i}]`);
+                    mixIns.push(`[vo${i}]`);
+                    idx++;
+                }
+            }
+        }
+        const mixed = path.join(outDir, ".with-audio.mp4");
+        const graph = `${chains.join(";")};${mixIns.join("")}amix=inputs=${mixIns.length}:duration=longest:normalize=0,atrim=0:${dur.toFixed(2)}[a]`;
+        ff(["-i", mp4, ...audioIn, "-filter_complex", graph, "-map", "0:v", "-map", "[a]", "-c:v", "copy", "-c:a", "aac", "-b:a", "160k", "-movflags", "+faststart", "-shortest", mixed], log);
+        fs.renameSync(mixed, mp4);
+        for (const f of fs.readdirSync(outDir))
+            if (/^\.vo-\d+\.mp3$/.test(f))
+                fs.rmSync(path.join(outDir, f), { force: true });
+        mark("audio");
+    }
     if (o.scene)
         return { mp4, proofLog };
     // --- 3. GIF (secondary, opt-in) --------------------------------------------
@@ -429,9 +543,19 @@ export async function render(m, take, outDir, opts = {}) {
         }
         mark("gif");
     }
+    // Cards are spliced onto the front of the deliverable, so every timestamp
+    // in the take is that much later in the file frames are pulled from.
+    const cardShift = !o.scene && m.intro ? m.intro.ms / 1000 : 0;
     // --- 4. thumbnail ----------------------------------------------------------
+    // A person's chosen poster (the window's "Use this frame" / a still / an
+    // upload) outlives re-renders: the choice writes a .poster marker, and the
+    // scene-based default never overwrites a deliberate choice.
     let thumbnail;
-    if (m.outputs.thumbnail) {
+    if (m.outputs.thumbnail && fs.existsSync(path.join(outDir, ".poster")) && fs.existsSync(path.join(outDir, "thumbnail.png"))) {
+        thumbnail = path.join(outDir, "thumbnail.png");
+        log?.("thumbnail: keeping the poster you chose (delete .poster to go back to the scene default)");
+    }
+    else if (m.outputs.thumbnail) {
         const sc = scenes(take);
         let at;
         if (typeof m.outputs.thumbnail === "object") {
@@ -449,7 +573,14 @@ export async function render(m, take, outDir, opts = {}) {
             at = last ? last.start - take.trimBefore + 1.0 : Math.max(0, take.duration - take.trimBefore - 0.5);
         }
         thumbnail = path.join(outDir, "thumbnail.png");
-        ff(["-ss", Math.max(0, at).toFixed(2), "-i", mp4, "-frames:v", "1", thumbnail], log);
+        ff(["-ss", Math.max(0, at + cardShift).toFixed(2), "-i", mp4, "-frames:v", "1", thumbnail], log);
+        // A launch cut gets a second candidate: this frame with the title on it.
+        // The person picks between them (or any still, or their own file) in the
+        // window; both are just PNGs, and the poster is whichever is thumbnail.png.
+        if (m.mode === "launch" && m.intro) {
+            const d = probe(mp4);
+            await renderTitledCover(ffmpegBin(), thumbnail, path.join(outDir, "cover-titled.png"), m.intro, d.width, d.height, q.theme);
+        }
         mark("thumbnail");
     }
     // --- 5. scene stills -------------------------------------------------------
@@ -470,14 +601,14 @@ export async function render(m, take, outDir, opts = {}) {
             const at = Math.min(Math.max(0, from + Math.max(0.8, (next - from) / 2)), Math.max(0, end - 0.2));
             const base = `${String(i + 1).padStart(2, "0")}-${(sce.label || "scene").replace(/[^a-z0-9-]+/gi, "-")}`;
             const file = path.join(dir, `${base}.png`);
-            ff(["-ss", at.toFixed(2), "-i", mp4, "-frames:v", "1", file], log);
+            ff(["-ss", (at + cardShift).toFixed(2), "-i", mp4, "-frames:v", "1", file], log);
             stills.push(file);
             // And the scene's last moment: the caption names what the scene
             // achieves, and that is usually on screen at the end, not the middle.
             const atEnd = Math.min(Math.max(from + 0.4, next - 0.6), Math.max(0, end - 0.2));
             if (atEnd - at > 0.5) {
                 const fe = path.join(dir, `${base}-end.png`);
-                ff(["-ss", atEnd.toFixed(2), "-i", mp4, "-frames:v", "1", fe], log);
+                ff(["-ss", (atEnd + cardShift).toFixed(2), "-i", mp4, "-frames:v", "1", fe], log);
                 stills.push(fe);
             }
         }