receptron/mulmocast-cli

MulmoCast: A Multi-Modal Presentation Tool for the AI-Native Era

Quick Start Guide

If you want to try our beta version, follow the instruction in the release note below.

What is MulmoCast?

Note: The video version of "What is MulmoCast?" is available on X, which is created by MulmoCast itself.

MulmoCast is a next-generation presentation platform, purpose-built for a world where AI and humans collaborate to create and share ideas.

Unlike traditional tools like PowerPoint or Keynote—both designed in the pre-AI era for human creators—MulmoCast is AI-native: reimagined from the ground up to work hand-in-hand with generative AI that understands and produces natural language, images, audio, and video.

As AI takes on an increasingly central role in content creation, it needs more than raw capability—it needs an environment designed for its strengths. MulmoCast provides that environment, empowering AI to generate rich, coherent presentations across multiple formats, while keeping humans in the creative loop.

At the core of MulmoCast is MulmoScript, a JSON-based intermediate language that functions like a screenplay or web markup. Generated by large language models, MulmoScript defines everything from narrative structure to visuals, making it easy to produce presentations that adapt seamlessly across formats.

flowchart TD
    S_TextEditor["Creator"] <--> S_AIChat2("LLM")
    S_AIChat2 --> MulmoScript["MulmoScript"]
    MulmoScript --> MulmoCast["MulmoCast"]
    MulmoCast --> O_Video("Video") & O_Podcast("Podcast") & O_Slideshow("Slideshow") & O_PDF("PDF") & O_Manga("Manga") & O_SwipeAnime("Swipe Anime")

    MulmoScript@{ shape: div-proc}
    MulmoCast@{ shape: trap-t}
     S_TextEditor:::StoryInput
     S_AIChat2:::ScriptInput
     O_Video:::ScriptOutput
     O_Podcast:::ScriptOutput
     O_Slideshow:::ScriptOutput
     O_PDF:::ScriptOutput
     O_Manga:::ScriptOutput
     O_SwipeAnime:::ScriptOutput
    classDef StoryInput stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef ScriptInput stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef ScriptOutput stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D

In today’s world, people consume information through many channels—on Zoom calls, in Slack threads, via videos on the go, or through podcasts during commutes. Presentations can no longer be confined to a single format or device. That’s why MulmoCast is built to be truly multi-modal, enabling output not only as slide decks but also as videos, podcasts, manga-style comics, and PDF documents.

Whether you're building a podcast from a research report or turning a business pitch into a narrated video, MulmoCast transforms source material into dynamic, multi-format content with the help of state-of-the-art AI like ChatGPT and Claude.

MulmoCast isn't just a tool. It’s a new foundation for communication—one where humans and AI co-create across every mode of expression.

MulmoScript

MulmoScript is a simple JSON/YAML format for describing multi-modal content.
You can define speakers, text, images, and layout — all in one script.

Here is the "Hello World" in MulmoScript.

{
  "$mulmocast": {
    "version": "1.1"
  },
  "beats": [
    { "text": "Hello World" }
  ]
}

See MulmoScript Format for details on the structure.

Installation

npm install -g mulmocast

You'll also need to install ffmpeg:

# For macOS with Homebrew
brew install ffmpeg

# For other platforms
# Visit https://ffmpeg.org/download.html

You can also use Dockerfile which helps you install the pre-requisits.

docker build -t mulmo-cli .

You can use the Docker image like this:

docker run -e OPENAI_API_KEY=<your_openai_api_key> -it mulmo-cli mulmo tool scripting -i -t children_book -o ./ -s story

Configuration

Create a .env file in your project directory with the following API keys:

Required

OPENAI_API_KEY=your_openai_api_key

(Optional) For Google's image and TTS.

GEMINI_API_KEY=your_google_gemini_api_key

(Optional) For AI providers

# For Anthropic Claude (htmlPrompt feature)
ANTHROPIC_API_TOKEN=your_anthropic_api_token

For htmlPrompt configuration, see docs/image.md.

(Optional) For Movie models

REPLICATE_API_TOKEN=your_replicate_api_key

(Optional) For TTS models

# For ElevenLabs TTS
ELEVENLABS_API_KEY=your_elevenlabs_api_key

(Optional) to access web in mulmo tool

BROWSERLESS_API_TOKEN=your_browserless_api_token # to access web in mulmo tool

(Optional) Local usage tracking

MULMOCAST_DUMP_USAGE=1                 # print JSON usage dump to stdout after each CLI action
MULMOCAST_DUMP_USAGE=/tmp/usage.json   # ...or write it to a file

Token / per-second / per-char usage per provider:model. See docs/api.md for the full reference.

Google Vertex AI

For enterprise/production environments, or to use Veo movie models that are only available on Vertex AI, use Vertex AI with Application Default Credentials (ADC):

# Install gcloud CLI and authenticate
gcloud auth application-default login

Configure in MulmoScript:

