@docyrus/animaguru 0.8.1 → 0.9.0

package/package.json

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

package/skills/animaguru/SKILL.md

@@ -117,6 +117,14 @@ The JSON result returns the video ID and watch URL. Owners manage details and re
 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.
 

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
 

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>;