mulmocast 2.4.8 → 2.4.9

package/assets/html/tailwind_animated.html

@@ -254,6 +254,40 @@
         result.catch(console.error);
       }
     }
+
+    /**
+     * Play animation in real-time using requestAnimationFrame.
+     * Returns a Promise that resolves when all frames have been rendered.
+     * Called by Puppeteer's page.evaluate() during screencast recording.
+     */
+    window.playAnimation = function() {
+      return new Promise(function(resolve) {
+        var mulmo = window.__MULMO;
+        var fps = mulmo.fps;
+        var totalFrames = mulmo.totalFrames;
+        var frameDuration = 1000 / fps;
+        var startTime = null;
+
+        function tick(timestamp) {
+          if (startTime === null) startTime = timestamp;
+          var elapsed = timestamp - startTime;
+          var frame = Math.min(Math.floor(elapsed / frameDuration), totalFrames - 1);
+
+          mulmo.frame = frame;
+          if (typeof render === 'function') {
+            render(frame, totalFrames, fps);
+          }
+
+          if (frame < totalFrames - 1) {
+            requestAnimationFrame(tick);
+          } else {
+            resolve();
+          }
+        }
+
+        requestAnimationFrame(tick);
+      });
+    };
   </script>
 </body>
 </html>

package/lib/methods/mulmo_beat.d.ts

