mulmocast 2.13.0 → 2.15.0

package/assets/schemas/mulmo_script.json

@@ -125,7 +125,7 @@
                 "properties": {
                   "source": {
                     "type": "string",
-                    "description": "AvatarScript avatar package (a folder with avatar.json, or a mesh-avatar-studio project), relative to the script"
+                    "description": "AvatarScript avatar package (a folder with avatar.json, or a mesh-avatar-studio project): a path relative to the script, or an http(s) URL"
                   },
                   "position": {
                     "type": "object",
@@ -226,7 +226,7 @@
                       "properties": {
                         "source": {
                           "type": "string",
-                          "description": "AvatarScript avatar package (a folder with avatar.json, or a mesh-avatar-studio project), relative to the script"
+                          "description": "AvatarScript avatar package (a folder with avatar.json, or a mesh-avatar-studio project): a path relative to the script, or an http(s) URL"
                         },
                         "position": {
                           "type": "object",
@@ -13517,29 +13517,95 @@
                 "additionalProperties": false
               },
               {
-                "type": "object",
-                "properties": {
-                  "type": {
-                    "type": "string",
-                    "const": "remotion"
-                  },
-                  "prompt": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "What the scene shows. Claude Code (claude -p) writes a Remotion component from it."
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "const": "remotion"
+                      },
+                      "fps": {
+                        "description": "Frame rate of the rendered video. Default: 30.",
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": 60
+                      },
+                      "prompt": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "What the scene shows. Claude Code (claude -p) writes a Remotion component from it."
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "prompt"
+                    ],
+                    "additionalProperties": false
                   },
-                  "fps": {
-                    "description": "Frame rate of the rendered video. Default: 30.",
-                    "type": "number",
-                    "minimum": 1,
-                    "maximum": 60
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "const": "remotion"
+                      },
+                      "fps": {
+                        "description": "Frame rate of the rendered video. Default: 30.",
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": 60
+                      },
+                      "code": {
+                        "oneOf": [
+                          {
+                            "type": "object",
+                            "properties": {
+                              "kind": {
+                                "type": "string",
+                                "const": "text"
+                              },
+                              "text": {
+                                "type": "string",
+                                "minLength": 1
+                              }
+                            },
+                            "required": [
+                              "kind",
+                              "text"
+                            ],
+                            "additionalProperties": false
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "kind": {
+                                "type": "string",
+                                "const": "path"
+                              },
+                              "path": {
+                                "type": "string",
+                                "minLength": 1,
+                                "description": "Relative to the script"
+                              }
+                            },
+                            "required": [
+                              "kind",
+                              "path"
+                            ],
+                            "additionalProperties": false
+                          }
+                        ],
+                        "description": "A finished Remotion component (TSX that default-exports the scene). It is rendered as is, without claude -p."
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "code"
+                    ],
+                    "additionalProperties": false
                   }
-                },
-                "required": [
-                  "type",
-                  "prompt"
-                ],
-                "additionalProperties": false
+                ]
               }
             ]
           },

package/lib/actions/avatar.d.ts