{
  "imageParams": {
    "provider": "google",
    "model": "gemini-2.5-flash-image",
    "vertexai_project": "your-project-id",
    "vertexai_location": "us-central1"
  }
}

Parameter	Description	Default
`vertexai_project`	Google Cloud Project ID	None (enables Vertex AI mode when set)
`vertexai_location`	Region	`us-central1`

For detailed setup instructions, see Vertex AI Setup Guide.

Azure OpenAI

To use Azure OpenAI instead of OpenAI API:

# For image generation
IMAGE_OPENAI_API_KEY=<your-azure-openai-api-key>
IMAGE_OPENAI_BASE_URL=https://<resource-name>.openai.azure.com/

# For TTS (Text-to-Speech)
TTS_OPENAI_API_KEY=<your-azure-openai-api-key>
TTS_OPENAI_BASE_URL=https://<resource-name>.openai.azure.com/

# For LLM (translate, scripting)
LLM_OPENAI_API_KEY=<your-azure-openai-api-key>
LLM_OPENAI_BASE_URL=https://<resource-name>.openai.azure.com/
LLM_OPENAI_API_VERSION=2025-04-01-preview  # optional

MulmoScript configuration (same as OpenAI):

{
  "imageParams": {
    "provider": "openai",
    "model": "gpt-image-1.5"
  },
  "speechParams": {
    "speakers": {
      "Presenter": {
        "provider": "openai",
        "voiceId": "alloy",
        "model": "tts"
      }
    }
  }
}

Important: Azure deployment names must match model names exactly (e.g., deployment name gpt-image-1.5 for model gpt-image-1.5).

For detailed setup and region availability, see Azure OpenAI Usage Guide.

mulmo.config.json

Create a mulmo.config.json file to set project-wide defaults. The CLI searches for it in CWD first, then home directory (~/).

{
  "speechParams": {
    "provider": "elevenlabs"
  },
  "imageParams": {
    "provider": "google"
  },
  "audioParams": {
    "bgm": { "kind": "path", "path": "assets/bgm.mp3" },
    "bgmVolume": 0.15
  }
}

Top-level keys are applied as defaults (script values take precedence). Use the override key to force values over scripts — useful for enterprise branding or TTS provider enforcement:

{
  "speechParams": {
    "provider": "elevenlabs"
  },
  "override": {
    "speechParams": {
      "provider": "elevenlabs",
      "model": "eleven_multilingual_v2",
      "speakers": {
        "Presenter": { "provider": "elevenlabs", "voiceId": "Rachel" }
      }
    }
  }
}

Priority chain: config (defaults) < template/style < script < config.override < presentationStyle (-p)

Note: kind: "path" entries in mulmo.config.json are resolved relative to the script file directory, not the config file location. This is consistent with all other path resolution in MulmoScript.

Verify the merged result with:

mulmo tool info merged --script <script.json>

Workflow

Create a MulmoScript JSON file with mulmo tool scripting
Generate audio with mulmo audio
Generate images with mulmo images
Create final video with mulmo movie

Quick Start

Step 1: Generate a MulmoScript with interactive mode

Step 1-1: Run the script generation command
```
mulmo tool scripting -i -t children_book -o ./ -s story
```
This will initiate the script creation process.
Step 1-2: Interactive conversation with AI

After running the command, you'll engage in an interactive conversation with the AI to create your story script. The AI will guide you through the process and help shape your content based on your inputs. Once completed, a JSON file (like ⁠story-1746600802426.json) will be generated.

Step 2: Generate both audio and images, then combine into video

mulmo movie {generated_script_file}

Replace {generated_script_file} with the output file from STEP 1, such as story-1746600802426.json.

Optionally, you can specify __clipboard as the script file name to paste the script from the clipboard, which is generated by other interactive environment such as ChatGPT or Claude.

Quick Start for Ghibli-Style Animation

Click the image above to watch an example of what you can create

Step 1: Check/Update Environment Setup

Verify your .env file contains:

OPENAI_API_KEY=your_openai_api_key

Note: Ensure your OpenAI organization is verified to access the GPT Image models. Visit https://platform.openai.com/settings/organization/general and complete the "Verifications" section.

Step 2: Generate a Ghibli-style MulmoScript

mulmo tool scripting -i -t ghibli_comic -o ./ -s story

This will initiate an interactive conversation with the AI to create your Ghibli-inspired story. Once completed, a JSON file (e.g., story-1747834931950.json) will be generated.

Step 3: Translate the MulmoScript

mulmo translate {generated_script_file_from_step_2}

Step 4: Generate video with Japanese subtitles

mulmo movie {generated_script_file_from_step_2} -c ja

The -c ja flag adds Japanese subtitles to your video.

When the process completes, the CLI will display the path to your generated video file:

Video created successfully! 14.939 sec
writing: /Users/username/path/to/output/story-1747834931950__ja.mp4

Generate MulmoScript

# Generate script from web content (requires Browserless API KEY)
mulmo tool scripting -u https://example.com