@@ -1,11 +1,13 @@
 import { MulmoBeat } from "../types/index.js";
 type AnimationConfig = {
     fps?: number;
+    movie?: boolean;
 };
 export declare const MulmoBeatMethods: {
     isAnimationEnabled: (animation: unknown) => animation is true | AnimationConfig;
     isAnimationObject: (animation: unknown) => animation is AnimationConfig;
     isAnimatedHtmlTailwind: (beat: MulmoBeat) => boolean;
+    isMovieMode: (animation: unknown) => boolean;
     getHtmlPrompt(beat: MulmoBeat): string | undefined;
     getPlugin(beat: MulmoBeat): {
         imageType: string;

package/lib/methods/mulmo_beat.js

@@ -7,6 +7,10 @@ const isAnimationObject = (animation) => {
 const isAnimationEnabled = (animation) => {
     return animation === true || isAnimationObject(animation);
 };
+/** Check if movie mode (CDP screencast) is enabled */
+const isMovieMode = (animation) => {
+    return isAnimationObject(animation) && animation.movie === true;
+};
 /** Check if a beat has html_tailwind animation enabled */
 const isAnimatedHtmlTailwind = (beat) => {
     if (!beat.image || beat.image.type !== "html_tailwind")
@@ -18,6 +22,7 @@ export const MulmoBeatMethods = {
     isAnimationEnabled,
     isAnimationObject,
     isAnimatedHtmlTailwind,
+    isMovieMode,
     getHtmlPrompt(beat) {
         if (beat?.htmlPrompt?.data) {
             return beat.htmlPrompt.prompt + "\n\n[data]\n" + JSON.stringify(beat.htmlPrompt.data, null, 2);

package/lib/types/schema.d.ts

@@ -374,6 +374,7 @@ export declare const mulmoMermaidMediaSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const htmlTailwindAnimationSchema: z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
     fps: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    movie: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>]>;
 export declare const mulmoHtmlTailwindMediaSchema: z.ZodObject<{
     type: z.ZodLiteral<"html_tailwind">;
@@ -381,6 +382,7 @@ export declare const mulmoHtmlTailwindMediaSchema: z.ZodObject<{
     script: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     animation: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
         fps: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        movie: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>]>>;
 }, z.core.$strict>;
 export declare const mulmoBeatReferenceMediaSchema: z.ZodObject<{
@@ -553,6 +555,7 @@ export declare const mulmoImageAssetSchema: z.ZodUnion<readonly [z.ZodObject<{
     script: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     animation: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
         fps: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        movie: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>]>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"beat">;
@@ -3606,6 +3609,7 @@ export declare const mulmoBeatSchema: z.ZodObject<{
         script: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
         animation: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
             fps: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+            movie: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>]>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"beat">;
@@ -7404,6 +7408,7 @@ export declare const mulmoScriptSchema: z.ZodObject<{
             script: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
             animation: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
                 fps: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+                movie: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>]>>;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"beat">;
@@ -10821,6 +10826,7 @@ export declare const mulmoStudioSchema: z.ZodObject<{
                 script: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
                 animation: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
                     fps: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+                    movie: z.ZodOptional<z.ZodBoolean>;
                 }, z.core.$strip>]>>;
             }, z.core.$strict>, z.ZodObject<{
                 type: z.ZodLiteral<"beat">;

package/lib/types/schema.js

@@ -198,6 +198,7 @@ export const htmlTailwindAnimationSchema = z.union([
     z.literal(true),
     z.object({
         fps: z.number().min(1).max(60).optional().default(30),
+        movie: z.boolean().optional().describe("Use CDP screencast for real-time recording (experimental, faster). Default: false (frame-by-frame screenshot)."),
     }),
 ]);
 export const mulmoHtmlTailwindMediaSchema = z

package/lib/utils/browser_pool.d.ts

@@ -0,0 +1,5 @@
+import puppeteer from "puppeteer";
+/** Get a shared browser instance. Launches one if none exists. */
+export declare const getBrowser: () => Promise<puppeteer.Browser>;
+/** Close the shared browser instance. Call at the end of processing. */
+export declare const closeBrowser: () => Promise<void>;

package/lib/utils/browser_pool.js

@@ -0,0 +1,39 @@
+import puppeteer from "puppeteer";
+const isCI = process.env.CI === "true";
+const launchArgs = isCI ? ["--no-sandbox", "--allow-file-access-from-files"] : ["--allow-file-access-from-files"];
+let browserInstance = null;
+let launchPromise = null;
+const launchBrowser = async () => {
+    const browser = await puppeteer.launch({ args: launchArgs });
+    browser.on("disconnected", () => {
+        browserInstance = null;
+        launchPromise = null;
+    });
+    return browser;
+};
+/** Get a shared browser instance. Launches one if none exists. */
+export const getBrowser = async () => {
+    if (browserInstance?.connected) {
+        return browserInstance;
+    }
+    // Prevent multiple concurrent launches
+    if (!launchPromise) {
+        launchPromise = launchBrowser().then((browser) => {
+            browserInstance = browser;
+            launchPromise = null;
+            return browser;
+        });
+    }
+    return launchPromise;
+};
+/** Close the shared browser instance. Call at the end of processing. */
+export const closeBrowser = async () => {
+    if (launchPromise) {
+        await launchPromise;
+    }
+    if (browserInstance?.connected) {
+        await browserInstance.close();
+    }
+    browserInstance = null;
+    launchPromise = null;
+};

package/lib/utils/context.d.ts

@@ -1725,6 +1725,7 @@ export declare const createStudioData: (_mulmoScript: MulmoScript, fileName: str
                 script?: string | string[] | undefined;
                 animation?: true | {
                     fps: number;
+                    movie?: boolean | undefined;
                 } | undefined;
             } | {
                 type: "beat";
@@ -3819,6 +3820,7 @@ export declare const initializeContextFromFiles: (files: FileObject, raiseError:
                     script?: string | string[] | undefined;
                     animation?: true | {
                         fps: number;
+                        movie?: boolean | undefined;
                     } | undefined;
                 } | {
                     type: "beat";

package/lib/utils/html_render.d.ts

@@ -10,5 +10,11 @@ export declare const renderHTMLToImage: (html: string, outputPath: string, width
  * The user-defined render() function may be sync or async.
  */
 export declare const renderHTMLToFrames: (html: string, outputDir: string, width: number, height: number, totalFrames: number, fps: number) => Promise<string[]>;
+/**
+ * Record an animated HTML page as video using Puppeteer's screencast API.
+ * The animation plays in real-time via requestAnimationFrame, and
+ * page.screencast() captures frames directly to an mp4 file.
+ */
+export declare const renderHTMLToVideo: (html: string, videoPath: string, width: number, height: number, totalFrames: number, fps: number) => Promise<void>;
 export declare const renderMarkdownToImage: (markdown: string, style: string, outputPath: string, width: number, height: number) => Promise<void>;
 export declare const interpolate: (template: string, data: Record<string, string>) => string;

package/lib/utils/html_render.js

@@ -135,6 +135,39 @@ export const renderHTMLToFrames = async (html, outputDir, width, height, totalFr
         await browser.close();
     }
 };
+/**
+ * Record an animated HTML page as video using Puppeteer's screencast API.
+ * The animation plays in real-time via requestAnimationFrame, and
+ * page.screencast() captures frames directly to an mp4 file.
+ */
+export const renderHTMLToVideo = async (html, videoPath, width, height, totalFrames, fps) => {
+    const duration_ms = (totalFrames / fps) * 1000;
+    const browser = await puppeteer.launch({
+        args: isCI ? ["--no-sandbox", "--allow-file-access-from-files"] : ["--allow-file-access-from-files"],
+    });
+    try {
+        const page = await browser.newPage();
+        await loadHtmlIntoPage(page, html, 30000);
+        await page.setViewport({ width, height });
+        await page.addStyleTag({ content: "html{height:100%;margin:0;padding:0;overflow:hidden}" });
+        await scaleContentToFit(page, width, height);
+        const recorder = await page.screencast({
+            path: videoPath,
+            format: "mp4",
+            fps,
+        });
+        // Play animation in real-time and wait for completion
+        await page.evaluate(() => {
+            return window.playAnimation();
+        });
+        // Small buffer to ensure the last frame is captured
+        await new Promise((resolve) => setTimeout(resolve, Math.min(duration_ms * 0.1, 500)));
+        await recorder.stop();
+    }
+    finally {
+        await browser.close();
+    }
+};
 export const renderMarkdownToImage = async (markdown, style, outputPath, width, height) => {
     const header = `<head><style>${style}</style></head>`;
     const body = await marked(markdown);

package/lib/utils/image_plugins/html_tailwind.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import nodePath from "node:path";
 import { MulmoBeatMethods } from "../../methods/mulmo_beat.js";
 import { getHTMLFile } from "../file.js";
-import { renderHTMLToImage, interpolate, renderHTMLToFrames } from "../html_render.js";
+import { renderHTMLToImage, interpolate, renderHTMLToFrames, renderHTMLToVideo } from "../html_render.js";
 import { framesToVideo } from "../ffmpeg_utils.js";
 import { parrotingImagePath } from "./utils.js";
 export const imageType = "html_tailwind";
@@ -47,9 +47,9 @@ const getAnimationConfig = (params) => {
     const animation = beat.image.animation;
     if (!MulmoBeatMethods.isAnimationEnabled(animation))
         return null;
-    if (MulmoBeatMethods.isAnimationObject(animation))
-        return { fps: animation.fps ?? DEFAULT_ANIMATION_FPS };
-    return { fps: DEFAULT_ANIMATION_FPS };
+    const fps = MulmoBeatMethods.isAnimationObject(animation) ? (animation.fps ?? DEFAULT_ANIMATION_FPS) : DEFAULT_ANIMATION_FPS;
+    const movie = MulmoBeatMethods.isMovieMode(animation);
+    return { fps, movie };
 };
 const processHtmlTailwindAnimated = async (params) => {
     const { beat, imagePath, canvasSize, context } = params;
@@ -81,15 +81,21 @@ const processHtmlTailwindAnimated = async (params) => {
     const htmlData = resolveRelativeImagePaths(resolvedRefs, context.fileDirs.mulmoFileDirPath);
     // imagePath is set to the .mp4 path by imagePluginAgent for animated beats
     const videoPath = imagePath;
-    // Create frames directory next to the video file
-    const framesDir = videoPath.replace(/\.[^/.]+$/, "_frames");
-    fs.mkdirSync(framesDir, { recursive: true });
-    try {
-        await renderHTMLToFrames(htmlData, framesDir, canvasSize.width, canvasSize.height, totalFrames, fps);
-        await framesToVideo(framesDir, videoPath, fps, canvasSize.width, canvasSize.height);
+    if (animConfig.movie) {
+        // CDP screencast: real-time recording (experimental, faster)
+        await renderHTMLToVideo(htmlData, videoPath, canvasSize.width, canvasSize.height, totalFrames, fps);
     }
-    finally {
-        fs.rmSync(framesDir, { recursive: true, force: true });
+    else {
+        // Frame-by-frame screenshot (deterministic, slower)
+        const framesDir = videoPath.replace(/\.[^/.]+$/, "_frames");
+        fs.mkdirSync(framesDir, { recursive: true });
+        try {
+            await renderHTMLToFrames(htmlData, framesDir, canvasSize.width, canvasSize.height, totalFrames, fps);
+            await framesToVideo(framesDir, videoPath, fps, canvasSize.width, canvasSize.height);
+        }
+        finally {
+            fs.rmSync(framesDir, { recursive: true, force: true });
+        }
     }
     return videoPath;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.4.8",
+  "version": "2.4.9",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",
@@ -111,7 +111,7 @@
     "marked": "^17.0.4",
     "mulmocast-vision": "^1.0.8",
     "ora": "^9.3.0",
-    "puppeteer": "^24.38.0",
+    "puppeteer": "^24.39.0",
     "replicate": "^1.4.0",
     "yaml": "^2.8.2",
     "yargs": "^18.0.0",
@@ -125,15 +125,15 @@
     "@types/jsdom": "^28.0.0",
     "@types/yargs": "^17.0.35",
     "cross-env": "^10.1.0",
-    "eslint": "^10.0.2",
+    "eslint": "^10.0.3",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
-    "eslint-plugin-sonarjs": "^4.0.1",
+    "eslint-plugin-sonarjs": "^4.0.2",
     "globals": "^17.4.0",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "6.0.0-beta",
-    "typescript-eslint": "^8.56.1"
+    "typescript-eslint": "^8.57.0"
   },
   "engines": {
     "node": ">=22.0.0"