@docyrus/animaguru 0.9.0 → 0.10.0

package/README.md

@@ -273,6 +273,16 @@ animaguru submit --file production/exports/film.zip --dry-run
 
 An optional positional directory selects the workspace; file and poster paths are relative to it. HTML5 exports upload the compiled animation and local media; source code, project instructions, credentials and generation receipts are not submitted. MP4 and AnimaGuru HTML5 ZIP are both supported. The CLI prints the video ID and full watch URL. Public HTML5 videos offer embed markup on the watch page; private sharing requires the selected AnimaGuru users to sign in.
 
+MP4 subtitles: CLI 0.10.0 uploads an MP4's subtitles with it, and the AnimaGuru player shows them over the picture with a CC button to turn them off and a menu when there are several languages. The MP4 itself stays clean. With the default `--subtitles auto`, `submit --file FILM.mp4` adds `FILM.vtt` (or else `FILM.srt`), which `npm run export:mp4` writes beside it. `--subtitles FILE` chooses another `.vtt`/`.srt` file and `--subtitles none` skips them. The language comes from `--subtitle-language`, a WebVTT `Language:` header, the export receipt (`FILM.json`) or `film.config.json`. The file is checked before any video bytes are sent, and the dry run lists it. An MP4's width, height and duration now come from the MP4 itself and its default title from the export receipt, so another language's cut no longer takes the current `film.config.json` values. Burned-in `--burn-captions` exports have no subtitle files, so nothing is added. To add, replace or remove one language on an uploaded MP4:
+
+```sh
+animaguru videos subtitles VIDEO_ID --file production/exports/film-tr.vtt --yes   # language from the file or its export receipt
+animaguru videos subtitles VIDEO_ID --file subtitles.srt --language de --yes
+animaguru videos subtitles VIDEO_ID --remove de --yes
+```
+
+Each upload of up to 1 MiB is stored as WebVTT, up to 20 languages per video. HTML5 films draw their own captions and take no subtitle files. New subtitles on a public video send it back for staff review, like a new poster; removing a language does not.
+
 To request public gallery publication, upload privately, open the video in My videos on the website, choose Share → Public, and accept the public video sharing agreement. Staff must approve the submission before anyone else can access its public link, download or embed. Direct CLI public-sharing requests without agreement acceptance are refused by the API.
 
 `videos list --scope mine|shared|public` lists films. Owners can edit metadata, change visibility and replace recipients on the website, or use `videos share VIDEO_ID --visibility private --share "alex@example.com" --yes`. `videos delete VIDEO_ID --yes` removes the film and files. Making a film private or removing a recipient revokes access to existing playback links.

package/dist/animaguru.js

