@docyrus/animaguru 0.8.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/animaguru",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Agent-friendly AnimaGuru CLI built with CrustJS",
   "type": "module",
   "bin": {

package/skills/animaguru/SKILL.md

@@ -114,9 +114,19 @@ Submissions default to private. `--share` is a comma-separated list of verified
 
 The JSON result returns the video ID and watch URL. Owners manage details and recipients on that page, or run `animaguru videos share VIDEO_ID --visibility private --share "reviewer@example.com" --yes`; this replaces the entire recipient list. Public sharing uses `--visibility public` without `--share`. Removing a recipient or making a public film private blocks previous playback URLs immediately. `animaguru videos delete VIDEO_ID --yes` removes the hosted files.
 
+For an MP4, `submit` also uploads `FILM.vtt` or `FILM.srt` from beside it as subtitles, which the AnimaGuru player shows over the picture (CLI 0.10.0). The dry run lists the file and language; use `--subtitles FILE`, `--subtitles none` or `--subtitle-language CODE` when needed. Upload the clean MP4 with its subtitles rather than a `-captioned.mp4`, unless the user wants captions in the picture. `animaguru videos subtitles VIDEO_ID --file FILE --yes` adds or replaces one language on an uploaded MP4 and `--remove CODE --yes` removes one. New subtitles on a public video send it back for staff review.
+
 Uploads use checksum-verified parts. After an interrupted submission, inspect the printed ID first. If all parts arrived, `animaguru videos complete VIDEO_ID` safely retries finalization and returns the existing result when already complete. Otherwise cancel that draft with `videos delete --yes` before submitting again. Do not silently delete a potentially successful publication after a network timeout.
 
 
+## Upload a local MP4 to YouTube
+
+CLI 0.9.0 adds local YouTube uploads independently of AnimaGuru hosting. Discover `youtube` in `animaguru schema`. Run `animaguru youtube auth login --client-file PATH --yes --no-browser` only when channel authorization is requested; the user approves the printed Google URL on the same computer. Use a Google **Desktop app** OAuth JSON file. Add `--captions` only when the user wants subtitles uploaded, and tell them it grants Google's broader `youtube.force-ssl` permission, which also allows managing their videos. Never read or print saved tokens or upload session URLs.
+
+After MP4 export, inspect with `animaguru youtube upload --file FILE --title TITLE --privacy private --made-for-kids no --synthetic-media yes --dry-run`. Choose the audience and realistic synthetic-content declarations from the actual film and the user's answers; those example values are not defaults. A request to create/export a film does not authorize sending it to YouTube. Use `--yes` only when the user authorizes the file, channel and visibility. `youtube auth status` identifies the connected channel and whether caption uploads are allowed; `--channel CHANNEL_ID` can pin the destination. By default the upload adds `FILM.srt` (or `FILM.vtt`) from beside the MP4 as a caption track, with the language from the export receipt; the dry run lists it. Use `--captions FILE`, `--captions none` or `--caption-language CODE` when needed. It also sets `FILM.jpg` from beside the MP4 (the export's `poster` frame) as the custom thumbnail; `--thumbnail FILE` or `--thumbnail none` change that, and custom thumbnails need a verified channel. A `captionsError` or `thumbnailError` in the result means the video is uploaded but that part is not; resume the printed upload ID with `youtube uploads resume UPLOAD_ID --yes`.
+
+Uploads run locally while the CLI is open. After interruption, use `youtube uploads list` and `youtube uploads resume UPLOAD_ID --yes` instead of starting another upload. Resumption uses the original file and settings and probes Google's persisted offset. `youtube auth logout --yes` revokes access and removes local credentials and receipts; videos remain on YouTube. No AnimaGuru backend, sign-in or generation credits are used.
+
 ## Shared workspace commands
 
 Run tooling from the workspace root. `npm run dev` opens a hub with separate animation URLs. Use `npm run build -- --animation NAME`, `npm run export:html -- --animation NAME`, `npm run export:mp4 -- --animation NAME`, or `npm run review -- --animation NAME`. These select one film and save outputs/receipts under its `production/` directory. `npm run example -- STYLE_ID --animation NAME` installs an original study only when the selected film is untouched. Root `runtime/`, `scripts/`, skills and dependencies are shared infrastructure.