# Generate script from local file
mulmo tool scripting --input-file story.txt

# Generate script with interactive mode
mulmo tool scripting -i

Note:

When -i is specified, --input-file value will be ignored
When --input-file is specified, -u value will be ignored

Complete MulmoScript from minimal beats

You can create a minimal JSON with just beats and complete it with mulmo tool complete:

{
  "beats": [{ "text": "Hello, welcome to MulmoCast!" }, { "text": "This is a simple example." }]
}

Save this as my_beats.json, then complete it with a style:

# Complete with built-in style
mulmo tool complete my_beats.json -s ani

# Complete with custom style file
mulmo tool complete my_beats.json -s ./my_style.json

# Output to specific file
mulmo tool complete my_beats.json -s ani -o my_script.json

This generates a complete MulmoScript with all required fields (canvasSize, speechParams, imageParams, etc.) from the style.

Generate content from MulmoScript

Mulmo provides several commands to handle different aspects of content creation:

# Generate audio from script
mulmo audio script.json

# Generate images for script
mulmo images script.json

# Generate both audio and images, then combine into video
mulmo movie script.json

# Translate script to Japanese
mulmo translate script.json

Usage tracking (token / character / predict-second per provider:model)

Any of the commands above can dump a JSON breakdown of upstream AI consumption when MULMOCAST_DUMP_USAGE is set:

# print JSON to stdout (pipe-friendly: `... | jq .`)
MULMOCAST_DUMP_USAGE=1 mulmo audio script.json

# ...or write it to a file
MULMOCAST_DUMP_USAGE=/tmp/usage.json mulmo movie script.json

Payload shape:

{
  "records": 3,
  "byModel": [
    { "provider": "openai", "model": "gpt-4o-mini-tts", "records": 1, "inputChars": 20 },
    { "provider": "gemini", "model": "gemini-3.8-flash-tts", "records": 1, "inputTokens": 9, "outputTokens": 59, "totalTokens": 68 },
    { "provider": "elevenlabs", "model": "eleven_multilingual_v2", "records": 1, "inputChars": 18 }
  ],
  "snapshot": [/* per-call UsageRecord[] */]
}

