@docyrus/animaguru 0.28.0 → 0.29.1

package/README.md

@@ -66,7 +66,7 @@ animaguru templates
 animaguru create my-video
 ```
 
-`create` takes only the project folder name. Use a new folder whose parent already exists; the command refuses existing destinations, including empty folders and symlinks. It installs PixiJS, Vite, TypeScript and FFmpeg/FFprobe tools. npm progress goes to stderr and successful results are JSON. If installation fails, the generated files remain; enter the folder and run `npm install` to resume.
+`create` takes only the project folder name. Use a new folder whose parent already exists; the command refuses existing destinations, including empty folders and symlinks. It installs PixiJS, Vite and TypeScript. The audio tools and MP4 export use FFmpeg and FFprobe 7.1 or newer from your PATH (or `FFMPEG_PATH` and `FFPROBE_PATH`); `create` checks them and, when they are missing or older, says how to install a current build (macOS: `brew install ffmpeg`) in its notes and `ffmpeg` result. CLI 0.29.1 made that change: earlier workspaces installed their own FFmpeg 4.x builds from npm. npm progress goes to stderr and successful results are JSON. If installation fails, the generated files remain; enter the folder and run `npm install` to resume.
 
 Open the generated folder in **Codex or Claude Code**, then describe the video you want. It includes:
 
@@ -581,6 +581,13 @@ 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.
 
+CLI 0.29.0 lets admins tag a film for the showcase as they upload it: the public gallery films the lead invitation page shows under "Films made with AnimaGuru", grouped by sector with the lead's own first. `--showcase SECTOR` adds it (`cafe`, `restaurant`, `food`, `retail`, `beauty`, `fitness`, `workspace`, `hospitality`, `realestate`, `education`, `health`, `events`, `technology` or `services`). `--showcase-tags` says what it is for (comma-separated: `social`, `website`, `product`, `space`, `offer`, `brand`, `explainer`, `event`). `--showcase-language en|tr|sv|none` gives the language it speaks or shows, and `--showcase-position N` its order (lower first). The film shows there once it is public and approved; admins can change the tags later on Staff → Video reviews. Other accounts get a 403.
+
+```sh
+animaguru submit --file production/exports/film.mp4 --poster production/exports/poster.jpg \
+  --showcase cafe --showcase-tags social,offer --showcase-language tr --showcase-position 10 --yes
+```
+
 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

@@ -19761,7 +19761,7 @@ var require_ignore2 = __commonJS({
 // cli/package.json
 var package_default = {
   name: "@docyrus/animaguru",
-  version: "0.28.0",
+  version: "0.29.1",
   description: "Agent-friendly AnimaGuru CLI built with CrustJS",
   type: "module",
   bin: {
@@ -25288,208 +25288,6 @@ function unzipSync(data, opts) {
 // shared/auth.ts
 var CLI_CLIENT_ID = "animaguru-cli";
 
-// shared/sprites/styles.ts
-var GAME_SPRITE_STYLES = ["hd-cartoon", "pixel", "painted", "vector"];
-var VIDEO_SPRITE_STYLES = [
-  "photoreal-cutout",
-  "photo-collage",
-  "paper-cutout",
-  "photoreal-stop-motion",
-  "cutout-motion-graphics"
-];
-var SPRITE_STYLES = [...GAME_SPRITE_STYLES, ...VIDEO_SPRITE_STYLES];
-
-// shared/credits.ts
-var UNITS_PER_CREDIT = 10;
-var toCredits = (units) => Math.round(units) / UNITS_PER_CREDIT;
-var toUnits = (credits) => Math.round(credits * UNITS_PER_CREDIT);
-
-// shared/sprites/types.ts
-var SPRITE_KINDS = ["character", "vehicle", "machine", "effect"];
-var SPRITE_ACTIONS = ["idle", "walk", "run", "skid-stop", "shoot", "jump", "hurt", "death", "slide", "punch", "kick"];
-var SPRITE_KIND_ACTIONS = {
-  character: SPRITE_ACTIONS,
-  vehicle: ["idle", "move", "fire", "hurt", "destroyed"],
-  machine: ["idle", "work", "activate", "fire", "hurt", "break"],
-  effect: ["projectile", "charge", "impact", "explosion", "aura"]
-};
-var ALL_SPRITE_ACTIONS = [...new Set(Object.values(SPRITE_KIND_ACTIONS).flat())];
-var SPRITE_TOP_ACTIONS = {
-  vehicle: ["hull-move", "hull-destroyed", "turret-fire"],
-  machine: ["hull-break", "turret-fire"]
-};
-var ALL_TOP_ACTIONS = [...new Set(Object.values(SPRITE_TOP_ACTIONS).flat())];
-var CUSTOM_FRAMES = { min: 2, max: 12 };
-
-// shared/sprites/models.ts
-var DEFAULT_SPRITE_IMAGE_MODEL = "fal/gpt-image-2.5-medium";
-var SPRITE_IMAGE_MODELS = [
-  { id: DEFAULT_SPRITE_IMAGE_MODEL, label: "GPT Image 2.5 \xB7 medium (fal)", provider: "fal", edit: true, nativeAlpha: true, maxImages: 16, relCost: 0.3, quality: "medium", endpoints: { generate: "openai/gpt-image-2.5/flare/text-to-image", edit: "openai/gpt-image-2.5/flare/edit" } },
-  { id: "fal/gpt-image-2-low", label: "GPT Image 2 \xB7 low (fal)", provider: "fal", edit: true, spriteBackupCutout: true, maxImages: 16, relCost: 0.2, quality: "low", endpoints: { generate: "openai/gpt-image-2", edit: "openai/gpt-image-2/edit" } },
-  { id: "fal/muse-image", label: "Muse Image (fal)", provider: "fal", edit: true, maxImages: 10, relCost: 0.2, endpoints: { generate: "meta/muse-image/text-to-image", edit: "meta/muse-image/edit" } },
-  { id: "fal/krea-2-turbo", label: "Krea 2 Turbo (fal)", provider: "fal", edit: false, maxImages: 0, relCost: 0.16, endpoints: { generate: "fal-ai/krea-2/turbo" } },
-  { id: "gpt-image-2.5", label: "GPT Image 2.5 (OpenAI)", provider: "openai", edit: true, nativeAlpha: true, maxImages: 16, relCost: 1 },
-  { id: "black-forest-labs/flux-2-max", label: "FLUX.2 [max]", provider: "workers-ai", edit: true, maxImages: 8, relCost: 3 },
-  { id: "bytedance/seedream-5-pro", label: "Seedream 5 Pro", provider: "workers-ai", edit: true, maxImages: 10, relCost: 1.5 },
-  { id: "xai/grok-imagine-image-2.0", label: "Grok Imagine Image 2.0", provider: "workers-ai", edit: true, maxImages: 5, relCost: 1 },
-  { id: "alibaba/qwen-image-3.0-pro", label: "Qwen Image 3.0 Pro", provider: "workers-ai", edit: false, maxImages: 0, relCost: 0.5 },
-  { id: "krea/krea-2-medium-turbo", label: "Krea 2 Medium Turbo", provider: "workers-ai", edit: false, maxImages: 0, relCost: 0.25 }
-];
-var SPRITE_IMAGE_MODEL_IDS = SPRITE_IMAGE_MODELS.map((m) => m.id);
-function spriteImageModel(id2) {
-  return SPRITE_IMAGE_MODELS.find((m) => m.id === id2) ?? SPRITE_IMAGE_MODELS[0];
-}
-var VIDEO_WORKFLOWS = ["image-to-video", "text-to-video", "extend-video", "reference-to-video", "lip-sync", "camera-controls", "insert-video", "recast", "relight", "3d-to-video", "style", "keyframes-to-video"];
-var STUDIO_VIDEO_WORKFLOWS = ["image-to-video", "text-to-video", "extend-video"];
-var MEDIA_LENGTH_WORKFLOWS = ["lip-sync", "recast", "relight", "3d-to-video"];
-var lengthFromMedia = (workflow) => MEDIA_LENGTH_WORKFLOWS.includes(workflow);
-var VIDEO_STYLES = ["vhs", "retro-toon-70s", "low-poly", "hand-drawn", "16bit-pixel"];
-var VHS_DAMAGE_LEVELS = ["light", "medium", "heavy"];
-var VIDEO_RESOLUTIONS = ["480p", "720p", "768p", "1080p", "2k"];
-var H3_RESOLUTIONS = ["480p", "768p", "1080p", "2k"];
-var VIDEO_ASPECT_RATIOS = ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"];
-var PROMPT_EXPANSION_MODES = ["disabled", "balanced", "quality"];
-var EXTEND_OUTPUTS = ["extended", "continuation"];
-var SOUNDTRACK_MAX_BYTES = 15 * 1024 * 1024;
-var EXTEND_SOURCE_MAX_BYTES = 50 * 1024 * 1024;
-var MAX_AUDIO_REFERENCES = 3;
-var MAX_VIDEO_REFERENCE_IMAGES = 9;
-var MAX_REFERENCE_VIDEOS = 3;
-var MAX_REFERENCE_FILES = 12;
-var MAX_RECAST_PEOPLE = 4;
-var MAX_3D_REFERENCES = 8;
-var MAX_CAMERA_KEYFRAMES = 12;
-var MAX_CAMERA_TURNS = 32;
-var MAX_IMAGE_KEYFRAMES = 10;
-var KEYFRAME_FPS = 24;
-var H3_MAX = "minimax/h3-max";
-var FLUX_3_MAX = "blackforestlabs/flux-3-max";
-var h3Endpoints = (route) => ({ "image-to-video": `${route}/image-to-video`, "text-to-video": `${route}/text-to-video`, "extend-video": `${route}/extend-video` });
-var SPRITE_VIDEO_MODELS = [
-  {
-    id: "pruna/p-video-2-pro",
-    label: "Pruna P-Video 2 Pro",
-    provider: "pruna",
-    workflows: ["image-to-video"],
-    resolutions: ["480p", "768p"],
-    modes: ["cost", "speed", "quality"],
-    lastFrame: true,
-    estimatedCreditsPerSecond: { "480p": { cost: 1, speed: 2, quality: 4 }, "768p": { cost: 2.5, speed: 3.5, quality: 7.5 } },
-    seconds: { min: 5, max: 15 }
-  },
-  {
-    id: "heygen/heygen-video-1",
-    label: "HeyGen Video 1",
-    provider: "heygen",
-    workflows: ["image-to-video"],
-    resolutions: ["480p", "768p"],
-    modes: ["cost"],
-    lastFrame: false,
-    estimatedCreditsPerSecond: { "480p": { cost: 1 }, "768p": { cost: 1.5 } },
-    seconds: { min: 5, max: 15 }
-  },
-  {
-    id: "fal/minimax-h3-max",
-    label: "MiniMax H3 Max (fal.ai)",
-    provider: "fal",
-    // Every workflow but FLUX 3 Max's keyframes.
-    workflows: VIDEO_WORKFLOWS.filter((w) => w !== "keyframes-to-video"),
-    endpoints: {
-      ...h3Endpoints(H3_MAX),
-      "reference-to-video": `${H3_MAX}/reference-to-video`,
-      "lip-sync": `${H3_MAX}/lip-sync/image-to-video`,
-      "camera-controls": `${H3_MAX}/camera-controls`,
-      "insert-video": `${H3_MAX}/insert-video`,
-      recast: `${H3_MAX}/recast`,
-      relight: `${H3_MAX}/relight`,
-      "3d-to-video": `${H3_MAX}/3d-to-video`,
-      style: `${H3_MAX}/styles`
-    },
-    resolutions: ["480p", "768p", "1080p"],
-    workflowOptions: {
-      "extend-video": { resolutions: H3_RESOLUTIONS },
-      "lip-sync": { resolutions: H3_RESOLUTIONS, seconds: { min: 5, max: 900, fractional: true } },
-      "insert-video": { resolutions: ["480p", "768p"], seconds: { min: 5, max: 13, fractional: true }, creditsPerSecond: { "480p": 5, "768p": 6 } },
-      recast: { resolutions: ["768p", "1080p"], seconds: { min: 5, max: 30, fractional: true }, creditsPerSecond: { "768p": 30, "1080p": 45 } },
-      relight: { resolutions: H3_RESOLUTIONS, seconds: { min: 2.33, max: 15, fractional: true } },
-      "3d-to-video": { seconds: { min: 1, max: 15, fractional: true } },
-      style: { resolutions: ["768p"], seconds: { min: 5, max: 15 } }
-    },
-    modes: ["quality"],
-    lastFrame: true,
-    endFrameOnly: true,
-    seed: true,
-    promptExpansion: PROMPT_EXPANSION_MODES,
-    audio: true,
-    estimatedCreditsPerSecond: { "480p": { quality: 5 }, "768p": { quality: 8 }, "1080p": { quality: 16 }, "2k": { quality: 32 } },
-    seconds: { min: 1, max: 15, fractional: true }
-  },
-  {
-    id: "fal/minimax-h3-max-turbo",
-    label: "MiniMax H3 Max Turbo (fal.ai)",
-    provider: "fal",
-    workflows: STUDIO_VIDEO_WORKFLOWS,
-    endpoints: h3Endpoints("minimax/h3-max-turbo"),
-    resolutions: ["480p", "768p", "1080p"],
-    workflowOptions: { "extend-video": { resolutions: H3_RESOLUTIONS } },
-    modes: ["speed"],
-    lastFrame: true,
-    endFrameOnly: true,
-    seed: true,
-    promptExpansion: PROMPT_EXPANSION_MODES,
-    audio: true,
-    estimatedCreditsPerSecond: { "480p": { speed: 2.5 }, "768p": { speed: 4 }, "1080p": { speed: 8 }, "2k": { speed: 16 } },
-    seconds: { min: 1, max: 15, fractional: true }
-  },
-  {
-    id: "fal/flux-3-max",
-    label: "FLUX 3 Max (fal.ai)",
-    provider: "fal",
-    workflows: ["image-to-video", "text-to-video", "keyframes-to-video"],
-    endpoints: { "image-to-video": `${FLUX_3_MAX}/image-to-video`, "text-to-video": `${FLUX_3_MAX}/text-to-video`, "keyframes-to-video": `${FLUX_3_MAX}/keyframes-to-video` },
-    falInputs: "flux",
-    resolutions: ["720p", "1080p"],
-    modes: ["quality"],
-    lastFrame: true,
-    seed: true,
-    promptExpansion: ["balanced", "quality"],
-    estimatedCreditsPerSecond: { "720p": { quality: 17 }, "1080p": { quality: 29 } },
-    seconds: { min: 5, max: 20 }
-  }
-];
-var SPRITE_VIDEO_MODEL_IDS = SPRITE_VIDEO_MODELS.map((m) => m.id);
-var DEFAULT_SPRITE_VIDEO_MODEL = "pruna/p-video-2-pro";
-function spriteVideoModel(id2) {
-  return SPRITE_VIDEO_MODELS.find((m) => m.id === id2) ?? SPRITE_VIDEO_MODELS[0];
-}
-function videoResolutions(model, workflow = "image-to-video") {
-  return model.workflowOptions?.[workflow]?.resolutions ?? model.resolutions;
-}
-function videoSeconds(model, workflow = "image-to-video") {
-  return model.workflowOptions?.[workflow]?.seconds ?? model.seconds;
-}
-var INCLUDED_REFERENCE_TOKENS = 4096;
-var imageReferenceTokens = (size) => size && size[0] > 0 && size[1] > 0 ? 32 * Math.ceil(32 * Math.max(...size) / Math.min(...size)) : 1824;
-var clipReferenceTokens = (seconds2, resolution) => Math.ceil(Math.max(0, seconds2) * (resolution === "480p" ? 2700 : 6900));
-var audioReferenceTokens = (seconds2) => Math.ceil(Math.max(0, seconds2) * 80);
-var DEFAULT_GENERATED_REFERENCES = 2;
-function billedVideoSeconds(model, workflow, seconds2) {
-  const s = videoSeconds(model, workflow).fractional ? seconds2 : Math.round(seconds2);
-  if (workflow === "3d-to-video") return Math.max(5, s);
-  return workflow === "lip-sync" && s > 15 ? s * 1.2 : s;
-}
-function videoCreditsPerSecond(model, p) {
-  const override = model.workflowOptions?.[p.workflow ?? "image-to-video"]?.creditsPerSecond?.[p.resolution];
-  if (override !== void 0) return override;
-  const byMode = model.estimatedCreditsPerSecond[p.resolution] ?? model.estimatedCreditsPerSecond[model.resolutions[0]];
-  return byMode[p.mode] ?? byMode[model.modes[0]] ?? 0;
-}
-function spriteVideoEstimate(model, p, extras2 = {}) {
-  const seconds2 = billedVideoSeconds(model, p.workflow ?? "image-to-video", p.seconds);
-  const beyond = Math.max(0, (extras2.referenceTokens ?? 0) - INCLUDED_REFERENCE_TOKENS) * 2e-3 + (extras2.generatedReferences ?? 0) * 3;
-  return Math.max(1, Math.ceil((videoCreditsPerSecond(model, p) * seconds2 + beyond) * UNITS_PER_CREDIT));
-}
-
 // node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -45158,6 +44956,220 @@ function date4(params) {
   return _coercedDate(ZodDate, params);
 }
 
+// shared/showcase.ts
+var SHOWCASE_SECTORS = ["cafe", "restaurant", "food", "retail", "beauty", "fitness", "workspace", "hospitality", "realestate", "education", "health", "events", "technology", "services"];
+var SHOWCASE_TAGS = ["social", "website", "product", "space", "offer", "brand", "explainer", "event"];
+var SHOWCASE_LOCALES = ["", "en", "tr", "sv"];
+var showcaseEntry = external_exports.object({
+  sector: external_exports.enum(SHOWCASE_SECTORS),
+  tags: external_exports.array(external_exports.enum(SHOWCASE_TAGS)).max(SHOWCASE_TAGS.length).default([]).transform((tags) => [...new Set(tags)]),
+  locale: external_exports.enum(SHOWCASE_LOCALES).default(""),
+  /** Lower comes first; films with the same position show newest first. */
+  position: external_exports.number().int().min(0).max(1e3).default(0)
+}).strict();
+
+// shared/sprites/styles.ts
+var GAME_SPRITE_STYLES = ["hd-cartoon", "pixel", "painted", "vector"];
+var VIDEO_SPRITE_STYLES = [
+  "photoreal-cutout",
+  "photo-collage",
+  "paper-cutout",
+  "photoreal-stop-motion",
+  "cutout-motion-graphics"
+];
+var SPRITE_STYLES = [...GAME_SPRITE_STYLES, ...VIDEO_SPRITE_STYLES];
+
+// shared/credits.ts
+var UNITS_PER_CREDIT = 10;
+var toCredits = (units) => Math.round(units) / UNITS_PER_CREDIT;
+var toUnits = (credits) => Math.round(credits * UNITS_PER_CREDIT);
+
+// shared/sprites/types.ts
+var SPRITE_KINDS = ["character", "vehicle", "machine", "effect"];
+var SPRITE_ACTIONS = ["idle", "walk", "run", "skid-stop", "shoot", "jump", "hurt", "death", "slide", "punch", "kick"];
+var SPRITE_KIND_ACTIONS = {
+  character: SPRITE_ACTIONS,
+  vehicle: ["idle", "move", "fire", "hurt", "destroyed"],
+  machine: ["idle", "work", "activate", "fire", "hurt", "break"],
+  effect: ["projectile", "charge", "impact", "explosion", "aura"]
+};
+var ALL_SPRITE_ACTIONS = [...new Set(Object.values(SPRITE_KIND_ACTIONS).flat())];
+var SPRITE_TOP_ACTIONS = {
+  vehicle: ["hull-move", "hull-destroyed", "turret-fire"],
+  machine: ["hull-break", "turret-fire"]
+};
+var ALL_TOP_ACTIONS = [...new Set(Object.values(SPRITE_TOP_ACTIONS).flat())];
+var CUSTOM_FRAMES = { min: 2, max: 12 };
+
+// shared/sprites/models.ts
+var DEFAULT_SPRITE_IMAGE_MODEL = "fal/gpt-image-2.5-medium";
+var SPRITE_IMAGE_MODELS = [
+  { id: DEFAULT_SPRITE_IMAGE_MODEL, label: "GPT Image 2.5 \xB7 medium (fal)", provider: "fal", edit: true, nativeAlpha: true, maxImages: 16, relCost: 0.3, quality: "medium", endpoints: { generate: "openai/gpt-image-2.5/flare/text-to-image", edit: "openai/gpt-image-2.5/flare/edit" } },
+  { id: "fal/gpt-image-2-low", label: "GPT Image 2 \xB7 low (fal)", provider: "fal", edit: true, spriteBackupCutout: true, maxImages: 16, relCost: 0.2, quality: "low", endpoints: { generate: "openai/gpt-image-2", edit: "openai/gpt-image-2/edit" } },
+  { id: "fal/muse-image", label: "Muse Image (fal)", provider: "fal", edit: true, maxImages: 10, relCost: 0.2, endpoints: { generate: "meta/muse-image/text-to-image", edit: "meta/muse-image/edit" } },
+  { id: "fal/krea-2-turbo", label: "Krea 2 Turbo (fal)", provider: "fal", edit: false, maxImages: 0, relCost: 0.16, endpoints: { generate: "fal-ai/krea-2/turbo" } },
+  { id: "gpt-image-2.5", label: "GPT Image 2.5 (OpenAI)", provider: "openai", edit: true, nativeAlpha: true, maxImages: 16, relCost: 1 },
+  { id: "black-forest-labs/flux-2-max", label: "FLUX.2 [max]", provider: "workers-ai", edit: true, maxImages: 8, relCost: 3 },
+  { id: "bytedance/seedream-5-pro", label: "Seedream 5 Pro", provider: "workers-ai", edit: true, maxImages: 10, relCost: 1.5 },
+  { id: "xai/grok-imagine-image-2.0", label: "Grok Imagine Image 2.0", provider: "workers-ai", edit: true, maxImages: 5, relCost: 1 },
+  { id: "alibaba/qwen-image-3.0-pro", label: "Qwen Image 3.0 Pro", provider: "workers-ai", edit: false, maxImages: 0, relCost: 0.5 },
+  { id: "krea/krea-2-medium-turbo", label: "Krea 2 Medium Turbo", provider: "workers-ai", edit: false, maxImages: 0, relCost: 0.25 }
+];
+var SPRITE_IMAGE_MODEL_IDS = SPRITE_IMAGE_MODELS.map((m) => m.id);
+function spriteImageModel(id2) {
+  return SPRITE_IMAGE_MODELS.find((m) => m.id === id2) ?? SPRITE_IMAGE_MODELS[0];
+}
+var VIDEO_WORKFLOWS = ["image-to-video", "text-to-video", "extend-video", "reference-to-video", "lip-sync", "camera-controls", "insert-video", "recast", "relight", "3d-to-video", "style", "keyframes-to-video"];
+var STUDIO_VIDEO_WORKFLOWS = ["image-to-video", "text-to-video", "extend-video"];
+var MEDIA_LENGTH_WORKFLOWS = ["lip-sync", "recast", "relight", "3d-to-video"];
+var lengthFromMedia = (workflow) => MEDIA_LENGTH_WORKFLOWS.includes(workflow);
+var VIDEO_STYLES = ["vhs", "retro-toon-70s", "low-poly", "hand-drawn", "16bit-pixel"];
+var VHS_DAMAGE_LEVELS = ["light", "medium", "heavy"];
+var VIDEO_RESOLUTIONS = ["480p", "720p", "768p", "1080p", "2k"];
+var H3_RESOLUTIONS = ["480p", "768p", "1080p", "2k"];
+var VIDEO_ASPECT_RATIOS = ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"];
+var PROMPT_EXPANSION_MODES = ["disabled", "balanced", "quality"];
+var EXTEND_OUTPUTS = ["extended", "continuation"];
+var SOUNDTRACK_MAX_BYTES = 15 * 1024 * 1024;
+var EXTEND_SOURCE_MAX_BYTES = 50 * 1024 * 1024;
+var MAX_AUDIO_REFERENCES = 3;
+var MAX_VIDEO_REFERENCE_IMAGES = 9;
+var MAX_REFERENCE_VIDEOS = 3;
+var MAX_REFERENCE_FILES = 12;
+var MAX_RECAST_PEOPLE = 4;
+var MAX_3D_REFERENCES = 8;
+var MAX_CAMERA_KEYFRAMES = 12;
+var MAX_CAMERA_TURNS = 32;
+var MAX_IMAGE_KEYFRAMES = 10;
+var KEYFRAME_FPS = 24;
+var H3_MAX = "minimax/h3-max";
+var FLUX_3_MAX = "blackforestlabs/flux-3-max";
+var h3Endpoints = (route) => ({ "image-to-video": `${route}/image-to-video`, "text-to-video": `${route}/text-to-video`, "extend-video": `${route}/extend-video` });
+var SPRITE_VIDEO_MODELS = [
+  {
+    id: "pruna/p-video-2-pro",
+    label: "Pruna P-Video 2 Pro",
+    provider: "pruna",
+    workflows: ["image-to-video"],
+    resolutions: ["480p", "768p"],
+    modes: ["cost", "speed", "quality"],
+    lastFrame: true,
+    estimatedCreditsPerSecond: { "480p": { cost: 1, speed: 2, quality: 4 }, "768p": { cost: 2.5, speed: 3.5, quality: 7.5 } },
+    seconds: { min: 5, max: 15 }
+  },
+  {
+    id: "heygen/heygen-video-1",
+    label: "HeyGen Video 1",
+    provider: "heygen",
+    workflows: ["image-to-video"],
+    resolutions: ["480p", "768p"],
+    modes: ["cost"],
+    lastFrame: false,
+    estimatedCreditsPerSecond: { "480p": { cost: 1 }, "768p": { cost: 1.5 } },
+    seconds: { min: 5, max: 15 }
+  },
+  {
+    id: "fal/minimax-h3-max",
+    label: "MiniMax H3 Max (fal.ai)",
+    provider: "fal",
+    // Every workflow but FLUX 3 Max's keyframes.
+    workflows: VIDEO_WORKFLOWS.filter((w) => w !== "keyframes-to-video"),
+    endpoints: {
+      ...h3Endpoints(H3_MAX),
+      "reference-to-video": `${H3_MAX}/reference-to-video`,
+      "lip-sync": `${H3_MAX}/lip-sync/image-to-video`,
+      "camera-controls": `${H3_MAX}/camera-controls`,
+      "insert-video": `${H3_MAX}/insert-video`,
+      recast: `${H3_MAX}/recast`,
+      relight: `${H3_MAX}/relight`,
+      "3d-to-video": `${H3_MAX}/3d-to-video`,
+      style: `${H3_MAX}/styles`
+    },
+    resolutions: ["480p", "768p", "1080p"],
+    workflowOptions: {
+      "extend-video": { resolutions: H3_RESOLUTIONS },
+      "lip-sync": { resolutions: H3_RESOLUTIONS, seconds: { min: 5, max: 900, fractional: true } },
+      "insert-video": { resolutions: ["480p", "768p"], seconds: { min: 5, max: 13, fractional: true }, creditsPerSecond: { "480p": 5, "768p": 6 } },
+      recast: { resolutions: ["768p", "1080p"], seconds: { min: 5, max: 30, fractional: true }, creditsPerSecond: { "768p": 30, "1080p": 45 } },
+      relight: { resolutions: H3_RESOLUTIONS, seconds: { min: 2.33, max: 15, fractional: true } },
+      "3d-to-video": { seconds: { min: 1, max: 15, fractional: true } },
+      style: { resolutions: ["768p"], seconds: { min: 5, max: 15 } }
+    },
+    modes: ["quality"],
+    lastFrame: true,
+    endFrameOnly: true,
+    seed: true,
+    promptExpansion: PROMPT_EXPANSION_MODES,
+    audio: true,
+    estimatedCreditsPerSecond: { "480p": { quality: 5 }, "768p": { quality: 8 }, "1080p": { quality: 16 }, "2k": { quality: 32 } },
+    seconds: { min: 1, max: 15, fractional: true }
+  },
+  {
+    id: "fal/minimax-h3-max-turbo",
+    label: "MiniMax H3 Max Turbo (fal.ai)",
+    provider: "fal",
+    workflows: STUDIO_VIDEO_WORKFLOWS,
+    endpoints: h3Endpoints("minimax/h3-max-turbo"),
+    resolutions: ["480p", "768p", "1080p"],
+    workflowOptions: { "extend-video": { resolutions: H3_RESOLUTIONS } },
+    modes: ["speed"],
+    lastFrame: true,
+    endFrameOnly: true,
+    seed: true,
+    promptExpansion: PROMPT_EXPANSION_MODES,
+    audio: true,
+    estimatedCreditsPerSecond: { "480p": { speed: 2.5 }, "768p": { speed: 4 }, "1080p": { speed: 8 }, "2k": { speed: 16 } },
+    seconds: { min: 1, max: 15, fractional: true }
+  },
+  {
+    id: "fal/flux-3-max",
+    label: "FLUX 3 Max (fal.ai)",
+    provider: "fal",
+    workflows: ["image-to-video", "text-to-video", "keyframes-to-video"],
+    endpoints: { "image-to-video": `${FLUX_3_MAX}/image-to-video`, "text-to-video": `${FLUX_3_MAX}/text-to-video`, "keyframes-to-video": `${FLUX_3_MAX}/keyframes-to-video` },
+    falInputs: "flux",
+    resolutions: ["720p", "1080p"],
+    modes: ["quality"],
+    lastFrame: true,
+    seed: true,
+    promptExpansion: ["balanced", "quality"],
+    estimatedCreditsPerSecond: { "720p": { quality: 17 }, "1080p": { quality: 29 } },
+    seconds: { min: 5, max: 20 }
+  }
+];
+var SPRITE_VIDEO_MODEL_IDS = SPRITE_VIDEO_MODELS.map((m) => m.id);
+var DEFAULT_SPRITE_VIDEO_MODEL = "pruna/p-video-2-pro";
+function spriteVideoModel(id2) {
+  return SPRITE_VIDEO_MODELS.find((m) => m.id === id2) ?? SPRITE_VIDEO_MODELS[0];
+}
+function videoResolutions(model, workflow = "image-to-video") {
+  return model.workflowOptions?.[workflow]?.resolutions ?? model.resolutions;
+}
+function videoSeconds(model, workflow = "image-to-video") {
+  return model.workflowOptions?.[workflow]?.seconds ?? model.seconds;
+}
+var INCLUDED_REFERENCE_TOKENS = 4096;
+var imageReferenceTokens = (size) => size && size[0] > 0 && size[1] > 0 ? 32 * Math.ceil(32 * Math.max(...size) / Math.min(...size)) : 1824;
+var clipReferenceTokens = (seconds2, resolution) => Math.ceil(Math.max(0, seconds2) * (resolution === "480p" ? 2700 : 6900));
+var audioReferenceTokens = (seconds2) => Math.ceil(Math.max(0, seconds2) * 80);
+var DEFAULT_GENERATED_REFERENCES = 2;
+function billedVideoSeconds(model, workflow, seconds2) {
+  const s = videoSeconds(model, workflow).fractional ? seconds2 : Math.round(seconds2);
+  if (workflow === "3d-to-video") return Math.max(5, s);
+  return workflow === "lip-sync" && s > 15 ? s * 1.2 : s;
+}
+function videoCreditsPerSecond(model, p) {
+  const override = model.workflowOptions?.[p.workflow ?? "image-to-video"]?.creditsPerSecond?.[p.resolution];
+  if (override !== void 0) return override;
+  const byMode = model.estimatedCreditsPerSecond[p.resolution] ?? model.estimatedCreditsPerSecond[model.resolutions[0]];
+  return byMode[p.mode] ?? byMode[model.modes[0]] ?? 0;
+}
+function spriteVideoEstimate(model, p, extras2 = {}) {
+  const seconds2 = billedVideoSeconds(model, p.workflow ?? "image-to-video", p.seconds);
+  const beyond = Math.max(0, (extras2.referenceTokens ?? 0) - INCLUDED_REFERENCE_TOKENS) * 2e-3 + (extras2.generatedReferences ?? 0) * 3;
+  return Math.max(1, Math.ceil((videoCreditsPerSecond(model, p) * seconds2 + beyond) * UNITS_PER_CREDIT));
+}
+
 // shared/sprites/generation-models.ts
 var generationModelShape = {
   videoModel: external_exports.enum(SPRITE_VIDEO_MODEL_IDS).optional()
@@ -45349,7 +45361,7 @@ async function installSkills(options) {
 import { spawn } from "node:child_process";
 import { cp, mkdir as mkdir7, readFile as readFile5, readdir as readdir3, access as access2, writeFile as writeFile6, rename as rename3 } from "node:fs/promises";
 import { basename as basename2, dirname as dirname6, delimiter as delimiter2, join as join7, resolve as resolve6 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 // shared/locales/en/animation-styles.json
 var animation_styles_default = {
@@ -46341,7 +46353,7 @@ var animation_styles_default = {
         "Rack focus between details",
         "Callouts that track parts"
       ],
-      previewCaption: "Generated headphones turn on a stone plinth as the camera pulls back from a macro of the brushed yoke, focus racking from part to part under pinned callouts, ending on a lockup for an invented brand. Model generated with Tripo H3.1, rendered in three.js.",
+      previewCaption: "Generated headphones turn on a stone plinth as the camera pulls back from a macro of the brushed yoke, focus racking from part to part under pinned callouts, ending on a lockup for an invented brand.",
       family: "3d",
       example: true
     },
@@ -46358,7 +46370,7 @@ var animation_styles_default = {
         "Crossfaded gestures",
         "A camera that follows the character"
       ],
-      previewCaption: "A generated, auto-rigged baker walks across a painted square, turns to camera, waves and explains, his shadow falling over the painting. Character made with Tripo H3.1 and Meshy's auto-rig, rendered in three.js.",
+      previewCaption: "A generated, auto-rigged baker walks across a painted square, turns to camera, waves and explains, his shadow falling over the painting.",
       family: "3d",
       example: true
     },
@@ -46375,7 +46387,7 @@ var animation_styles_default = {
         "Little cars and figures on loops",
         "Focus pulled through the scene"
       ],
-      previewCaption: "A camera glides over a toy harbour town as little cars and boats run their loops, everything sharp only in a thin band of focus. Props generated with Tripo H3.1, rendered in three.js.",
+      previewCaption: "A camera glides over a toy harbour town as little cars and boats run their loops, everything sharp only in a thin band of focus.",
       family: "3d",
       example: true
     },
@@ -46630,6 +46642,15 @@ async function installDependencies(directory, options) {
     child.once("close", (code) => code === 0 ? resolveInstall() : reject(new Error(`npm install exited with code ${code}.`)));
   });
 }
+async function ffmpegProblem() {
+  const { findFfmpeg } = await import(pathToFileURL(join7(packageRoot, "templates/video/scripts/ffmpeg-binaries.mjs")).href);
+  try {
+    await findFfmpeg();
+    return null;
+  } catch (error62) {
+    return error62 instanceof Error ? error62.message : String(error62);
+  }
+}
 var STARTER_STORY = {
   version: 1,
   start: "opening",
@@ -46711,13 +46732,15 @@ async function createVideoProject(options, installer = installDependencies) {
   if (options.story) await writeStarterStory(directory);
   if (options.quiz) await writeStarterQuiz(directory, options.story);
   if (options.install !== false) {
-    options.log?.("Installing PixiJS, Vite, TypeScript, and the MP4 tools\u2026");
+    options.log?.("Installing PixiJS, Vite and TypeScript\u2026");
     try {
       await installer(directory, options);
     } catch (error62) {
       throw new Error(`Project files are ready at ${directory}, but dependency installation failed: ${error62 instanceof Error ? error62.message : String(error62)} Open that folder and run npm install to resume; do not rerun create into it.`);
     }
   }
+  const ffmpeg = await ffmpegProblem();
+  if (ffmpeg) options.log?.(`Note: ${ffmpeg}`);
   options.log?.(`Ready. Open ${directory} in Codex or Claude Code and describe your video.
 ${options.install === false ? "Run npm install, then " : "Run "}npm run dev inside that folder to preview.`);
   return {
@@ -46729,7 +46752,8 @@ ${options.install === false ? "Run npm install, then " : "Run "}npm run dev insi
     installed: options.install !== false,
     skills: [...skills, ...pixiSkills],
     agents: ["Codex", "Claude Code"],
-    nextSteps: ["Open this folder in Codex or Claude Code and describe your video. The agent asks for Explainer, Advertisement or General Video, then a visual style and a compact creative brief.", ...options.install === false ? ["Run npm install."] : [], "Run npm run dev to preview.", "Run npm run export:mp4 when the film is ready."]
+    ffmpeg: ffmpeg ? { ready: false, problem: ffmpeg } : { ready: true },
+    nextSteps: ["Open this folder in Codex or Claude Code and describe your video. The agent asks for Explainer, Advertisement or General Video, then a visual style and a compact creative brief.", ...options.install === false ? ["Run npm install."] : [], ...ffmpeg ? [ffmpeg] : [], "Run npm run dev to preview.", "Run npm run export:mp4 when the film is ready."]
   };
 }
 async function createWorkspace(options, installer = installDependencies) {
@@ -46782,6 +46806,8 @@ async function createWorkspace(options, installer = installDependencies) {
       throw new Error(`Workspace files are ready at ${directory}, but dependency installation failed: ${error62 instanceof Error ? error62.message : String(error62)} Run npm install there to finish.`);
     }
   }
+  const ffmpeg = result.ffmpeg;
+  if (!ffmpeg.ready) options.log?.(`Note: ${ffmpeg.problem}`);
   options.log?.(`Workspace ready: ${directory}. Open it in Codex or Claude Code with your website or brand guide, then create an animation.`);
   return {
     type: "workspace",
@@ -46792,7 +46818,8 @@ async function createWorkspace(options, installer = installDependencies) {
     installed: options.install !== false,
     branding: join7(directory, "branding"),
     animations: join7(directory, "animations"),
-    nextSteps: ["Open this workspace in Codex or Claude Code and provide your website or brand guide; the agent asks if it is missing.", "Build the shared brand kit in branding/.", "Run animaguru create animation my-video.", "Run npm run dev for the animation hub."]
+    ffmpeg,
+    nextSteps: ["Open this workspace in Codex or Claude Code and provide your website or brand guide; the agent asks if it is missing.", "Build the shared brand kit in branding/.", ...ffmpeg.ready ? [] : [ffmpeg.problem], "Run animaguru create animation my-video.", "Run npm run dev for the animation hub."]
   };
 }
 async function findWorkspace(start = process.cwd()) {
@@ -47336,7 +47363,9 @@ var videoSubmission = videoDetails.and(external_exports.object({
   bytes: external_exports.number().int().positive(),
   width: external_exports.number().int().min(1).max(4096).default(1920),
   height: external_exports.number().int().min(1).max(4096).default(1080),
-  duration: external_exports.number().positive().max(7200).optional()
+  duration: external_exports.number().positive().max(7200).optional(),
+  /** Admins only: adds the video to the showcase (shared/showcase.ts), where it shows once it is public and approved. */
+  showcase: showcaseEntry.optional()
 })).refine((value) => value.bytes <= VIDEO_MAX_BYTES[value.format], "HTML5 ZIPs support up to 64 MiB; MP4s support up to 512 MiB.").refine((value) => !value.animation || value.project, "Name the project of the animation.");
 var videoMove = external_exports.object({ workspace: videoWorkspace }).strict();
 function videoPosterType(bytes) {
@@ -48282,6 +48311,17 @@ async function restoreCloud(options) {
 }
 
 // cli/src/videos.ts
+function showcaseOption(options) {
+  const extra = options["showcase-tags"] !== void 0 || options["showcase-language"] !== void 0 || options["showcase-position"] !== void 0;
+  if (!options.showcase) {
+    if (extra) throw new Error("Pass --showcase SECTOR to add the video to the showcase.");
+    return {};
+  }
+  const tags = options["showcase-tags"] ? options["showcase-tags"].split(",").map((tag) => tag.trim()).filter(Boolean) : [];
+  const parsed = showcaseEntry.safeParse({ sector: options.showcase, tags, locale: options["showcase-language"] === "none" ? "" : options["showcase-language"] ?? "", position: options["showcase-position"] ?? 0 });
+  if (!parsed.success) throw new Error(`Check the showcase tags: ${parsed.error.issues[0]?.message ?? "invalid"} (tags are ${SHOWCASE_TAGS.join(", ")}).`);
+  return { showcase: parsed.data };
+}
 var subtitlesBody = (content) => new Blob([new Uint8Array(content)], { type: "text/plain; charset=utf-8" });
 function libraryWorkspace(value) {
   if (value === "personal" || value === "me") return "me";
@@ -48326,6 +48366,7 @@ 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 workspace3 = options.workspace === void 0 ? void 0 : libraryWorkspace(options.workspace);
+  const showcase = showcaseOption(options);
   const root = resolve10(options.directory ?? ".");
   const context = await localProject(root, options.animation);
   const file2 = options.file ? resolve10(root, options.file) : await exportHtml(context.toolsRoot, context.animation, options.signal, options.log);
@@ -48370,7 +48411,8 @@ async function submitVideo(client, options) {
     bytes: info.size,
     width: metadata.width,
     height: metadata.height,
-    duration: metadata.duration
+    duration: metadata.duration,
+    ...showcase
   });
   let subtitles = null;
   const choice = options.subtitles ?? "auto";
@@ -50091,6 +50133,7 @@ var brandCreate = brandFields.extend({ requestId: external_exports.string().uuid
 var brandUpdate = external_exports.object(fieldShape).partial().strict();
 var brandResearch = external_exports.object({ requestId: external_exports.string().uuid(), workspace, url: brandWebsite, name: external_exports.string().trim().min(1).max(120).optional() }).strict();
 var brandRefresh = external_exports.object({ requestId: external_exports.string().uuid(), url: brandWebsite.optional() }).strict();
+var brandTransfer = external_exports.object({ workspace }).strict();
 var DEFAULT_BRAND_COLORS = { primary: "#2563eb", background: "#ffffff", text: "#111827", accent: null, palette: [] };
 var DEFAULT_BRAND_FONTS = { heading: { family: "Inter, sans-serif", file: null }, body: { family: "Inter, sans-serif", file: null } };
 var brandDraftFields = brandFields.extend({
@@ -50702,6 +50745,10 @@ function createCli() {
     { 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: "showcase", type: "string", choices: [...SHOWCASE_SECTORS], description: "Admins: add the video to the showcase under this sector; it shows on lead pages once public and approved" },
+    { name: "showcase-tags", type: "string", description: `Admins: what the film is for, comma-separated: ${SHOWCASE_TAGS.join(", ")}` },
+    { name: "showcase-language", type: "string", choices: ["en", "tr", "sv", "none"], description: "Admins: the language the film speaks or shows; none for music and pictures only (default)" },
+    { name: "showcase-position", type: "number", description: "Admins: order in the showcase, lower first (default 0)" },
     { 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 a video library (the selected workspace's by default), privately shared videos, or the public gallery" }, (command) => command.flags(

package/package.json

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

package/skills/animaguru-video/SKILL.md

@@ -112,7 +112,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. A branching story (`story.json`) and a quiz film (`quiz.json`) are HTML5 only. 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 on the user's own computer, run `npm run export:mp4 -- --headless`; it captures in a local headless Chrome (installed Chrome or Edge, `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`, or `npx playwright install chromium`). Without `--headless`, open the printed local capture URL in a 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. The cloud Animator makes no MP4s and `export:mp4` refuses to run there: the user applies the draft and exports the MP4 in their browser.
+For MP4 on the user's own computer, run `npm run export:mp4 -- --headless`; it captures in a local headless Chrome (installed Chrome or Edge, `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`, or `npx playwright install chromium`). Without `--headless`, open the printed local capture URL in a 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. The cloud Animator makes no MP4s and `export:mp4` refuses to run there: the user exports the MP4 in their browser from the draft page.
 
 `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