package/skills/animaguru-video/SKILL.md

@@ -64,7 +64,7 @@ Run `npm run build`. Review the actual browser at desktop and mobile sizes, play
 
 Deliver the playable HTML film first unless the user asked for MP4 too. For an embeddable HTML5 deliverable, use the download menu or `npm run export:html`. Unzip and test the static package over HTTP(S), including its iframe example; it should play without the authoring workspace or an AnimaGuru account. `npm run build` includes the same download in the static player. Preserve embed mode and hide authoring controls there.
 
-For MP4, run `npm run export:mp4`, open the printed local capture URL in an available browser, and keep it open until completion. The script verifies H.264/AAC, dimensions, duration and exact frame count and writes a JSON report next to the MP4. Exporting existing local assets spends no generation credits. If browser control is unavailable, give the user the printed URL and explain the one manual step.
+For MP4, run `npm run export:mp4`, open the printed local capture URL in an available browser, and keep it open until completion. The script verifies H.264/AAC, dimensions, duration and exact frame count and writes a JSON report next to the MP4. Captions stay out of the picture; the `captions` resource track becomes `.srt` (YouTube, desktop players) and `.vtt` (HTML5) subtitle files with the MP4's name, so keep that track's clips equal to the spoken lines. For social feeds that need open captions, add `-- --burn-captions`; it saves `SLUG-LANGUAGE-captioned.mp4` with captions in the picture and no subtitle files. Set `"poster"` in `film.config.json` to the seconds of the film's most representative frame (title, product or end card, never a fade or a blank moment); the export saves it beside the MP4 as a 1280-pixel JPEG thumbnail, which `animaguru youtube upload` and video pages can use. Exporting existing local assets spends no generation credits. If browser control is unavailable, give the user the printed URL and explain the one manual step.
 
 `npm run dev` starts the preview. The capture API and file map are documented in the generated project README. Publishing a website, package or campaign is separate from creating the local video.
 
@@ -78,7 +78,7 @@ Use `src/studies/timing.ts` for analytic easing, measured stroke reveals and cue
 
 ## Sharing a finished film
 
-When the user requests hosting or sharing, use `animaguru submit --yes` from this workspace; it builds and submits the portable HTML5 animation. For an MP4 use `--file production/exports/film.mp4`. Read the local AnimaGuru skill's submission section for audience, recipient and recovery rules. Private is the default; use `--share "reviewer@example.com"` for selected verified accounts or `--visibility public` for [the public Videos section](https://animaguru.com/videos). Preserve the user's audience choice and include a cover using `--poster` when available. Local creation or export alone does not imply publication.
+When the user requests hosting or sharing, use `animaguru submit --yes` from this workspace; it builds and submits the portable HTML5 animation. For an MP4 use `--file production/exports/film.mp4`; its `.vtt`/`.srt` subtitles beside it are uploaded too and shown by the AnimaGuru player, so submit the clean MP4 rather than a `-captioned.mp4`. Read the local AnimaGuru skill's submission section for audience, recipient and recovery rules. Private is the default; use `--share "reviewer@example.com"` for selected verified accounts or `--visibility public` for [the public Videos section](https://animaguru.com/videos). Preserve the user's audience choice and include a cover using `--poster` when available. Local creation or export alone does not imply publication.
 
 
 ## Multi-animation workspace

package/templates/video/AGENTS.md