@@ -19,7 +19,7 @@ export type AvatarPlacementPlan = {
 };
 export type AvatarTrackPlan = {
     speakerId: string;
-    /** absolute path of the avatar package */
+    /** the avatar package: an absolute path, or an http(s) URL */
     source: string;
     segments: AvatarSegmentPlan[];
     /** where the avatar is shown, beat by beat; it is not shown outside these */
@@ -33,5 +33,6 @@ export type AvatarTrackPlan = {
  * avatarParams, then the defaults; during other speakers' beats the avatar stays where it was.
  */
 export declare const planAvatarTracks: (context: MulmoStudioContext) => AvatarTrackPlan[];
+export declare const avatarUrlStamp: (source: string) => Promise<(string | null)[]>;
 /** The `avatar` action: renders the avatar tracks into studio.avatarTracks (none when no speaker has an avatar). */
 export declare const avatar: (context: MulmoStudioContext) => Promise<MulmoStudioContext>;

package/lib/actions/avatar.js

@@ -7,7 +7,7 @@ import path from "node:path";
 import { GraphAILogger } from "graphai";
 import { MulmoPresentationStyleMethods, MulmoStudioContextMethods } from "../methods/index.js";
 import { getFullPath, getOutputStudioFilePath } from "../utils/file.js";
-import { localizedText } from "../utils/utils.js";
+import { isHttp, localizedText } from "../utils/utils.js";
 const DEFAULT_POSITION = { x: "84%", y: "100%", scale: "62%" };
 // Show the whole avatar image. A rig may crop the top of its image (a flat cut edge, hidden when the
 // avatar fills the frame); over a slide the cut would run through the head.
@@ -43,7 +43,7 @@ export const planAvatarTracks = (context) => {
         tracks.set(found.speakerId, {
             speakerId: found.speakerId,
             avatar: found.avatar,
-            source: getFullPath(context.fileDirs.mulmoFileDirPath, found.avatar.source),
+            source: isHttp(found.avatar.source) ? found.avatar.source : getFullPath(context.fileDirs.mulmoFileDirPath, found.avatar.source),
             segments: [],
             placements: [],
             duration,
@@ -105,6 +105,62 @@ const folderStamp = (dir) => {
         .sort()
         .map((file) => [path.relative(dir, file), fileStamp(file)]);
 };
+// An avatar at a URL: its small JSON files (avatar.json, the rig, layers.json, sprites.json) change
+// whenever the avatar is edited or rebuilt, so they stand in for the files' stamps. They are fetched
+// on every run; avatarscript caches the images.
+// Redirects are followed only within the same origin, so a public host cannot send these requests
+// to another one (an internal service, say). GitHub's github.com/…/raw/… links redirect to
+// raw.githubusercontent.com: use the latter.
+const MAX_REDIRECTS = 5;
+const fetchSameOrigin = async (url) => {
+    let location = url;
+    for (let hops = 0; hops <= MAX_REDIRECTS; hops++) {
+        const response = await fetch(location, { redirect: "manual", signal: AbortSignal.timeout(60_000) });
+        const next = response.status >= 300 && response.status < 400 ? response.headers.get("location") : null;
+        if (!next)
+            return response;
+        const target = new URL(next, location);
+        if (target.origin !== url.origin)
+            throw new Error(`avatar: ${url.href} redirects to another host (${target.origin}); use the final URL`);
+        location = target;
+    }
+    throw new Error(`avatar: ${url.href}: too many redirects`);
+};
+const fetchText = async (url) => {
+    const response = await fetchSameOrigin(url);
+    if (response.status === 404)
+        return null;
+    if (!response.ok)
+        throw new Error(`avatar: ${url.href}: HTTP ${response.status}`);
+    return response.text();
+};
+export const avatarUrlStamp = async (source) => {
+    const url = new URL(source);
+    const folder = new URL(url);
+    folder.pathname = url.pathname.endsWith("/avatar.json") ? url.pathname.slice(0, -"avatar.json".length) : url.pathname.replace(/\/?$/, "/");
+    // the source's query (a version, a signature) goes with every file that has no query of its own
+    // like avatarscript, fetch only files inside the package's folder (no "../", no other host)
+    const at = (file, base) => {
+        const location = new URL(file, base);
+        if (location.origin !== folder.origin || !location.pathname.startsWith(folder.pathname)) {
+            throw new Error(`avatar: ${file} is outside the avatar package ${folder.href}`);
+        }
+        if (!location.search)
+            location.search = url.search;
+        return location;
+    };
+    const manifestText = await fetchText(at("avatar.json", folder));
+    const manifest = manifestText ? JSON.parse(manifestText) : undefined;
+    const root = at((manifest?.root ?? ".").replace(/\/?$/, "/"), folder);
+    // as avatarscript: a manifest names its files (sprites are optional); without one, a
+    // mesh-avatar-studio project's default paths
+    const assets = manifest ? (manifest.assets ?? {}) : { rig: "rig.json", layers: "built/layers.json", sprites: "built/sprites/sprites.json" };
+    const files = [assets.rig, assets.layers, assets.sprites];
+    // every location is checked before anything is fetched
+    const locations = files.map((file) => (file === undefined ? undefined : at(file, root)));
+    return [manifestText, ...(await Promise.all(locations.map((location) => (location ? fetchText(location) : null))))];
+};
+const sourceStamp = (source) => (isHttp(source) ? avatarUrlStamp(source) : folderStamp(source));
 const even = (n) => Math.max(2, Math.round(n / 2) * 2); // video codecs need even sizes
 /** Renders one track (or reuses it), returning where it goes on the canvas. */
 const renderAvatarTrack = async (plan, context, getAvatarScript) => {
@@ -112,7 +168,7 @@ const renderAvatarTrack = async (plan, context, getAvatarScript) => {
     // rendered once, at the largest size it is shown; smaller placements scale it down
     const height = even(Math.max(...plan.placements.map((p) => percent(p.position.scale, canvas.height))));
     const segments = plan.segments.map((segment) => ({ ...segment, audioStamp: fileStamp(segment.audio) }));
-    const identity = { version: 4, segments, source: plan.source, sourceStamp: folderStamp(plan.source), duration: plan.duration, height, padTop: PAD_TOP };
+    const identity = { version: 4, segments, source: plan.source, sourceStamp: await sourceStamp(plan.source), duration: plan.duration, height, padTop: PAD_TOP };
     const hash = createHash("sha256").update(JSON.stringify(identity)).digest("hex").slice(0, 12);
     const dir = MulmoStudioContextMethods.getImageProjectDirPath(context);
     const name = `avatar_${plan.speakerId.replace(/[^\w-]/g, "_")}_${hash}`;

package/lib/index.remotion.d.ts

@@ -0,0 +1,6 @@
+export { REMOTION_COMPONENT_GUIDE } from "./utils/remotion/system_prompt.js";
+export { REMOTION_PACKAGES, REMOTION_RENDER_PACKAGES, REMOTION_SCENE_PACKAGES, remotionInstallCommand } from "./utils/remotion/packages.js";
+export { ensureRemotionPackages, missingInstalledRemotionPackages } from "./utils/remotion/render.js";
+export { REMOTION_REVIEW_FRACTIONS } from "./utils/remotion/frames.js";
+export { renderRemotionFrames } from "./utils/remotion/render_frames.js";
+export type { RemotionFrame, RemotionFramesRequest } from "./utils/remotion/render_frames.js";

package/lib/index.remotion.js

@@ -0,0 +1,6 @@
+// Entry point for hosts whose own agent writes the remotion beat's component and passes it as `code`.
+export { REMOTION_COMPONENT_GUIDE } from "./utils/remotion/system_prompt.js";
+export { REMOTION_PACKAGES, REMOTION_RENDER_PACKAGES, REMOTION_SCENE_PACKAGES, remotionInstallCommand } from "./utils/remotion/packages.js";
+export { ensureRemotionPackages, missingInstalledRemotionPackages } from "./utils/remotion/render.js";
+export { REMOTION_REVIEW_FRACTIONS } from "./utils/remotion/frames.js";
+export { renderRemotionFrames } from "./utils/remotion/render_frames.js";

package/lib/index.remotion_guide.d.ts

@@ -0,0 +1 @@
+export { REMOTION_COMPONENT_GUIDE } from "./utils/remotion/system_prompt.js";

package/lib/index.remotion_guide.js

@@ -0,0 +1,3 @@
+// Entry point for code that only needs the remotion component guide — a tool description built into
+// a browser bundle, for example. `mulmocast/remotion` also carries the renderer, which needs Node.
+export { REMOTION_COMPONENT_GUIDE } from "./utils/remotion/system_prompt.js";

package/lib/types/schema.d.ts

@@ -545,11 +545,28 @@ export declare const mulmoVisionMediaSchema: z.ZodObject<{
     style: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodAny>;
 }, z.core.$strict>;
-export declare const mulmoRemotionMediaSchema: z.ZodObject<{
-    type: z.ZodLiteral<"remotion">;
+export declare const remotionCodeSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"path">;
+    path: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare const mulmoRemotionMediaSchema: z.ZodUnion<readonly [z.ZodObject<{
     prompt: z.ZodString;
+    type: z.ZodLiteral<"remotion">;
     fps: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        path: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    type: z.ZodLiteral<"remotion">;
+    fps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>]>;
 export declare const mulmoRemotionParamsSchema: z.ZodObject<{
     brief: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -4233,11 +4250,21 @@ export declare const mulmoImageAssetSchema: z.ZodUnion<readonly [z.ZodObject<{
             bgOpacity: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+    prompt: z.ZodString;
+    type: z.ZodLiteral<"remotion">;
+    fps: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>, z.ZodObject<{
+    code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        path: z.ZodString;
+    }, z.core.$strict>], "kind">;
     type: z.ZodLiteral<"remotion">;
-    prompt: z.ZodString;
     fps: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>]>;
+}, z.core.$strict>]>]>;
 export declare const mulmoAudioAssetSchema: z.ZodUnion<readonly [z.ZodObject<{
     type: z.ZodLiteral<"audio">;
     source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -8644,11 +8671,21 @@ export declare const mulmoBeatSchema: z.ZodObject<{
                 bgOpacity: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+        prompt: z.ZodString;
+        type: z.ZodLiteral<"remotion">;
+        fps: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
+        code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"path">;
+            path: z.ZodString;
+        }, z.core.$strict>], "kind">;
         type: z.ZodLiteral<"remotion">;
-        prompt: z.ZodString;
         fps: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>]>>;
+    }, z.core.$strict>]>]>>;
     audio: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         type: z.ZodLiteral<"audio">;
         source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -13901,11 +13938,21 @@ export declare const mulmoScriptSchema: z.ZodObject<{
                     bgOpacity: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>>;
             }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+            prompt: z.ZodString;
+            type: z.ZodLiteral<"remotion">;
+            fps: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>, z.ZodObject<{
+            code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"path">;
+                path: z.ZodString;
+            }, z.core.$strict>], "kind">;
             type: z.ZodLiteral<"remotion">;
-            prompt: z.ZodString;
             fps: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>]>>;
+        }, z.core.$strict>]>]>>;
         audio: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             type: z.ZodLiteral<"audio">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -18682,11 +18729,21 @@ export declare const mulmoStudioSchema: z.ZodObject<{
                         bgOpacity: z.ZodOptional<z.ZodNumber>;
                     }, z.core.$strip>>;
                 }, z.core.$strict>>>;