@@ -10,7 +10,7 @@ Example prompt:
 
 ## Preview
 
-Requires Node.js 24+. Dependencies are installed by `animaguru create NAME`. If installation was interrupted, run `npm install` inside this folder to finish it.
+Requires Node.js 24+, and FFmpeg 7.1 or newer with FFprobe for the audio tools and MP4 export: they run the `ffmpeg` and `ffprobe` on PATH, or `FFMPEG_PATH` and `FFPROBE_PATH` (macOS: `brew install ffmpeg`; Windows: `winget install Gyan.FFmpeg`; Debian 13: `sudo apt install ffmpeg`). Dependencies are installed by `animaguru create NAME`. If installation was interrupted, run `npm install` inside this folder to finish it.
 
 ```sh
 npm run dev
@@ -71,9 +71,9 @@ npm run export:mp4 -- --burn-captions
 npm run export:mp4 -- --watermark
 ```
 
-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.
+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 FFmpeg, and mixes the configured soundtrack. An AAC soundtrack at 48 kHz that lasts the whole film, such as `npm run audio:mix` writes, is copied into the MP4 as it is; any other soundtrack is encoded to AAC and padded to length. The initial starter exports with a silent AAC track. Exporting local media does not call AnimaGuru or spend credits. The export stops before capturing when FFmpeg or FFprobe is missing or older than 7.1.
 
