manim-reel

reelgen — Text → Reels/Shorts Explainer Videos

Turn text content into polished 9:16 explainer videos for Reels, Shorts, and TikTok — animated Manim visuals, a Deepgram voiceover, and captions synced to the audio. Give it a storyboard; it gives you a finished .mp4.

---

Table of contents

1. What you get
2. Prerequisites
3. Install
4. Quick start
5. Make your own video
6. The six layouts
7. CLI reference
8. Using the Claude Code skill
9. Troubleshooting
10. How it works
11. Project structure
12. Tests

---

What you get

• 1080×1920, 30 fps vertical video — the native Reels/Shorts/TikTok size.
• A Deepgram Aura voiceover generated from your text.
• Captions synced to the audio — each line appears with the words spoken.
• 48 kHz stereo AAC audio, loudness-normalized — plays everywhere.
• Safe-zone-aware layout, so titles and captions never collide with platform UI.

---

Prerequisites

Need	Notes
Python 3.10+	python --version
FFmpeg	Must be on your PATH. Check: ffmpeg -version
Deepgram API key	For the voiceover. Free key at https://console.deepgram.com/. Optional — without it, reels still render with silent (correctly-timed) narration.

---

Install

1. Install the engine

git clone https://github.com/Yash-Kavaiya/manim-reels-youtube.git
cd manim-reels-youtube
pip install -e .            # installs reelgen + manim

2. Add your Deepgram key

cp .env.example .env
#   then edit .env and set:  DEEPGRAM_API_KEY=your_key_here

.env is git-ignored — your key never gets committed.

3. (Optional) Install the manim-reel skill for Claude Code

So you can just ask Claude "make a reel about <topic>" instead of writing storyboards by hand.

As a plugin — inside Claude Code:

/plugin marketplace add Yash-Kavaiya/manim-reels-youtube
/plugin install manim-reel@reelgen

Or with the install script — copies the skill into ~/.claude/skills/:

bash skills.sh

---

Quick start — render the example

A ready-made 7-scene storyboard ships in examples/. Render it:

python -m reelgen build examples/harness-ai-agents.json --out output/demo.mp4

When it finishes you'll see:

[OK] Reel ready: output/demo.mp4
     1080x1920 @ 30fps  | 43.5s  | audio: yes  | voice: deepgram

Open output/demo.mp4 — that's a complete reel with voiceover and captions.

Tip: add --preview to render at half resolution ~4× faster while you iterate, then drop it for the final export.

---

Make your own video

A video is described by a storyboard JSON file — a list of scenes. You write the storyboard; reelgen renders it. You never write Manim code.

Step 1 — Create a storyboard

Save a file like storyboards/my-topic.json:

{
  "title": "What is an API",
  "handle": "@yourhandle",
  "voice": "aura-2-thalia-en",
  "scenes": [
    {
      "layout": "title",
      "narration": "Ever wondered how apps talk to each other? Let us break it down.",
      "visual": { "title": "What is an API?", "subtitle": "The messenger of software" }
    },
    {
      "layout": "steps",
      "narration": "Your app sends a request. The API delivers it. The server replies.",
      "visual": {
        "heading": "How it flows",
        "items": ["App sends a request", "API delivers it", "Server replies"]
      }
    },
    {
      "layout": "outro",
      "narration": "That is an API. Simple. Follow for more.",
      "visual": { "title": "Now you know APIs", "cta": "Follow for more" }
    }
  ]
}

Writing rules that keep the render clean:

• Each sentence of narration becomes one on-screen caption line.
• Don't use abbreviations with periods — write AI, US, eg, not A.I., U.S., e.g. (a period always ends a caption line).
• Aim for ~100–140 words total across all scenes → a ~40–50 s reel.
• For steps / diagram / comparison, write roughly one sentence per item so reveals stay in sync with the narration.

Step 2 — Validate it

python -m reelgen validate storyboards/my-topic.json

valid: 3 scenes, layouts=['title', 'steps', 'outro']

Fix any error it reports (it points at the exact scene).

Step 3 — Preview (fast)

python -m reelgen build storyboards/my-topic.json --out output/my-topic.mp4 --preview

Half-resolution, quick. Check the layout and timing.

Step 4 — Final render

python -m reelgen build storyboards/my-topic.json --out output/my-topic.mp4

Full 1080×1920. Done.