@@ -542,7 +542,7 @@ var init_dist = __esm({
 // cli/package.json
 var package_default = {
   name: "@docyrus/animaguru",
-  version: "0.9.0",
+  version: "0.10.0",
   description: "Agent-friendly AnimaGuru CLI built with CrustJS",
   type: "module",
   bin: {
@@ -2670,9 +2670,9 @@ var styleMethodCodes = {
 };
 var styleMethodNames = Object.freeze(Object.keys(styleMethodCodes));
 var styleMethodPairs = Object.freeze(Object.fromEntries(styleMethodNames.map((name) => {
-  const [open5, close] = styleMethodCodes[name];
+  const [open6, close] = styleMethodCodes[name];
   return [name, {
-    open: `\x1B[${open5}m`,
+    open: `\x1B[${open6}m`,
     close: `\x1B[${close}m`
   }];
 })));
@@ -3479,9 +3479,9 @@ function applyStyle(text, style2) {
   if (text == null) return "";
   let result = String(text);
   if (result === "") return "";
-  const { open: open5, close } = style2;
-  if (result.includes(close)) result = result.replaceAll(close, close + open5);
-  return open5 + result + close;
+  const { open: open6, close } = style2;
+  if (result.includes(close)) result = result.replaceAll(close, close + open6);
+  return open6 + result + close;
 }
 var FG_CLOSE = "\x1B[39m";
 var BG_CLOSE = "\x1B[49m";
@@ -3684,15 +3684,15 @@ function buildChainableStyleFactory(resolveCapabilities, runtime) {
       value: (input2) => createChainableStyle([...steps, colorStep(kind, input2)]),
       writable: false
     });
-    let open5 = "";
+    let open6 = "";
     let close = "";
     for (const step of steps) {
       const pair = stepPair(step, pairDepth);
-      open5 += pair.open;
+      open6 += pair.open;
       close = pair.close + close;
     }
     Object.defineProperty(styleFn, "open", {
-      value: open5,
+      value: open6,
       writable: false,
       configurable: false,
       enumerable: true
@@ -5076,8 +5076,8 @@ var version = defineExtension(VERSION).factory((extension, value, options = {})
 
 // cli/src/commands.ts
 import { spawn as spawn3 } from "node:child_process";
-import { readFile as readFile11, writeFile as writeFile9 } from "node:fs/promises";
-import { resolve as resolve10 } from "node:path";
+import { readFile as readFile12, writeFile as writeFile9 } from "node:fs/promises";
+import { resolve as resolve11 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 
 // node_modules/fflate/esm/index.mjs
@@ -11223,7 +11223,7 @@ var recursive = /* @__PURE__ */ new WeakMap();
 var NONE = 0;
 var ASSUMED = 1;
 var PROVEN = 2;
-function isRecursive(inst, stack, resolve11) {
+function isRecursive(inst, stack, resolve12) {
   const cached2 = recursive.get(inst);
   if (cached2 !== void 0)
     return cached2 ? PROVEN : NONE;
@@ -11233,7 +11233,7 @@ function isRecursive(inst, stack, resolve11) {
   let result = NONE;
   const check2 = (child) => {
     if (result !== PROVEN && child?._zod) {
-      const answer = isRecursive(child, stack, resolve11);
+      const answer = isRecursive(child, stack, resolve12);
       if (answer > result)
         result = answer;
     }
@@ -11244,7 +11244,7 @@ function isRecursive(inst, stack, resolve11) {
       const desc = Object.getOwnPropertyDescriptor(sh, key);
       if (spread && !desc.enumerable)
         continue;
-      const child = desc.get ? ASSUMED : desc.value?._zod ? isRecursive(desc.value, stack, resolve11) : NONE;
+      const child = desc.get ? ASSUMED : desc.value?._zod ? isRecursive(desc.value, stack, resolve12) : NONE;
       if (child > answer)
         answer = child;
     }
@@ -11308,7 +11308,7 @@ function isRecursive(inst, stack, resolve11) {
       break;
     // `$ZodLazy` caches its inner on the def, so a resolved edge is followed exactly
     case "lazy": {
-      const inner = def._cachedInner ?? (resolve11 ? inst._zod.innerType : void 0);
+      const inner = def._cachedInner ?? (resolve12 ? inst._zod.innerType : void 0);
       merge2(inner ? isRecursive(inner, stack, false) : ASSUMED);
       break;
     }
@@ -26999,8 +26999,8 @@ async function createWorkspace(options, installer = installDependencies) {
   await rm2(join5(directory, "runtime/main.ts"));
   await rename3(join5(directory, "film.config.json"), join5(directory, "templates/animation/film.config.json"));
   await rename3(join5(directory, "shared/locales/en/film.json"), join5(directory, "templates/animation/shared/locales/en/film.json"));
-  const { createHash: createHash4 } = await import("node:crypto");
-  await writeFile6(join5(directory, "templates/animation/starter-film.sha256"), createHash4("sha256").update(await readFile4(join5(directory, "templates/animation/src/film.ts"))).digest("hex") + "\n");
+  const { createHash: createHash5 } = await import("node:crypto");
+  await writeFile6(join5(directory, "templates/animation/starter-film.sha256"), createHash5("sha256").update(await readFile4(join5(directory, "templates/animation/src/film.ts"))).digest("hex") + "\n");
   await rm2(join5(directory, "animaguru.project.json"));
   await mkdir6(join5(directory, "animations"));
   await mkdir6(join5(directory, "branding"));
@@ -27184,7 +27184,7 @@ function elevenLabsSpeechCostUsd(model, characters, now = Date.now()) {
   const rate = model === "eleven_v4_turbo" ? promotion ? 0.011 : 0.04 : promotion ? 0.022 : 0.08;
   return Math.max(0, characters) * rate / 1e3;
 }
-var elevenLabsSfxCostUsd = (seconds) => Math.max(0, seconds) * 0.12 / 60;
+var elevenLabsSfxCostUsd = (seconds2) => Math.max(0, seconds2) * 0.12 / 60;
 var speechCharacters = (text) => Array.from(text).length;
 function assetEstimate(p) {
   if (p.type === "image") return Math.ceil(130 * spriteImageModel(p.model).relCost);
@@ -27196,11 +27196,11 @@ function assetEstimate(p) {
 }
 
 // cli/src/videos.ts
-import { open as open2, readFile as readFile6, stat } from "node:fs/promises";
-import { basename as basename3, join as join7, resolve as resolve7 } from "node:path";
+import { open as open3, readFile as readFile7, stat as stat2 } from "node:fs/promises";
+import { basename as basename4, join as join7, resolve as resolve8 } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { spawn as spawn2 } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 
 // shared/videos.ts
 var VIDEO_PART_BYTES = 8 * 1024 * 1024;
@@ -27242,11 +27242,158 @@ function videoPosterType(bytes) {
   throw new Error("Use a PNG, JPEG or WebP poster up to 2 MiB.");
 }
 
+// shared/subtitles.ts
+var SUBTITLE_MAX_BYTES = 1024 * 1024;
+var MAX_CUES = 5e3;
+var MAX_CUE_TEXT = 1e3;
+var MAX_SECONDS = 7200;
+var subtitleLanguage = external_exports.string().regex(/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/, "Use a subtitle language code such as en, tr or pt-BR.");
+var TIME = /^(?:(\d{1,3}):)?(\d{1,2}):(\d{2})[.,](\d{3})$/;
+function seconds(value) {
+  const match = TIME.exec(value.trim());
+  if (!match || Number(match[2]) > 59 || Number(match[3]) > 59) return NaN;
+  return Number(match[1] ?? 0) * 3600 + Number(match[2]) * 60 + Number(match[3]) + Number(match[4]) / 1e3;
+}
+var subRipText = (text) => text.replace(/<(?!\/?[ibu]>)[^<>]*>/gi, "").replace(/&(?!(?:[a-z][a-z\d]*|#\d+|#x[\da-f]+);)/gi, "&amp;").replace(/<(?!\/?[ibu]>)/gi, "&lt;");
+function parseSubtitles(input2, duration3) {
+  const text = input2.replace(/^/, "").replace(/\r\n?/g, "\n");
+  if (text.includes("\0") || text.includes("\uFFFD")) throw new Error("Use a UTF-8 text subtitle file.");
+  const vtt = /^WEBVTT(?:[ \t][^\n]*)?(?:\n|$)/.test(text);
+  const cues = [];
+  for (const [index, block] of text.split(/\n[ \t]*\n/).entries()) {
+    const lines = block.split("\n").filter((line) => line.trim());
+    if (!lines.length || vtt && (index === 0 || /^(?:NOTE|STYLE|REGION)(?:[ \t]|$)/.test(lines[0]))) continue;
+    const timing = lines.findIndex((line) => line.includes("-->"));
+    if (timing < 0 || timing > 1) throw new Error(`Subtitle block ${index + 1} has no "start --> end" timing line.`);
+    const [from, rest = ""] = lines[timing].split("-->");
+    const start = seconds(from);
+    let end = seconds(rest.trim().split(/[ \t]+/)[0] ?? "");
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start || end > MAX_SECONDS) throw new Error(`Subtitle block ${index + 1} has an invalid timing: ${lines[timing].trim().slice(0, 60)}`);
+    const body = lines.slice(timing + 1).filter((line) => !line.includes("-->")).map((line) => line.trimEnd()).join("\n").trim();
+    if (!body) continue;
+    const cueText = vtt ? body : subRipText(body);
+    if (cueText.length > MAX_CUE_TEXT) throw new Error(`Subtitle block ${index + 1} is longer than ${MAX_CUE_TEXT} characters.`);
+    if (duration3 != null) {
+      if (start >= duration3) continue;
+      end = Math.min(end, duration3);
+    }
+    cues.push({ start, end, text: cueText });
+    if (cues.length > MAX_CUES) throw new Error(`Subtitle files can have up to ${MAX_CUES} captions.`);
+  }
+  if (!cues.length) throw new Error("The subtitle file has no timed captions.");
+  return cues.sort((a, b) => a.start - b.start || a.end - b.end);
+}
+
+// cli/src/export-files.ts
+import { open as open2, readFile as readFile5, stat } from "node:fs/promises";
+import { basename as basename3, resolve as resolve6 } from "node:path";
+import { createHash } from "node:crypto";
+async function exportReceipt(file2) {
+  try {
+    const receipt = JSON.parse(await readFile5(file2.replace(/\.mp4$/i, ".json"), "utf8"));
+    if (receipt.file !== basename3(file2)) return {};
+    return { title: typeof receipt.title === "string" ? receipt.title : void 0, language: typeof receipt.settings?.language === "string" ? receipt.settings.language : void 0 };
+  } catch {
+    return {};
+  }
+}
+async function readSubtitleFile(file2, maxBytes) {
+  let info;
+  try {
+    info = await stat(file2);
+  } catch {
+    throw new Error(`Cannot read the subtitle file ${file2}.`);
+  }
+  if (!info.isFile() || !/\.(?:srt|vtt)$/i.test(file2) || info.size < 1 || info.size > maxBytes) throw new Error(`Use a .srt or .vtt subtitle file up to ${maxBytes / 1024 / 1024} MiB, such as the one npm run export:mp4 writes beside the MP4.`);
+  const content = await readFile5(file2);
+  const text = content.toString("utf8");
+  if (text.includes("\uFFFD") || !/\d\d:\d\d[,.]\d{3} --> /.test(text)) throw new Error("Use a UTF-8 .srt or .vtt subtitle file with timed captions.");
+  return { content, sha256: createHash("sha256").update(content).digest("hex"), language: /^\uFEFF?WEBVTT[^\n]*\n(?:[^\n]+\n)*?Language:[ \t]*([^\s]+)/.exec(text)?.[1] };
+}
+async function subtitleFile(root, mp4, choice, extensions) {
+  if (choice === "none") return null;
+  if (choice !== "auto") return { file: resolve6(root, choice), explicit: true };
+  for (const extension of extensions) {
+    const file2 = mp4.replace(/\.mp4$/i, extension);
+    if (await stat(file2).then((info) => info.isFile(), () => false)) return { file: file2, explicit: false };
+  }
+  return null;
+}
+function* boxes(data) {
+  for (let offset = 0; offset + 8 <= data.length; ) {
+    let size = data.readUInt32BE(offset);
+    let header = 8;
+    if (size === 1) {
+      size = Number(data.readBigUInt64BE(offset + 8));
+      header = 16;
+    } else if (size === 0) size = data.length - offset;
+    if (size < header || offset + size > data.length) return;
+    yield { type: data.toString("latin1", offset + 4, offset + 8), body: data.subarray(offset + header, offset + size) };
+    offset += size;
+  }
+}
+async function mp4Info(file2) {
+  const handle = await open2(file2, "r");
+  try {
+    const { size } = await handle.stat();
+    const read2 = async (offset, length) => {
+      const buffer = Buffer.alloc(length);
+      const { bytesRead } = await handle.read(buffer, 0, length, offset);
+      return buffer.subarray(0, bytesRead);
+    };
+    let moov = null;
+    for (let offset = 0; offset + 8 <= size; ) {
+      const header = await read2(offset, 16);
+      let length = header.readUInt32BE(0);
+      let headerSize = 8;
+      if (length === 1) {
+        length = Number(header.readBigUInt64BE(8));
+        headerSize = 16;
+      } else if (length === 0) length = size - offset;
+      if (length < headerSize) break;
+      if (header.toString("latin1", 4, 8) === "moov") {
+        if (length <= 64 * 1024 * 1024) moov = await read2(offset + headerSize, length - headerSize);
+        break;
+      }
+      offset += length;
+    }
+    if (!moov) return null;
+    let duration3 = 0;
+    let width = 0;
+    let height = 0;
+    for (const box of boxes(moov)) {
+      if (box.type === "mvhd" && box.body.length >= 32) {
+        const long = box.body[0] === 1;
+        const timescale = box.body.readUInt32BE(long ? 20 : 12);
+        const units = long ? Number(box.body.readBigUInt64BE(24)) : box.body.readUInt32BE(16);
+        if (timescale) duration3 = units / timescale;
+      } else if (box.type === "trak" && !width) {
+        let tkhd;
+        let handler = "";
+        for (const child of boxes(box.body)) {
+          if (child.type === "tkhd") tkhd = child.body;
+          if (child.type === "mdia") {
+            for (const media of boxes(child.body)) if (media.type === "hdlr" && media.body.length >= 12) handler = media.body.toString("latin1", 8, 12);
+          }
+        }
+        const at = tkhd?.[0] === 1 ? 88 : 76;
+        if (handler !== "vide" || !tkhd || tkhd.length < at + 8) continue;
+        width = Math.round(tkhd.readUInt32BE(at) / 65536);
+        height = Math.round(tkhd.readUInt32BE(at + 4) / 65536);
+        if (tkhd.readInt32BE(at - 36) === 0 && tkhd.readInt32BE(at - 20) === 0) [width, height] = [height, width];
+      }
+    }
+    return width && height && duration3 ? { width, height, duration: Math.round(duration3 * 1e3) / 1e3 } : null;
+  } finally {
+    await handle.close();
+  }
+}
+
 // cli/src/local-project.ts
-import { readFile as readFile5, readdir as readdir2 } from "node:fs/promises";
-import { join as join6, relative, resolve as resolve6, sep } from "node:path";
+import { readFile as readFile6, readdir as readdir2 } from "node:fs/promises";
+import { join as join6, relative, resolve as resolve7, sep } from "node:path";
 async function localProject(directory, selected) {
-  const root = resolve6(directory);
+  const root = resolve7(directory);
   let workspace;
   try {
     workspace = await findWorkspace(root);
@@ -27261,7 +27408,7 @@ async function localProject(directory, selected) {
     for (const entry of await readdir2(join6(workspace, "animations"), { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
       try {
-        await readFile5(join6(workspace, "animations", entry.name, "animaguru.project.json"));
+        await readFile6(join6(workspace, "animations", entry.name, "animaguru.project.json"));
         names.push(entry.name);
       } catch (error62) {
         if (error62.code !== "ENOENT") throw error62;
@@ -27272,17 +27419,18 @@ async function localProject(directory, selected) {
   }
   if (!/^[a-z0-9][a-z0-9-]{0,79}$/.test(animation)) throw new Error("Use a lowercase, hyphenated animation name.");
   const projectRoot = join6(workspace, "animations", animation);
-  await readFile5(join6(projectRoot, "animaguru.project.json"));
+  await readFile6(join6(projectRoot, "animaguru.project.json"));
   return { toolsRoot: workspace, projectRoot, animation };
 }
 
 // cli/src/videos.ts
+var subtitlesBody = (content) => new Blob([new Uint8Array(content)], { type: "text/plain; charset=utf-8" });
 function sharingEmails(value) {
   return value ? value.split(",").map((email3) => email3.trim()).filter(Boolean) : [];
 }
 async function exportHtml(root, animation, signal, log) {
   const script = join7(root, "scripts/export-html.mjs");
-  await stat(script).catch(() => {
+  await stat2(script).catch(() => {
     throw new Error("Choose an AnimaGuru video project, or pass --file for an exported HTML5 ZIP or MP4.");
   });
   log?.("Building the portable HTML5 animation\u2026");
@@ -27314,25 +27462,26 @@ async function exportHtml(root, animation, signal, log) {
 }
 async function submitVideo(client, options) {
   if (!options.yes && !options["dry-run"]) throw new Error("Pass --yes to authorize uploading and sharing this animation, or --dry-run to inspect the submission.");
-  const root = resolve7(options.directory ?? ".");
+  const root = resolve8(options.directory ?? ".");
   const context = await localProject(root, options.animation);
-  const file2 = options.file ? resolve7(root, options.file) : await exportHtml(context.toolsRoot, context.animation, options.signal, options.log);
-  const info = await stat(file2);
+  const file2 = options.file ? resolve8(root, options.file) : await exportHtml(context.toolsRoot, context.animation, options.signal, options.log);
+  const info = await stat2(file2);
   const format = file2.toLowerCase().endsWith(".zip") ? "html5" : file2.toLowerCase().endsWith(".mp4") ? "mp4" : null;
   if (!info.isFile() || !format) throw new Error("Submit an AnimaGuru HTML5 .zip export or an .mp4 file.");
   videoSubmission.parse({ title: options.title ?? "Video", format, bytes: info.size });
   let metadata = {};
+  let receipt = {};
   if (format === "html5") {
-    const files = unzipSync(new Uint8Array(await readFile6(file2)), { filter: (entry) => entry.name === "manifest.json" && entry.originalSize <= 256 * 1024 });
+    const files = unzipSync(new Uint8Array(await readFile7(file2)), { filter: (entry) => entry.name === "manifest.json" && entry.originalSize <= 256 * 1024 });
     if (!files["manifest.json"]) throw new Error("Use an AnimaGuru HTML5 export with manifest.json.");
     metadata = JSON.parse(strFromU8(files["manifest.json"]));
     if (metadata.format !== "spriteguru-html5" || metadata.version !== 1) throw new Error("Use an AnimaGuru HTML5 export.");
   } else {
     try {
-      metadata = JSON.parse(await readFile6(join7(context.projectRoot, "film.config.json"), "utf8"));
+      metadata = JSON.parse(await readFile7(join7(context.projectRoot, "film.config.json"), "utf8"));
     } catch {
     }
-    const handle2 = await open2(file2, "r");
+    const handle2 = await open3(file2, "r");
     try {
       const header = Buffer.alloc(12);
       await handle2.read(header, 0, 12, 0);
@@ -27340,9 +27489,13 @@ async function submitVideo(client, options) {
     } finally {
       await handle2.close();
     }
+    receipt = await exportReceipt(file2);
+    const probe = await mp4Info(file2).catch(() => null);
+    if (!probe) options.log?.("Could not read the MP4's size and duration; using film.config.json.");
+    metadata = { ...metadata, ...receipt.title ? { title: receipt.title } : {}, ...probe };
   }
   const body = videoSubmission.parse({
-    title: options.title ?? metadata.title ?? basename3(file2).replace(/\.(zip|mp4)$/i, ""),
+    title: options.title ?? metadata.title ?? basename4(file2).replace(/\.(zip|mp4)$/i, ""),
     description: options.description ?? "",
     visibility: options.visibility ?? "private",
     recipients: sharingEmails(options.share),
@@ -27352,18 +27505,29 @@ async function submitVideo(client, options) {
     height: metadata.height,
     duration: metadata.duration
   });
+  let subtitles = null;
+  const choice = options.subtitles ?? "auto";
+  if (format === "html5" && choice !== "auto" && choice !== "none") throw new Error("Subtitle files are for MP4 uploads; HTML5 films show their own captions.");
+  const found = format === "mp4" ? await subtitleFile(root, file2, choice, [".vtt", ".srt"]) : null;
+  if (found) {
+    const { content, language: header } = await readSubtitleFile(found.file, SUBTITLE_MAX_BYTES);
+    const language = subtitleLanguage.safeParse(options["subtitle-language"] ?? header ?? receipt.language ?? metadata.language);
+    if (!language.success) throw new Error("Pass --subtitle-language with the subtitles' language code, such as en or tr.");
+    parseSubtitles(content.toString("utf8"), body.duration);
+    subtitles = { file: found.file, language: language.data, content };
+  }
   let poster;
   if (options.poster) {
-    const path = resolve7(root, options.poster);
-    const info2 = await stat(path);
+    const path = resolve8(root, options.poster);
+    const info2 = await stat2(path);
     if (!info2.isFile() || info2.size > 2 * 1024 * 1024) throw new Error("Poster must be a PNG, JPEG or WebP up to 2 MiB.");
-    poster = await readFile6(path);
+    poster = await readFile7(path);
     videoPosterType(poster);
   }
-  if (options["dry-run"]) return { dryRun: true, file: file2, submission: body, poster: options.poster ?? null };
+  if (options["dry-run"]) return { dryRun: true, file: file2, submission: body, poster: options.poster ?? null, subtitles: subtitles && { file: subtitles.file, language: subtitles.language } };
   const draft = await client.request("/api/v1/videos", { method: "POST", body });
   if (!Number.isInteger(draft.partBytes) || draft.partBytes < 1 || draft.partBytes > 8 * 1024 * 1024 || !/^vid_[a-f0-9]{32}$/.test(draft.id)) throw new Error("The server returned an invalid video upload session.");
-  const handle = await open2(file2, "r");
+  const handle = await open3(file2, "r");
   let completed2 = false;
   try {
     for (let offset = 0, part = 1; offset < info.size; offset += draft.partBytes, part++) {
@@ -27372,7 +27536,7 @@ async function submitVideo(client, options) {
       const read2 = await handle.read(bytes, 0, bytes.length, offset);
       if (read2.bytesRead !== bytes.length) throw new Error("The export changed while uploading. Retry with a stable exported file.");
       options.log?.(`Uploading part ${part}/${Math.ceil(info.size / draft.partBytes)}\u2026`);
-      const sha256 = createHash("sha256").update(bytes).digest("hex");
+      const sha256 = createHash2("sha256").update(bytes).digest("hex");
       for (let attempt = 0; ; attempt++) {
         try {
           await client.request(`/api/v1/videos/${draft.id}/parts/${part}`, { method: "PUT", body: new Blob([bytes]), headers: { "X-Content-SHA256": sha256 }, timeout: 18e4 });
@@ -27384,6 +27548,10 @@ async function submitVideo(client, options) {
       }
     }
     if (poster) await client.request(`/api/v1/videos/${draft.id}/poster`, { method: "PUT", body: new Blob([new Uint8Array(poster)]) });
+    if (subtitles) {
+      options.log?.(`Adding ${subtitles.language} subtitles from ${subtitles.file}\u2026`);
+      await client.request(`/api/v1/videos/${draft.id}/subtitles/${subtitles.language}`, { method: "PUT", body: subtitlesBody(subtitles.content) });
+    }
     options.log?.("Preparing your AnimaGuru player\u2026");
     const result = await client.request(`/api/v1/videos/${draft.id}/complete`, { method: "POST", timeout: 3e5 });
     completed2 = true;
@@ -27395,10 +27563,25 @@ async function submitVideo(client, options) {
     await handle.close();
   }
 }
+async function changeVideoSubtitles(client, id2, options) {
+  if (!options.yes) throw new Error("Pass --yes to change this video's subtitles.");
+  const path = `/api/v1/videos/${encodeURIComponent(id2)}/subtitles/`;
+  if (options.remove) {
+    if (options.file) throw new Error("Pass either --file or --remove.");
+    return client.request(path + encodeURIComponent(options.remove), { method: "DELETE" });
+  }
+  if (!options.file) throw new Error("Pass --file with a .srt or .vtt subtitle file, or --remove LANGUAGE.");
+  const file2 = resolve8(options.file);
+  const { content, language: header } = await readSubtitleFile(file2, SUBTITLE_MAX_BYTES);
+  const language = subtitleLanguage.safeParse(options.language ?? header ?? (await exportReceipt(file2.replace(/\.(?:srt|vtt)$/i, ".mp4"))).language);
+  if (!language.success) throw new Error("Pass --language with the subtitles' language code, such as en or tr.");
+  parseSubtitles(content.toString("utf8"));
+  return client.request(path + language.data, { method: "PUT", body: subtitlesBody(content) });
+}
 
 // cli/src/assets.ts
-import { readFile as readFile7, writeFile as writeFile7 } from "node:fs/promises";
-import { resolve as resolve8 } from "node:path";
+import { readFile as readFile8, writeFile as writeFile7 } from "node:fs/promises";
+import { resolve as resolve9 } from "node:path";
 var extras = { image: ["aspect-ratio", "transparent"], video: ["workflow", "reference", "end-reference", "source", "soundtrack", "audio-references", "seconds", "resolution", "mode", "aspect-ratio", "prompt-expansion", "seed", "extend-output"], music: [], speech: ["voice", "delivery"], sfx: ["seconds", "loop", "prompt-influence"] };
 function parseAsset(input2) {
   const parsed = assetRequest.safeParse(input2);
@@ -27436,7 +27619,7 @@ function assetFromFlags(flags) {
   return parseAsset({ ...base2, ...flags.type === "speech" ? { voice: flags.voice, delivery: flags.delivery } : {} });
 }
 async function assetFromFile(file2, model) {
-  const input2 = JSON.parse(await readFile7(file2, "utf8"));
+  const input2 = JSON.parse(await readFile8(file2, "utf8"));
   if (!input2 || typeof input2 !== "object" || Array.isArray(input2)) throw new Error("The asset file must contain a JSON object.");
   return parseAsset({ ...input2, ...model ? { model } : {} });
 }
@@ -27451,7 +27634,7 @@ async function downloadAsset(client, project, assetId, output2) {
   if (!asset) throw new Error("Asset not found in this project. Run assets list to find its id.");
   if (!library.ownerId || !/^[a-f0-9]{64}$/.test(asset.file)) throw new Error("Invalid asset download metadata.");
   const response = await client.request(`/api/v1/blobs/${encodeURIComponent(library.ownerId)}/${asset.file}`, { raw: true });
-  const path = resolve8(output2);
+  const path = resolve9(output2);
   const bytes = new Uint8Array(await response.arrayBuffer());
   await writeFile7(path, bytes, { flag: "wx" });
   return { path, id: asset.id, type: asset.type, mimeType: asset.mimeType, size: bytes.byteLength };
@@ -27459,11 +27642,11 @@ async function downloadAsset(client, project, assetId, output2) {
 
 // cli/src/youtube-auth.ts
 import { createServer } from "node:http";
-import { randomBytes, createHash as createHash2, timingSafeEqual } from "node:crypto";
-import { readFile as readFile9, stat as stat2 } from "node:fs/promises";
+import { randomBytes, createHash as createHash3, timingSafeEqual } from "node:crypto";
+import { readFile as readFile10, stat as stat3 } from "node:fs/promises";
 
 // cli/src/youtube-store.ts
-import { chmod as chmod3, lstat, mkdir as mkdir7, open as open3, readFile as readFile8, readdir as readdir3, rename as rename4, unlink, writeFile as writeFile8 } from "node:fs/promises";
+import { chmod as chmod3, lstat, mkdir as mkdir7, open as open4, readFile as readFile9, readdir as readdir3, rename as rename4, unlink, writeFile as writeFile8 } from "node:fs/promises";
 import { dirname as dirname6, join as join8 } from "node:path";
 import { randomUUID as randomUUID2 } from "node:crypto";
 var youtubeMetadata = external_exports.object({
@@ -27547,7 +27730,7 @@ async function readPrivate(file2) {
     const info = await lstat(file2);
     if (info.isSymbolicLink() || !info.isFile() || info.size > 65536) throw new Error("Invalid local YouTube state file.");
     await chmod3(file2, 384);
-    return JSON.parse(await readFile8(file2, "utf8"));
+    return JSON.parse(await readFile9(file2, "utf8"));
   } catch (error62) {
     if (error62.code === "ENOENT") return null;
     throw new Error("Cannot read local YouTube state. Check your AnimaGuru configuration directory.");
@@ -27618,7 +27801,7 @@ async function clearYouTubeData() {
 async function withYouTubeLock(operation) {
   await privateDirectory(youtubeDirectory());
   const file2 = join8(youtubeDirectory(), "operation.lock");
-  const lock = await open3(file2, "wx", 384).catch((error62) => {
+  const lock = await open4(file2, "wx", 384).catch((error62) => {
     if (error62.code === "EEXIST") throw new Error(`Another YouTube command is running. If a previous command was killed, verify it has stopped before removing ${file2}.`);
     throw error62;
   });
@@ -27756,19 +27939,19 @@ async function revoke(token, signal) {
 }
 async function youtubeLogin(options) {
   if (!options.yes) throw new Error("Pass --yes to accept YouTube's Terms of Service and authorize saving YouTube credentials locally. Review https://www.youtube.com/t/terms and https://policies.google.com/privacy first.");
-  const seconds = options.timeout ?? 300;
-  if (!Number.isFinite(seconds) || seconds < 1 || seconds > 600) throw new Error("Use an authorization timeout between 1 and 600 seconds.");
+  const seconds2 = options.timeout ?? 300;
+  if (!Number.isFinite(seconds2) || seconds2 < 1 || seconds2 > 600) throw new Error("Use an authorization timeout between 1 and 600 seconds.");
   const requested = options.captions ? [...YOUTUBE_SCOPES, YOUTUBE_CAPTION_SCOPE] : YOUTUBE_SCOPES;
   return withYouTubeLock(async () => {
     const existing = await readYouTubeCredentials();
     if (existing && options.captions && !canAddCaptions(existing)) throw new Error("A YouTube channel is already connected without caption permission. Run youtube auth logout --yes, then youtube auth login --captions.");
     if (existing) throw new Error("A YouTube channel is already connected. Run youtube auth logout --yes before switching channels.");
     const file2 = options["client-file"];
-    const info = await stat2(file2);
+    const info = await stat3(file2);
     if (!info.isFile() || info.size > 65536) throw new Error("Use Google's downloaded Desktop app OAuth client JSON.");
     let installed;
     try {
-      installed = JSON.parse(await readFile9(file2, "utf8")).installed;
+      installed = JSON.parse(await readFile10(file2, "utf8")).installed;
     } catch {
     }
     if (!installed || typeof installed.client_id !== "string" || !installed.client_id.endsWith(".apps.googleusercontent.com") || installed.client_secret !== void 0 && typeof installed.client_secret !== "string") throw new Error("Use Google's Desktop app OAuth client JSON (installed), not a web client or API key.");
@@ -27778,8 +27961,8 @@ async function youtubeLogin(options) {
     let receive;
     let fail;
     let used = false;
-    const callback = new Promise((resolve11, reject) => {
-      receive = resolve11;
+    const callback = new Promise((resolve12, reject) => {
+      receive = resolve12;
       fail = reject;
     });
     void callback.catch(() => {
@@ -27817,21 +28000,21 @@ async function youtubeLogin(options) {
       response.end("Authorization received. Return to your AnimaGuru terminal.");
       receive(code);
     });
-    await new Promise((resolve11, reject) => {
+    await new Promise((resolve12, reject) => {
       server.once("error", reject);
-      server.listen(0, "127.0.0.1", resolve11);
+      server.listen(0, "127.0.0.1", resolve12);
     });
     const address = server.address();
     if (!address || typeof address === "string") throw new Error("Cannot open the local YouTube authorization listener.");
     redirectUri = `http://127.0.0.1:${address.port}/oauth2callback`;
-    const timer = setTimeout(() => fail(new Error("YouTube authorization timed out. Run login again.")), seconds * 1e3);
+    const timer = setTimeout(() => fail(new Error("YouTube authorization timed out. Run login again.")), seconds2 * 1e3);
     const abort = () => fail(new Error("YouTube authorization cancelled."));
     options.signal?.addEventListener("abort", abort, { once: true });
     let token;
     try {
       options.signal?.throwIfAborted();
       const url2 = new URL("https://accounts.google.com/o/oauth2/v2/auth");
-      url2.search = new URLSearchParams({ client_id: client.clientId, redirect_uri: redirectUri, response_type: "code", scope: requested.join(" "), state, code_challenge: createHash2("sha256").update(verifier).digest("base64url"), code_challenge_method: "S256", access_type: "offline", prompt: "consent select_account" }).toString();
+      url2.search = new URLSearchParams({ client_id: client.clientId, redirect_uri: redirectUri, response_type: "code", scope: requested.join(" "), state, code_challenge: createHash3("sha256").update(verifier).digest("base64url"), code_challenge_method: "S256", access_type: "offline", prompt: "consent select_account" }).toString();
       options.log?.("YouTube authorization stays on this machine. Tokens and upload receipts are saved in owner-only local files. Video bytes go directly to Google. Google privacy: https://policies.google.com/privacy \xB7 YouTube terms: https://www.youtube.com/t/terms");
       options.log?.(`Open ${url2.href}`);
       if (options.browser !== false) await options.openBrowser?.(url2.href);
@@ -27854,7 +28037,7 @@ async function youtubeLogin(options) {
       clearTimeout(timer);
       options.signal?.removeEventListener("abort", abort);
       server.closeAllConnections();
-      await new Promise((resolve11) => server.close(() => resolve11()));
+      await new Promise((resolve12) => server.close(() => resolve12()));
     }
   });
 }
@@ -27883,9 +28066,9 @@ async function youtubeLogout(options) {
 }
 
 // cli/src/youtube-upload.ts
-import { createHash as createHash3, randomUUID as randomUUID3 } from "node:crypto";
-import { open as open4, readFile as readFile10, stat as stat3 } from "node:fs/promises";
-import { basename as basename4, join as join9, resolve as resolve9 } from "node:path";
+import { createHash as createHash4, randomUUID as randomUUID3 } from "node:crypto";
+import { open as open5, readFile as readFile11, stat as stat4 } from "node:fs/promises";
+import { basename as basename5, join as join9, resolve as resolve10 } from "node:path";
 import { setTimeout as delay2 } from "node:timers/promises";
 var YOUTUBE_CHUNK_BYTES = 8 * 1024 * 1024;
 function safeYouTubeSession(value) {
@@ -27899,14 +28082,14 @@ function safeYouTubeSession(value) {
   return url2.href;
 }
 async function inspectMp4(file2, signal) {
-  const handle = await open4(file2, "r");
+  const handle = await open5(file2, "r");
   try {
     const info = await handle.stat();
     if (!info.isFile() || !file2.toLowerCase().endsWith(".mp4") || info.size < 12 || info.size > 256 * 1024 ** 3) throw new Error("Choose an exported .mp4 file up to 256 GiB. Export an HTML5 animation with npm run export:mp4 first.");
     const header = Buffer.alloc(12);
     await handle.read(header, 0, header.length, 0);
     if (header.toString("ascii", 4, 8) !== "ftyp") throw new Error("Use a valid MP4 file.");
-    const hash2 = createHash3("sha256");
+    const hash2 = createHash4("sha256");
     for await (const buffer of handle.createReadStream({ start: 0, autoClose: false, signal })) hash2.update(buffer);
     const fingerprint = (value) => `${value.dev}:${value.ino}:${value.size}:${value.mtimeMs}:${value.ctimeMs}`;
     const check2 = async () => {
@@ -27920,44 +28103,13 @@ async function inspectMp4(file2, signal) {
     throw error62;
   }
 }
-async function exportReceipt(file2) {
-  try {
-    const receipt = JSON.parse(await readFile10(file2.replace(/\.mp4$/i, ".json"), "utf8"));
-    if (receipt.file !== basename4(file2)) return {};
-    return { title: typeof receipt.title === "string" ? receipt.title : void 0, language: typeof receipt.settings?.language === "string" ? receipt.settings.language : void 0 };
-  } catch {
-    return {};
-  }
-}
-async function readCaptionFile(file2) {
-  let info;
-  try {
-    info = await stat3(file2);
-  } catch {
-    throw new Error(`Cannot read the subtitle file ${file2}.`);
-  }
-  if (!info.isFile() || !/\.(?:srt|vtt)$/i.test(file2) || info.size < 1 || info.size > 5 * 1024 * 1024) throw new Error("Use a .srt or .vtt subtitle file up to 5 MiB, such as the one npm run export:mp4 writes beside the MP4.");
-  const content = await readFile10(file2);
-  const text = content.toString("utf8");
-  if (text.includes("\uFFFD") || !/\d\d:\d\d[,.]\d{3} --> /.test(text)) throw new Error("Use a UTF-8 .srt or .vtt subtitle file with timed captions.");
-  return { content, sha256: createHash3("sha256").update(content).digest("hex") };
-}
+var readCaptionFile = (file2) => readSubtitleFile(file2, 5 * 1024 * 1024);
 async function planCaptions(root, mp4, options, fallbackLanguage) {
   const choice = options.captions ?? "auto";
-  if (choice === "none") return null;
-  let file2 = choice === "auto" ? void 0 : resolve9(root, choice);
-  if (!file2) {
-    for (const extension of [".srt", ".vtt"]) {
-      const candidate = mp4.replace(/\.mp4$/i, extension);
-      if (await stat3(candidate).then((info) => info.isFile(), () => false)) {
-        file2 = candidate;
-        break;
-      }
-    }
-    if (!file2) return null;
-  }
-  const { content, sha256 } = await readCaptionFile(file2);
-  const header = /^\uFEFF?WEBVTT[^\n]*\n(?:[^\n]+\n)*?Language:[ \t]*([^\s]+)/.exec(content.toString("utf8"))?.[1];
+  const found = await subtitleFile(root, mp4, choice, [".srt", ".vtt"]);
+  if (!found) return null;
+  const { file: file2 } = found;
+  const { content, sha256, language: header } = await readCaptionFile(file2);
   const language = options["caption-language"] ?? header ?? fallbackLanguage;
   const name = options["caption-name"] ?? "";
   const plan = youtubeCaptions.safeParse({ file: file2, bytes: content.length, sha256, language, name, status: "pending", captionId: null });
@@ -27967,23 +28119,23 @@ async function planCaptions(root, mp4, options, fallbackLanguage) {
 async function readThumbnail(file2) {
   let info;
   try {
-    info = await stat3(file2);
+    info = await stat4(file2);
   } catch {
     throw new Error(`Cannot read the thumbnail ${file2}.`);
   }
   if (!info.isFile() || info.size < 8 || info.size > 2 * 1024 * 1024) throw new Error("Use a JPEG or PNG thumbnail up to 2 MiB, such as the one npm run export:mp4 saves beside the MP4.");
-  const content = await readFile10(file2);
+  const content = await readFile11(file2);
   const type = content[0] === 255 && content[1] === 216 && content[2] === 255 ? "image/jpeg" : content.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ? "image/png" : null;
   if (!type) throw new Error("Use a JPEG or PNG thumbnail.");
-  return { content, type, sha256: createHash3("sha256").update(content).digest("hex") };
+  return { content, type, sha256: createHash4("sha256").update(content).digest("hex") };
 }
 async function planThumbnail(root, mp4, choice = "auto") {
   if (choice === "none") return null;
-  let file2 = choice === "auto" ? void 0 : resolve9(root, choice);
+  let file2 = choice === "auto" ? void 0 : resolve10(root, choice);
   if (!file2) {
     for (const extension of [".jpg", ".jpeg", ".png"]) {
       const candidate = mp4.replace(/\.mp4$/i, extension);
-      if (await stat3(candidate).then((info) => info.isFile(), () => false)) {
+      if (await stat4(candidate).then((info) => info.isFile(), () => false)) {
         file2 = candidate;
         break;
       }
@@ -28167,16 +28319,16 @@ async function transfer(credentials, job, source, options) {
 async function uploadYouTube(options) {
   if (!options.yes && !options["dry-run"]) throw new Error("Pass --yes to authorize the YouTube upload, or --dry-run to inspect it locally.");
   if (!["yes", "no"].includes(options["made-for-kids"]) || !["yes", "no"].includes(options["synthetic-media"])) throw new Error("Set --made-for-kids yes|no and --synthetic-media yes|no explicitly.");
-  const root = resolve9(options.directory ?? ".");
-  const file2 = resolve9(root, options.file);
+  const root = resolve10(options.directory ?? ".");
+  const file2 = resolve10(root, options.file);
   const context = await localProject(root, options.animation);
   let config2 = {};
   try {
-    config2 = JSON.parse(await readFile10(join9(context.projectRoot, "film.config.json"), "utf8"));
+    config2 = JSON.parse(await readFile11(join9(context.projectRoot, "film.config.json"), "utf8"));
   } catch {
   }
   const receipt = await exportReceipt(file2);
-  const parsed = youtubeMetadata.safeParse({ title: options.title ?? receipt.title ?? config2.title ?? basename4(file2).replace(/\.mp4$/i, ""), description: options.description ?? "", privacy: options.privacy ?? "private", madeForKids: options["made-for-kids"] === "yes", syntheticMedia: options["synthetic-media"] === "yes" });
+  const parsed = youtubeMetadata.safeParse({ title: options.title ?? receipt.title ?? config2.title ?? basename5(file2).replace(/\.mp4$/i, ""), description: options.description ?? "", privacy: options.privacy ?? "private", madeForKids: options["made-for-kids"] === "yes", syntheticMedia: options["synthetic-media"] === "yes" });
   if (!parsed.success) throw new Error("Use a title of 1\u2013100 characters and a description up to 5,000 UTF-8 bytes, without < or >, and private, unlisted or public privacy.");
   const metadata = parsed.data;
   let captions = await planCaptions(root, file2, options, receipt.language ?? config2.language);
@@ -28273,12 +28425,12 @@ var workspaceQuery = async (client) => {
 async function openBrowser(url2) {
   const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
   const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url2] : [url2];
-  await new Promise((resolve11) => {
+  await new Promise((resolve12) => {
     const child = spawn3(command, args, { stdio: "ignore", detached: true });
-    child.once("error", () => resolve11());
+    child.once("error", () => resolve12());
     child.once("spawn", () => {
       child.unref();
-      resolve11();
+      resolve12();
     });
   });
 }
@@ -28316,6 +28468,8 @@ function createCli() {
     { name: "visibility", type: "string", choices: ["private", "public"], default: "private" },
     { name: "share", type: "string", description: "Comma-separated emails of verified AnimaGuru users (private videos)" },
     { name: "poster", type: "string", description: "PNG, JPEG or WebP cover image" },
+    { name: "subtitles", type: "string", default: "auto", description: "MP4 subtitle file (.vtt or .srt) the player shows over the picture; auto uses FILM.vtt or FILM.srt beside FILM.mp4; none skips" },
+    { name: "subtitle-language", type: "string", description: "Subtitle language code such as en or tr; defaults to the MP4's export receipt or film.config.json" },
     { name: "yes", type: "boolean", description: "Authorize upload and chosen sharing" },
     { name: "dry-run", type: "boolean", description: "Inspect locally without uploading" }
   ).action(async ({ args, flags, stdout, stderr, signal }) => out(stdout, await submitVideo(new Client(flags.url, signal), { ...flags, directory: args.directory, log: stderr, signal }))))).command("videos", (videos) => videos.add(defineCommand("list", { description: "List your videos, privately shared videos, or the public gallery" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }, { name: "scope", type: "string", choices: ["mine", "shared", "public"], default: "mine" }, { name: "page", type: "number", default: 1 }).action(async ({ flags, stdout, signal }) => out(stdout, await new Client(flags.url, signal).request(flags.scope === "public" ? `/api/videos?page=${flags.page}` : `/api/v1/videos?scope=${flags.scope}&page=${flags.page}`, { authenticated: flags.scope !== "public" }))))).add(defineCommand("get", { description: "Get a video's details or the state of your unfinished upload" }, (command) => command.args({ name: "id", type: "string", required: true }).flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }).action(async ({ args, flags, stdout, signal }) => out(stdout, await new Client(flags.url, signal).request(`/api/v1/videos/${encodeURIComponent(args.id)}`))))).add(defineCommand("complete", { description: "Retry completion of an already uploaded animation" }, (command) => command.args({ name: "id", type: "string", required: true }).flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }).action(async ({ args, flags, stdout, signal }) => out(stdout, await new Client(flags.url, signal).request(`/api/v1/videos/${encodeURIComponent(args.id)}/complete`, { method: "POST", timeout: 3e5 }))))).add(defineCommand("share", { description: "Replace a video's visibility and recipient list" }, (command) => command.args({ name: "id", type: "string", required: true }).flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }, { name: "visibility", type: "string", required: true, choices: ["private", "public"] }, { name: "share", type: "string" }, { name: "yes", type: "boolean", required: true }).action(async ({ args, flags, stdout, signal }) => {
@@ -28323,7 +28477,13 @@ function createCli() {
     const client = new Client(flags.url, signal);
     const { video } = await client.request(`/api/videos/${encodeURIComponent(args.id)}`);
     out(stdout, await client.request(`/api/v1/videos/${encodeURIComponent(args.id)}`, { method: "PATCH", body: videoDetails.parse({ ...video, visibility: flags.visibility, recipients: sharingEmails(flags.share) }) }));
-  }))).add(defineCommand("delete", { description: "Remove a video and its hosted files" }, (command) => command.args({ name: "id", type: "string", required: true }).flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }, { name: "yes", type: "boolean", required: true }).action(async ({ args, flags, stdout, signal }) => {
+  }))).add(defineCommand("subtitles", { description: "Add or replace an MP4's subtitles in one language, or remove a language" }, (command) => command.args({ name: "id", type: "string", required: true }).flags(
+    { name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } },
+    { name: "file", type: "string", description: ".srt or .vtt subtitle file" },
+    { name: "language", type: "string", description: "Language code such as en or tr; defaults to a WebVTT Language header or the export receipt" },
+    { name: "remove", type: "string", description: "Language code of the subtitles to remove" },
+    { name: "yes", type: "boolean", required: true }
+  ).action(async ({ args, flags, stdout, signal }) => out(stdout, await changeVideoSubtitles(new Client(flags.url, signal), args.id, flags))))).add(defineCommand("delete", { description: "Remove a video and its hosted files" }, (command) => command.args({ name: "id", type: "string", required: true }).flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }, { name: "yes", type: "boolean", required: true }).action(async ({ args, flags, stdout, signal }) => {
     if (!flags.yes) throw new Error("Pass --yes to delete the video.");
     out(stdout, await new Client(flags.url, signal).request(`/api/v1/videos/${encodeURIComponent(args.id)}`, { method: "DELETE" }));
   })))).command("auth", (auth) => auth.add(defineCommand("login", { description: "Approve a browser sign-in and save a seven-day CLI session" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" }, description: "Server origin" }).flags({ name: "browser", type: "boolean", default: true, description: "Open the browser; --no-browser prints the URL only" }).action(async ({ flags, stdout, stderr, signal }) => {
@@ -28412,7 +28572,7 @@ Confirm code: ${device.user_code}`);
     ...assetAuthorizationFlags
   ).action(async ({ args, flags, stdout, signal }) => out(stdout, await submitAsset(new Client(flags.url, signal), args.id, assetFromFlags(flags), flags))))).add(defineCommand("submit", { description: "Submit a validated JSON asset file; --yes authorizes credits" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }).args(id).flags({ name: "file", type: "string", required: true, description: "JSON asset request" }, { name: "model", type: "string", choices: assetModelIds, description: "Override the model in the file" }, ...assetAuthorizationFlags).action(async ({ args, flags, stdout, signal }) => out(stdout, await submitAsset(new Client(flags.url, signal), args.id, await assetFromFile(flags.file, flags.model), flags))))).add(defineCommand("download", { description: "Download a saved asset by id; refuses to overwrite" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }).args(id, { name: "asset", type: "string", required: true, description: "Asset id from assets list" }).flags({ name: "output", type: "string", required: true }).action(async ({ args, flags, stdout, signal }) => out(stdout, await downloadAsset(new Client(flags.url, signal), args.id, args.asset, flags.output)))))).command("jobs", (jobs) => jobs.add(defineCommand("list", { description: "List the latest generation jobs" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" }, description: "Server origin" }).args(id).action(async ({ args, flags, stdout, signal }) => out(stdout, await new Client(flags.url, signal).request(`${projectPath(args.id)}/jobs`))))).add(defineCommand("submit", { description: "Submit a typed JSON job: character, animate, custom or redraw; spends credits" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" }, description: "Server origin" }).args(id).flags(...modelFlags).flags({ name: "file", type: "string", required: true, description: "JSON job file" }, { name: "yes", type: "boolean", required: true, description: "Authorize spending credits" }).action(async ({ args, flags, stdout, signal }) => {
     if (!flags.yes) throw new Error("Pass --yes to authorize spending credits.");
-    const body = spriteJobBody.parse({ ...JSON.parse(await readFile11(flags.file, "utf8")), ...selectedModels(flags) });
+    const body = spriteJobBody.parse({ ...JSON.parse(await readFile12(flags.file, "utf8")), ...selectedModels(flags) });
     out(stdout, await new Client(flags.url, signal).request(`${projectPath(args.id)}/jobs`, { method: "POST", body }));
   }))).add(defineCommand("wait", { description: "Wait for a specific job; fail if generation fails or times out" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" }, description: "Server origin" }).args(id, { name: "job", type: "string", required: true }).flags({ name: "timeout", type: "number", default: 600, description: "Maximum seconds to wait" }).action(async ({ args, flags, stdout, signal }) => {
     if (!Number.isFinite(flags.timeout) || flags.timeout <= 0) throw new Error("Timeout must be positive.");
@@ -28441,7 +28601,7 @@ Confirm code: ${device.user_code}`);
     const extension = flags.file.split(".").at(-1)?.toLowerCase();
     const type = extension === "png" ? "image/png" : extension === "jpg" || extension === "jpeg" ? "image/jpeg" : extension === "webp" ? "image/webp" : void 0;
     if (!type) throw new Error("Use a PNG, JPEG or WebP image.");
-    const bytes = await readFile11(flags.file);
+    const bytes = await readFile12(flags.file);
     if (bytes.length > 10 * 1024 * 1024) throw new Error("Image must be at most 10 MB.");
     const form = new FormData();
     form.set("image", new Blob([bytes], { type }), `reference.${extension}`);
@@ -28459,7 +28619,7 @@ Confirm code: ${device.user_code}`);
       const response = await client.request(`/api/v1/blobs/${encodeURIComponent(manifest.ownerId)}/${file2.sha}`, { raw: true });
       entries[path2] = new Uint8Array(await response.arrayBuffer());
     }
-    const path = resolve10(flags.output);
+    const path = resolve11(flags.output);
     await writeFile9(path, zipSync(entries, { level: 0 }), { flag: "wx" });
     out(stdout, { path, files: manifest.files.length });
   })))).extend(version(package_default.version, { format: "plain" })).extend(help()).extend(completion());

package/package.json

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

package/skills/animaguru/SKILL.md

@@ -114,6 +114,8 @@ 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.
 
 

package/skills/animaguru-video/SKILL.md

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

@@ -100,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.