mega-shot — type an idea, get a finished video

mega-shot turns a request like "make a 90-second vertical video about why the sea is salty" into a finished,
publish-ready video: researched script → cloned narration voice → visuals in the style you pick → karaoke subtitles →
music and sound effects → high-quality export + phone preview → automatic quality checks → titles, description,
hashtags, chapters, subtitles (SRT) and thumbnails.

It works two ways:

• As a Claude Code skill (recommended): just say what video you want — Claude researches, writes, builds and checks it for you
  (behind the scenes it writes the video's script file, video.yaml, and runs the xp CLI).
  Other coding agents (Codex, Cursor, Gemini CLI, …) can use it through AGENTS.md.
• As a plain CLI: write the script file (video.yaml) yourself and run xp narrate → xp render → xp export.

Features

Gallery

Made with mega-shot

Real frames from videos produced end-to-end with mega-shot — footage with live captions, a 3D depth HUD, code-built 3D,
a 3D product cutaway, old paintings in 2.5D, manifesto typography, stick-figure stories and flat 2D explainers.

Animated subtitles & titles

Word-timed karaoke subtitles (7 styles) and title animations (8 styles), springs and easing driven by the narration.
Works in any language — the preview below is Vietnamese, with full diacritics.

Subtitle styles	Title styles

Thumbnails that get clicked

Eleven thumbnail styles — cut-out subject, big words, versus, red circle, breaking news, poster, cinematic and more.

Characters, drawn in code

Cartoon characters with poses, expressions and lip-sync — no image AI needed. One rig, many drawing styles, plus animal
mascots and 3D people for history and explainer scenes.

Drawing styles · one rig	Animal friends

Talking characters	3D people

Requirements

Tested on Windows 11. macOS and Linux work for the core pipeline (setup handles FFmpeg, VoiceStudio and Chromium there too).

Install

# A) as a personal Claude Code skill (available in every project)
git clone https://github.com/stevenguyenbt/mega-shot ~/.claude/skills/mega-shot

# B) or inside one project
git clone https://github.com/stevenguyenbt/mega-shot <project>/.claude/skills/mega-shot

Then, from your project folder (any empty folder works — it will hold .mega-shot/ and videos/):

~/.claude/skills/mega-shot/xp setup          # Windows: %USERPROFILE%\.claude\skills\mega-shot\xp.cmd setup

xp setup checks everything, starts VoiceStudio if it is installed, and prints NEEDS YOUR INPUT — the items you
decide on. Nothing large is installed without your approval: run xp setup --install chromium,fonts (etc.) for what
you want, and xp setup --policy once you agree to automatic licensed downloads. Put your keys in .env
(copy .env.example). Tip: add alias xp=~/.claude/skills/mega-shot/xp to your shell profile.

With Claude Code, just open the project and ask for a video — copy docs/CLAUDE.project.md
into your project's CLAUDE.md so the AI always runs setup and asks the style first.

Your first video in 5 minutes

No API keys and no voice model needed — this uses the blank Canvas template and a recording you make yourself.

cd my-project
xp setup --install chromium                  # once
xp new hello --template blank --format 9x16
cd videos/hello

Edit video.yaml (English keys):

name: hello
format: 9x16
language: en
scenes:
  - id: opening
    heading: Hello, mega-shot
    narration: This is my first video made with mega-shot.
  - id: main-idea
    heading: One file, one video
    extra: 1.5
    narration: Everything you see comes from a single YAML file.

Record one WAV per scene (seg1.wav, seg2.wav in a folder — or let VoiceStudio narrate with xp narrate), then:

xp narrate --import-from ~/recordings/hello   # or: xp narrate   (VoiceStudio)
xp preview                                    # look at build/thu.jpg
xp mix && xp render && xp export && xp check

Result: out/hello_9x16.mp4 (upload quality), out/hello_9x16_xem_thu.mp4 (phone preview), publishing notes in
out/. Next: docs/getting-started.md for the real-footage workflow with research,
fact-checking, stock search and thumbnails.

How it works

video.yaml ──► xp narrate ──► build/audio/*.wav + word timestamps ──► build/timeline.json
     │              (VoiceStudio TTS, Whisper listen-back)                  │
     ├──► xp assets / art / hf / blender ──► footage, drawn layers, 3D, graphics
     │                                                                      ▼
film.html + engine/ (Canvas 2D · Three.js · stills · text FX) ──► xp render (headless Chromium, per-scene cache, WebCodecs)
     │                                                                      ▼
xp mix (voice + music + SFX, −14 LUFS) ──► xp export (upload file + preview + publish pack + SRT) ──► xp check

Details: docs/architecture.md.

Documentation

FAQ (short)

• Why are some names Vietnamese? The project was built in Vietnamese. Every command, flag and YAML key now has an
  English name; the Vietnamese names still work so existing videos never break. Some internal file names
  (build/thu.jpg = preview sheet, giay_phep.json = licence book) are explained in docs/yaml-reference.md.
• Does it need the cloud? No. Everything runs locally; network is used only for stock search/downloads you allow,
  and optional APIs (YouTube, your own posting adapter).
• Can I use my own voice? Yes — xp voice add <audio-or-video> --name me --consent (only voices you own or have permission to clone).
• More in docs/faq.md.

Credits

mega-shot stands on the shoulders of these open-source projects — thank you:

• huashu-art-motion by alchaincyf (MIT) — the drawn explainer
  grammars (whiteboard, stick-figure story, flat 2D, collage, kinetic typography, math/concept) and the 35 painterly art
  styles shown in the style gallery (styles 3–9).
• huashu-motion by Huashu (MIT) — the motion-language library
  (references/chuyen-dong/) and the ABC-notation composer used by xp nhac.
• lemo-opuscar by LemoLab (MIT) — the Evidence Films styles and director guide (references/evidence/).
• img2threejs (Apache-2.0) — ideas for the 3D material/geometry kit and reference-review workflow.
• blender-skills contributors (MIT) — Blender craft guides (references/blender/).
• VoiceStudio (AGPL-3.0, separate program), three.js,
  Playwright, FFmpeg, faster-whisper,
  HyperFrames, uv.
• Footage and images in the galleries come from open sources (Pixabay, NASA and other public-domain archives, Wikimedia Commons).

Full list with licences: THIRD_PARTY_NOTICES.md.

Contributing & licence

Contributions welcome — see CONTRIBUTING.md, CODE_OF_CONDUCT.md and
SECURITY.md. mega-shot is released under the MIT licence. Assets, voices and music you put in
your videos keep their own licences — mega-shot logs them, you are responsible for respecting them.

Support

mega-shot is free and will stay free. If it saved you a few hours of editing and you'd like to say thanks,
you can buy me a coffee ☕ — completely optional.
A ⭐ on the repo, a bug report, or sharing a video you made with it helps just as much. Thank you!