byModel groups by provider:model (different models have different rate cards, so summing across them isn't meaningful). The full per-call snapshot is also included so a billing layer can apply its own grouping. See docs/api.md § Usage tracking for the per-agent field-population matrix and the programmatic (library) API.

Usage estimation (before running anything)

Every generation command accepts --estimate: it prints what the command would consume — scoped to that command's pipeline — and exits without generating:

mulmo movie script.json --estimate         # table per provider:model + total cost
mulmo audio script.json --estimate --json  # raw UsageEstimate[] records (pipe-friendly)

mulmo audio --estimate covers TTS (plus translation when -l differs from the script language); mulmo images / mulmo pdf cover image, htmlImage, movie, sound-effect, lip-sync and reference-media generation; mulmo movie covers everything; mulmo translate only translation. Values marked ~ are heuristic estimates; unmarked values are exact for the given script.

The library API can estimate the same thing — per beat, per process — without calling any API:

import { estimateUsage } from "mulmocast";

const estimates = estimateUsage(script, { targetLangs: ["ja"] });
// [{ process: "tts", beatIndex: 0, provider: "openai", model: "gpt-4o-mini-tts",
//    inputChars: { value: 50, precision: "exact" }, outputTokens: { value: 150, precision: "estimated" },
//    costUSD: 0.0019, pricingAsOf: "2026-07-03" }, ...]

Each metric carries a precision flag: "exact" for values that are deterministic from the script (TTS character counts, tokenized OpenAI prompts, fixed image-output token tables) and "estimated" for heuristics (LLM output length, speech duration derived from text). costUSD appears when pricing data exists in modelPricing (src/types/provider2agent.ts), where every price records the date it was last verified. See docs/api.md § Pre-run estimation.

Strict network mode (scripts you did not write)

HTML-based beats (html_tailwind, markdown, textSlide, chart, mermaid, slide, captions, HTML prompts) and PDF output are rendered in a headless browser that normally has full network access. For a script from an untrusted source, add --strict-network (or set MULMO_STRICT_NETWORK=1; library callers set context.strictNetwork):

mulmo images untrusted.json --strict-network

The renderer may then load only files in the script's folder and mulmocast's output folders, data: / blob: URLs, and the CDNs mulmocast's own templates use (cdn.tailwindcss.com, fonts.googleapis.com, fonts.gstatic.com, and on cdn.jsdelivr.net only the mermaid and Chart.js files the templates load). Anything else — other local files, remote images in the script, fetch, WebSockets, WebRTC, popups, preconnect hints — is blocked, and each blocked request is logged (strict network: blocked …). Files next to the script in the same folder remain readable, so keep an untrusted script in a folder of its own (a script loaded by URL gets the output folders only). Requests to the allowed CDNs still reach those providers, so treat what a page sends there as visible to them. Strict mode guards what the browser loads; files the script names with kind: "path" (images, movies, logos, mermaid or remotion code) are read by mulmocast itself and are not restricted yet (#1622). Remotion beats are always guarded this way. The vision beat renders in its own browser inside mulmocast-vision, which the guard cannot reach, so in strict mode a vision beat stops with an error instead of rendering unguarded.

Cache and Re-run

When running the same mulmo command multiple times, previously generated files are treated as cache. For example, audio or image files will not be regenerated if they already exist.

To force regeneration, delete the old files — including temporary files — under the output directory before re-running the command or use -f (force) option.

If you modify the text or instruction fields in a MulmoScript, mulmo will automatically detect the changes and regenerate the corresponding audio content upon re-run.

Slide Presentations

MulmoCast includes a powerful Slide DSL (type: "slide") for creating structured presentation slides with JSON. Slides are rendered via Tailwind CSS + Puppeteer into images.

Features

12 Layouts: title, columns, comparison, grid, bigQuote, stats, timeline, split, matrix, table, funnel, waterfall
10 Content Block Types: text, bullets, code, callout, metric, divider, image, imageRef, chart, mermaid
Chart.js Plugins: sankey (chartjs-chart-sankey) and treemap (chartjs-chart-treemap) auto-loaded by chart type
13-Color Theme System: Semantic color palette with dark/light support
6 Preset Themes: dark, pop, warm, creative, minimal, corporate

Usage

Set a theme once with slideParams.theme, then use "type": "slide" in each beat:

{
  "$mulmocast": { "version": "1.1" },
  "slideParams": {
    "theme": {
      "colors": {
        "bg": "0F172A",
        "bgCard": "1E293B",
        "bgCardAlt": "334155",
        "text": "F8FAFC",
        "textMuted": "CBD5E1",
        "textDim": "64748B",
        "primary": "3B82F6",
        "accent": "8B5CF6",
        "success": "22C55E",
        "warning": "F59E0B",
        "danger": "EF4444",
        "info": "14B8A6",
        "highlight": "EC4899"
      },
      "fonts": { "title": "Georgia", "body": "Calibri", "mono": "Consolas" }
    }
  },
  "beats": [
    {
      "text": "Welcome to the presentation",
      "image": {
        "type": "slide",
        "slide": { "layout": "title", "title": "Main Title", "subtitle": "Subtitle" }
      }
    }
  ]
}

Or use a preset presentation style:

mulmo tool complete beats.json -s slide_dark -o presentation.json

Available preset styles: slide_dark, slide_pop, slide_warm, slide_creative, slide_minimal, slide_corporate

For detailed layout specifications and content block reference, see the Slide DSL documentation.

Markdown Slide Styles

MulmoCast includes 100 pre-designed CSS styles for markdown slides, organized in 10 categories:

Category	Description	Example Styles
business	Professional corporate designs	corporate-blue, executive-gray, finance-green
tech	Technology and developer themes	cyber-neon, matrix-green, terminal-dark
creative	Artistic and expressive styles	artistic-splash, watercolor-soft, graffiti
minimalist	Clean and simple designs	clean-white, zen-beige, nordic-light
nature	Nature-inspired themes	forest-green, ocean-blue, sunset-orange
dark	Dark mode and elegant themes	charcoal-elegant, midnight-blue, obsidian
colorful	Vibrant and bold colors	vibrant-pink, candy-colors, aurora
vintage	Retro and classic styles	retro-70s, art-deco, typewriter
japanese	Japanese aesthetic designs	washi-paper, sakura-pink, zen-garden
geometric	Pattern-based designs	hexagon-pattern, isometric, bauhaus

Usage

Add the style property to a markdown beat:

{
  "beats": [
    {
      "text": "Corporate presentation slide",
      "image": {
        "type": "markdown",
        "markdown": "# Quarterly Report\n\n## Key Highlights\n\n- Revenue up 15%\n- New market expansion\n- Team growth",
        "style": "corporate-blue"
      }
    }
  ]
}

Discover Available Styles

Use the mulmo tool info command to see all available styles:

mulmo tool info styles

MulmoScript Format

MulmoScript is a JSON format to define podcast or video scripts: Schema definition: schema.ts

Sample MulmoScript

https://github.com/receptron/mulmocast-cli/tree/main/scripts

Directory Structure

Directory	Description
`output/`	Artifacts generated by commands — e.g., `.json`, audio, and video files
`output/audio/`	Temporary audio fragments used in the final audio assembly
`output/images/`	Image files generated by the `images` command
`output/cache/`	Internal cache files for various processing steps

These directories are automatically created as needed by the mulmo commands.

Help

CLI Usage

mulmo <command> [options]

Commands:
  mulmo translate <file>  Translate Mulmo script
  mulmo audio <file>      Generate audio files
  mulmo images <file>     Generate image files
  mulmo movie <file>      Generate movie file
  mulmo pdf <file>        Generate PDF files
  mulmo markdown <file>   Generate markdown files
  mulmo bundle <file>     Generate bundle files
  mulmo html <file>       Generate html files
  mulmo tool <command>    Generate Mulmo script and other tools

Options:
      --version  Show version number                                   [boolean]
  -v, --verbose  verbose log               [boolean] [required] [default: false]
  -h, --help     Show help                                             [boolean]

mulmo translate <file>

Translate Mulmo script

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]