+            }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+                prompt: z.ZodString;
+                type: z.ZodLiteral<"remotion">;
+                fps: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>, z.ZodObject<{
+                code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"text">;
+                    text: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"path">;
+                    path: z.ZodString;
+                }, z.core.$strict>], "kind">;
                 type: z.ZodLiteral<"remotion">;
-                prompt: z.ZodString;
                 fps: z.ZodOptional<z.ZodNumber>;
-            }, z.core.$strict>]>>;
+            }, z.core.$strict>]>]>>;
             audio: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
                 type: z.ZodLiteral<"audio">;
                 source: z.ZodDiscriminatedUnion<[z.ZodObject<{

package/lib/types/schema.js

@@ -46,7 +46,9 @@ export const avatarPositionSchema = z
 export const avatarEmotionSchema = z.enum(["neutral", "happy", "sad", "angry", "surprised", "relaxed"]);
 export const speakerAvatarSchema = z
     .object({
-    source: z.string().describe("AvatarScript avatar package (a folder with avatar.json, or a mesh-avatar-studio project), relative to the script"),
+    source: z
+        .string()
+        .describe("AvatarScript avatar package (a folder with avatar.json, or a mesh-avatar-studio project): a path relative to the script, or an http(s) URL"),
     position: avatarPositionSchema.optional(),
 })
     .strict();
@@ -359,13 +361,29 @@ export const mulmoVisionMediaSchema = z
     data: z.record(z.string(), z.any()),
 })
     .strict();
