yamlreel

Write a short YAML file. Get a finished video.

yamlreel turns a YAML file into a finished video: system-design explainers, code tips, project launches and feature demos for YouTube, Shorts and LinkedIn, with diagrams, typed code, original music and an optional voiceover in your own voice.

▶ Watch the 1-minute demo: a video about yamlreel, made by yamlreel from one YAML file, with no video editor.

_{Every scene of examples/cache-stampede-45s.yaml, rendered from one YAML file.}

What you get

Every render writes this layout (the output folder is yamlreel-output/ unless you pass --out DIR):

yamlreel-output/
├── vertical/            one folder per format: landscape 1920×1080, vertical 1080×1920, square 1080×1080
│   ├── video.mp4        H.264 (+ AAC when there is music or a voice). Frame 0 is the poster, so the thumbnail is never blank.
│   ├── poster.jpg       the settled hook frame, ready to upload as a thumbnail
│   └── contact.png      two labelled stills per scene: look at this before you publish
└── share-copy.txt       title, description and hashtags for the whole video, ready to paste

share-copy.txt adds #Shorts for vertical clips up to 60 seconds. Videos can be any length, and only a vertical video over 3 minutes gets a warning. Music is generated on your machine (plucked strings in a Japanese scale), so there is nothing to license or credit.

Quick start

You need Python 3.10 or newer. pip installs everything else except fonts on macOS and Windows (see the note below).

python3 -m venv .venv && source .venv/bin/activate
pip install "yamlreel[ffmpeg]"

Prefer an isolated command-line install? pipx install "yamlreel[ffmpeg]" works too. (The vidgen package on PyPI is unrelated to this project, which was called vidgen before 0.2.)

Make your first video:

yamlreel init system-design my-video.yaml     # a starter spec (or: project, code-tip)
yamlreel render my-video.yaml --preview       # half size, 12 fps: check layout and timing in seconds
yamlreel render my-video.yaml                 # full quality, every format in the spec

Open yamlreel-output/<format>/contact.png first. To try the showcased example without setting up a voice:

curl -LO https://raw.githubusercontent.com/nsijwali/yamlreel/main/examples/cache-stampede-45s.yaml
yamlreel render cache-stampede-45s.yaml --no-voice

Fonts on macOS and Windows: yamlreel draws text with the free DejaVu fonts, which most Linux systems include. On macOS run brew install --cask font-dejavu once. On Windows, install them from dejavu-fonts.github.io ("Install for me" is fine).

Examples

It is narrated; add --no-voice to render it with music only. For more starting points, run yamlreel init with the system-design, project or code-tip template.

Commands

Writing a spec

A spec is a list of scenes. Each scene has a type, how many seconds it lasts, and an optional caption (a lower third that fades in).

meta: {title: "Cache stampede in 45 seconds", tags: [systemdesign, caching]}
theme: midnight                     # sumi | washi | midnight | your own
formats: [vertical, landscape]
scenes:
  - type: type
    text: What is a cache stampede?
    seconds: 3
  - type: bullets
    title: The fix
    items: [Let one request rebuild the key, Serve stale while it refreshes, Add jitter to every TTL]
  - type: stat
    value: "10,000 → 1"
    label: database queries per expiry

meta: {title, description, tags: [], links: [], credits: []}
theme: sumi | washi | midnight | <a theme from your config>
formats: [vertical, landscape, square]
music: {style: koto | none | path/to.mp3, bpm: 72, root: D, scale: hirajoshi, seed: 7, snap: false, volume: 0.9}
watermark: "Your Name"        # or {text|image: logo.png, position: top-left|top-right|bottom-left|bottom-right, opacity: 0.75, size: 30}
poster: {scene: 0, at: 2.6}   # optional; default is the first scene, just before it ends
voiceover: {voice, language, gap, music_level, read_screen}
scenes: [...]

Tips

• Text never silently overflows. It wraps, then shrinks, and render warns you when it had to.
• In vertical frames, content sits above the lower third, clear of the Shorts UI.
• A 15-second video carries one idea. Before you publish, check anything you simplified.

Voiceover in your own voice

Give a scene a narration: line and yamlreel speaks it, lowers the music under the voice, and makes the scene as long as the speech needs. Speech comes from a text-to-speech server running on your own machine, for example VoiceStudio, which can also clone your voice from a short recording.

scenes:
  - type: type
    text: What is a cache stampede?
    narration: Ever seen one expired cache key take down a whole database? That's a cache stampede.
  - type: title
    title: Cache stampede
    narration: false          # silent end card

Write narration, don't read the screen. The voice sounds natural when it explains what the viewer sees, in a sentence or two. read_screen: true (or --read-screen) speaks every title, bullet and caption word for word, for scenes without their own narration:. That is fine as a quick draft, but it sounds robotic in a finished video. --no-voice renders any spec with music only.

Configuration

Defaults live in a config file, so a spec only needs to say what is different for that video. You can adapt yamlreel to your own name, colours and music without touching code.

yamlreel config init            # ./yamlreel.config.yaml: this project (add it to your .gitignore)
yamlreel config init --user     # ~/.config/yamlreel/config.yaml: every project
yamlreel config show            # the merged settings, and the files they came from

Settings apply in this order, lowest to highest: built-in defaults → user config → project config → the spec → command-line flags. Nested settings merge, so setting only music.bpm keeps the rest. meta.tags, links and credits add up across layers.

What you can set: theme, your own themes (colours, extends, display: serif | sans, frame), formats, fps, output_dir, watermark (text or a logo), music, voiceover, meta defaults and limits. Your name, watermark and default tags belong in config, not in code. Every option is explained in yamlreel/templates/config.example.yaml.

A few settings widen what a spec can touch, so yamlreel only reads them from your user config or the command line, never from a spec or project config you downloaded: allow_paths, allow_private_hosts, chromium_path, font_dir and voice_server. See SECURITY.md.

Troubleshooting

Built with

If you publish a video voiced with OmniVoice, credit it and keep it non-commercial: its licence (CC-BY-NC) requires both, and VoiceStudio's audio tokenizer has its own terms (see Licences above). yamlreel puts a spec's meta.credits into share-copy.txt for you.

Why yamlreel

• Manim is excellent for math animation, but each animation is code you write. yamlreel is a spec: you describe scenes, not frames.
• Remotion renders video from React and is very flexible. yamlreel trades that flexibility for zero JavaScript and a fixed set of scene types.
• MoviePy edits and composes video clips you already have. yamlreel generates frames and music itself and adds an optional voiceover.
• Online AI video tools are quick but run in the cloud, usually cost money, and your script and voice leave your machine. yamlreel runs locally and is MIT licensed.

Contributing

Bug reports, new scene types, examples and docs are welcome. See CONTRIBUTING.md for setup and the pull request flow.

Development

git clone https://github.com/nsijwali/yamlreel.git
cd yamlreel
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev,ffmpeg]'
pytest -q

Tests never read your own user or project config. Checks that need ffprobe, Playwright or Chromium are skipped when those tools are missing. CI runs on Ubuntu with Python 3.10 and 3.12.

Security and licence

Specs are treated as untrusted input. File access is confined, URL captures are checked, and settings that widen access come only from you. SECURITY.md covers the details and how to report a vulnerability.

yamlreel is MIT licensed. Tools you pair it with keep their own licences.