Story

/story — Structured MulmoScript Creation

Create compelling MulmoScript through a structured creative process. Present Topic Brief + Beat Outline + Narrations + Visual plan to the user, then assemble the final JSON.

Key principle: Separate what to say (narration) from how to show it (visuals). Never generate both simultaneously.

Phase 1: Research & Understanding

Determine the input source

Ask the user what they want to create content about. Inputs can be:

• URL: Fetch and analyze the page content
• Topic: Research with WebSearch
• File: Read the provided file(s)
• Freeform description: Work directly from the user's description

Web fetching strategy

Try WebFetch first. Only use Playwright MCP when WebFetch fails (403, paywalled, JS-heavy).

1. WebFetch (default): Simple and sufficient for most public pages.
2. Playwright MCP (fallback): browser_navigate + browser_snapshot. Close with browser_close after all browser operations (fetching + image collection).
3. WebSearch (supplement): Gather additional context regardless of the primary fetch method.

If the page has pagination, fetch ALL pages before proceeding.

Conduct deep research

• For URLs: Extract main arguments, key data points, quotes, and structure
• For topics: Search 3-5 sources, cross-reference facts
• For files: Analyze content, identify themes

Collect visual assets

During research, actively download real images. Real images > AI-generated for recognizable subjects.

Store in output/images/{scriptBasename}/:

mkdir -p output/images/{scriptBasename}
curl -fL -o output/images/{scriptBasename}/{name}.jpg "URL"

If using Playwright, collect image URLs with browser_evaluate:

() => Array.from(document.querySelectorAll('img')).filter(img => img.naturalWidth > 200).map(img => ({src: img.src, alt: img.alt || ''}))

Present Topic Brief for approval

## Topic Brief

**Subject**: [one line]
**Target audience**: [who]
**Tone**: [professional / conversational / energetic / serious]
**Orientation**: [landscape (1280×720) / portrait (1080×1920)]
**Key insights** (3-5):
1. ...

**Suggested theme**: [corporate / pop / warm / creative / minimal / dark]
**Collected images** (N found):
- [description]: [local path]

Ask the user about orientation. Default to landscape (1280×720) for presentations and standard videos. Use portrait (1080×1920) for short-form content (TikTok, Reels, Shorts, Stories).

Theme-to-Content Matching

Default to light/bright themes. Dark theme is only for explicitly technical/developer content.

Phase 2: Story Structure

Determine scale

When user asks for condensed/few slides, aim for 3-5 dense beats.

YouTube Shorts constraint: When portrait orientation is selected for Shorts, limit to 3-5 beats with short narrations (1-2 sentences each) to keep total duration ≤ 60 seconds. Each beat typically produces ~8-12 seconds of audio.

Present Beat Outline for approval

## Beat Outline (N beats)

| # | Tag | Summary |
|---|-----|---------|
| 1 | HOOK | ... |
| N | CLOSE | ... |

Phase 3: Narration Writing

Quality standards

GOOD narration: Opens with specific detail, uses sensory language, natural spoken rhythm, each beat advances the story.

BAD narration: Generic statements ("AI is changing the world"), listy recitation, robotic transitions.

Guidelines

• Length: 2-4 sentences per beat (30-60 words)
• Language: Match the lang field
• Flow: Each beat should feel like a natural continuation

Present narrations for approval

Phase 4: Visual Design

Theme selection

Read the theme JSON from assets/slide_themes/{theme}.json and embed in slideParams.theme.

Color scheme discipline

Follow a restrained color palette. Too many colors creates visual noise.

1. Pick 1 base color per presentation (usually primary): Use for headings, sidebars, badges, dividers. Creates visual unity.
2. Add 1-2 highlight colors sparingly: danger/warning only for alarming data; success only for positive metrics. Target specific words or values, not entire sections.
3. Section sidebars share the base color: Don't assign different colors to each sidebar — use primary for all. Differentiation comes from label text.
4. Inline {color:text} is surgical: Highlight 1-2 key terms per bullet. Default text color handles the rest.
5. Metrics encode meaning consistently: Green=positive, red=negative, primary=neutral. Don't use 4 colors for 4 metrics unless each encodes different meaning.

BAD (rainbow sidebars):

{ "type": "section", "label": "A", "color": "primary" },
{ "type": "section", "label": "B", "color": "accent" },
{ "type": "section", "label": "C", "color": "warning" }

GOOD (unified base + surgical accent):

{ "type": "section", "label": "A", "color": "primary" },
{ "type": "section", "label": "B", "color": "primary" },
{ "type": "section", "label": "C", "color": "primary" }

Then inside bullets: "Key point about {danger:critical risk} and normal context"

Slide density by beat count

Fill space with visuals: In any density, if a panel has room, add imageRef, imagePrompt, chart, or mermaid. Never leave panels empty.