mulmo audio <file>

Generate audio files

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]
  -a, --audiodir           Audio output directory                       [string]

mulmo images <file>

Generate image files

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]
  -i, --imagedir           Image output directory                       [string]

mulmo movie <file>

Generate movie file

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]
  -a, --audiodir           Audio output directory                       [string]
  -i, --imagedir           Image output directory                       [string]
  -c, --caption            Video captions
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]

mulmo pdf <file>

Generate PDF files

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]
  -i, --imagedir           Image output directory                       [string]
      --pdf_mode           PDF mode
               [string] [choices: "slide", "talk", "handout"] [default: "slide"]
      --pdf_size           PDF paper size (default: letter)
                                   [choices: "letter", "a4"] [default: "letter"]

mulmo markdown <file>

Generate markdown files

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local f

MulmoCast: A Multi-Modal Presentation Tool for the AI-Native Era

Quick Start Guide

If you want to try our beta version, follow the instruction in the release note below.

What is MulmoCast?

Note: The video version of "What is MulmoCast?" is available on X, which is created by MulmoCast itself.

MulmoCast is a next-generation presentation platform, purpose-built for a world where AI and humans collaborate to create and share ideas.

flowchart TD
    S_TextEditor["Creator"] <--> S_AIChat2("LLM")
    S_AIChat2 --> MulmoScript["MulmoScript"]
    MulmoScript --> MulmoCast["MulmoCast"]
    MulmoCast --> O_Video("Video") & O_Podcast("Podcast") & O_Slideshow("Slideshow") & O_PDF("PDF") & O_Manga("Manga") & O_SwipeAnime("Swipe Anime")

    MulmoScript@{ shape: div-proc}
    MulmoCast@{ shape: trap-t}
     S_TextEditor:::StoryInput
     S_AIChat2:::ScriptInput
     O_Video:::ScriptOutput
     O_Podcast:::ScriptOutput
     O_Slideshow:::ScriptOutput
     O_PDF:::ScriptOutput
     O_Manga:::ScriptOutput
     O_SwipeAnime:::ScriptOutput
    classDef StoryInput stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef ScriptInput stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef ScriptOutput stroke-width:1px, stroke-dasharray:none, stroke:#FBB35A, fill:#FFEFDB, color:#8F632D

MulmoCast isn't just a tool. It’s a new foundation for communication—one where humans and AI co-create across every mode of expression.

MulmoScript

MulmoScript is a simple JSON/YAML format for describing multi-modal content.
You can define speakers, text, images, and layout — all in one script.

Here is the "Hello World" in MulmoScript.

{
  "$mulmocast": {
    "version": "1.1"
  },
  "beats": [
    { "text": "Hello World" }
  ]
}

See MulmoScript Format for details on the structure.

Installation

npm install -g mulmocast

You'll also need to install ffmpeg:

# For macOS with Homebrew
brew install ffmpeg

# For other platforms
# Visit https://ffmpeg.org/download.html

You can also use Dockerfile which helps you install the pre-requisits.

docker build -t mulmo-cli .

You can use the Docker image like this:

docker run -e OPENAI_API_KEY=<your_openai_api_key> -it mulmo-cli mulmo tool scripting -i -t children_book -o ./ -s story

Configuration

Create a .env file in your project directory with the following API keys:

Required

OPENAI_API_KEY=your_openai_api_key

(Optional) For Google's image and TTS.

GEMINI_API_KEY=your_google_gemini_api_key

(Optional) For AI providers

# For Anthropic Claude (htmlPrompt feature)
ANTHROPIC_API_TOKEN=your_anthropic_api_token

For htmlPrompt configuration, see docs/image.md.

(Optional) For Movie models

REPLICATE_API_TOKEN=your_replicate_api_key

(Optional) For TTS models

# For ElevenLabs TTS
ELEVENLABS_API_KEY=your_elevenlabs_api_key

(Optional) to access web in mulmo tool

BROWSERLESS_API_TOKEN=your_browserless_api_token # to access web in mulmo tool

(Optional) Local usage tracking

MULMOCAST_DUMP_USAGE=1                 # print JSON usage dump to stdout after each CLI action
MULMOCAST_DUMP_USAGE=/tmp/usage.json   # ...or write it to a file

Token / per-second / per-char usage per provider:model. See docs/api.md for the full reference.

Google Vertex AI

For enterprise/production environments, or to use Veo movie models that are only available on Vertex AI, use Vertex AI with Application Default Credentials (ADC):

# Install gcloud CLI and authenticate
gcloud auth application-default login

