Convert presentations (Keynote, PowerPoint, PDF, Marp) and videos to MulmoScript format
npm install @mulmocast/slideA collection of tools to convert presentation files into MulmoScript format, enabling automated narration and processing of slide decks.
MulmoCast-Slides provides converters that extract slides and speaker notes from various presentation formats (Keynote, PowerPoint, PDF, etc.) and generate MulmoScript JSON files. Each slide is exported as an image paired with its speaker notes.
- Node.js 22 or later
- yarn or npm
``bashRequired for PDF and PPTX conversion
brew install imagemagick ghostscript
$3
`bash
Required for PDF and PPTX conversion
sudo apt-get update
sudo apt-get install -y imagemagick ghostscriptRequired for PPTX conversion
sudo apt-get install -y libreoffice
`$3
`bash
Required for LLM narration generation (-g option)
export OPENAI_API_KEY=your-openai-api-keyOptional: Set default language (en, ja, fr, de)
export MULMO_LANG=ja
`$3
| Feature | macOS | Linux | Required Tools |
|---------|-------|-------|----------------|
| Marp (.md) | Yes | Yes | Node.js only |
| PPTX (.pptx) | Yes | Yes | LibreOffice, ImageMagick, Ghostscript |
| PDF (.pdf) | Yes | Yes | ImageMagick, Ghostscript |
| Keynote (.key) | Yes | No | Keynote app, Python 3 |
| LLM Narration (-g) | Yes | Yes | OPENAI_API_KEY |
Installation
$3
`bash
npm install -g @mulmocast/slide
`After installation, use the
mulmo-slide command:`bash
mulmo-slide marp presentation.md
mulmo-slide pptx presentation.pptx
mulmo-slide pdf presentation.pdf
mulmo-slide movie presentation.pptx
`$3
`bash
npx @mulmocast/slide marp presentation.md
npx @mulmocast/slide pptx presentation.pptx -g -l ja
`$3
`bash
git clone https://github.com/receptron/MulmoCast-Slides.git
cd MulmoCast-Slides
yarn install
yarn build # Build TypeScript to lib/
`$3
The
samples/ directory contains example files for testing:`bash
Marp markdown
yarn marp samples/sample.md
yarn marp samples/custom_theme_demo.md --theme samples/custom-ocean.cssPowerPoint
yarn pptx samples/omochikaeri.pptx
yarn pptx samples/omochikaeri.pptx -g -l ja # with LLM narrationPDF
yarn pdf samples/20251008_2.pdf
yarn pdf samples/20251008_2.pdf -g -l ja # with LLM narrationKeynote (macOS only)
yarn keynote samples/GraphAI.keyGenerate movie from sample
yarn movie samples/omochikaeri.pptx -g -l jaGenerate bundle from sample
yarn bundle samples/sample.md -g -l ja
`Note: When re-running commands, the existing MulmoScript JSON will be reused. To regenerate:
- Delete the existing JSON file:
rm scripts/
- Or use the -f (force) flag with movie/bundle: yarn movie samples/sample.pptx -f -gUnified CLI
All commands are available through the unified
mulmo-slide CLI:`bash
mulmo-slide [options]Commands:
mulmo-slide convert Convert any presentation (auto-detect format)
mulmo-slide marp Convert Marp markdown to MulmoScript
mulmo-slide pptx Convert PowerPoint to MulmoScript
mulmo-slide pdf Convert PDF to MulmoScript
mulmo-slide keynote Convert Keynote to MulmoScript (macOS only)
mulmo-slide movie Generate movie from presentation
mulmo-slide bundle Generate MulmoViewer bundle from presentation
mulmo-slide narrate Generate narrated ExtendedScript (full pipeline)
mulmo-slide extend init Install Claude Code skills (/narrate, /extend)
mulmo-slide extend validate Validate ExtendedScript JSON against schema
mulmo-slide extend scaffold Create ExtendedScript skeleton from MulmoScript
`The
convert command auto-detects file format by extension (.pptx, .md, .key, .pdf).For development, you can also use yarn commands:
`bash
yarn cli marp presentation.md
yarn marp presentation.md # shorthand
`MulmoScript Format
MulmoScript is a JSON-based format that combines images with text for multimedia presentations. It supports multiple image formats:
$3
`json
{
"$mulmocast": {
"version": "1.1",
"credit": "closing"
},
"beats": [
{
"text": "Speaker notes or narration text",
"image": {
"type": "image",
"source": {
"kind": "path",
"path": "/absolute/path/to/slide.png"
}
}
}
]
}
`$3
`json
{
"$mulmocast": {
"version": "1.1",
"credit": "closing"
},
"beats": [
{
"text": "Speaker notes or narration text",
"image": {
"type": "markdown",
"markdown": [
"# Slide Title",
"- Bullet point 1",
"- Bullet point 2"
]
}
}
]
}
`Available Tools
$3
Extracts slides and speaker notes from Apple Keynote presentations.
Usage:
`bash
CLI
mulmo-slide keynote path/to/presentation.keyyarn (development)
yarn keynote path/to/presentation.keyTest with sample
yarn test:keynote
`Requirements:
- macOS
- Keynote installed
- Python 3
Output:
-
scripts/ - PNG images of each slide
- scripts/ - MulmoScript JSON file$3
Extracts slides and speaker notes from Marp markdown presentations, generating both PNG and Markdown formats.
Usage:
`bash
CLI
mulmo-slide marp path/to/presentation.md
mulmo-slide marp path/to/presentation.md -g -l en # with LLM narrationyarn (development)
yarn marp path/to/presentation.md
yarn marp path/to/presentation.md -g -l enTest with sample
yarn test:marp
`Options:
-
-l, --lang - Language for the MulmoScript (en, ja, fr, de)
- -g, --generate-text - Generate narration text using OpenAI LLM
- --theme - Path to custom theme CSS file
- --allow-local-files - Allow local file access in MarpRequirements:
- Node.js
- @marp-team/marp-cli
- Puppeteer (installed automatically)
- OpenAI API key (for
-g option)Output:
-
scripts/ - PNG images of each slide
- scripts/ - MulmoScript JSON file (PNG format)
- scripts/ - MulmoScript JSON file (Markdown format)Features:
- Extracts speaker notes from HTML comments (
)
- Generates both PNG images and structured Markdown output
- Preserves slide formatting and structure$3
Converts plain Markdown files to MulmoScript format with flexible separator options and plugin support.
Usage:
`bash
CLI
mulmo-slide markdown path/to/document.md
mulmo-slide markdown path/to/document.md -g -l ja # with LLM narration
mulmo-slide markdown path/to/document.md -s heading-2 # split by ## headings
mulmo-slide markdown path/to/document.md --mermaid --directive # with pluginsyarn (development)
yarn markdown path/to/document.md
yarn markdown path/to/document.md -s heading --mermaid --style corporate-blue
`Options:
-
-l, --lang - Language for the MulmoScript (en, ja, fr, de)
- -g, --generate-text - Generate narration text using LLM
- -s, --separator - Slide separator mode (see below)
- --mermaid - Convert mermaid code blocks to mermaid beat type
- --directive - Remove Marp-style directives
- --layout - Auto-detect layout based on content (see below)
- --style - Markdown slide style (e.g., corporate-blue, finance-green)Separator Modes:
| Mode | Description | Example |
|------|-------------|---------|
|
horizontal-rule | Split by --- (default) | Marp, reveal.js style |
| heading | Split by any heading | #, ##, ### |
| heading-1 | Split by # only | Top-level sections |
| heading-2 | Split by ## only | Second-level sections |
| heading-3 | Split by ### only | Third-level sections |
| blank-lines | Split by 3+ blank lines | Simple documents |
| comment | Split by | HTML-compatible |
| page-break | Split by | Print-style documents |Layout Auto-Detection (
--layout):When enabled, the converter automatically detects the best layout based on content.
Detection rules are evaluated in order (first match wins):
Phase 1: Header Detection (H1)
If markdown contains an H1 heading (
# Title), it becomes the header and remaining content is analyzed:`
┌─────────────────────────────────────┬─────────────────┬─────────────────────────────────┐
│ Content Pattern │ Layout │ Conditions │
├─────────────────────────────────────┼─────────────────┼─────────────────────────────────┤
│ H1 only │ (no layout) │ Only H1, no other content │
│ │ │ → default markdown (array) │
├─────────────────────────────────────┼─────────────────┼─────────────────────────────────┤
│ H1 + unstructured content │ header+content │ H1 + text without H2/H3 │
│ │ │ → { header, content: [...] } │
├─────────────────────────────────────┼─────────────────┼─────────────────────────────────┤
│ H1 + structured content │ header+row-2 │ H1 + content matching row-2/2x2 │
│ │ header+2x2 │ → { header, "row-2": [...] } │
└─────────────────────────────────────┴─────────────────┴─────────────────────────────────┘
`Phase 2: Content Layout Rules (no H1, or applied to content after H1)
`
┌─────────────────────────────────────┬────────────┬─────────────────────────────────────┐
│ Content Pattern │ Layout │ Conditions │
├─────────────────────────────────────┼────────────┼─────────────────────────────────────┤
│ 1. Single code block + text │ row-2 │ Exactly 1 code block (`) │
│ │ │ Text content > 20 chars │
│ │ │ → [text, code] │
├─────────────────────────────────────┼────────────┼─────────────────────────────────────┤
│ 2. Single image + text │ row-2 │ Exactly 1 image (![]()) │
│ │ │ Text content > 20 chars │
│ │ │ → [text, image] │
├─────────────────────────────────────┼────────────┼─────────────────────────────────────┤
│ 3. 4+ H3 sections (short) │ 2x2 │ 4 or more ### headings │
│ │ │ Avg content < 200 chars │
│ │ │ → first 4 sections │
├─────────────────────────────────────┼────────────┼─────────────────────────────────────┤
│ 4. 4+ H2 sections (short) │ 2x2 │ 4 or more ## headings │
│ │ │ Avg content < 200 chars │
│ │ │ → first 4 sections │
├─────────────────────────────────────┼────────────┼─────────────────────────────────────┤
│ 5. 4+ H2 sections (long) │ row-2 │ 4 or more ## headings │
│ │ │ Avg content >= 200 chars │
│ │ │ → first 2 sections │
├─────────────────────────────────────┼────────────┼─────────────────────────────────────┤
│ 6. 2+ H2 sections │ row-2 │ 2 or more ## headings │
│ │ │ → first 2 sections │
├─────────────────────────────────────┼────────────┼─────────────────────────────────────┤
│ 7. Otherwise │ default │ No layout applied │
└─────────────────────────────────────┴────────────┴─────────────────────────────────────┘
`Notes:
- "Meaningful text" = text without headings > 20 characters
- Multiple code blocks or images → no layout detected
- H3 has no fallback (only 2x2 if short, otherwise no layout)
- H1 always becomes header; remaining content is analyzed for structure
Example:
`bash
Auto-detect layout for better visual presentation
mulmo-slide markdown document.md --layout --style corporate-blue
`Output:
-
scripts/ - MulmoScript JSON file (Markdown format)$3
Converts PowerPoint presentations to MulmoScript format with high-quality PNG exports.
Usage:
`bash
CLI
mulmo-slide pptx path/to/presentation.pptx
mulmo-slide pptx path/to/presentation.pptx -g -l ja # with LLM narrationyarn (development)
yarn pptx path/to/presentation.pptx
yarn pptx path/to/presentation.pptx -g -l ja
`Options:
-
-l, --lang - Language for the MulmoScript (en, ja, fr, de)
- -g, --generate-text - Generate narration text using OpenAI LLMRequirements:
- Node.js
- LibreOffice (used for PPTX to PDF conversion)
- ImageMagick (for high-quality PNG export with antialiasing)
- OpenAI API key (for
-g option)Output:
-
scripts/ - Directory named after input file
- scripts/ - PNG images of each slide
- scripts/ - MulmoScript JSON file$3
Converts PDF files to MulmoScript format with high-quality PNG exports.
Usage:
`bash
CLI
mulmo-slide pdf path/to/presentation.pdf
mulmo-slide pdf path/to/presentation.pdf -g -l ja # with LLM narrationyarn (development)
yarn pdf path/to/presentation.pdf
yarn pdf path/to/presentation.pdf -g -l ja
`Options:
-
-l, --lang - Language for the MulmoScript (en, ja, fr, de)
- -g, --generate-text - Generate narration text using OpenAI LLMRequirements:
- Node.js
- ImageMagick (for high-quality PNG export with antialiasing)
- OpenAI API key (for
-g option)Output:
-
scripts/ - Directory named after input file
- scripts/ - PNG images of each page
- scripts/ - MulmoScript JSON fileMovie Generation
Generate a movie directly from any supported presentation format.
Usage:
`bash
CLI
mulmo-slide movie path/to/presentation.pptx
mulmo-slide movie path/to/presentation.pdf
mulmo-slide movie path/to/presentation.md
mulmo-slide movie path/to/presentation.key # macOS only
mulmo-slide movie path/to/presentation.pptx -f -g -l ja # force regenerate with LLM in Japaneseyarn (development)
yarn movie path/to/presentation.pptx
yarn movie path/to/presentation.pptx -f -g -l ja
`Options:
-
-l, --lang - Language for the MulmoScript (en, ja, fr, de)
- -f, --force - Force regenerate MulmoScript (default: use existing if available)
- -g, --generate-text - Generate narration text using OpenAI LLM (only when generating)This command:
1. Converts the presentation to MulmoScript format (or uses existing)
2. Generates audio and images using mulmocast
3. Creates the final movie
Output:
-
output/ - Movie and related filesBundle Generation
Generate a MulmoViewer bundle directly from any supported presentation format.
Usage:
`bash
CLI
mulmo-slide bundle path/to/presentation.pptx
mulmo-slide bundle path/to/presentation.pdf
mulmo-slide bundle path/to/presentation.md
mulmo-slide bundle path/to/presentation.key # macOS only
mulmo-slide bundle path/to/presentation.pptx -f -g -l ja # force regenerate with LLM in Japaneseyarn (development)
yarn bundle path/to/presentation.pptx
yarn bundle path/to/presentation.pptx -f -g -l ja
`Options:
-
-l, --lang - Language for the MulmoScript (en, ja, fr, de)
- -f, --force - Force regenerate MulmoScript (default: use existing if available)
- -g, --generate-text - Generate narration text using OpenAI LLM (only when generating)This command:
1. Converts the presentation to MulmoScript format (or uses existing)
2. Translates content to multiple languages (ja, en)
3. Generates audio and images
4. Creates a bundle for MulmoViewer (skipZip mode)
Output:
-
output/ - Bundle files for MulmoViewerLanguage Setting
All converters support setting the language for the generated MulmoScript.
Supported languages:
en (English), ja (Japanese), fr (French), de (German)Priority: CLI option > Environment variable > Default (
en)CLI option:
`bash
mulmo-slide pptx presentation.pptx -l ja
mulmo-slide marp presentation.md --lang fr
mulmo-slide keynote presentation.key -l de
`Environment variable:
`bash
export MULMO_LANG=ja
yarn pptx presentation.pptx
`LLM Text Generation
Generate narration text for each slide using OpenAI's GPT-4o model.
Usage:
`bash
PPTX: Uses slide images with Vision API
mulmo-slide pptx presentation.pptx -g -l jaPDF: Uses page images with Vision API
mulmo-slide pdf presentation.pdf -g -l jaMarp: Uses markdown content
mulmo-slide marp presentation.md -g -l enBundle/Movie: Use with -f to regenerate
mulmo-slide bundle presentation.pptx -f -g
`Requirements:
-
OPENAI_API_KEY environment variable must be setHow it works:
- For PPTX/PDF: Converts slides/pages to images and uses OpenAI Vision API to understand content
- For Marp: Uses the markdown content directly
- The LLM considers the overall presentation structure to generate contextual narration
- Output is in the specified language (
-l option)Narrate CLI
Generate a narrated ExtendedScript from any supported source file in one command. This automates the full pipeline: conversion to MulmoScript, LLM-based narration and metadata generation, and validation.
Usage:
`bash
Full pipeline (requires OPENAI_API_KEY)
mulmo-slide narrate paper.pdf
mulmo-slide narrate slides.pptx -l ja
mulmo-slide narrate document.md --mermaid -s headingScaffold only (no LLM, for Claude Code handoff)
mulmo-slide narrate paper.pdf --scaffold-onlyyarn (development)
yarn narrate samples/sample.pdf -l ja
yarn narrate samples/sample.pdf --scaffold-only
`Options:
-
-l, --lang - Language for narration (en, ja, fr, de)
- --scaffold-only - Only create ExtendedScript skeleton (no LLM). Useful as preparation for Claude Code /narrate analysis
- -f, --force - Force regenerate MulmoScript even if it exists
- -s, --separator - Slide separator mode (for Markdown files)
- --mermaid - Convert mermaid code blocks (for Markdown files)Output:
scripts/{basename}/extended_script.json$3
Create an ExtendedScript skeleton from an existing MulmoScript without any LLM calls. This adds beat IDs, empty metadata fields, and imports extracted texts as notes.
`bash
mulmo-slide extend scaffold scripts//.jsonyarn (development)
yarn cli extend scaffold scripts//.json
`Narrate: Source File to Narrated Video (Claude Code Skill)
> Tip: If you don't need interactive analysis and want a fully automated pipeline, use the Narrate CLI instead (
mulmo-slide narrate ). It runs the full pipeline with OpenAI GPT-4o without requiring Claude Code.The
/narrate skill converts any supported source file into a narrated ExtendedScript in one step. It handles the full pipeline: conversion, narration generation, metadata, and validation.$3
Install the Claude Code skills into your project:
`bash
If installed globally
mulmo-slide extend initWith npx
npx @mulmocast/slide extend initDevelopment
yarn cli extend init
`This copies the skill files to
.claude/skills/ in your project directory.$3
In Claude Code, use the
/narrate command with any supported source file:`
/narrate your-paper.pdf
/narrate your-slides.pptx
/narrate your-slides.md
/narrate your-slides.key
`The skill automatically:
1. Converts the source file to MulmoScript (slide images + text extraction)
2. Generates AI narration for each slide
3. Adds metadata (keywords, sections, context, FAQ)
4. Validates the output
5. Shows you the next steps
Output:
scripts/{basename}/extended_script.json$3
`bash
Query the content interactively
npx mulmocast-preprocessor query scripts/{basename}/extended_script.json -iGenerate a summary
npx mulmocast-preprocessor summarize scripts/{basename}/extended_script.jsonGenerate a narrated video
npx mulmocast-preprocessor scripts/{basename}/extended_script.json -o scripts/{basename}/{basename}.json
npx mulmo movie scripts/{basename}/{basename}.json
`$3
Validate an ExtendedScript JSON file against the schema:
`bash
mulmo-slide extend validate scripts/simple_text/extended_script.jsonDevelopment
yarn cli extend validate scripts/simple_text/extended_script.json
`Outputs beat count, scriptMeta presence, meta coverage percentage, and sections found.
$3
If you already have a MulmoScript and just want to add metadata:
`
/extend scripts/simple_text/simple_text.json
`$3
- English: PDF to Narrated Video
- Japanese: PDF からナレーション付き動画
Output Structure
All tools generate MulmoScript output in
scripts/ with a unified structure:`
scripts//
├── images/
│ ├── -0.png (or images.001.png for Marp)
│ ├── -1.png (or images.002.png for Marp)
│ └── ...
├── .json # MulmoScript (all formats)
└── -markdown.json # Marp only: Markdown format
``MIT