@gentbajko/slopify 2.3.0 → 2.4.0

package/dist/slices/shorts/pick.js

@@ -0,0 +1,232 @@
+import { z } from "zod";
+import { youtubeTimestamp } from "../youtube/timestamps.js";
+import { shortHashtagsMax, shortHashtagsMin, shortTitleMax } from "./model.js";
+export const shortPickSchema = z.object({
+    number: z.number().int().positive(),
+    first: z.number().int().positive(),
+    last: z.number().int().positive(),
+    start: z.number().finite().nonnegative(),
+    end: z.number().finite().positive(),
+    title: z.string(),
+    description: z.string(),
+    hashtags: z.array(z.string()),
+    why: z.string(),
+    text: z.string(),
+    seed: z.string().nullable().optional(),
+});
+// A clip keeps the number, title, description, hashtags and seed it had when a pick made
+// again chooses exactly the same sentences, as long as that number is still in range; the
+// other clips take the free numbers in the order they play. Everything after the pick is
+// keyed by number, so an unchanged clip plans the same work under the same keys.
+export function keepNumbers(picks, previous, seed) {
+    const taken = new Set();
+    const kept = new Map();
+    for (const pick of picks) {
+        const before = previous.find((one) => one.first === pick.first &&
+            one.last === pick.last &&
+            one.seed !== undefined &&
+            one.number <= picks.length &&
+            !taken.has(one.number));
+        if (before === undefined)
+            continue;
+        taken.add(before.number);
+        kept.set(pick, { ...before, start: pick.start, end: pick.end, text: pick.text });
+    }
+    const free = Array.from({ length: picks.length }, (_value, at) => at + 1).filter((number) => !taken.has(number));
+    return picks
+        .map((pick) => kept.get(pick) ?? { ...pick, number: free.shift() ?? pick.number, seed })
+        .toSorted((left, right) => left.number - right.number);
+}
+// ceiling: a clip opens a quarter second before its first word and closes 0.4 s after its
+// last, so the first consonant and the last breath are kept; never past halfway to the
+// neighbouring sentence, so a clip holds nothing of the words around it.
+const leadSeconds = 0.25;
+const tailSeconds = 0.4;
+// Where a clip of sentences `first` to `last` (1-based, inclusive) starts and ends.
+export function clipBounds(sentences, first, last, durationSeconds) {
+    const opening = sentences[first - 1];
+    const closing = sentences[last - 1];
+    if (opening === undefined || closing === undefined || first > last)
+        return undefined;
+    const before = sentences[first - 2]?.end ?? 0;
+    const after = sentences[last]?.start ?? durationSeconds;
+    const start = Math.max(0, opening.start - Math.max(0, Math.min(leadSeconds, (opening.start - before) / 2)));
+    const end = Math.min(durationSeconds, closing.end + Math.max(0, Math.min(tailSeconds, (after - closing.end) / 2)));
+    return { start: round(start), end: round(end) };
+}
+export function pickMessages(brief) {
+    const plural = brief.count === 1 ? "short" : "shorts";
+    return [
+        {
+            role: "system",
+            content: [
+                "You pick clips from a narrated video to publish as vertical shorts. Answer with one JSON array and nothing else, best clip first, in this shape:",
+                '[{"first": 12, "last": 19, "title": "...", "description": "...", "hashtags": ["#Example"], "why": "..."}]',
+                "",
+                "Rules the answer must follow:",
+                `- Exactly ${String(brief.count)} ${plural}, unless the video is too short to hold that many.`,
+                '- "first" and "last" are sentence numbers from the transcript. A clip runs from the start of sentence "first" to the end of sentence "last", both included.',
+                `- Each clip lasts between ${String(brief.minSeconds)} and ${String(brief.maxSeconds)} seconds, measured from the start time of its first sentence to the end time of its last one.`,
+                "- No two clips share a sentence.",
+                `- "title" is at most ${String(shortTitleMax)} characters, one line, without hashtags.`,
+                '- "description" is one line.',
+                `- "hashtags" holds ${String(shortHashtagsMin)} to ${String(shortHashtagsMax)} single words, each starting with #.`,
+                '- "why" is one short sentence saying why the clip works on its own.',
+            ].join("\n"),
+        },
+        {
+            role: "user",
+            content: [
+                brief.instruction,
+                "",
+                `Video title: ${brief.title}`,
+                `Video length: ${youtubeTimestamp(brief.durationSeconds)}`,
+                `Shorts wanted: ${String(brief.count)}, each ${String(brief.minSeconds)}-${String(brief.maxSeconds)} seconds long`,
+                "",
+                "Transcript, one sentence per line, each led by its number and the time it runs in the video:",
+                "",
+                brief.sentences,
+            ].join("\n"),
+        },
+    ];
+}
+// The second and last ask: the first answer, and what was wrong with it, so the model can
+// keep the clips that worked and replace the rest.
+export function pickRetryMessages(brief, answer, problems) {
+    return [
+        ...pickMessages(brief),
+        { role: "assistant", content: answer },
+        {
+            role: "user",
+            content: [
+                "Some of those clips can't be used:",
+                ...problems.map((problem) => `- ${problem}`),
+                "",
+                `Answer again with the whole list of ${String(brief.count)} clips as one JSON array, following every rule.`,
+            ].join("\n"),
+        },
+    ];
+}
+const answerSchema = z.array(z.object({
+    first: z.union([z.number(), z.string()]),
+    last: z.union([z.number(), z.string()]),
+    title: z.string(),
+    description: z.string(),
+    hashtags: z.array(z.string()),
+    why: z.string().optional(),
+}));
+const fix = "Retry stage, or choose another model in Edit project → Providers.";
+// Timing noise: the length rules are checked to the hundredth of a second.
+const tolerance = 0.01;
+// Reads the model's answer and keeps the clips that follow the rules: in range, the right
+// length, not overlapping one already kept, best first until `count`, then in video order.
+// Not being a JSON array of clips is the one failure; everything else is a problem to tell
+// the model about.
+export function checkPicks(text, sentences, limits) {
+    const parsed = answerSchema.safeParse(jsonArrayOf(text));
+    if (!parsed.success)
+        return {
+            ok: false,
+            reason: `The AI model's choice of shorts didn't come back in the expected format (a JSON list of clips, each with first and last sentence numbers, a title, a description and hashtags). ${fix}`,
+        };
+    const problems = [];
+    const kept = [];
+    for (const [index, row] of parsed.data.entries()) {
+        const label = `Clip ${String(index + 1)}`;
+        if (kept.length >= limits.count)
+            break;
+        const first = Number(row.first);
+        const last = Number(row.last);
+        if (!Number.isInteger(first) ||
+            !Number.isInteger(last) ||
+            first < 1 ||
+            last > sentences.length ||
+            first > last) {
+            problems.push(`${label} runs from sentence ${String(row.first)} to ${String(row.last)}, but the transcript has sentences 1 to ${String(sentences.length)} and the first must not come after the last.`);
+            continue;
+        }
+        const bounds = clipBounds(sentences, first, last, limits.durationSeconds);
+        if (bounds === undefined)
+            continue;
+        const { start, end } = bounds;
+        const seconds = end - start;
+        if (seconds < limits.minSeconds - tolerance || seconds > limits.maxSeconds + tolerance) {
+            problems.push(`${label} (sentences ${String(first)}-${String(last)}) lasts ${String(Math.round(seconds))} seconds, and each clip must last ${String(limits.minSeconds)}-${String(limits.maxSeconds)} seconds.`);
+            continue;
+        }
+        const clash = kept.find((one) => first <= one.last && last >= one.first);
+        if (clash !== undefined) {
+            problems.push(`${label} (sentences ${String(first)}-${String(last)}) shares sentences with the clip of sentences ${String(clash.first)}-${String(clash.last)}.`);
+            continue;
+        }
+        const title = row.title.replace(/\s+/g, " ").trim();
+        if (title === "" || title.length > shortTitleMax) {
+            problems.push(title === ""
+                ? `${label} has no title.`
+                : `${label}'s title is ${String(title.length)} characters; keep it to ${String(shortTitleMax)}.`);
+            continue;
+        }
+        const description = row.description.replace(/\s+/g, " ").trim();
+        if (description === "") {
+            problems.push(`${label} has no description.`);
+            continue;
+        }
+        const hashtags = [
+            ...new Set(row.hashtags
+                .map((tag) => tag.trim().replace(/^#*/, ""))
+                .filter((tag) => /^[\p{L}\p{N}_]+$/u.test(tag))
+                .map((tag) => `#${tag}`)),
+        ].slice(0, shortHashtagsMax);
+        if (hashtags.length === 0) {
+            problems.push(`${label} has no usable hashtags (single words starting with #).`);
+            continue;
+        }
+        kept.push({
+            first,
+            last,
+            start: round(start),
+            end: round(end),
+            title,
+            description,
+            hashtags,
+            why: (row.why ?? "").replace(/\s+/g, " ").trim(),
+            text: sentences
+                .slice(first - 1, last)
+                .map((sentence) => sentence.text)
+                .join(" "),
+        });
+    }
+    if (kept.length < limits.count && parsed.data.length < limits.count)
+        problems.push(`The answer lists ${String(parsed.data.length)} ${parsed.data.length === 1 ? "clip" : "clips"}, and ${String(limits.count)} were asked for.`);
+    return {
+        ok: true,
+        picks: kept
+            .toSorted((left, right) => left.start - right.start)
+            .map((pick, index) => ({ number: index + 1, ...pick })),
+        problems,
+    };
+}
+// The sentence a failed pick ends on, when not even the second answer held a usable clip.
+export function noPicksMessage(problems, limits) {
+    const shortVideo = limits.durationSeconds < limits.minSeconds;
+    if (shortVideo)
+        return `The narration is ${String(Math.round(limits.durationSeconds))} seconds long, shorter than the ${String(limits.minSeconds)}-second minimum for a short, so there is nothing to cut. Lower the shortest length in Edit project → Shorts, then Retry stage.`;
+    return `The AI model didn't pick any clip Slopify could use as a short, twice (${problems[0] ?? "no clips were listed"}). Retry stage; if it keeps happening, widen the length range in Edit project → Shorts, or choose another model in Edit project → Providers.`;
+}
+function round(seconds) {
+    return Math.round(seconds * 1000) / 1000;
+}
+// The array in the answer, wherever the model put it: bare, in a ```json fence, or after a
+// sentence of its own.
+function jsonArrayOf(text) {
+    const start = text.indexOf("[");
+    const end = text.lastIndexOf("]");
+    if (start === -1 || end <= start)
+        return undefined;
+    try {
+        return JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/slices/shorts/prompts.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+export function imagePromptMessages(brief) {
+    const plural = brief.count === 1 ? "prompt" : "prompts";
+    return [
+        {
+            role: "system",
+            content: [
+                "You write prompts for an image model. Answer with one JSON array of strings and nothing else, like:",
+                '["...", "..."]',
+                "",
+                "Rules the answer must follow:",
+                `- Exactly ${String(brief.count)} ${plural}, one per image, in the order the images are shown.`,
+                `- Each image is on screen for about ${String(brief.imageSeconds)} seconds of the clip, so image 1 shows the start of what is said, the next one what follows, and so on.`,
+                "- Every image is vertical (9:16).",
+                "- Each prompt stands on its own: the image model sees one prompt at a time, so repeat the style in every prompt.",
+                "- No text, captions or letters in the images.",
+            ].join("\n"),
+        },
+        {
+            role: "user",
+            content: [
+                "Style and instructions for every image:",
+                brief.style,
+                "",
+                `Video: ${brief.videoTitle}`,
+                `Short: ${brief.shortTitle}`,
+                "",
+                "What is said in the short:",
+                brief.text,
+            ].join("\n"),
+        },
+    ];
+}
+const fix = "Retry stage, or choose another model in Edit project → Providers.";
+// The reason is the sentence the stage shows; the provider wrapper's `check` asks the model
+// again while attempts remain.
+export function checkImagePrompts(text, count) {
+    const parsed = z.array(z.string()).safeParse(jsonArrayOf(text));
+    if (!parsed.success)
+        return {
+            ok: false,
+            reason: `The AI model's image prompts for a short didn't come back in the expected format (a JSON list of prompts). ${fix}`,
+        };
+    const prompts = parsed.data.map((prompt) => prompt.replace(/\s+/g, " ").trim());
+    if (prompts.length !== count)
+        return {
+            ok: false,
+            reason: `The AI model wrote ${String(prompts.length)} image prompts for a short that needs exactly ${String(count)}. ${fix}`,
+        };
+    if (prompts.some((prompt) => prompt === ""))
+        return {
+            ok: false,
+            reason: `One of the AI model's image prompts for a short is empty. ${fix}`,
+        };
+    return { ok: true, prompts };
+}
+function jsonArrayOf(text) {
+    const start = text.indexOf("[");
+    const end = text.lastIndexOf("]");
+    if (start === -1 || end <= start)
+        return undefined;
+    try {
+        return JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/slices/shorts/render.js

@@ -0,0 +1,163 @@
+import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { editListVersion } from "../video/edit-list.js";
+import { runFfmpeg } from "../video/ffmpeg.js";
+import { motionFor } from "../video/motion.js";
+import { fps } from "../video/plan.js";
+import { renderSlideshow } from "../video/slideshow.js";
+import { fasterWords, shortCaptionsAss } from "./captions.js";
+// A short is rendered in three steps. Its sound is cut out of the video's own timeline (the
+// silence at the start, intro, gaps, body, outro), which is the timeline the word timing
+// walked, so a clip's start and end in seconds are the same seconds in the audio. Then the
+// images play as the video's slideshow does, with the project's motion, and the join burns
+// the captions in through the same `ass` filter and font folder the video's captions use.
+export const shortFrame = { width: 1080, height: 1920 };
+const sampleRate = 44100;
+const channelLayout = "stereo";
+// ceiling: the ducking. The music dips once the narration passes about -34 dBFS, by up to
+// 8:1, within 20 ms, and comes back over 400 ms after the voice stops, so it swells in the
+// pauses without pumping between words. It fades in over the first second and out over the
+// last two.
+const duck = "threshold=0.02:ratio=8:attack=20:release=400:makeup=1";
+const fadeIn = 1;
+const fadeOut = 2;
+// The segments of the timeline the clip overlaps, joined and trimmed to the clip at the
+// sample, as a WAV the slideshow's join plays under the images. At a speed above 1 the
+// narration is played faster with its pitch kept (`atempo`); with music, the file is looped
+// to the clip's length, faded in and out, and mixed under the narration, dipping while it
+// speaks.
+export function shortAudioArgs(timeline, start, end, output, options = {}) {
+    const inputs = [];
+    const chains = [];
+    let offset = 0;
+    let first;
+    let count = 0;
+    for (const segment of timeline) {
+        const from = offset;
+        offset += segment.seconds;
+        if (offset <= start || from >= end)
+            continue;
+        first ??= from;
+        if (segment.path === null)
+            inputs.push("-f", "lavfi", "-t", segment.seconds.toFixed(6), "-i", `anullsrc=r=${String(sampleRate)}:cl=${channelLayout}`);
+        else
+            inputs.push("-i", segment.path);
+        chains.push(`[${String(count)}:a]aformat=sample_fmts=fltp:sample_rates=${String(sampleRate)}:channel_layouts=${channelLayout}[a${String(count)}]`);
+        count += 1;
+    }
+    if (count === 0 || first === undefined)
+        throw new Error("A short's clip falls outside the narration, so it has no sound to cut. Use Pick different moments in Edit project → Shorts, then Retry stage.");
+    const joined = Array.from({ length: count }, (_value, at) => `[a${String(at)}]`).join("");
+    chains.push(`${joined}concat=n=${String(count)}:v=0:a=1[joined]`);
+    const speed = options.speed ?? 1;
+    const music = options.music;
+    const trimmed = `[joined]atrim=start=${(start - first).toFixed(6)}:end=${(end - first).toFixed(6)},asetpts=PTS-STARTPTS`;
+    const tempo = speed === 1 ? "" : `,atempo=${speed.toFixed(4)}`;
+    if (music === undefined)
+        chains.push(`${trimmed}${tempo}[a]`);
+    else {
+        const seconds = (end - start) / speed;
+        const out = Math.max(0, seconds - fadeOut);
+        // Looped endlessly and cut to the clip, so a file shorter than the short plays again.
+        inputs.push("-stream_loop", "-1", "-i", music.path);
+        chains.push(`${trimmed}${tempo},asplit=2[voice][key]`);
+        chains.push(`[${String(count)}:a]aformat=sample_fmts=fltp:sample_rates=${String(sampleRate)}:channel_layouts=${channelLayout},atrim=end=${seconds.toFixed(6)},asetpts=PTS-STARTPTS,volume=${(music.volume / 100).toFixed(4)},afade=t=in:st=0:d=${String(fadeIn)},afade=t=out:st=${out.toFixed(6)}:d=${String(fadeOut)}[bed]`);
+        chains.push(`[bed][key]sidechaincompress=${duck}[ducked]`);
+        // The narration keeps its level; `normalize=0` stops amix halving both.
+        chains.push("[voice][ducked]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[a]");
+    }
+    return [
+        "-hide_banner",
+        "-nostdin",
+        "-loglevel",
+        "error",
+        "-progress",
+        "pipe:1",
+        "-nostats",
+        "-y",
+        ...inputs,
+        "-filter_complex",
+        chains.join(";"),
+        "-map",
+        "[a]",
+        "-c:a",
+        "pcm_s16le",
+        output,
+    ];
+}
+// The images each hold `imageSeconds` in order, the last one running to the end of the clip,
+// moving as the video's shots move by their place.
+export function shortEditList(input) {
+    if (input.images.length === 0)
+        throw new Error("A short has no images to show. Use Make this short again in Edit project → Shorts, then Retry stage.");
+    const total = Math.max(1, Math.round(input.seconds * fps));
+    const each = Math.max(1, Math.round(input.imageSeconds * fps));
+    const images = input.images.slice(0, Math.max(1, Math.ceil(total / each)));
+    const shots = images.flatMap((path, at) => {
+        const frames = at < images.length - 1 ? each : total - each * (images.length - 1);
+        return frames > 0
+            ? [
+                {
+                    source: { kind: "image", path },
+                    frames,
+                    motion: motionFor(input.motionStyle, at, input.zoomPercent),
+                },
+            ]
+            : [];
+    });
+    return {
+        version: editListVersion,
+        ...shortFrame,
+        fps,
+        audio: [{ kind: "body", path: input.audioPath, seconds: input.seconds }],
+        shots,
+    };
+}
+export async function renderShort(run) {
+    const speed = run.speed ?? 1;
+    // The images keep their share of what is said, so at a higher speed each is on screen
+    // for less time and the count stays the one the prompts were written for.
+    const seconds = (run.end - run.start) / speed;
+    const workspace = mkdtempSync(join(run.scratch, "short-"));
+    try {
+        const audio = join(workspace, "clip.wav");
+        await runFfmpeg({
+            bin: run.bin,
+            args: shortAudioArgs(run.timeline, run.start, run.end, audio, {
+                speed,
+                music: run.music,
+            }),
+            signal: run.signal,
+            log: run.log,
+            onProgress: () => undefined,
+        });
+        writeFileSync(join(workspace, "subtitles.ass"), shortCaptionsAss(fasterWords(run.words, speed), {
+            ...shortFrame,
+            fontName: run.font.assName,
+            ...(run.title === undefined ? {} : { title: { text: run.title, seconds } }),
+        }), { mode: 0o600 });
+        mkdirSync(join(workspace, "fonts"), { mode: 0o700 });
+        copyFileSync(run.font.path, join(workspace, "fonts", `selected${run.font.extension}`));
+        await renderSlideshow({
+            bin: run.bin,
+            edit: shortEditList({
+                audioPath: audio,
+                seconds,
+                images: run.images,
+                imageSeconds: run.imageSeconds / speed,
+                motionStyle: run.motionStyle,
+                zoomPercent: run.zoomPercent,
+            }),
+            output: run.output,
+            burnSubtitles: true,
+            cwd: workspace,
+            scratch: workspace,
+            signal: run.signal,
+            log: run.log,
+            onProgress: run.onProgress,
+        });
+    }
+    finally {
+        rmSync(workspace, { recursive: true, force: true });
+    }
+}

package/dist/slices/storage/asset-name.js

@@ -2,7 +2,8 @@
 // the project page builds the same URL for every image, player and download link it
 // draws, and `downloads.ts` reads the disk: importing it into the SPA would drag
 // `node:fs` and the zip encoder into the browser bundle. Nothing here touches IO.
-// An output's role is its asset name; images add their place in the slideshow, and the
+// An output's role is its asset name; images (and animated images) add their place in the
+// slideshow, and the
 // instructions add their stage, those being the two roles a project holds more than one of -
 // research and the article each store what they sent.
 export function assetOf(output) {
@@ -10,10 +11,16 @@ export function assetOf(output) {
     if ((output.role === "narration_txt" || output.role === "tts_script") &&
         output.meta.segment !== undefined)
         return `${asset}-${output.meta.segment}`;
+    // A project holds one video per short and several images per short.
+    if (output.role === "short_video" && output.meta.short !== undefined)
+        return `${asset}-${String(output.meta.short)}`;
+    if (output.role === "short_image" && output.meta.short !== undefined)
+        return `${asset}-${String(output.meta.short)}-${String(output.meta.index ?? 1)}`;
     if (output.role === "instructions") {
         return `${output.stageKind}-${asset}`;
     }
-    return output.role === "image" && output.meta.index !== undefined
+    return (output.role === "image" || output.role === "animated_image") &&
+        output.meta.index !== undefined
         ? `${asset}-${String(output.meta.index)}`
         : asset;
 }

package/dist/slices/storage/layout.js

@@ -60,6 +60,14 @@ export function outputFileName(role, index, extension, stageKind) {
             return "description.txt";
         case "youtube_tags":
             return "tags.txt";
+        case "shorts":
+            return "shorts.json";
+        case "short_image":
+            return `shorts/image-${String(index).padStart(3, "0")}${extension}`;
+        case "short_video":
+            return `shorts/short-${String(index).padStart(2, "0")}${extension}`;
+        case "animated_image":
+            return `animated/image-${String(index).padStart(3, "0")}${extension}`;
         case "audio_body":
             return `audio-body${extension}`;
         case "audio_export":

package/dist/slices/storage/model.js

@@ -27,5 +27,11 @@ export const outputRoles = [
     "document_pdf",
     "youtube_description",
     "youtube_tags",
+    // The Shorts step: the picked clips (JSON), each clip's vertical images, and each clip.
+    "shorts",
+    "short_image",
+    "short_video",
+    // An image of the slideshow brought to life by an image-to-video model (Animate images).
+    "animated_image",
 ];
 export const stagedFileStates = ["copying", "staged"];

package/dist/slices/storage/schema.js

@@ -9,6 +9,9 @@ export const metaSchema = z.object({
     promptName: z.string().optional(),
     prompt: z.string().optional(),
     index: z.number().optional(),
+    short: z.number().optional(),
+    sentences: z.tuple([z.number(), z.number()]).optional(),
+    warnings: z.array(z.string()).optional(),
     provider: z.string().optional(),
     model: z.string().optional(),
     voice: z.string().optional(),

package/dist/slices/telemetry/model.js

@@ -37,4 +37,7 @@ export const payloadSchema = z.strictObject({
     // A written YouTube description. Its event names no stage: it is made inside the Video
     // stage, and a collector counting stage "video" as a finished video must not count it.
     descriptions: z.number().int().nonnegative().optional(),
+    // A rendered short. Like a description it names no stage: the Shorts step runs inside
+    // the Video stage, and a short is not a finished video.
+    shorts: z.number().int().nonnegative().optional(),
 });

package/dist/slices/video/cards.js

@@ -0,0 +1,72 @@
+// Chapter cards as an ASS script the clips draw with libass, the renderer the captions use,
+// so a card is set in the subtitle font without a font-rendering filter of its own (this
+// ffmpeg has none). Each card is centred, well above where captions sit by default, and fades
+// in and out. Every clip a card shows in gets its own script with the times counted from the
+// clip's first frame (`offset`), since a clip's frames count from zero.
+// ceiling: the owner's eye. The fades take 0.4 s each of the card's 2.5 s.
+const fadeMs = 400;
+export function cardsAss(edit, cards, fontName, offset = 0) {
+    const { width, height, fps } = edit;
+    // The title is sized from the frame's short side, so a vertical video's card fits too. At
+    // 8% it read as a caption rather than a chapter title; 11% and bold gives it presence.
+    const size = Math.round(Math.min(width, height) * 0.11);
+    // A wide, blurred, half-clear dark outline: a soft shadow all round that keeps the title
+    // readable on a bright picture without a box behind it.
+    const outline = Math.max(2, Math.round(size / 10));
+    const header = [
+        "[Script Info]",
+        "ScriptType: v4.00+",
+        `PlayResX: ${String(width)}`,
+        `PlayResY: ${String(height)}`,
+        "WrapStyle: 0",
+        "ScaledBorderAndShadow: yes",
+        "",
+        "[V4+ Styles]",
+        "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
+        // White bold text, the soft outline, no offset shadow, centred (alignment 5), letter-spaced.
+        `Style: Card,${fontName.replace(/,/g, " ")},${String(size)},&H00FFFFFF,&H00FFFFFF,&H60000000,&H00000000,-1,0,0,0,100,100,${String(Math.round(size / 12))},0,1,${String(outline)},0,5,${String(Math.round(width * 0.1))},${String(Math.round(width * 0.1))},0,1`,
+        "",
+        "[Events]",
+        "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
+    ];
+    const events = cards.flatMap((card) => {
+        const from = card.startFrame - offset;
+        const to = from + card.frames;
+        if (to <= 0)
+            return [];
+        // A card that began before this clip starts with the clip, part way through its fade in
+        // (or past it), so it runs on from the clip before without a second fade.
+        const before = Math.max(0, (-from / fps) * 1000);
+        const length = Math.round((to / fps) * 1000);
+        const fade = before === 0
+            ? `\\fad(${String(fadeMs)},${String(fadeMs)})`
+            : `\\fade(${String(Math.round(255 * Math.max(0, 1 - before / fadeMs)))},0,255,0,${String(Math.max(0, Math.round(fadeMs - before)))},${String(length - fadeMs)},${String(length)})`;
+        return [
+            `Dialogue: 0,${assTime(Math.max(0, from) / fps)},${assTime(to / fps)},Card,,0,0,0,,{\\blur${String(outline)}${fade}${settle(before)}}${assText(card.title)}`,
+        ];
+    });
+    return `${[...header, ...events].join("\n")}\n`;
+}
+// The title settles from 96% to full size while it fades in, a small movement that reads as
+// a title arriving rather than text appearing. A card carried on from the clip before is
+// already settled.
+function settle(before) {
+    if (before >= fadeMs)
+        return "";
+    const from = Math.round(96 + (4 * before) / fadeMs);
+    return `\\fscx${String(from)}\\fscy${String(from)}\\t(0,${String(Math.round(fadeMs - before))},\\fscx100\\fscy100)`;
+}
+// h:mm:ss.cc, the centiseconds ASS counts in.
+function assTime(seconds) {
+    const centis = Math.max(0, Math.round(seconds * 100));
+    const h = Math.floor(centis / 360000);
+    const m = Math.floor((centis % 360000) / 6000);
+    const s = Math.floor((centis % 6000) / 100);
+    const c = centis % 100;
+    return `${String(h)}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}.${String(c).padStart(2, "0")}`;
+}
+// A title is plain text: braces would start an override block and a backslash an escape, so
+// both are replaced, and a line break is a space.
+function assText(text) {
+    return text.replace(/[{}]/g, "").replace(/\\/g, "/").replace(/\s+/g, " ").trim();
+}