Configure in MulmoScript:

{
  "imageParams": {
    "provider": "google",
    "model": "gemini-2.5-flash-image",
    "vertexai_project": "your-project-id",
    "vertexai_location": "us-central1"
  }
}

Parameter	Description	Default
`vertexai_project`	Google Cloud Project ID	None (enables Vertex AI mode when set)
`vertexai_location`	Region	`us-central1`

For detailed setup instructions, see Vertex AI Setup Guide.

Azure OpenAI

To use Azure OpenAI instead of OpenAI API:

# For image generation
IMAGE_OPENAI_API_KEY=<your-azure-openai-api-key>
IMAGE_OPENAI_BASE_URL=https://<resource-name>.openai.azure.com/

# For TTS (Text-to-Speech)
TTS_OPENAI_API_KEY=<your-azure-openai-api-key>
TTS_OPENAI_BASE_URL=https://<resource-name>.openai.azure.com/

# For LLM (translate, scripting)
LLM_OPENAI_API_KEY=<your-azure-openai-api-key>
LLM_OPENAI_BASE_URL=https://<resource-name>.openai.azure.com/
LLM_OPENAI_API_VERSION=2025-04-01-preview  # optional

MulmoScript configuration (same as OpenAI):

{
  "imageParams": {
    "provider": "openai",
    "model": "gpt-image-1.5"
  },
  "speechParams": {
    "speakers": {
      "Presenter": {
        "provider": "openai",
        "voiceId": "alloy",
        "model": "tts"
      }
    }
  }
}

Important: Azure deployment names must match model names exactly (e.g., deployment name gpt-image-1.5 for model gpt-image-1.5).

For detailed setup and region availability, see Azure OpenAI Usage Guide.

mulmo.config.json

Create a mulmo.config.json file to set project-wide defaults. The CLI searches for it in CWD first, then home directory (~/).

{
  "speechParams": {
    "provider": "elevenlabs"
  },
  "imageParams": {
    "provider": "google"
  },
  "audioParams": {
    "bgm": { "kind": "path", "path": "assets/bgm.mp3" },
    "bgmVolume": 0.15
  }
}

Top-level keys are applied as defaults (script values take precedence). Use the override key to force values over scripts — useful for enterprise branding or TTS provider enforcement:

{
  "speechParams": {
    "provider": "elevenlabs"
  },
  "override": {
    "speechParams": {
      "provider": "elevenlabs",
      "model": "eleven_multilingual_v2",
      "speakers": {
        "Presenter": { "provider": "elevenlabs", "voiceId": "Rachel" }
      }
    }
  }
}

Priority chain: config (defaults) < template/style < script < config.override < presentationStyle (-p)

Note: kind: "path" entries in mulmo.config.json are resolved relative to the script file directory, not the config file location. This is consistent with all other path resolution in MulmoScript.

Verify the merged result with:

mulmo tool info merged --script <script.json>

Workflow

Create a MulmoScript JSON file with mulmo tool scripting
Generate audio with mulmo audio
Generate images with mulmo images
Create final video with mulmo movie

Quick Start

Step 1: Generate a MulmoScript with interactive mode

Step 1-1: Run the script generation command
```
mulmo tool scripting -i -t children_book -o ./ -s story
```
This will initiate the script creation process.
Step 1-2: Interactive conversation with AI

After running the command, you'll engage in an interactive conversation with the AI to create your story script. The AI will guide you through the process and help shape your content based on your inputs. Once completed, a JSON file (like ⁠story-1746600802426.json) will be generated.

Step 2: Generate both audio and images, then combine into video

mulmo movie {generated_script_file}

Replace {generated_script_file} with the output file from STEP 1, such as story-1746600802426.json.

Optionally, you can specify __clipboard as the script file name to paste the script from the clipboard, which is generated by other interactive environment such as ChatGPT or Claude.

Quick Start for Ghibli-Style Animation

Click the image above to watch an example of what you can create

Step 1: Check/Update Environment Setup

Verify your .env file contains:

OPENAI_API_KEY=your_openai_api_key

Note: Ensure your OpenAI organization is verified to access the GPT Image models. Visit https://platform.openai.com/settings/organization/general and complete the "Verifications" section.

Step 2: Generate a Ghibli-style MulmoScript

mulmo tool scripting -i -t ghibli_comic -o ./ -s story

This will initiate an interactive conversation with the AI to create your Ghibli-inspired story. Once completed, a JSON file (e.g., story-1747834931950.json) will be generated.

Step 3: Translate the MulmoScript

mulmo translate {generated_script_file_from_step_2}

Step 4: Generate video with Japanese subtitles

mulmo movie {generated_script_file_from_step_2} -c ja

The -c ja flag adds Japanese subtitles to your video.

When the process completes, the CLI will display the path to your generated video file:

Video created successfully! 14.939 sec
writing: /Users/username/path/to/output/story-1747834931950__ja.mp4

Generate MulmoScript