@@ -31,4 +31,4 @@ Original 2.5D study recipes are in `src/studies/`. In an untouched starter, `npm
 
 ## Submit to AnimaGuru
 
-When asked to host or share the finished film, read the local AnimaGuru skill's submission section. `animaguru submit --yes` builds the portable HTML5 export and uploads it privately; `--file` accepts an existing HTML5 ZIP or MP4. `--share "reviewer@example.com"` selects verified AnimaGuru accounts, while `--visibility public` publishes to https://animaguru.com/videos and allows watching, downloading and HTML5 embedding. Include a cover with `--poster public/assets/cover.png` when available. Do not infer public sharing from a request to create or export a film. The CLI returns the hosted watch URL and video ID. Owners can change details and sharing from that page.
+When asked to host or share the finished film, read the local AnimaGuru skill's submission section. `animaguru submit --yes` builds the portable HTML5 export and uploads it privately; `--file` accepts an existing HTML5 ZIP or MP4; an MP4's `.vtt`/`.srt` subtitles beside it are uploaded with it, so prefer the clean MP4 over a `-captioned.mp4`. `--share "reviewer@example.com"` selects verified AnimaGuru accounts, while `--visibility public` publishes to https://animaguru.com/videos and allows watching, downloading and HTML5 embedding. Include a cover with `--poster public/assets/cover.png` when available. Do not infer public sharing from a request to create or export a film. The CLI returns the hosted watch URL and video ID. Owners can change details and sharing from that page.

package/templates/video/CLAUDE.md

@@ -16,4 +16,4 @@ Accept schema 2 projects and saved `advertorial` as Advertisement with editorial
 
 Original 2.5D study recipes are in `src/studies/`. In an untouched starter, `npm run example -- STYLE_ID` installs one; it refuses to overwrite an authored film. Import the recipe directly for an existing production. `npm run review` checks actual visible text bounds and seek consistency, then saves frames and a report. Keep the HTML5-first delivery and use the client's identity in the film. Physically rendered 3D remains deferred.
 
-For requested hosting or sharing, use `animaguru submit --yes` in this workspace (private by default). `--share "reviewer@example.com"` shares with selected verified AnimaGuru accounts; `--visibility public` publishes to https://animaguru.com/videos. `--file` accepts an existing HTML5 ZIP or MP4. Read the local AnimaGuru skill's submission section for audience selection and upload recovery. Creation and local export do not imply publication.
+For requested hosting or sharing, use `animaguru submit --yes` in this workspace (private by default). `--share "reviewer@example.com"` shares with selected verified AnimaGuru accounts; `--visibility public` publishes to https://animaguru.com/videos. `--file` accepts an existing HTML5 ZIP or MP4; an MP4's `.vtt`/`.srt` subtitles beside it are uploaded with it. Read the local AnimaGuru skill's submission section for audience selection and upload recovery. Creation and local export do not imply publication.

package/templates/video/README.md

@@ -65,11 +65,13 @@ Allow extra iframe height for controls if needed. `?autoplay=1&loop=1&controls=0
 npm run export:mp4
 # If the export port is occupied:
 npm run export:mp4 -- --port 5197
