{
  "markdown": "# notes-to-video\n\n[![GitHub stars](https://img.shields.io/github/stars/cymcymcymcym/notes-to-video.svg?style=social)](https://github.com/cymcymcymcym/notes-to-video)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![npm](https://img.shields.io/npm/v/notes-to-video.svg)](https://www.npmjs.com/package/notes-to-video)\n[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey.svg)]()\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-skill-blueviolet.svg)](https://claude.com/claude-code)\n\nTurn notes (LaTeX, PDF, or plain text) into animated explainer videos in the style popularized by 3Blue1Brown — using Manim, TTS, and ffmpeg.\n\n<p align=\"center\">\n  <img src=\"docs/teaser.gif\" alt=\"Change your notes into a 3Blue1Brown-style video\" width=\"720\">\n</p>\n\nA [Claude Code](https://claude.com/claude-code) skill that handles the full pipeline: content extraction, narration writing with cue markers, Manim scene generation with audio-video sync, validation, rendering, and composition.\n\n## Demo\n\nFeed it lecture notes, get an animated explainer video. **🔊 Turn sound on** — the video has narration.\n\n<table>\n<tr>\n<td width=\"40%\" align=\"center\"><strong>Input: CS229 Lecture Notes</strong></td>\n<td width=\"60%\" align=\"center\"><strong>Output: Animated Explainer</strong></td>\n</tr>\n<tr>\n<td>\n\n<picture>\n  <source media=\"(prefers-color-scheme: dark)\" srcset=\"docs/cs229_vae_notes_dark.png\">\n  <img src=\"docs/cs229_vae_notes.png\" alt=\"CS229 VAE lecture notes\" width=\"100%\">\n</picture>\n\n*Section 11.5 — Variational Auto-Encoder*\n*[CS229 Lecture Notes](https://cs229.stanford.edu/main_notes.pdf) — Andrew Ng & Tengyu Ma, Stanford University*\n*Used as demo input with attribution.*\n\n</td>\n<td>\n\n<video src=\"https://github.com/user-attachments/assets/c2c9d8b3-cdeb-429d-8b9d-ec9a97bf57a1\" poster=\"docs/vae_thumbnail.png\" controls style=\"max-height:400px; width:100%;\"></video>\n\n*🔊 Sound on. 3 min video, generated from notes in one command. [Download](https://github.com/cymcymcymcym/notes-to-video/releases/download/v1.0.0/vae_explainer_captioned.mp4)*\n\n</td>\n</tr>\n</table>\n\n## Install\n\nThis is a Claude Code skill, not a standalone CLI. The npm package is a one-shot installer that drops the skill files where Claude Code can find them.\n\n**1. Install the skill files:**\n\n```bash\nnpx notes-to-video\n```\n\nThis copies:\n- `skills/notes-to-video/` → `~/.claude/skills/notes-to-video/`\n- `video_utils/` → `~/tools/video_utils/` (shared Python helpers the skill imports)\n\nRe-run any time to upgrade.\n\n**2. Set up the Python environment** (one-time, shared across projects):\n\n```bash\npython3 -m venv ~/tools/.venv\n~/tools/.venv/bin/pip install manim edge-tts pydub faster-whisper\n# Optional: chatterbox-tts (local voice cloning), torch with CUDA\n```\n\n**3. (Optional) Add API keys** for cloud TTS backends:\n\n```bash\nmkdir -p ~/tools/credentials\ncat > ~/tools/credentials/.env <<'EOF'\nMINIMAX_API_KEY=...\nMINIMAX_GROUP_ID=...\nOPENAI_API_KEY=...\nEOF\n```\n\n### Alternative install methods\n\n**Claude Code plugin:**\n```bash\n/plugin marketplace add cymcymcymcym/notes-to-video\n/plugin install notes-to-video@notes-to-video-marketplace\n```\n\n**Manual:** clone this repo, copy `skills/notes-to-video/` to `~/.claude/skills/` and `video_utils/` to `~/tools/video_utils/`.\n\n## Quick Start\n\n1. Open Claude Code in your project and ask:\n   ```\n   make a 3b1b-style video from my_notes.tex\n   ```\n\n2. Claude will:\n   - Extract key concepts from your notes\n   - Write a narration script with cue markers\n   - Generate Manim scenes synced to the narration\n   - Validate all scenes for visual issues\n   - Hand you the build command\n\n## Features\n\n- **Notes to video pipeline** — feed in LaTeX, PDF, or plain text notes, get animated explainer videos\n- **Audio-video sync** — cue-based system that synchronizes Manim animations to narration timestamps\n- **CText kerning fix** — workaround for Manim's broken Pango kerning ([manim #2844](https://github.com/ManimCommunity/manim/issues/2844))\n- **4 TTS backends** — Edge-TTS (free, default), MiniMax (best quality), Chatterbox (local + voice cloning), OpenAI\n- **Scene validator** — catches text overlaps, out-of-bounds elements, text overflow, and line-through-text issues before rendering\n- **Cross-platform** — Linux, macOS, Windows\n\n## TTS Options\n\n| Backend | Quality | Cost | Requirements |\n|---------|---------|------|-------------|\n| **Edge-TTS** (default) | Good | Free | None |\n| **MiniMax** | Best | ~$0.04/min | API key |\n| **Chatterbox** | Good + voice cloning | Free | NVIDIA GPU |\n| **OpenAI TTS** | Good | ~$0.06/min | API key |\n\n## How It Works\n\nThe core innovation is the **cue-based audio-video sync system**:\n\n1. Narration is written with `{CUE_NAME}` markers at visual event points\n2. TTS generates per-sentence audio and estimates cue positions by character ratio\n3. Manim scenes read cue timestamps and sync animations accordingly\n4. `until()` fills gaps with slow animations, `sync()` waits for exact cue times\n\nThis produces smooth, naturally-paced videos where animations fire exactly when the narrator says the relevant keyword.\n\n## Project Structure\n\nEach video is a self-contained `<project>/` subfolder. Adding a second video is zero migration — just create another.\n\n```\nfinal/                               # THE DELIVERABLE — what you watch/share\n  <project>/\n    <project>.pdf                    # source paper, if applicable\n    <project>.mp4                    # final video\n    <project>.srt                    # soft subtitles (sidecar)\n    <project>_captioned.mp4          # optional: burned-in captions\n\nintermediate/                        # everything else (heavy; .gitignore by default)\n  <project>/\n    src/\n      video_<project>.py             # Manim scenes\n      part_<project>_narration.py    # narration with {CUE} markers\n      generate_tts_<project>.py      # TTS runner\n      build_<project>.py             # render + mux + caption\n      assets/<project>/*.png         # extracted source figures\n    audio/video_<project>/           # TTS output + durations.json\n    media/videos/video_<project>/    # manim render cache\n    review/video_<project>/          # validator screenshots\n    output/                          # per-scene muxed MP4s\n    plan_<project>.md                # scene-by-scene plan\n```\n\nThe skill ships with:\n\n```\nvideo_utils/                # Bundled library (→ ~/tools/video_utils/ on install)\n  manim_helpers.py          # CText, colors, sync helpers\n  tts_edge.py              # Edge-TTS (free, default)\n  tts_minimax.py           # MiniMax TTS (cloud)\n  tts_local.py             # Chatterbox + Whisper (local)\n  tts_openai.py            # OpenAI TTS (cloud)\n  validate_scenes.py       # Scene validator\n  captions.py              # SRT generator\n\nskills/notes-to-video/\n  SKILL.md                 # Claude Code skill definition\n```\n\n## Acknowledgments\n\n- **[Manim Community](https://www.manim.community/)** — the animation engine this project is built on. Manim was originally created by [Grant Sanderson](https://www.3blue1brown.com/) (3Blue1Brown) and is now maintained by the Manim Community (MIT License).\n- **[3Blue1Brown](https://www.3blue1brown.com/)** — the visual style this project emulates. Grant Sanderson's videos set the standard for mathematical explainer animation.\n- **[CS229 Lecture Notes](https://cs229.stanford.edu/main_notes.pdf)** — Andrew Ng & Tengyu Ma, Stanford University. Used as source material for the VAE demo video (Section 11.5), with attribution.\n\n**Disclaimer:** This project is not affiliated with, endorsed by, or sponsored by 3Blue1Brown, Grant Sanderson, Stanford University, or the Manim Community. \"3Blue1Brown\" is used here as a descriptive reference to the visual style.\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n",
  "bytes": 7969,
  "sha": "f8713d38632d67bf5b103761867302f8c2d7b473fd249363d5b2f883d52a1958",
  "repo_slug": "cymcymcymcym/notes-to-video",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_cymcymcymcym_notes_to_video_notes_to_vid_5382e9a0/readme"
}