# Generate script from web content (requires Browserless API KEY)
mulmo tool scripting -u https://example.com

# Generate script from local file
mulmo tool scripting --input-file story.txt

# Generate script with interactive mode
mulmo tool scripting -i

Note:

When -i is specified, --input-file value will be ignored
When --input-file is specified, -u value will be ignored

Complete MulmoScript from minimal beats

You can create a minimal JSON with just beats and complete it with mulmo tool complete:

{
  "beats": [{ "text": "Hello, welcome to MulmoCast!" }, { "text": "This is a simple example." }]
}

Save this as my_beats.json, then complete it with a style:

# Complete with built-in style
mulmo tool complete my_beats.json -s ani

# Complete with custom style file
mulmo tool complete my_beats.json -s ./my_style.json

# Output to specific file
mulmo tool complete my_beats.json -s ani -o my_script.json

This generates a complete MulmoScript with all required fields (canvasSize, speechParams, imageParams, etc.) from the style.

Generate content from MulmoScript

Mulmo provides several commands to handle different aspects of content creation:

# Generate audio from script
mulmo audio script.json

# Generate images for script
mulmo images script.json

# Generate both audio and images, then combine into video
mulmo movie script.json

# Translate script to Japanese
mulmo translate script.json

Usage tracking (token / character / predict-second per provider:model)

Any of the commands above can dump a JSON breakdown of upstream AI consumption when MULMOCAST_DUMP_USAGE is set:

# print JSON to stdout (pipe-friendly: `... | jq .`)
MULMOCAST_DUMP_USAGE=1 mulmo audio script.json

# ...or write it to a file
MULMOCAST_DUMP_USAGE=/tmp/usage.json mulmo movie script.json

Payload shape:

{
  "records": 3,
  "byModel": [
    { "provider": "openai", "model": "gpt-4o-mini-tts", "records": 1, "inputChars": 20 },
    { "provider": "gemini", "model": "gemini-3.8-flash-tts", "records": 1, "inputTokens": 9, "outputTokens": 59, "totalTokens": 68 },
    { "provider": "elevenlabs", "model": "eleven_multilingual_v2", "records": 1, "inputChars": 18 }
  ],
  "snapshot": [/* per-call UsageRecord[] */]
}

Usage estimation (before running anything)

Every generation command accepts --estimate: it prints what the command would consume — scoped to that command's pipeline — and exits without generating:

mulmo movie script.json --estimate         # table per provider:model + total cost
mulmo audio script.json --estimate --json  # raw UsageEstimate[] records (pipe-friendly)

The library API can estimate the same thing — per beat, per process — without calling any API:

import { estimateUsage } from "mulmocast";

const estimates = estimateUsage(script, { targetLangs: ["ja"] });
// [{ process: "tts", beatIndex: 0, provider: "openai", model: "gpt-4o-mini-tts",
//    inputChars: { value: 50, precision: "exact" }, outputTokens: { value: 150, precision: "estimated" },
//    costUSD: 0.0019, pricingAsOf: "2026-07-03" }, ...]

Strict network mode (scripts you did not write)

mulmo images untrusted.json --strict-network

Cache and Re-run

When running the same mulmo command multiple times, previously generated files are treated as cache. For example, audio or image files will not be regenerated if they already exist.

To force regeneration, delete the old files — including temporary files — under the output directory before re-running the command or use -f (force) option.

If you modify the text or instruction fields in a MulmoScript, mulmo will automatically detect the changes and regenerate the corresponding audio content upon re-run.

Slide Presentations

MulmoCast includes a powerful Slide DSL (type: "slide") for creating structured presentation slides with JSON. Slides are rendered via Tailwind CSS + Puppeteer into images.

Features

12 Layouts: title, columns, comparison, grid, bigQuote, stats, timeline, split, matrix, table, funnel, waterfall
10 Content Block Types: text, bullets, code, callout, metric, divider, image, imageRef, chart, mermaid
Chart.js Plugins: sankey (chartjs-chart-sankey) and treemap (chartjs-chart-treemap) auto-loaded by chart type
13-Color Theme System: Semantic color palette with dark/light support
6 Preset Themes: dark, pop, warm, creative, minimal, corporate

Usage

Set a theme once with slideParams.theme, then use "type": "slide" in each beat:

{
  "$mulmocast": { "version": "1.1" },
  "slideParams": {
    "theme": {
      "colors": {
        "bg": "0F172A",
        "bgCard": "1E293B",
        "bgCardAlt": "334155",
        "text": "F8FAFC",
        "textMuted": "CBD5E1",
        "textDim": "64748B",
        "primary": "3B82F6",
        "accent": "8B5CF6",
        "success": "22C55E",
        "warning": "F59E0B",
        "danger": "EF4444",
        "info": "14B8A6",
        "highlight": "EC4899"
      },
      "fonts": { "title": "Georgia", "body": "Calibri", "mono": "Consolas" }
    }
  },
  "beats": [
    {
      "text": "Welcome to the presentation",
      "image": {
        "type": "slide",
        "slide": { "layout": "title", "title": "Main Title", "subtitle": "Subtitle" }
      }
    }
  ]
}