+# Captions drawn into the picture, e.g. for social feeds (saved as SLUG-LANGUAGE-captioned.mp4):
+npm run export:mp4 -- --burn-captions
 ```
 
 Open the local capture URL printed by the command and keep it open until complete. The script runs a separate loopback Vite server (default port 5196), streams high-quality JPEG frames from the Pixi canvas to the bundled FFmpeg binary, and mixes the configured soundtrack. The initial starter exports with a silent AAC track. Exporting local media does not call AnimaGuru or spend credits. FFmpeg/FFprobe binaries are supplied through platform-specific npm dependencies; installation needs a supported platform and network access.
 
-Completed H.264/AAC MP4s and JSON verification reports appear in `production/exports/`. Existing files are preserved. Frame retries are deduplicated. Ctrl+C removes only this session's unfinished output. The verification checks duration, exact frame count, dimensions, pixel format, codecs and audio language tag. The exporter supports even dimensions up to 4096 pixels, 24/25/30/60 fps and films up to ten minutes. Set duration to an exact number of frames.
+Completed H.264/AAC MP4s and JSON verification reports appear in `production/exports/`. Captions are not drawn into the MP4 picture: the film's `captions` resource track is saved beside it as `SLUG-LANGUAGE.srt` (for YouTube and desktop players, which load a same-named file automatically) and `SLUG-LANGUAGE.vtt` (for an HTML5 `<track>`). `--burn-captions` instead draws them into the picture and writes no subtitle files, so players cannot show them twice. `"poster"` in `film.config.json` (seconds) picks the frame saved as `SLUG-LANGUAGE.jpg`, a caption-free thumbnail 1280 pixels on its longer side and under YouTube's 2 MB limit; without it, no thumbnail is saved. The live player and HTML5 export keep their CC toggle. Existing files are preserved. Frame retries are deduplicated. Ctrl+C removes only this session's unfinished output. The verification checks duration, exact frame count, dimensions, pixel format, codecs and audio language tag. The exporter supports even dimensions up to 4096 pixels, 24/25/30/60 fps and films up to ten minutes. Set duration to an exact number of frames.
 
 ## Capture API
 
@@ -98,4 +100,4 @@ Browse `animaguru.templates.json` for all 31 styles and purpose workflows. The e
 
 ## Share on AnimaGuru
 
-After signing in with `animaguru auth login`, run `animaguru submit --yes` here to build and host the finished HTML5 animation privately. Add `--share "reviewer@example.com"` to invite selected verified AnimaGuru accounts, or `--visibility public` to list it at [Videos](https://animaguru.com/videos). `--poster public/assets/cover.png` adds a cover. Already exported an MP4? Pass `--file production/exports/film.mp4`. The CLI returns your hosted player URL; public HTML5 animations can be embedded from that page. Owners manage details and access there. Only the exported player/media are uploaded.
+After signing in with `animaguru auth login`, run `animaguru submit --yes` here to build and host the finished HTML5 animation privately. Add `--share "reviewer@example.com"` to invite selected verified AnimaGuru accounts, or `--visibility public` to list it at [Videos](https://animaguru.com/videos). `--poster public/assets/cover.png` adds a cover. Already exported an MP4? Pass `--file production/exports/film.mp4`; the `.vtt` subtitles beside it are uploaded too, and the AnimaGuru player shows them over the picture with a CC button. The CLI returns your hosted player URL; public HTML5 animations can be embedded from that page. Owners manage details and access there. Only the exported player/media are uploaded.

package/templates/video/WORKSPACE-AGENTS.md

@@ -13,7 +13,7 @@ Run commands from the workspace root:
 - `npm run dev`: the workspace hub and separate `/animations/NAME/` players.
 - `npm run build -- --animation NAME`: typecheck and build that film.
 - `npm run export:html -- --animation NAME`: portable HTML5 ZIP with local media and common branding.
-- `npm run export:mp4 -- --animation NAME`: verified MP4; open the printed capture page.
+- `npm run export:mp4 -- --animation NAME`: verified MP4 without burned-in captions, plus `.srt`/`.vtt` subtitle files from the captions track (`--burn-captions` draws them into the picture instead, as `NAME-LANG-captioned.mp4`), and a `.jpg` thumbnail of the `poster` frame set in film.config.json; open the printed capture page.
 - `npm run review -- --animation NAME`: frame, text, seeking and soundtrack checks.
 - `npm run example -- STYLE_ID --animation NAME`: install a study only in an untouched selected film.
 - `animaguru submit animations/NAME --yes`: private hosting; choose recipients/public sharing from the user's request.

package/templates/video/film.config.json

@@ -6,5 +6,6 @@
   "fps": 30,
   "duration": 24,
   "language": "en",
-  "audio": null
+  "audio": null,
+  "poster": 3
 }

package/templates/video/scripts/export-mp4.mjs

@@ -9,12 +9,19 @@ import ffmpeg from "@ffmpeg-installer/ffmpeg";
 import ffprobe from "@ffprobe-installer/ffprobe";
 import { projectArguments, projectContext, publicFile } from "./project-context.mjs";
 import { workspacePlugin } from "./workspace-plugin.mjs";
+import { subtitleCues, toSrt, toVtt } from "./subtitles.mjs";
 
 const root = fileURLToPath(new URL("../", import.meta.url));
 const selection = projectArguments(process.argv.slice(2));
 const args = selection.rest;
-if (args.length && (args.length !== 2 || args[0] !== "--port" || !/^\d+$/.test(args[1]))) throw new Error("Usage: npm run export:mp4 -- [--port 5196]");
-const port = Number(args[1] ?? 5196);
+let port = 5196;
+// Captions become subtitle files beside the MP4 unless --burn-captions draws them into the picture, e.g. for social feeds.
+let burnCaptions = false;
+for (let index = 0; index < args.length; index++) {
+  if (args[index] === "--burn-captions") burnCaptions = true;
+  else if (args[index] === "--port" && /^\d+$/.test(args[index + 1] ?? "")) port = Number(args[++index]);
+  else throw new Error("Usage: npm run export:mp4 -- [--port 5196] [--burn-captions]");
+}
 if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("Export port must be 1024–65535.");
 const context = await projectContext(root, selection.animation);
 const config = context.config;
@@ -28,13 +35,18 @@ if (config.audio !== null) {
   if (typeof config.audio !== "string" || !config.audio) throw new Error("audio must be null or a local path relative to public/.");
   audioSource = await publicFile(context, config.audio);
 }
+// "poster": seconds in film.config.json picks the frame saved as a 1280-pixel JPEG thumbnail beside the MP4.
+if (config.poster != null && (typeof config.poster !== "number" || !Number.isFinite(config.poster) || config.poster < 0 || config.poster >= duration)) throw new Error("Set poster in film.config.json to a time within the film, in seconds, or leave it out.");
+const thumbnailScale = Math.min(1, 1280 / Math.max(width, height));
+const thumbnail = config.poster == null ? null : { time: config.poster, width: Math.round(width * thumbnailScale), height: Math.round(height * thumbnailScale) };
 const outputDirectory = context.output;
 await mkdir(outputDirectory, { recursive: true });
-let destination = path.join(outputDirectory, `${config.slug}-${language}.mp4`);
-for (const candidate of [destination, destination.replace(/\.mp4$/, ".partial.mp4")]) {
+const name = `${config.slug}-${language}${burnCaptions ? "-captioned" : ""}`;
+let destination = path.join(outputDirectory, `${name}.mp4`);
+for (const candidate of [destination, ...[".partial.mp4", ".srt", ".vtt", ".jpg"].map((extension) => destination.replace(/\.mp4$/, extension))]) {
   try {
     await access(candidate);
-    destination = path.join(outputDirectory, `${config.slug}-${language}-${randomUUID()}.mp4`);
+    destination = path.join(outputDirectory, `${name}-${randomUUID()}.mp4`);
     break;
   } catch (error) { if (error.code !== "ENOENT") throw error; }
 }
@@ -45,6 +57,8 @@ let encoderDone;
 let encoderError;
 let encoderLog = "";
 let settings;
+let subtitles = [];
+let thumbnailImage;
 let received = 0;
 let lastFrameHash;
 let frameQueue = Promise.resolve();
@@ -106,10 +120,13 @@ async function route(request, response, url) {
   const send = (value) => response.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify(value));
   if (url.pathname === "/__export/start") {
     if (encoder) throw new Error("Export has already started. Keep the original capture tab open.");
-    settings = JSON.parse((await readBody(request, 2048)).toString());
+    settings = JSON.parse((await readBody(request, 1024 * 1024)).toString());
     if (settings.language !== language) throw new Error(`Expected ${language} text and captions. Refusing to pair a different language with the audio.`);
     if (settings.width !== width || settings.height !== height || settings.fps !== fps || settings.duration !== duration) throw new Error("The player settings differ from film.config.json. Restart the export after changing the configuration.");
     settings.frames = Math.round(settings.duration * fps);
+    subtitles = subtitleCues(settings.subtitles ?? [], settings.duration);
+    delete settings.subtitles;
+    settings.captions = !subtitles.length ? "none" : burnCaptions ? "burned" : "subtitle-files";
     await writeFile(partial, "", { flag: "wx" });
     ownsPartial = true;
     encoder = spawn(ffmpeg.path, [
@@ -131,8 +148,8 @@ async function route(request, response, url) {
       encoder.once("close", (code) => code === 0 ? resolve() : reject(new Error(`FFmpeg exited ${code}: ${encoderLog}`)));
     });
     encoderDone.catch((error) => { encoderError = error; });
-    console.log(`Rendering ${language.toUpperCase()}: ${settings.frames} frames (${settings.duration}s), ${width} × ${height} / ${fps} fps.`);
-    send({ fps, frames: settings.frames }); return;
+    console.log(`Rendering ${language.toUpperCase()}: ${settings.frames} frames (${settings.duration}s), ${width} × ${height} / ${fps} fps, ${subtitles.length ? `${subtitles.length} captions ${burnCaptions ? "drawn into the picture" : "as subtitle files"}` : "no captions"}.`);
+    send({ fps, frames: settings.frames, burnCaptions, thumbnail }); return;
   }
   if (url.pathname === "/__export/frame") {
     if (!encoder || encoding || finished || aborted) throw new Error("No active frame capture.");
@@ -159,8 +176,18 @@ async function route(request, response, url) {
     await operation;
     send({ received }); return;
   }
+  if (url.pathname === "/__export/thumbnail") {
+    if (!encoder || encoding || !thumbnail || thumbnailImage || received !== settings.frames) throw new Error("Capture the thumbnail once, after every frame.");
+    // YouTube accepts custom thumbnails up to 2 MB.
+    const image = await readBody(request, 2 * 1024 * 1024);
+    const dimensions = jpegDimensions(image);
+    if (request.headers["content-type"] !== "image/jpeg" || dimensions?.width !== thumbnail.width || dimensions?.height !== thumbnail.height) throw new Error("Expected a JPEG thumbnail of the configured size.");
+    thumbnailImage = image;
+    send({ bytes: image.length }); return;
+  }
   if (url.pathname === "/__export/finish") {
     if (!encoder || encoding || received !== settings.frames) throw new Error("The capture is incomplete.");
+    if (thumbnail && !thumbnailImage) throw new Error("The thumbnail was not captured.");
     encoding = true;
     encoder.stdin.end();
     await encoderDone;
@@ -171,13 +198,20 @@ async function route(request, response, url) {
     const audio = probe.streams.find((stream) => stream.codec_type === "audio");
     if (!video || video.codec_name !== "h264" || video.width !== width || video.height !== height || Number(video.nb_read_frames) !== settings.frames || video.pix_fmt !== "yuv420p" || !audio || audio.codec_name !== "aac" || audio.tags?.language !== languageTag || Math.abs(Number(probe.format.duration) - settings.duration) > 0.15) throw new Error("The encoded file did not pass duration, frame count, dimensions, language, or codec verification.");
     await rename(partial, destination);
-    await writeFile(destination.replace(/\.mp4$/, ".json"), JSON.stringify({ file: path.basename(destination), audio: config.audio, settings, verification: probe }, null, 2) + "\n");
+    // A player would show a same-named subtitle file on top of burned-in captions, so those exports get none.
+    const subtitleFiles = subtitles.length && !burnCaptions ? [[".srt", toSrt(subtitles)], [".vtt", toVtt(subtitles, language)]].map(([extension, text]) => ({ path: destination.replace(/\.mp4$/, extension), text })) : [];
+    for (const file of subtitleFiles) await writeFile(file.path, file.text);
+    const thumbnailFile = thumbnailImage ? destination.replace(/\.mp4$/, ".jpg") : null;
+    if (thumbnailFile) await writeFile(thumbnailFile, thumbnailImage);
+    await writeFile(destination.replace(/\.mp4$/, ".json"), JSON.stringify({ file: path.basename(destination), title: config.title, audio: config.audio, subtitles: subtitleFiles.map((file) => path.basename(file.path)), thumbnail: thumbnailFile && { file: path.basename(thumbnailFile), time: thumbnail.time }, settings, verification: probe }, null, 2) + "\n");
     const bytes = (await stat(destination)).size;
     finished = true;
     clearInterval(idleCheck);
     console.log(`Saved: ${destination}\nSize: ${(bytes / 1024 / 1024).toFixed(1)} MiB\nVerified: ${settings.frames} frames, ${settings.duration}s, H.264 video and AAC audio.`);
+    if (subtitleFiles.length) console.log(`Subtitles (${subtitles.length} captions, ${language}): ${subtitleFiles.map((file) => file.path).join(", ")}`);
+    console.log(thumbnailFile ? `Thumbnail (${thumbnail.time}s): ${thumbnailFile}` : 'No thumbnail: set "poster" in film.config.json to the seconds of the frame to save as one.');
     response.once("finish", () => { void server.close(); });
-    send({ path: destination, bytes }); return;
+    send({ path: destination, bytes, subtitles: subtitleFiles.map((file) => file.path), thumbnail: thumbnailFile }); return;
   }
   if (url.pathname === "/__export/abort") {
     const message = JSON.parse((await readBody(request, 4096)).toString());

package/templates/video/scripts/subtitles.mjs

@@ -0,0 +1,42 @@
+/** Subtitle files written beside an exported MP4: SubRip for YouTube and desktop players, WebVTT for HTML5 <track>. */
+
+const LINE_LENGTH = 42;
+
+/** Validates caption clips from the player and returns them in display order, clipped to the film. */
+export function subtitleCues(input, duration) {
+  if (!Array.isArray(input) || input.length > 5000) throw new Error("Subtitles must be a list of at most 5000 captions.");
+  return input.map((cue) => {
+    const start = Number(cue?.start), end = Math.min(Number(cue?.end), duration);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || typeof cue.text !== "string" || cue.text.length > 1000) throw new Error("Each caption needs a start, an end and text of up to 1000 characters.");
+    const text = cue.text.replace(/\r\n?/g, "\n").split("\n").map((line) => line.replace(/\s+/g, " ").trim()).filter(Boolean).join("\n");
+    return { start, end, text };
+  }).filter((cue) => cue.text && cue.end > cue.start).sort((a, b) => a.start - b.start || a.end - b.end);
+}
+
+/** Splits a long single-line caption into two lines; captions with their own line breaks are kept. */
+export function subtitleLines(text) {
+  if (text.includes("\n") || text.length <= LINE_LENGTH) return text;
+  let best = -1, bestCost = Infinity;
+  for (let index = text.indexOf(" "); index > 0; index = text.indexOf(" ", index + 1)) {
+    const first = text.slice(0, index), second = text.slice(index + 1);
+    // The shorter the longer line the better; a break after punctuation reads better, one after a short word like "a" worse.
+    const cost = Math.max(first.length, second.length) - (/[,;:.!?]$/.test(first) ? 8 : 0) + (/(?:^|\s)[\p{L}\p{N}']{1,3}$/u.test(first) ? 6 : 0);
+    if (cost < bestCost) { best = index; bestCost = cost; }
+  }
+  return best < 0 ? text : `${text.slice(0, best)}\n${text.slice(best + 1)}`;
+}
+
+function timestamp(seconds, separator) {
+  const ms = Math.round(seconds * 1000);
+  const pad = (value, size = 2) => String(value).padStart(size, "0");
+  return `${pad(Math.floor(ms / 3600000))}:${pad(Math.floor(ms / 60000) % 60)}:${pad(Math.floor(ms / 1000) % 60)}${separator}${pad(ms % 1000, 3)}`;
+}
+
+export function toSrt(cues) {
+  return cues.map((cue, index) => `${index + 1}\n${timestamp(cue.start, ",")} --> ${timestamp(cue.end, ",")}\n${subtitleLines(cue.text)}\n`).join("\n");
+}
+
+export function toVtt(cues, language) {
+  const escape = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return `WEBVTT\nLanguage: ${language}\n\n${cues.map((cue) => `${timestamp(cue.start, ".")} --> ${timestamp(cue.end, ".")}\n${escape(subtitleLines(cue.text))}\n`).join("\n")}`;
+}

package/templates/video/shared/locales/en/export.json

@@ -1,10 +1,12 @@
 {
   "preparing": "Preparing MP4 export…",
   "rendering": "Rendering MP4 · {percent}% · {frame} / {total} frames. Keep this tab open.",
+  "thumbnail": "Saving the thumbnail…",
   "finishing": "Finishing the MP4 and checking its video and audio…",
   "saved": "MP4 saved: {path}",
   "failed": "Export stopped: {error}",
   "requestFailed": "Capture request failed.",
   "languageChanged": "The language changed during capture. Restart the export.",
-  "captureFailed": "Could not capture frame {frame}."
+  "captureFailed": "Could not capture frame {frame}.",
+  "thumbnailFailed": "Could not capture the thumbnail."
 }

package/templates/video/src/exporter.ts

@@ -10,6 +10,7 @@ type CaptureApi = {
   canvas: HTMLCanvasElement;
   fps: number;
   language: string;
+  resources: { kind: string; clips: { start: number; end: number; label: string }[] }[];
   renderFrame(frame: number, fps: number): Promise<void>;
   setCaptions(enabled: boolean): void;
   pause(): void;
@@ -40,9 +41,11 @@ export async function exportMp4(api: CaptureApi, token: string) {
   };
   try {
     api.pause();
-    api.setCaptions(true);
     const language = api.language;
-    const settings = await request("start", JSON.stringify({ width: api.width, height: api.height, duration: api.duration, fps: api.fps, language }));
+    const subtitles = api.resources.filter((track) => track.kind === "captions").flatMap((track) => track.clips.map((clip) => ({ start: clip.start, end: clip.end, text: clip.label })));
+    const settings = await request("start", JSON.stringify({ width: api.width, height: api.height, duration: api.duration, fps: api.fps, language, subtitles }));
+    // The export command decides: captions drawn into the picture, or saved as .srt/.vtt files beside a clean MP4.
+    api.setCaptions(settings.burnCaptions === true);
     state.total = settings.frames;
     state.status = "rendering";
     for (let frame = 0; frame < settings.frames; frame++) {
@@ -54,6 +57,24 @@ export async function exportMp4(api: CaptureApi, token: string) {
       state.frame = frame + 1;
       status.textContent = message("rendering", { percent: Math.round(state.frame / state.total * 100), frame: state.frame.toLocaleString(), total: state.total.toLocaleString() });
     }
+    if (settings.thumbnail) {
+      // A clean frame without captions, scaled to YouTube's 1280-pixel thumbnail size and kept under its 2 MB limit.
+      status.textContent = copy.thumbnail;
+      api.setCaptions(false);
+      await api.renderFrame(Math.min(settings.frames - 1, Math.round(settings.thumbnail.time * settings.fps)), settings.fps);
+      const canvas = document.createElement("canvas");
+      canvas.width = settings.thumbnail.width; canvas.height = settings.thumbnail.height;
+      const context = canvas.getContext("2d")!;
+      context.imageSmoothingQuality = "high";
+      context.drawImage(api.canvas, 0, 0, canvas.width, canvas.height);
+      let image: Blob | null = null;
+      for (const quality of [0.92, 0.82, 0.7]) {
+        image = await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, "image/jpeg", quality));
+        if (image && image.size <= 2 * 1024 * 1024) break;
+      }
+      if (!image) throw new Error(copy.thumbnailFailed);
+      await request("thumbnail", image, "image/jpeg");
+    }
     state.status = "encoding";
     status.textContent = copy.finishing;
     const result = await request("finish", "{}");

package/templates/video/src/player-types.ts

@@ -4,6 +4,8 @@ import type { ResourceTrack } from "./timeline-model";
 export type FilmConfig = {
   title: string; slug: string; width: number; height: number; fps: number;
   duration: number; language: string; audio: string | null;
+  /** Seconds of the frame the MP4 export saves as its JPEG thumbnail. */
+  poster?: number | null;
 };
 export type Branding = {
   name: string; tagline: string; logo: string | null; assets?: Record<string, string>;