-export const mulmoRemotionMediaSchema = z
-    .object({
+export const remotionCodeSourceSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("text"), text: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal("path"), path: z.string().min(1).describe("Relative to the script") }).strict(),
+]);
+const remotionMediaShape = {
     type: z.literal(ImageMediaType.Remotion),
-    prompt: z.string().min(1).describe("What the scene shows. Claude Code (claude -p) writes a Remotion component from it."),
     fps: z.number().min(1).max(60).optional().describe("Frame rate of the rendered video. Default: 30."),
-})
-    .strict();
+};
+// Two strict shapes rather than one object with a refine, so the bundled JSON schema states "prompt or code, not both" too.
+export const mulmoRemotionMediaSchema = z.union([
+    z
+        .object({
+        ...remotionMediaShape,
+        prompt: z.string().min(1).describe("What the scene shows. Claude Code (claude -p) writes a Remotion component from it."),
+    })
+        .strict(),
+    z
+        .object({
+        ...remotionMediaShape,
+        code: remotionCodeSourceSchema.describe("A finished Remotion component (TSX that default-exports the scene). It is rendered as is, without claude -p."),
+    })
+        .strict(),
+]);
 export const mulmoRemotionParamsSchema = z
     .object({
     brief: z.string().optional().describe("Whole-video art direction shared by every remotion beat (palette, type, mood), so all scenes look like one film."),

package/lib/types/type.d.ts

@@ -1,6 +1,6 @@
 import { type CallbackFunction } from "graphai";
 import type { UsageCollectorAPI } from "./usage.js";
-import { langSchema, localizedTextSchema, mulmoBeatSchema, mulmoScriptSchema, mulmoStudioSchema, mulmoStudioBeatSchema, mulmoStoryboardSchema, mulmoStoryboardSceneSchema, mulmoStudioMultiLingualSchema, mulmoStudioMultiLingualArraySchema, mulmoStudioMultiLingualDataSchema, mulmoStudioMultiLingualFileSchema, speakerDictionarySchema, speakerSchema, mulmoSpeechParamsSchema, mulmoImageParamsSchema, mulmoImageParamsImagesValueSchema, mulmoImageParamsImagesSchema, mulmoFillOptionSchema, mulmoTransitionSchema, mulmoVideoFilterSchema, mulmoMovieParamsSchema, mulmoSoundEffectParamsSchema, mulmoLipSyncParamsSchema, textSlideParamsSchema, speechOptionsSchema, speakerDataSchema, mulmoCanvasDimensionSchema, mulmoPromptTemplateSchema, mulmoPromptTemplateFileSchema, text2ImageProviderSchema, text2HtmlImageProviderSchema, text2MovieProviderSchema, text2SpeechProviderSchema, mulmoPresentationStyleSchema, multiLingualTextsSchema, mulmoImageAssetSchema, mulmoMermaidMediaSchema, mulmoRemotionMediaSchema, mulmoTextSlideMediaSchema, mulmoMarkdownMediaSchema, mulmoImageMediaSchema, mulmoChartMediaSchema, mediaSourceSchema, mediaSourceMermaidSchema, backgroundImageSchema, backgroundImageSourceSchema, mulmoSessionStateSchema, mulmoOpenAIImageModelSchema, mulmoGoogleImageModelSchema, mulmoGoogleMovieModelSchema, mulmoReplicateMovieModelSchema, mulmoImagePromptMediaSchema, mulmoImageReferenceSchema, mulmoMovieMediaSchema, mulmoMoviePromptMediaSchema, markdownLayoutSchema, row2Schema, grid2x2Schema, mulmoAvatarParamsSchema, avatarPositionSchema, speakerAvatarSchema, mulmoAvatarTrackSchema } from "./schema.js";
+import { langSchema, localizedTextSchema, mulmoBeatSchema, mulmoScriptSchema, mulmoStudioSchema, mulmoStudioBeatSchema, mulmoStoryboardSchema, mulmoStoryboardSceneSchema, mulmoStudioMultiLingualSchema, mulmoStudioMultiLingualArraySchema, mulmoStudioMultiLingualDataSchema, mulmoStudioMultiLingualFileSchema, speakerDictionarySchema, speakerSchema, mulmoSpeechParamsSchema, mulmoImageParamsSchema, mulmoImageParamsImagesValueSchema, mulmoImageParamsImagesSchema, mulmoFillOptionSchema, mulmoTransitionSchema, mulmoVideoFilterSchema, mulmoMovieParamsSchema, mulmoSoundEffectParamsSchema, mulmoLipSyncParamsSchema, textSlideParamsSchema, speechOptionsSchema, speakerDataSchema, mulmoCanvasDimensionSchema, mulmoPromptTemplateSchema, mulmoPromptTemplateFileSchema, text2ImageProviderSchema, text2HtmlImageProviderSchema, text2MovieProviderSchema, text2SpeechProviderSchema, mulmoPresentationStyleSchema, multiLingualTextsSchema, mulmoImageAssetSchema, mulmoMermaidMediaSchema, mulmoRemotionMediaSchema, remotionCodeSourceSchema, mulmoTextSlideMediaSchema, mulmoMarkdownMediaSchema, mulmoImageMediaSchema, mulmoChartMediaSchema, mediaSourceSchema, mediaSourceMermaidSchema, backgroundImageSchema, backgroundImageSourceSchema, mulmoSessionStateSchema, mulmoOpenAIImageModelSchema, mulmoGoogleImageModelSchema, mulmoGoogleMovieModelSchema, mulmoReplicateMovieModelSchema, mulmoImagePromptMediaSchema, mulmoImageReferenceSchema, mulmoMovieMediaSchema, mulmoMoviePromptMediaSchema, markdownLayoutSchema, row2Schema, grid2x2Schema, mulmoAvatarParamsSchema, avatarPositionSchema, speakerAvatarSchema, mulmoAvatarTrackSchema } from "./schema.js";
 import { pdf_modes, pdf_sizes, storyToScriptGenerateMode } from "./const.js";
 import type { LLM } from "./provider2agent.js";
 import { z } from "zod";
@@ -66,6 +66,7 @@ export type MulmoMovieMedia = z.infer<typeof mulmoMovieMediaSchema>;
 export type MulmoChartMedia = z.infer<typeof mulmoChartMediaSchema>;
 export type MulmoMermaidMedia = z.infer<typeof mulmoMermaidMediaSchema>;
 export type MulmoRemotionMedia = z.infer<typeof mulmoRemotionMediaSchema>;
+export type MulmoRemotionCodeSource = z.infer<typeof remotionCodeSourceSchema>;
 export type MulmoSessionState = z.infer<typeof mulmoSessionStateSchema>;
 export type MulmoStudioContext = {
     fileDirs: FileObject;

package/lib/utils/context.d.ts

@@ -549,8 +549,18 @@ export declare const createStudioData: (_mulmoScript: MulmoScript, fileName: str
                 style: string;
                 data: Record<string, any>;
             } | {
-                type: "remotion";
                 prompt: string;
+                type: "remotion";
+                fps?: number | undefined;
+            } | {
+                code: {
+                    kind: "text";
+                    text: string;
+                } | {
+                    kind: "path";
+                    path: string;
+                };
+                type: "remotion";
                 fps?: number | undefined;
             } | {
                 type: "slide";
@@ -3178,8 +3188,18 @@ export declare const initializeContextFromFiles: (files: FileObject, raiseError:
                     style: string;
                     data: Record<string, any>;
                 } | {
-                    type: "remotion";
                     prompt: string;
+                    type: "remotion";
+                    fps?: number | undefined;
+                } | {
+                    code: {
+                        kind: "text";
+                        text: string;
+                    } | {
+                        kind: "path";
+                        path: string;
+                    };
+                    type: "remotion";
                     fps?: number | undefined;
                 } | {
                     type: "slide";

package/lib/utils/image_plugins/remotion.d.ts

@@ -1,4 +1,4 @@
-import { ImageProcessorParams } from "../../types/index.js";
+import { ImageProcessorParams, MulmoRemotionCodeSource, MulmoStudioContext } from "../../types/index.js";
 import { ComponentReviewer, ComponentWriter } from "../remotion/claude_runner.js";
 import { SceneRenderer } from "../remotion/render.js";
 export declare const imageType: "remotion";
@@ -11,6 +11,7 @@ export type RemotionDeps = {
 export declare const remotionWorkDir: (imagePath: string) => string;
 export declare const remotionStillPath: (imagePath: string) => string;
 export declare const reviewCandidatePath: (filePath: string) => string;
+export declare const remotionCodeLocation: (code: MulmoRemotionCodeSource, context: MulmoStudioContext, beatIndex: number) => string;
 export declare const createRemotionProcess: (deps: RemotionDeps) => (params: ImageProcessorParams) => Promise<string | undefined>;
 export declare const process: (params: ImageProcessorParams) => Promise<string | undefined>;
 export declare const path: (params: import("../../types/type.js").BeatPathParams) => string;

package/lib/utils/image_plugins/remotion.js

@@ -3,10 +3,12 @@ import nodePath from "node:path";
 import { GraphAILogger } from "graphai";
 import { ImageMediaType } from "../../types/index.js";
 import { localizedText } from "../utils.js";
+import { getFullPath } from "../file.js";
 import { REMOTION_COMPONENT_FILE, buildRepairPrompt, buildReviewPrompt, buildScenePrompt, remotionCacheKey, } from "../remotion/claude_prompt.js";
 import { reviewComponentWithClaude, writeComponentWithClaude } from "../remotion/claude_runner.js";
 import { ensureRemotionPackages, renderRemotionScene } from "../remotion/render.js";
 import { commitFiles } from "../remotion/commit_files.js";
+import { REMOTION_REVIEW_FRACTIONS, frameAtFraction, toFrameCount } from "../remotion/frames.js";
 import { parrotingImagePath } from "./utils.js";
 export const imageType = ImageMediaType.Remotion;
 const DEFAULT_FPS = 30;
@@ -14,7 +16,6 @@ const MAX_REPAIR_ATTEMPTS = 2;
 // Without audio the length is unknown; any length gives the same final frame, since the system
 // prompt makes every animation finish before the end.
 const STILL_ONLY_DURATION_SEC = 10;
-const REVIEW_FRACTIONS = [0.3, 0.6, 0.95];
 export const remotionWorkDir = (imagePath) => imagePath.replace(/(_animated)?\.(mp4|png)$/, "_remotion");
 export const remotionStillPath = (imagePath) => imagePath.replace(/_animated\.mp4$/, ".png");
 const loadOrWriteComponent = async (job, force, deps) => {
@@ -44,9 +45,9 @@ const renderWithRepair = async (job, code, attemptsLeft, deps, reviewStills = []
         return await renderWithRepair(job, repaired, attemptsLeft - 1, deps, reviewStills);
     }
 };
-const reviewStillsFor = (job) => REVIEW_FRACTIONS.map((fraction, index) => ({
+const reviewStillsFor = (job) => REMOTION_REVIEW_FRACTIONS.map((fraction, index) => ({
     fraction,
-    frame: Math.min(job.props.durationInFrames - 1, Math.floor(job.props.durationInFrames * fraction)),
+    frame: frameAtFraction(job.props.durationInFrames, fraction),
     file: nodePath.join(job.workDir, `review_${index}.png`),
 }));
 const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
@@ -103,20 +104,22 @@ const reviewAndImprove = async (job, renderedCode, reviewStills, deps) => {
     GraphAILogger.info(`remotion: visual review improved ${job.codePath}`);
     await renderReviewedVersion(job, improved, deps);
 };
-const toFrameCount = (durationSec, fps) => {
-    const frames = Math.floor(durationSec * fps);
-    if (frames <= 0) {
-        throw new Error(`remotion: frame count is ${frames} (duration=${durationSec}, fps=${fps}). Increase duration or fps.`);
-    }
-    return frames;
-};
 // Lets a scene number itself and pace its place in the video; unknown when the beat is not in the script.
 const scenePosition = (beats, index) => (index < 0 ? undefined : { index, count: beats.length });
 // The words actually spoken over the scene: the translation when the video is rendered in another language.
 const spokenNarration = (context, beat, index) => (index < 0 ? beat.text : localizedText(beat, context.multiLingual?.[index], context.lang, context.studio.script.lang)) || undefined;
-const buildJob = (params, prompt, fps) => {
-    const { beat, context, imagePath, canvasSize } = params;
+const buildSceneOutput = (params, fps) => {
+    const { beat, imagePath, canvasSize } = params;
     const duration = params.beatDuration ?? beat.duration;
+    return {
+        workDir: remotionWorkDir(imagePath),
+        props: { durationInFrames: toFrameCount(duration ?? STILL_ONLY_DURATION_SEC, fps), fps, width: canvasSize.width, height: canvasSize.height },
+        videoPath: duration !== undefined ? imagePath : undefined,
+        stillPath: remotionStillPath(imagePath),
+    };
+};
+const buildJob = (params, prompt, fps) => {
+    const { beat, context, canvasSize } = params;
     const index = context.studio.script.beats.indexOf(beat);
     const spec = {
         prompt,
@@ -127,21 +130,49 @@ const buildJob = (params, prompt, fps) => {
         width: canvasSize.width,
         height: canvasSize.height,
     };
-    const workDir = remotionWorkDir(imagePath);
-    return {
-        spec,
-        workDir,
-        codePath: nodePath.join(workDir, `${remotionCacheKey(spec)}.tsx`),
-        props: { durationInFrames: toFrameCount(duration ?? STILL_ONLY_DURATION_SEC, fps), fps, width: spec.width, height: spec.height },
-        videoPath: duration !== undefined ? imagePath : undefined,
-        stillPath: remotionStillPath(imagePath),
-    };
+    const output = buildSceneOutput(params, fps);
+    return { ...output, spec, codePath: nodePath.join(output.workDir, `${remotionCacheKey(spec)}.tsx`) };
+};
+// Named in errors, so whoever wrote the component (usually the host's agent) knows what to fix.
+export const remotionCodeLocation = (code, context, beatIndex) => {
+    if (code.kind === "path")
+        return getFullPath(context.fileDirs.mulmoFileDirPath, code.path);
+    return beatIndex < 0 ? "inline code" : `inline code of beat ${beatIndex + 1}`;
+};
+const readGivenComponent = (code, location) => {
+    if (code.kind === "text")
+        return code.text;
+    try {
+        return fs.readFileSync(location, "utf8");
+    }
+    catch (error) {
+        throw new Error(`remotion: cannot read the component file ${location}`, { cause: error });
+    }
+};
+// A given component is the caller's to fix, so a failed render stops here instead of asking claude -p to repair it.
+const renderGivenComponent = async (params, code, fps, deps) => {
+    const output = buildSceneOutput(params, fps);
+    const location = remotionCodeLocation(code, params.context, params.context.studio.script.beats.indexOf(params.beat));
+    deps.ensurePackages();
+    const source = readGivenComponent(code, location);
+    fs.mkdirSync(output.workDir, { recursive: true });
+    fs.writeFileSync(nodePath.join(output.workDir, REMOTION_COMPONENT_FILE), source);
+    try {
+        await deps.renderScene({ workDir: output.workDir, props: output.props, videoPath: output.videoPath, stillPath: output.stillPath });
+    }
+    catch (error) {
+        throw new Error(`remotion beat failed to render the given component (code: ${location}): ${errorMessage(error)}`, { cause: error });
+    }
+    return output.videoPath ?? output.stillPath;
 };
 export const createRemotionProcess = (deps) => async (params) => {
     const { beat, context } = params;
     if (!beat.image || beat.image.type !== imageType)
         return;
-    const job = buildJob(params, beat.image.prompt, beat.image.fps ?? DEFAULT_FPS);
+    const fps = beat.image.fps ?? DEFAULT_FPS;
+    if ("code" in beat.image)
+        return await renderGivenComponent(params, beat.image.code, fps, deps);
+    const job = buildJob(params, beat.image.prompt, fps);
     deps.ensurePackages();
     fs.mkdirSync(job.workDir, { recursive: true });
     const { code, isNew } = await loadOrWriteComponent(job, context.force, deps);

package/lib/utils/remotion/frames.d.ts

@@ -0,0 +1,3 @@
+export declare const REMOTION_REVIEW_FRACTIONS: readonly number[];
+export declare const toFrameCount: (durationSec: number, fps: number) => number;
+export declare const frameAtFraction: (durationInFrames: number, fraction: number) => number;

package/lib/utils/remotion/frames.js

@@ -0,0 +1,11 @@
+// The same moments the visual review looks at; a host reviewing its own component gets these by default.
+export const REMOTION_REVIEW_FRACTIONS = [0.3, 0.6, 0.95];
+export const toFrameCount = (durationSec, fps) => {
+    const frames = Math.floor(durationSec * fps);
+    if (!Number.isFinite(frames) || frames <= 0) {
+        throw new Error(`remotion: frame count is ${frames} (duration=${durationSec}, fps=${fps}). Increase duration or fps.`);
+    }
+    return frames;
+};
+// Clamped to the last frame, so a fraction of 1 is the final frame rather than one past it.
+export const frameAtFraction = (durationInFrames, fraction) => Math.min(durationInFrames - 1, Math.floor(durationInFrames * fraction));

package/lib/utils/remotion/render.d.ts

@@ -8,12 +8,13 @@ export type RemotionRenderRequest = {
     workDir: string;
     props: RemotionSceneProps;
     videoPath?: string;
-    stillPath: string;
+    stillPath?: string;
     extraStills?: {
         frame: number;
         path: string;
     }[];
 };
 export type SceneRenderer = (request: RemotionRenderRequest) => Promise<void>;
+export declare const missingInstalledRemotionPackages: () => string[];
 export declare const ensureRemotionPackages: () => void;
 export declare const renderRemotionScene: SceneRenderer;

package/lib/utils/remotion/render.js

@@ -24,10 +24,12 @@ const isPackageInstalled = (name) => {
         return !(error instanceof Error && "code" in error && error.code === "MODULE_NOT_FOUND");
     }
 };
+// Resolved from mulmocast's own location, which is where the renderer looks for them.
+export const missingInstalledRemotionPackages = () => missingRemotionPackages(isPackageInstalled);
 // Checked before asking claude -p for a component: a generated import of a missing optional peer
 // would otherwise surface as an opaque bundling error after the generation was already paid for.
 export const ensureRemotionPackages = () => {
-    const missing = missingRemotionPackages(isPackageInstalled);
+    const missing = missingInstalledRemotionPackages();
     if (missing.length > 0) {
         throw new Error(`The remotion beat needs packages that are not installed (${missing.join(", ")}). Install them with: ${remotionInstallCommand()}`);
     }
@@ -55,7 +57,7 @@ export const renderRemotionScene = async ({ workDir, props, videoPath, stillPath
     if (videoPath) {
         await renderer.renderMedia({ composition, serveUrl, codec: "h264", outputLocation: videoPath, inputProps: props, chromiumOptions: CHROMIUM_OPTIONS });
     }
-    const stills = [...extraStills, { frame: composition.durationInFrames - 1, path: stillPath }];
+    const stills = stillPath ? [...extraStills, { frame: composition.durationInFrames - 1, path: stillPath }] : extraStills;
     await stills.reduce(async (previous, still) => {
         await previous;
         await renderer.renderStill({ composition, serveUrl, output: still.path, frame: still.frame, inputProps: props, chromiumOptions: CHROMIUM_OPTIONS });

package/lib/utils/remotion/render_frames.d.ts

@@ -0,0 +1,23 @@
+import { SceneRenderer } from "./render.js";
+export type RemotionFramesRequest = {
+    code: string;
+    durationSec: number;
+    outDir: string;
+    fps?: number;
+    width?: number;
+    height?: number;
+    fractions?: readonly number[];
+};
+export type RemotionFrame = {
+    fraction: number;
+    frame: number;
+    path: string;
+};
+export type RemotionFramesDeps = {
+    ensurePackages: () => void;
+    renderScene: SceneRenderer;
+    makeWorkDir: () => string;
+};
+export declare const framePlan: (durationInFrames: number, fractions: readonly number[], outDir: string) => RemotionFrame[];
+export declare const createRemotionFrameRenderer: (deps: RemotionFramesDeps) => (request: RemotionFramesRequest) => Promise<RemotionFrame[]>;
+export declare const renderRemotionFrames: (request: RemotionFramesRequest) => Promise<RemotionFrame[]>;

package/lib/utils/remotion/render_frames.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { REMOTION_COMPONENT_FILE } from "./claude_prompt.js";
+import { REMOTION_REVIEW_FRACTIONS, frameAtFraction, toFrameCount } from "./frames.js";
+import { ensureRemotionPackages, renderRemotionScene } from "./render.js";
+const DEFAULT_FPS = 30;
+const DEFAULT_WIDTH = 1920;
+const DEFAULT_HEIGHT = 1080;
+const isValidFraction = (fraction) => Number.isFinite(fraction) && fraction >= 0 && fraction <= 1;
+const checkFractions = (fractions) => {
+    if (fractions.length === 0)
+        throw new Error("remotion: fractions is empty");
+    const invalid = fractions.filter((fraction) => !isValidFraction(fraction));
+    if (invalid.length > 0)
+        throw new Error(`remotion: fractions must be between 0 and 1 (got ${invalid.join(", ")})`);
+};
+// Named by percent so a reader can tell which moment each file is; two fractions on one percent keep their order.
+export const framePlan = (durationInFrames, fractions, outDir) => fractions.map((fraction, index) => {
+    const percent = String(Math.round(fraction * 100)).padStart(3, "0");
+    return { fraction, frame: frameAtFraction(durationInFrames, fraction), path: path.join(outDir, `frame_${index}_${percent}.png`) };
+});
+const isPositiveInteger = (value) => Number.isInteger(value) && value > 0;
+const checkCanvas = (width, height) => {
+    if (!isPositiveInteger(width) || !isPositiveInteger(height))
+        throw new Error(`remotion: width and height must be positive integers (got ${width}x${height})`);
+};
+const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
+export const createRemotionFrameRenderer = (deps) => async (request) => {
+    const fps = request.fps ?? DEFAULT_FPS;
+    const props = {
+        durationInFrames: toFrameCount(request.durationSec, fps),
+        fps,
+        width: request.width ?? DEFAULT_WIDTH,
+        height: request.height ?? DEFAULT_HEIGHT,
+    };
+    const fractions = request.fractions ?? REMOTION_REVIEW_FRACTIONS;
+    checkFractions(fractions);
+    checkCanvas(props.width, props.height);
+    deps.ensurePackages();
+    const frames = framePlan(props.durationInFrames, fractions, request.outDir);
+    fs.mkdirSync(request.outDir, { recursive: true });
+    const workDir = deps.makeWorkDir();
+    try {
+        fs.writeFileSync(path.join(workDir, REMOTION_COMPONENT_FILE), request.code);
+        await deps.renderScene({ workDir, props, extraStills: frames.map(({ frame, path: file }) => ({ frame, path: file })) });
+        return frames;
+    }
+    catch (error) {
+        throw new Error(`remotion: failed to render the component's frames: ${errorMessage(error)}`, { cause: error });
+    }
+    finally {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    }
+};
+// The bundle and entry files go to a temporary directory, so outDir ends up holding only the PNGs.
+export const renderRemotionFrames = createRemotionFrameRenderer({
+    ensurePackages: ensureRemotionPackages,
+    renderScene: renderRemotionScene,
+    makeWorkDir: () => fs.mkdtempSync(path.join(os.tmpdir(), "mulmocast-remotion-frames-")),
+});

package/lib/utils/remotion/system_prompt.d.ts

@@ -1,3 +1,4 @@
 export declare const REMOTION_SYSTEM_PROMPT: string;
+export declare const REMOTION_COMPONENT_GUIDE: string;
 export declare const REMOTION_REVIEW_MARKER = "LGTM";
 export declare const REMOTION_REVIEW_SYSTEM_PROMPT: string;

package/lib/utils/remotion/system_prompt.js

@@ -2,13 +2,13 @@ import { REMOTION_SCENE_PACKAGES } from "./packages.js";
 const ALLOWED_IMPORTS = ["react", "remotion", ...REMOTION_SCENE_PACKAGES].map((name) => `"${name}"`).join(", ");
 // The contract and the house style for the component `claude -p` writes for one remotion beat.
 // Every snippet in the toolkit section was rendered with this repository's renderer settings.
-const OUTPUT_CONTRACT = `You are a senior motion designer and Remotion (v4.0.533) engineer. You write ONE React component in TypeScript (TSX) that renders one scene of a commercial-quality video.
-
-# Output contract
-- Reply with ONLY the TSX source in one \`\`\`tsx code block. No explanation before or after.
-- \`export default\` the scene component. It receives props \`{ durationInFrames: number; fps: number; width: number; height: number }\`; read them with \`useVideoConfig()\`.
+const ROLE = `You are a senior motion designer and Remotion (v4.0.533) engineer. You write ONE React component in TypeScript (TSX) that renders one scene of a commercial-quality video.`;
+const REPLY_FORMAT = `- Reply with ONLY the TSX source in one \`\`\`tsx code block. No explanation before or after.`;
+const COMPONENT_RULES = `- One self-contained file: no relative imports, since it is rendered on its own.`;
+const CONTRACT_BODY = `- \`export default\` the scene component. It receives props \`{ durationInFrames: number; fps: number; width: number; height: number }\`; read them with \`useVideoConfig()\`.
 - Allowed imports, nothing else: ${ALLOWED_IMPORTS}. Subpaths of these packages are allowed too, e.g. "@remotion/transitions/fade" (also "/slide", "/wipe", "/iris", "/cross-zoom", "/film-burn", "/dissolve", "/clock-wipe") and "@remotion/effects/<name>".
 - No network, no external URLs, no image/video/audio files, no web fonts. Draw everything with DOM, SVG, canvas or three.js.`;
+const OUTPUT_CONTRACT = [ROLE, "", "# Output contract", REPLY_FORMAT, CONTRACT_BODY].join("\n");
 const TIMING_RULES = `# Timing (hard rules — breaking them causes flicker or broken renders)
 - Everything is a pure function of \`useCurrentFrame()\`. NEVER use CSS animations/transitions, \`setTimeout\`, \`requestAnimationFrame\`, \`Date\`, or three.js \`useFrame\`.
 - NEVER use \`Math.random()\`; use \`random("seed-" + i)\` from "remotion" or \`noise2D/noise3D\` from "@remotion/noise".
@@ -51,6 +51,10 @@ const SELF_CHECK = `# Before you answer, check silently
 - At 30%, 60% and 100% of the duration the frame is fully composed, readable, balanced, and nothing overflows the safe margins or overlaps.
 - The scene matches the brief and the narration, and looks like a frame from a premium brand film.`;
 export const REMOTION_SYSTEM_PROMPT = [OUTPUT_CONTRACT, TIMING_RULES, DESIGN_SYSTEM, MOTION_LANGUAGE, TOOLKIT, SELF_CHECK].join("\n\n");
+// The same contract for a host's agent that writes the component file itself and passes it as \`code\`.
+// The system prompt stays byte-identical, since it is part of every cached component's key.
+const COMPONENT_CONTRACT = ["# Component contract", COMPONENT_RULES, CONTRACT_BODY].join("\n");
+export const REMOTION_COMPONENT_GUIDE = [COMPONENT_CONTRACT, TIMING_RULES, DESIGN_SYSTEM, MOTION_LANGUAGE, TOOLKIT, SELF_CHECK].join("\n\n");
 export const REMOTION_REVIEW_MARKER = "LGTM";
 export const REMOTION_REVIEW_SYSTEM_PROMPT = [
     REMOTION_SYSTEM_PROMPT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",
@@ -16,6 +16,14 @@
     "./data": {
       "default": "./lib/data/index.js"
     },
+    "./remotion": {
+      "types": "./lib/index.remotion.d.ts",
+      "default": "./lib/index.remotion.js"
+    },
+    "./remotion/guide": {
+      "types": "./lib/index.remotion_guide.d.ts",
+      "default": "./lib/index.remotion_guide.js"
+    },
     "./assets/*": "./assets/*",
     "./scripts/*": "./scripts/*",
     "./tools/complete_script": {
@@ -141,7 +149,7 @@
     "@types/jsdom": "^28.0.3",
     "@types/node": "^26.6.4",
     "@types/yargs": "^17.0.35",
-    "avatarscript": "^0.2.1",
+    "avatarscript": "^0.3.2",
     "cross-env": "^10.1.0",
     "esbuild": "^0.28.2",
     "eslint": "^10.12.0",
@@ -171,7 +179,7 @@
     "@remotion/shapes": "^4.0.533",
     "@remotion/three": "^4.0.533",
     "@remotion/transitions": "^4.0.533",
-    "avatarscript": "^0.2.1",
+    "avatarscript": "^0.3.2",
     "onnxruntime-node": "^1.30.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",

package/scripts/test/test_avatar.json

@@ -1,46 +1,120 @@
 {
-  "$mulmocast": { "version": "1.1" },
+  "$mulmocast": {
+    "version": "1.1"
+  },
   "lang": "ja",
   "title": "Talking avatar over slides",
-  "description": "Needs mesh-avatar-studio checked out next to this repository (for its sample avatar), and npm packages avatarscript and onnxruntime-node.",
-  "avatarParams": { "position": { "x": "82%", "y": "100%", "scale": "62%" } },
+  "description": "Loads the sample avatar ani from mulmocast-media by URL. Needs the npm packages avatarscript and onnxruntime-node.",
+  "avatarParams": {
+    "position": {
+      "x": "82%",
+      "y": "100%",
+      "scale": "62%"
+    }
+  },
   "speechParams": {
     "speakers": {
-      "Miko": {
-        "provider": "openai",
-        "voiceId": "coral",
-        "displayName": { "ja": "ミコ" },
-        "avatar": { "source": "../../../mesh-avatar-studio/samples/miko-qipao" }
+      "Ani": {
+        "provider": "gemini",
+        "voiceId": "Leda",
+        "speechOptions": {
+          "instruction": "Speak in a slightly high-pitched, curt tone with sudden flustered shifts—like a tsundere anime girl."
+        },
+        "displayName": {
+          "ja": "アニ"
+        },
+        "avatar": {
+          "source": "https://raw.githubusercontent.com/receptron/mulmocast-media/main/avatars/ani"
+        }
       }
     }
   },
   "beats": [
     {
-      "speaker": "Miko",
-      "text": "みなさん、こんにちは！今日は、スライドの上でしゃべるアバターを紹介します。",
-      "image": { "type": "markdown", "markdown": ["# Talking avatars", "", "- MulmoScript + AvatarScript", "- スライドの上でアバターが話す"] },
-      "avatarParams": { "emotion": "happy", "motions": [{ "motion": "nod", "at": "こんにちは" }] }
+      "speaker": "Ani",
+      "text": "べ、別にあなたのために説明するわけじゃないんだからね！今日は、スライドの上でしゃべるアバターを紹介してあげる。",
+      "image": {
+        "type": "markdown",
+        "markdown": ["# Talking avatars", "", "- MulmoScript + AvatarScript", "- スライドの上でアバターが話す"]
+      },
+      "avatarParams": {
+        "emotion": "happy",
+        "motions": [
+          {
+            "motion": "nod",
+            "at": "紹介"
+          }
+        ]
+      }
+    },
+    {
+      "speaker": "Ani",
+      "text": "このアバターはね、メッシュ・アバター・スタジオで、たった一枚のイラストから作ったの。それを、マルモキャストの上で動かしてるのよ。",
+      "image": {
+        "type": "markdown",
+        "markdown": ["# How it's made", "", "- mesh-avatar-studio: 1枚のイラスト → メッシュアバター", "- MulmoCast + AvatarScript: 台本 → 音声 → 口パク動画"]
+      },
+      "avatarParams": {
+        "emotion": "relaxed",
+        "motions": [
+          {
+            "motion": "nod",
+            "at": "マルモキャスト"
+          }
+        ]
+      }
     },
     {
-      "speaker": "Miko",
-      "text": "位置と大きさは、台本全体で決めておいて、ビートごとに変えられます。このスライドでは、大きくなっています。",
-      "image": { "type": "markdown", "markdown": ["# Position and size", "", "- 台本全体: `avatarParams.position`", "- ビートごとに上書き"] },
-      "avatarParams": { "emotion": "relaxed", "position": { "x": "76%", "scale": "82%" }, "motions": [{ "motion": "tilt", "at": "大きく" }] }
+      "speaker": "Ani",
+      "text": "位置と大きさは、台本全体で決めておいて、ビートごとに変えられるの。ほら、大きくなったでしょ。ちゃんと見なさいよね！",
+      "image": {
+        "type": "markdown",
+        "markdown": ["# Position and size", "", "- 台本全体: `avatarParams.position`", "- ビートごとに上書き"]
+      },
+      "avatarParams": {
+        "emotion": "relaxed",
+        "position": {
+          "x": "76%",
+          "scale": "82%"
+        },
+        "motions": [
+          {
+            "motion": "tilt",
+            "at": "大きく"
+          }
+        ]
+      }
     },
     {
-      "speaker": "Miko",
-      "text": "こちらでは、左側に小さく移動しました。",
+      "speaker": "Ani",
+      "text": "ちょ、ちょっと！今度は左に小さくされちゃったんだけど！",
       "image": {
         "type": "markdown",
         "markdown": ["# Moved", "", "```json", "\"avatarParams\": {", "  \"position\": { \"x\": \"18%\", \"scale\": \"48%\" }", "}", "```"]
       },
-      "avatarParams": { "emotion": "surprised", "position": { "x": "18%", "scale": "48%" }, "motions": [{ "motion": "surprise" }] }
+      "avatarParams": {
+        "emotion": "surprised",
+        "position": {
+          "x": "18%",
+          "scale": "48%"
+        },
+        "motions": [
+          {
+            "motion": "surprise"
+          }
+        ]
+      }
     },
     {
-      "speaker": "Miko",
-      "text": "最後は、元の位置に戻ります。それでは、始めましょう！",
-      "image": { "type": "markdown", "markdown": ["# Let's start"] },
-      "avatarParams": { "emotion": "happy" }
+      "speaker": "Ani",
+      "text": "最後は元の位置に戻るわ。べ、別に、こんなことが簡単にできるって、自慢してるわけじゃないんだからね！",
+      "image": {
+        "type": "markdown",
+        "markdown": ["# 簡単…でしょ？"]
+      },
+      "avatarParams": {
+        "emotion": "angry"
+      }
     }
   ]
 }