-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. `--watermark` also saves `SLUG-LANGUAGE-watermarked.mp4`, the same film with AnimaGuru's "Made with AnimaGuru" badge in its bottom-right corner, drawn with the font, logo and layout AnimaGuru's web app uses; it is the preview AnimaGuru's lead pipeline plays before a lead claims the clean film. The picture is encoded again with the badge and verified like the film; the sound is copied. 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. `--watermark` also saves `SLUG-LANGUAGE-watermarked.mp4`, the same film with AnimaGuru's "Made with AnimaGuru" badge in its bottom-right corner, drawn with the font, logo and layout AnimaGuru's web app uses; it is the preview AnimaGuru's lead pipeline plays before a lead claims the clean film. The picture is encoded again with the badge and verified like the film; the sound is copied. 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. It also measures the MP4's own sound (integrated loudness and true peak, saved as `soundtrack` in the JSON report) and warns when its true peak is above -1 dBTP. 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/package.json

@@ -25,8 +25,6 @@
     "three": "0.186.1"
   },
   "devDependencies": {
-    "@ffmpeg-installer/ffmpeg": "1.1.0",
-    "@ffprobe-installer/ffprobe": "2.1.2",
     "@types/three": "0.186.0",
     "fflate": "0.8.3",
     "playwright-core": "1.64.0",

package/templates/video/scripts/audio-mix.mjs

@@ -7,13 +7,35 @@ import { mkdir, readFile, writeFile, access } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { projectArguments, projectContext } from "./project-context.mjs";
-import { ffmpeg, measureLoudness, parseFlags, projectPath, readJson, round } from "./audio-tools.mjs";
+import { ffmpeg, loudnormReport, measureLoudness, parseFlags, projectPath, readJson, round } from "./audio-tools.mjs";
 
 const RATE = 48000;
 export const MIX_DEFAULTS = { musicDb: -9, duck: { threshold: 0.03, ratio: 6, attack: 20, release: 350 }, loudness: { i: -14, tp: -2, lra: 9 } };
+// The largest LRA target loudnorm accepts (FFmpeg 7.1 and newer).
+const LRA_LIMIT = 50;
+
+/**
+ * The second loudnorm pass: one linear gain from the first pass's measurements. loudnorm stays linear only while the
+ * measured loudness range fits the LRA target and the gain keeps the true peak under TP; otherwise it switches to
+ * dynamic mode without an error and rides the gain, which can pump. The LRA target does nothing else on a linear
+ * pass, so it is widened to the mix's own range unless mix.json sets loudness.lra. `blockers` say what keeps the pass
+ * from staying linear, each with the change that would let it.
+ */
+export function loudnormPass(first, loudness, { keepRange = false } = {}) {
+  const lra = keepRange ? loudness.lra : Math.min(LRA_LIMIT, Math.max(loudness.lra, Math.ceil(first.range * 10) / 10));
+  const gain = loudness.i - first.integrated, peak = first.truePeak + gain, blockers = [];
+  if (first.range > lra) blockers.push(keepRange
+    ? { reason: `its loudness range of ${round(first.range, 1)} LU is wider than loudness.lra (${lra} LU)`, fix: "raise or remove loudness.lra" }
+    : { reason: `its loudness range of ${round(first.range, 1)} LU is wider than the ${LRA_LIMIT} LU loudnorm accepts`, fix: "bring the quietest and loudest passages closer together" });
+  // The loudest target one gain reaches without passing the ceiling, rounded down so it stays under it.
+  const loudest = Math.floor((loudness.tp - first.truePeak + first.integrated) * 10) / 10;
+  if (peak > loudness.tp) blockers.push({ reason: `a ${gain >= 0 ? "+" : ""}${round(gain, 1)} dB gain would lift its true peak to ${round(peak, 1)} dBTP, above the ${loudness.tp} dBTP ceiling`, fix: `lower loudness.i to ${loudest} or below` });
+  const filter = `loudnorm=I=${loudness.i}:TP=${loudness.tp}:LRA=${lra}:measured_I=${first.integrated}:measured_TP=${first.truePeak}:measured_LRA=${first.range}:measured_thresh=${first.threshold}:offset=${first.offset}:linear=true:print_format=json`;
+  return { filter, lra, gain, blockers };
+}
 
 /** The music part of the graph for input `input`, as edited by audio:music (a trim or a bar-aligned cut). */
-// Padding counts samples at RATE: the bundled Linux ffmpeg (@ffmpeg-installer) has no apad whole_dur option.
+// Padding counts samples at RATE, so the padded length is exact.
 export function musicGraph(edit, { input = 0, duration, musicDb = MIX_DEFAULTS.musicDb, label = "music" }) {
   const headIn = Math.max(0, Number(edit?.headIn ?? 0)), fadeIn = Number(edit?.fadeIn ?? (headIn > 0.05 ? 0.25 : 0.02)), fadeOut = Number(edit?.fadeOut ?? 0.6);
   const ending = `atrim=0:${duration},apad=whole_len=${Math.round(duration * RATE)},afade=t=out:st=${round(Math.max(0, duration - fadeOut))}:d=${fadeOut},volume=${musicDb}dB,aformat=sample_fmts=fltp:sample_rates=${RATE}:channel_layouts=stereo[${label}]`;
@@ -81,8 +103,10 @@ async function main() {
   await ffmpeg(["-y", "-loglevel", "error", ...(music ? ["-i", music] : []), ...(vo ? ["-i", vo] : []), "-filter_complex", graph, "-map", "[mix]", "-ar", String(RATE), "-ac", "2", "-c:a", "pcm_s24le", "-t", String(duration), premaster]);
   // Two-pass loudnorm: measure, then normalise linearly with the measured values.
   const first = await measureLoudness(premaster, loudness);
-  const second = `loudnorm=I=${loudness.i}:TP=${loudness.tp}:LRA=${loudness.lra}:measured_I=${first.integrated}:measured_TP=${first.truePeak}:measured_LRA=${first.range}:measured_thresh=${first.threshold}:offset=${first.offset}:linear=true`;
-  await ffmpeg(["-y", "-loglevel", "error", "-i", premaster, "-af", second, "-ar", String(RATE), "-ac", "2", "-c:a", "pcm_s24le", "-t", String(duration), master]);
+  const pass = loudnormPass(first, loudness, { keepRange: mix.loudness?.lra !== undefined });
+  // No -loglevel error here: loudnorm reports which mode it used at the info level.
+  const { stderr } = await ffmpeg(["-y", "-nostats", "-i", premaster, "-af", pass.filter, "-ar", String(RATE), "-ac", "2", "-c:a", "pcm_s24le", "-t", String(duration), master]);
+  const mode = loudnormReport(stderr)?.normalization_type;
   await ffmpeg(["-y", "-loglevel", "error", "-i", master, "-c:a", "aac", "-b:a", "192k", "-ar", String(RATE), "-ac", "2", "-movflags", "+faststart", output]);
   const result = await measureLoudness(output, loudness);
 
@@ -93,7 +117,9 @@ async function main() {
 
   const parts = [vo ? `voiceover ${path.relative(base, vo)}` : null, music ? `music ${path.relative(base, music)}${edit?.type === "cut" ? ` (${edit.headIn}–${edit.cutA} s → ${edit.cutB} s)` : edit ? ` (from ${edit.headIn} s)` : ""}` : null].filter(Boolean);
   console.log(`Mixed ${parts.join(" + ")}${music && vo ? `, music at ${mix.musicDb ?? MIX_DEFAULTS.musicDb} dB, ducked under the voice` : ""}.`);
-  console.log(`Before normalising: ${round(first.integrated, 1)} LUFS, ${round(first.truePeak, 1)} dBTP. Encoded AAC: ${round(result.integrated, 1)} LUFS, ${round(result.truePeak, 1)} dBTP (target ${loudness.i} LUFS, ${loudness.tp} dBTP).`);
+  const how = mode === "linear" ? ` Normalised with one ${pass.gain >= 0 ? "+" : ""}${round(pass.gain, 1)} dB gain.` : mode === "dynamic" ? " Normalised with dynamic gain." : "";
+  console.log(`Before normalising: ${round(first.integrated, 1)} LUFS, ${round(first.truePeak, 1)} dBTP, ${round(first.range, 1)} LU range.${how} Encoded AAC: ${round(result.integrated, 1)} LUFS, ${round(result.truePeak, 1)} dBTP (target ${loudness.i} LUFS, ${loudness.tp} dBTP).`);
+  if (mode === "dynamic") console.log(`Warning: loudnorm rode the gain instead of applying one gain, which can pump${pass.blockers.length ? `, because ${pass.blockers.map((item) => item.reason).join(" and ")}. To keep one gain, ${pass.blockers.map((item) => item.fix).join(" and ")} in production/audio/mix.json and rerun` : ""}. Listen to the mix before exporting.`);
   if (result.truePeak > -1) console.log("Warning: the encoded true peak is above -1 dBTP; lower loudness.tp in production/audio/mix.json and rerun.");
   if (Math.abs(result.integrated - loudness.i) > 1) console.log("Warning: the encoded loudness is more than 1 LU off target; check for long silences or a very dynamic bed.");
   console.log(`Wrote ${path.relative(base, output)}; film.config.json audio is "${audio}". Listen once with npm run dev before exporting.`);

package/templates/video/scripts/audio-tools.mjs

@@ -1,29 +1,20 @@
-/** Shared helpers for audio:vo, audio:music and audio:mix: the bundled ffmpeg, PCM decoding and small DSP routines. */
+/** Shared helpers for audio:vo, audio:music and audio:mix: the installed ffmpeg, PCM decoding and small DSP routines. */
 import { execFile, spawn } from "node:child_process";
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
+import { ffmpegBinaries } from "./ffmpeg-binaries.mjs";
 
 const run = promisify(execFile);
-let binaries;
-
-/** The ffmpeg/ffprobe builds installed with the workspace; loaded lazily so the pure helpers import anywhere. */
-export async function audioBinaries() {
-  if (!binaries) {
-    const [{ default: ffmpeg }, { default: ffprobe }] = await Promise.all([import("@ffmpeg-installer/ffmpeg"), import("@ffprobe-installer/ffprobe")]);
-    binaries = { ffmpeg: ffmpeg.path, ffprobe: ffprobe.path };
-  }
-  return binaries;
-}
 
 export async function ffmpeg(args) {
-  const { ffmpeg: binary } = await audioBinaries();
+  const { ffmpeg: binary } = await ffmpegBinaries();
   try { return await run(binary, ["-hide_banner", "-nostdin", ...args], { maxBuffer: 64 * 1024 * 1024 }); }
   catch (error) { throw new Error(`ffmpeg failed: ${String(error.stderr ?? error.message).trim().split("\n").slice(-3).join(" ")}`); }
 }
 
 export async function mediaDuration(file) {
-  const { ffprobe } = await audioBinaries();
+  const { ffprobe } = await ffmpegBinaries();
   const { stdout } = await run(ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file]);
   const duration = Number(stdout);
   if (!Number.isFinite(duration)) throw new Error(`Could not read the duration of ${file}.`);
@@ -32,7 +23,7 @@ export async function mediaDuration(file) {
 
 /** Decodes any audio file to mono Float32 samples at the given rate. */
 export async function decodePcm(file, sampleRate = 22050) {
-  const { ffmpeg: binary } = await audioBinaries();
+  const { ffmpeg: binary } = await ffmpegBinaries();
   return new Promise((resolve, reject) => {
     const child = spawn(binary, ["-v", "error", "-nostdin", "-i", file, "-ac", "1", "-ar", String(sampleRate), "-f", "f32le", "pipe:1"], { stdio: ["ignore", "pipe", "pipe"] });
     const chunks = []; let errors = "";
@@ -48,12 +39,17 @@ export async function decodePcm(file, sampleRate = 22050) {
   });
 }
 
-/** EBU R128 measurement with ffmpeg's loudnorm; returns the measured values its second pass needs. */
-export async function measureLoudness(file, { i = -14, tp = -2, lra = 9, filter = "" } = {}) {
-  const { stderr } = await ffmpeg(["-nostats", "-i", file, "-af", `${filter ? `${filter},` : ""}loudnorm=I=${i}:TP=${tp}:LRA=${lra}:print_format=json`, "-f", "null", "-"]);
+/** The report loudnorm prints at the info log level when it finishes with print_format=json, or null. */
+export function loudnormReport(stderr) {
   const json = stderr.match(/\{\s*"input_i"[\s\S]*?\}/)?.[0];
-  if (!json) throw new Error(`Loudness could not be measured for ${file}.`);
-  const values = JSON.parse(json);
+  return json ? JSON.parse(json) : null;
+}
+
+/** EBU R128 measurement with ffmpeg's loudnorm; returns the measured values its second pass needs. A video's picture is skipped. */
+export async function measureLoudness(file, { i = -14, tp = -2, lra = 9, filter = "" } = {}) {
+  const { stderr } = await ffmpeg(["-nostats", "-i", file, "-vn", "-af", `${filter ? `${filter},` : ""}loudnorm=I=${i}:TP=${tp}:LRA=${lra}:print_format=json`, "-f", "null", "-"]);
+  const values = loudnormReport(stderr);
+  if (!values) throw new Error(`Loudness could not be measured for ${file}.`);
   return { integrated: Number(values.input_i), truePeak: Number(values.input_tp), range: Number(values.input_lra), threshold: Number(values.input_thresh), offset: Number(values.target_offset) };
 }
 

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

@@ -5,15 +5,16 @@ import { mkdir, access, rename, rm, stat, writeFile, readFile, realpath } from "
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
-import ffmpeg from "@ffmpeg-installer/ffmpeg";
-import ffprobe from "@ffprobe-installer/ffprobe";
+import { ffmpegBinaries } from "./ffmpeg-binaries.mjs";
 import { projectArguments, projectContext, publicFile } from "./project-context.mjs";
 import { workspacePlugin } from "./workspace-plugin.mjs";
 import { subtitleCues, toSrt, toVtt } from "./subtitles.mjs";
 import { captureHeadless, takeHeadlessFlag } from "./headless-browser.mjs";
+import { BT709_FRAMES, canCopySoundtrack, isBt709, mp4Language } from "./mp4-tools.mjs";
+import { measureLoudness } from "./audio-tools.mjs";
 
-// The cloud Animator makes no MP4s: once the user applies the draft, they export it in their own browser.
-if (process.env.ANIMAGURU_CLOUD_WORKSPACE) throw new Error("MP4 export is not available in the cloud Animator. After the user applies the draft, they export the MP4 in their browser from the draft page.");
+// The cloud Animator makes no MP4s: the user exports the film in their own browser, from the draft page.
+if (process.env.ANIMAGURU_CLOUD_WORKSPACE) throw new Error("MP4 export is not available in the cloud Animator. The user exports the MP4 in their browser from the draft page.");
 
 const root = fileURLToPath(new URL("../", import.meta.url));
 const selection = projectArguments(process.argv.slice(2));
@@ -40,7 +41,9 @@ const { width, height, fps, duration, language } = config;
 if (![width, height].every((n) => Number.isInteger(n) && n >= 2 && n <= 4096 && n % 2 === 0) || ![24, 25, 30, 60].includes(fps) || !Number.isFinite(duration) || duration <= 0 || duration > 600 || Math.abs(duration * fps - Math.round(duration * fps)) > 0.000001) throw new Error("Use even dimensions up to 4096px, 24/25/30/60 fps, and a frame-aligned duration up to 600s in film.config.json.");
 if (typeof language !== "string" || !/^[a-z]{2,3}(?:-[A-Za-z]{2,4})?$/.test(language)) throw new Error("Set a language code in film.config.json.");
 if (typeof config.slug !== "string" || !/^[a-z0-9][a-z0-9-]{0,79}$/.test(config.slug)) throw new Error("Use a lowercase, hyphenated film slug (1–80 characters).");
-const languageTag = ({ en: "eng", tr: "tur", de: "deu", fr: "fra", es: "spa" })[language.split("-")[0]] ?? "und";
+const languageTag = mp4Language(language);
+// Before any capture starts: a missing or pre-7.1 FFmpeg stops here with how to install a current one.
+const binaries = await ffmpegBinaries();
 let audioSource;
 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/.");
@@ -89,6 +92,8 @@ let ownsPartial = false;
 let server;
 let lastActivity = Date.now();
 const run = promisify(execFile);
+// An AAC soundtrack that already fits the film, such as audio:mix's, is copied rather than encoded a second time.
+const copySoundtrack = audioSource ? canCopySoundtrack(JSON.parse((await run(binaries.ffprobe, ["-v", "error", "-select_streams", "a:0", "-show_entries", "stream=codec_name,profile,sample_rate,start_time,duration:format=duration", "-of", "json", audioSource])).stdout), duration) : false;
 
 async function readBody(request, limit = 24 * 1024 * 1024) {
   let bytes = 0;
@@ -121,13 +126,15 @@ function pngDimensions(bytes) {
   return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
 }
 
-/** Reads an encoded MP4 back and checks that it is the whole film: frames, duration, dimensions, codecs and language. */
+/** Reads an encoded MP4 back and checks that it is the whole film: frames, duration, dimensions, codecs, colour tags and language. */
 async function verify(file, what) {
-  const { stdout } = await run(ffprobe.path, ["-v", "error", "-count_frames", "-show_streams", "-show_format", "-of", "json", file], { maxBuffer: 1024 * 1024 });
+  const { stdout } = await run(binaries.ffprobe, ["-v", "error", "-count_frames", "-show_streams", "-show_format", "-of", "json", file], { maxBuffer: 1024 * 1024 });
   const probe = JSON.parse(stdout);
   const video = probe.streams.find((stream) => stream.codec_type === "video");
   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 ${what} did not pass duration, frame count, dimensions, language, or codec verification.`);
+  // Players guess the colours of a video without these tags, and some guess differently.
+  if (!isBt709(video)) throw new Error(`The encoded ${what} is not tagged BT.709 limited range (${["color_space", "color_primaries", "color_transfer", "color_range"].map((key) => video[key] ?? "unknown").join(", ")}).`);
   return probe;
 }
 
@@ -140,7 +147,7 @@ async function watermarkCopy() {
   await writeFile(watermarkedPartial, "", { flag: "wx" });
   ownsWatermarkedPartial = true;
   // The badge arrives on stdin as a single PNG frame, which the overlay keeps over the whole film.
-  const child = spawn(ffmpeg.path, [
+  const child = spawn(binaries.ffmpeg, [
     "-hide_banner", "-loglevel", "warning", "-y", "-i", partial, "-f", "png_pipe", "-i", "pipe:0",
     "-filter_complex", `[1:v]scale=out_color_matrix=bt709:out_range=tv,format=yuva420p[mark];[0:v][mark]overlay=x=${badge.x}:y=${badge.y}:format=yuv420,format=yuv420p[film]`,
     "-map", "[film]", "-map", "0:a:0",
@@ -201,15 +208,16 @@ async function route(request, response, url) {
     settings.captions = !subtitles.length ? "none" : burnCaptions ? "burned" : "subtitle-files";
     await writeFile(partial, "", { flag: "wx" });
     ownsPartial = true;
-    encoder = spawn(ffmpeg.path, [
+    encoder = spawn(binaries.ffmpeg, [
       "-hide_banner", "-loglevel", "warning", "-y",
       "-f", "image2pipe", "-framerate", String(fps), "-vcodec", "mjpeg", "-i", "pipe:0",
       ...(audioSource ? ["-i", audioSource] : ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"]),
       "-map", "0:v:0", "-map", "1:a:0",
       "-c:v", "libx264", "-preset", "medium", "-crf", "18",
-      "-vf", `scale=${width}:${height}:in_color_matrix=bt601:out_color_matrix=bt709:in_range=full:out_range=tv,format=yuv420p`,
+      // setparams labels the frames: from FFmpeg 7.1 on, the -color_* options below no longer tag frames that do not say so.
+      "-vf", `scale=${width}:${height}:in_color_matrix=bt601:out_color_matrix=bt709:in_range=full:out_range=tv,format=yuv420p,${BT709_FRAMES}`,
       "-color_primaries", "bt709", "-color_trc", "bt709", "-colorspace", "bt709",
-      "-af", "apad", "-c:a", "aac", "-b:a", "192k", "-ar", "48000",
+      ...(copySoundtrack ? ["-c:a", "copy"] : ["-af", "apad", "-c:a", "aac", "-b:a", "192k", "-ar", "48000"]),
       "-metadata:s:a:0", `language=${languageTag}`, "-metadata:s:v:0", `language=${languageTag}`,
       "-t", String(settings.duration), "-movflags", "+faststart", partial,
     ], { stdio: ["pipe", "ignore", "pipe"] });
@@ -275,6 +283,10 @@ async function route(request, response, url) {
     await encoderDone;
     console.log("Checking the encoded video and soundtrack…");
     const probe = await verify(partial, "file");
+    // Players hear the MP4's own sound, so its level is measured from the MP4, not assumed from the soundtrack file.
+    const sound = audioSource ? await measureLoudness(partial).then(
+      (levels) => ({ file: config.audio, copied: copySoundtrack, integratedLufs: levels.integrated, truePeakDb: levels.truePeak, rangeLu: levels.range }),
+      (error) => ({ file: config.audio, copied: copySoundtrack, error: error.message })) : null;
     if (watermark) {
       console.log("Making the watermarked copy…");
       await watermarkCopy();
@@ -287,11 +299,13 @@ async function route(request, response, url) {
     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 }, ...(watermark ? { watermarked: { file: path.basename(watermarked), badge: { x: badge.x, y: badge.y, width: badge.width, height: badge.height } } } : {}), settings, verification: probe }, null, 2) + "\n");
+    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 }, soundtrack: sound, ...(watermark ? { watermarked: { file: path.basename(watermarked), badge: { x: badge.x, y: badge.y, width: badge.width, height: badge.height } } } : {}), 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 (sound) console.log(`Sound: ${sound.file}, ${sound.copied ? "copied without a second AAC encode" : "encoded to AAC"}; ${sound.error ? `not measured (${sound.error})` : Number.isFinite(sound.integratedLufs) ? `the MP4 measures ${sound.integratedLufs.toFixed(1)} LUFS, ${sound.truePeakDb.toFixed(1)} dBTP` : "the MP4's sound is silent"}.`);
+    if (sound?.truePeakDb > -1) console.log("Warning: the MP4's sound peaks above -1 dBTP, where players and platforms can clip it. Lower the soundtrack's true peak (for npm run audio:mix, loudness.tp in production/audio/mix.json) and export again.");
     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.');
     if (watermark) console.log(`Watermarked copy ("Made with AnimaGuru"): ${watermarked}`);

package/templates/video/scripts/ffmpeg-binaries.mjs

@@ -0,0 +1,54 @@
+/**
+ * The FFmpeg and FFprobe the audio tools and MP4 export run: the ones on PATH, or FFMPEG_PATH and FFPROBE_PATH.
+ * The workspace installs none of its own. Both must be FFmpeg 7.1 or newer, which every script here is tested with.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+export const MINIMUM_FFMPEG = [7, 1];
+
+/** The release in the first line of `ffmpeg -version` (9.0.2, 7.1.5-0+deb13u1, n8.0.1, 8.0-essentials_build…), or null for a git snapshot. */
+export function ffmpegRelease(text) {
+  const match = /^ff(?:mpeg|probe) version n?(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(text).trim());
+  return match ? match.slice(1).map((part) => Number(part ?? 0)) : null;
+}
+
+/** How to install a current FFmpeg on this platform. */
+export function ffmpegInstallHint(platform = process.platform) {
+  const install = platform === "darwin" ? "Install it with `brew install ffmpeg`"
+    : platform === "win32" ? "Install it with `winget install Gyan.FFmpeg`, then open a new terminal"
+    : "Install your distribution's ffmpeg package if it is 7.1 or newer (Debian 13: `sudo apt install ffmpeg`), or a static build";
+  return `${install}, or point FFMPEG_PATH and FFPROBE_PATH at an ffmpeg and ffprobe of ${MINIMUM_FFMPEG.join(".")} or newer.`;
+}
+
+const older = (release, minimum) => release[0] !== minimum[0] ? release[0] < minimum[0] : release[1] < minimum[1];
+
+/** Runs `NAME -version` and throws, with how to install a current build, when it is missing or older than 7.1. */
+async function check(binary, name) {
+  let stdout;
+  try { ({ stdout } = await run(binary, ["-version"])); }
+  catch (error) {
+    if (error.code === "ENOENT") throw new Error(`${name} was not found ${binary === name ? "on PATH" : `at ${binary}`}. The audio tools and MP4 export need FFmpeg ${MINIMUM_FFMPEG.join(".")} or newer. ${ffmpegInstallHint()}`);
+    throw new Error(`${binary} -version failed: ${String(error.stderr || error.message).trim().split("\n").at(-1)}. ${ffmpegInstallHint()}`);
+  }
+  const release = ffmpegRelease(stdout);
+  if (release && older(release, MINIMUM_FFMPEG)) {
+    const version = String(stdout).trim().split("\n")[0].split(/\s+/)[2];
+    throw new Error(`${name} ${version} at ${binary} is too old: the audio tools and MP4 export need FFmpeg ${MINIMUM_FFMPEG.join(".")} or newer. ${ffmpegInstallHint()}`);
+  }
+}
+
+/** Finds and checks ffmpeg and ffprobe for the given environment; resolves to the commands to run. */
+export async function findFfmpeg(env = process.env) {
+  const ffmpeg = env.FFMPEG_PATH || "ffmpeg", ffprobe = env.FFPROBE_PATH || "ffprobe";
+  await Promise.all([check(ffmpeg, "ffmpeg"), check(ffprobe, "ffprobe")]);
+  return { ffmpeg, ffprobe };
+}
+
+let binaries;
+/** findFfmpeg() for this process, checked once. */
+export function ffmpegBinaries() {
+  binaries ??= findFfmpeg();
+  return binaries;
+}

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

@@ -0,0 +1,33 @@
+/** Decisions npm run export:mp4 makes about the MP4's streams, apart from its capture server so they can be tested. */
+
+// MP4 language tags are ISO 639-2 codes: FFmpeg writes a two-letter code such as "sv" as no tag at all.
+const LANGUAGE_TAGS = { en: "eng", tr: "tur", sv: "swe", de: "deu", fr: "fra", es: "spa" };
+
+/** The MP4 stream language tag for a film.config.json language such as "sv" or "en-GB"; "und" for one not listed. */
+export function mp4Language(language) {
+  return LANGUAGE_TAGS[language.split("-")[0]] ?? "und";
+}
+
+/**
+ * Labels the film's frames BT.709 limited range at the end of its filter chain. FFmpeg 7.1 and newer no longer write
+ * -color_primaries and -color_trc as plain tags: frames decoded from the capture's JPEGs carry no primaries or transfer,
+ * and without this label the MP4 says "unknown" for both (FFmpeg 9.0.2), which players fill in by guessing.
+ */
+export const BT709_FRAMES = "setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv";
+
+/** Whether ffprobe's video stream is tagged BT.709 limited range, as the film is encoded. */
+export function isBt709(stream) {
+  return stream?.color_space === "bt709" && stream.color_primaries === "bt709" && stream.color_transfer === "bt709" && stream.color_range === "tv";
+}
+
+/**
+ * Whether the soundtrack goes into the MP4 as it is, from ffprobe's JSON for its first audio stream: AAC-LC at 48 kHz
+ * that starts at 0 and lasts the whole film, as npm run audio:mix writes it. Copying keeps the loudness and true peak
+ * that audio:mix measured; a second AAC encode adds its own overshoot. Anything else is encoded and padded to length.
+ */
+export function canCopySoundtrack(probe, duration) {
+  const stream = probe?.streams?.[0];
+  const length = Number(stream?.duration ?? probe?.format?.duration);
+  return stream?.codec_name === "aac" && stream.profile === "LC" && Number(stream.sample_rate) === 48000
+    && Math.abs(Number(stream.start_time ?? Number.NaN)) < 0.001 && length >= duration - 0.05;
+}

package/templates/video/scripts/review-audio.mjs

@@ -1,19 +1,19 @@
 import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import ffmpeg from "@ffmpeg-installer/ffmpeg";
-import ffprobe from "@ffprobe-installer/ffprobe";
+import { ffmpegBinaries } from "./ffmpeg-binaries.mjs";
 
 const run=promisify(execFile);
 export async function inspectAudio(root,config) {
   if(!config.audio)return {status:"silent",message:"No soundtrack configured; audio checks are not applicable."};
   const publicRoot=path.resolve(root,"public"),file=path.resolve(publicRoot,config.audio);
   if(!file.startsWith(publicRoot+path.sep))throw new Error("Soundtrack must be inside public/.");
-  const {stdout}=await run(ffprobe.path,["-v","error","-show_streams","-show_format","-of","json",file]);
+  const {ffmpeg,ffprobe}=await ffmpegBinaries();
+  const {stdout}=await run(ffprobe,["-v","error","-show_streams","-show_format","-of","json",file]);
   const probe=JSON.parse(stdout),stream=probe.streams.find((s)=>s.codec_type==="audio");
   if(!stream)throw new Error("Configured soundtrack has no audio stream.");
   // Same targets as npm run audio:mix (−14 LUFS, −2 dBTP); the measured input values do not depend on them.
-  const {stderr}=await run(ffmpeg.path,["-hide_banner","-nostats","-i",file,"-af","loudnorm=I=-14:TP=-2:LRA=9:print_format=json","-f","null","-"],{maxBuffer:1024*1024});
+  const {stderr}=await run(ffmpeg,["-hide_banner","-nostats","-i",file,"-af","loudnorm=I=-14:TP=-2:LRA=9:print_format=json","-f","null","-"],{maxBuffer:1024*1024});
   const json=stderr.match(/\{\s*"input_i"[\s\S]*?\}/)?.[0];
   if(!json)throw new Error("Audio loudness could not be measured.");
   const levels=JSON.parse(json),duration=Number(probe.format.duration);