Layout selection guide

DSL reference and patterns

For layout/block specifications, Read slide_dsl_reference.md in this skill directory.

For design pattern examples (dense slides, charts, mermaid), Read slide_patterns.md in this skill directory.

Image embedding

Define images in imageParams.images, then reference with imageRef blocks in slide content:

{ "type": "imageRef", "ref": "keyVisual", "alt": "Description", "fit": "contain" }

Path formula: From scripts/samples/ to output/images/ = ../../output/images/{basename}/{filename}.

For AI-generated images when no real counterpart exists, use imagePrompt in imageParams.images (object form — defines a named image for imageRef to reference):

{ "type": "imagePrompt", "prompt": "Detailed description..." }

For image-only beats without slide layout, use imagePrompt as a beat-level string field (generates a standalone background image):

{ "text": "Narration", "imagePrompt": "Detailed prompt..." }

Animated beats (html_tailwind animation)

For beats that benefit from motion — cinematic intros, opening crawls, data visualizations, 3D effects — use html_tailwind animation instead of static slides or imagePrompt.

Read docs/llm/html_animation_reference.md for the full API reference (MulmoAnimation DSL, interpolate, Easing, property types).

When to use animation

Animated beat structure

{
  "image": {
    "type": "html_tailwind",
    "html": ["<div id='el' style='opacity:0'>...</div>"],
    "script": [
      "const animation = new MulmoAnimation();",
      "animation.animate('#el', { opacity: [0, 1], translateY: [30, 0] }, { start: 0, end: 0.5, easing: 'easeOut' });"
    ],
    "animation": true
  }
}

Key rules:

• html: HTML markup with Tailwind CSS (no <script> tags). Set initial styles inline (e.g., style='opacity:0')
• script: JavaScript code (no <script> tags). Use MulmoAnimation DSL or raw render() + interpolate()
• animation: true (30fps) or { "fps": 15 } for custom fps
• Do NOT set duration — it is auto-calculated from the audio length. Setting it explicitly causes audio/video desync. Only set duration for silent beats or fixed-length intros.
• Name the MulmoAnimation instance animation to enable auto-render (no manual render() needed)
• Use end: 'auto' for animations that span the entire beat duration

Mixing animated beats with slides

Animated beats can be freely mixed with slide beats and imagePrompt beats in the same script. When mixing, ensure slideParams.theme is present for any slide beats.

Present visual plan for approval

Phase 5: Assembly & Review

Select BGM

Choose background music from the mulmocast-media BGM catalog that matches the story mood:

URL pattern: https://github.com/receptron/mulmocast-media/raw/refs/heads/main/bgms/{name}

Select the BGM that best matches the tone from Phase 1's Topic Brief, and add it to audioParams.

Combine narrations + visuals into MulmoScript JSON

Note: The template below shows commonly used beat fields. If you need a field not listed here, run npx mulmo tool schema to verify it exists in the schema before adding it. The beat schema is strict — unrecognized fields will cause validation errors.

{
  "$mulmocast": { "version": "1.1" },
  "lang": "en",
  "canvasSize": { "width": 1280, "height": 720 },  // portrait: { "width": 1080, "height": 1920 }
  "title": "Title",
  "description": "Brief description",
  "references": [{ "url": "...", "title": "...", "type": "article" }],
  "speechParams": { "speakers": { "Presenter": { "voiceId": "shimmer" } } },
  "audioParams": {
    "bgm": { "kind": "url", "url": "https://github.com/receptron/mulmocast-media/raw/refs/heads/main/bgms/story001.mp3" },
    "bgmVolume": 0.15
  },
  "slideParams": { "theme": { } },
  "imageParams": { "provider": "google", "images": { } },
  "beats": [
    {
      "text": "Narration",
      "speaker": "Presenter",
      "image": {
        "type": "slide",
        "slide": { "layout": "...", "..." : "..." },
        "reference": "Source: ... (optional)"
      }
    }
  ]
}

Add reference to data-citing beats

For beats showing statistics or research findings, add "reference": "Source: ..." to the image object.

Quality checklist

1. Hook test: Does beat 1 grab attention?
2. Density test: Does every slide match the target density for its beat count?
3. Specificity test: Replace vague statements with concrete numbers, names, examples.
4. Visual variety: At least 2-3 different layout types used.
5. Visual-narration alignment: Each visual directly supports its narration.
6. Image check: Real images used for recognizable subjects; AI-generated only for abstract concepts.
7. Schema compliance: Version "1.1", proper beat structure.

Write the file and present output

Generate the movie directly — yarn movie automatically generates images and audio as well, so separate yarn images / yarn audio steps are unnecessary.

yarn movie --grouped <filename>

Wrote: <filename>

Summary:
- N beats, [theme] theme
- Key topics: [brief list]

Output: output/video/<basename>.mp4