Or use a preset presentation style:

mulmo tool complete beats.json -s slide_dark -o presentation.json

Available preset styles: slide_dark, slide_pop, slide_warm, slide_creative, slide_minimal, slide_corporate

For detailed layout specifications and content block reference, see the Slide DSL documentation.

Markdown Slide Styles

MulmoCast includes 100 pre-designed CSS styles for markdown slides, organized in 10 categories:

Category	Description	Example Styles
business	Professional corporate designs	corporate-blue, executive-gray, finance-green
tech	Technology and developer themes	cyber-neon, matrix-green, terminal-dark
creative	Artistic and expressive styles	artistic-splash, watercolor-soft, graffiti
minimalist	Clean and simple designs	clean-white, zen-beige, nordic-light
nature	Nature-inspired themes	forest-green, ocean-blue, sunset-orange
dark	Dark mode and elegant themes	charcoal-elegant, midnight-blue, obsidian
colorful	Vibrant and bold colors	vibrant-pink, candy-colors, aurora
vintage	Retro and classic styles	retro-70s, art-deco, typewriter
japanese	Japanese aesthetic designs	washi-paper, sakura-pink, zen-garden
geometric	Pattern-based designs	hexagon-pattern, isometric, bauhaus

Usage

Add the style property to a markdown beat:

{
  "beats": [
    {
      "text": "Corporate presentation slide",
      "image": {
        "type": "markdown",
        "markdown": "# Quarterly Report\n\n## Key Highlights\n\n- Revenue up 15%\n- New market expansion\n- Team growth",
        "style": "corporate-blue"
      }
    }
  ]
}

Discover Available Styles

Use the mulmo tool info command to see all available styles:

mulmo tool info styles

MulmoScript Format

MulmoScript is a JSON format to define podcast or video scripts: Schema definition: schema.ts

Sample MulmoScript

https://github.com/receptron/mulmocast-cli/tree/main/scripts

Directory Structure

Directory	Description
`output/`	Artifacts generated by commands — e.g., `.json`, audio, and video files
`output/audio/`	Temporary audio fragments used in the final audio assembly
`output/images/`	Image files generated by the `images` command
`output/cache/`	Internal cache files for various processing steps

These directories are automatically created as needed by the mulmo commands.

Help

CLI Usage

mulmo <command> [options]

Commands:
  mulmo translate <file>  Translate Mulmo script
  mulmo audio <file>      Generate audio files
  mulmo images <file>     Generate image files
  mulmo movie <file>      Generate movie file
  mulmo pdf <file>        Generate PDF files
  mulmo markdown <file>   Generate markdown files
  mulmo bundle <file>     Generate bundle files
  mulmo html <file>       Generate html files
  mulmo tool <command>    Generate Mulmo script and other tools

Options:
      --version  Show version number                                   [boolean]
  -v, --verbose  verbose log               [boolean] [required] [default: false]
  -h, --help     Show help                                             [boolean]

mulmo translate <file>

Translate Mulmo script

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]

mulmo audio <file>

Generate audio files

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]
  -a, --audiodir           Audio output directory                       [string]

mulmo images <file>

Generate image files

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]
  -i, --imagedir           Image output directory                       [string]

mulmo movie <file>

Generate movie file

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]
  -a, --audiodir           Audio output directory                       [string]
  -i, --imagedir           Image output directory                       [string]
  -c, --caption            Video captions
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]

mulmo pdf <file>

Generate PDF files

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local files and the
                           CDNs mulmocast's templates use (also
                           MULMO_STRICT_NETWORK=1)    [boolean] [default: false]
  -p, --presentationStyle  Presentation Style                           [string]
  -i, --imagedir           Image output directory                       [string]
      --pdf_mode           PDF mode
               [string] [choices: "slide", "talk", "handout"] [default: "slide"]
      --pdf_size           PDF paper size (default: letter)
                                   [choices: "letter", "a4"] [default: "letter"]

mulmo markdown <file>

Generate markdown files

Positionals:
  file  Mulmo Script File                                    [string] [required]

Options:
      --version            Show version number                         [boolean]
  -v, --verbose            verbose log     [boolean] [required] [default: false]
  -h, --help               Show help                                   [boolean]
  -o, --outdir             output dir                                   [string]
  -b, --basedir            base dir                                     [string]
  -l, --lang               target language
  [string] [choices: "en", "ja", "fr", "es", "de", "zh-CN", "zh-TW", "ko", "it",
                                                               "pt", "ar", "hi"]
  -f, --force              Force regenerate           [boolean] [default: false]
  -g, --grouped            Output all files under output/<basename>/ directory
                                                      [boolean] [default: false]
      --backup             create backup media file   [boolean] [default: false]
      --strict-network     Let HTML renderers reach only local f