Last updated 6 Nov 2026, for version 0.3.1. The commands and output layout below come from the project README and release notes.

Status at a glance

• Install: pip install "yamlreel[ffmpeg]" (Python 3.10 or newer)
• Source: https://github.com/nsijwali/yamlreel (MIT)
• Package: https://pypi.org/project/yamlreel/
• Output: vertical 1080x1920, landscape 1920x1080 and square 1080x1080
• Built with: Python. Core dependencies are pillow, numpy and pyyaml, and ffmpeg comes from the [ffmpeg] extra
• Agent skill: a Claude Code skill drives it for you: https://github.com/nsijwali/yamlreel-video-skills

Why I built it

I make short system-design explainers for YouTube Shorts and LinkedIn, and I wanted to stop opening a video editor every time. Editors make you drag clips around. A video is really a list of scenes, so I made the list the interface. You write the scenes, and the tool does the rest.

The idea: a video is a list of scenes

A spec is a short YAML file. Each scene has a type, a length and optional fields.

meta: {title: "Cache stampede in 45 seconds", tags: [systemdesign, caching]}
theme: midnight
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

Why YAML: the spec is plain text, so it lives in git, diffs cleanly and can be generated or edited by a script. A typo is an error before rendering, not a surprise after ten minutes of encoding.

Try it in five minutes

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

yamlreel init system-design my-video.yaml
yamlreel render my-video.yaml --preview
yamlreel render my-video.yaml

--preview renders at half size and 12 fps, so you can check layout and timing in seconds. The full render writes one folder per format.

yamlreel-output/
├── vertical/
│   ├── video.mp4
│   ├── poster.jpg
│   └── contact.png
└── share-copy.txt

Open contact.png first. It shows two labelled stills per scene, so you can spot overlap or a missing reveal before you upload. share-copy.txt holds the title, description and hashtags, ready to paste.

What it can draw

Let an AI agent drive it

There is also an Agent Skill, yamlreel-video-skills, for Claude Code and compatible clients. You ask for a video, for example "make a 15 second Short about Python f-string debugging", and the agent writes the spec with yamlreel story, previews it, checks the contact sheet and renders the final video. The skill supports macOS and Linux. Windows is untested and unsupported for now. Repo: https://github.com/nsijwali/yamlreel-video-skills

Three decisions worth explaining

Music is generated, not licensed. There are five styles, from plucked strings in a Japanese scale to lo-fi beats. Because the notes are produced on your machine, there is nothing to license or credit.

Subtitles are estimated, and the tool says so. With subtitles: true, narrated scenes get captions that show three to five words at a time with the spoken word highlighted. Without a word-timing file, yamlreel works out timing from the audio by finding loud parts and silent gaps. On a fast 40-second recording the average error was about 0.2 seconds per word. That is an estimate, so the tool prints a warning, and you can supply exact times with narration_words.

Unknown keys are errors. A misspelled field such as titel stops the render with a message that lists the allowed fields. Silent typos are the most annoying bug in a config-driven tool.

Known limits

• Fonts: yamlreel draws text with the free DejaVu fonts. Linux usually has them. On macOS run brew install --cask font-dejavu.
• Voiceover is optional and needs a separate speech server such as VoiceStudio. It is not bundled, and the agent skill renders music only by default.
• Subtitle timing is an estimate unless you provide a word-timing file.

FAQ

Do I need a video editor? No. The output is a finished MP4 with audio.

Does it need the internet? Rendering is local. Only shot scenes that capture a URL need a network.

Can it write the script for me? yamlreel story outline.yaml turns a short outline into a starter spec with a hook, a problem, one scene per step and a question end card. It works offline and gives the same spec for the same outline.

Can I use it commercially? Yes, it is MIT licensed.

Try it and tell me what breaks

Start with the example: examples/cache-stampede-45s.yaml in the repo, rendered with --no-voice. If something looks wrong, open an issue at https://github.com/nsijwali/yamlreel/issues with your system and the spec. Contributors are welcome too.

What else I'm building

Fenceline is a pixel territory game that runs from a single HTML file: https://fenceline.nitinsijwali.com

Last updated 6 Nov 2026. Every snippet below is copied from the shipped file, and the layout and flood-fill bugs were reproduced in headless Chromium tests before I fixed them.

Status at a glance

• Play: https://fenceline.nitinsijwali.com
• Source: https://github.com/nsijwali/fenceline (MIT)
• Board: 96x64 cells in landscape, 64x96 in portrait
• Goal: claim 70% of the board to clear a level
• Tested: desktop Chromium, small portrait and short landscape viewports. Not yet verified on a real iPhone.

The rules, in one paragraph

You walk along the walls. Step into open ground and you draw a fence. Close the loop and everything on the side without enemies becomes yours. Enemies and a pterodactyl try to cut your fence, and you have three lives.

Decision 1: flood fill from the enemies, not from the player

The classic problem is deciding which side of a new fence is "inside". Geometry tricks break on odd shapes. Instead, I flood outward from every enemy through open cells. Whatever the flood cannot reach gets claimed.

while (h < t) {
  const i = q[h++], x = i % W, y = (i / W) | 0;
  if (x > 0     && grid[i - 1] === 0 && !vis[i - 1]) { vis[i - 1] = 1; q[t++] = i - 1; }
  if (x < W - 1 && grid[i + 1] === 0 && !vis[i + 1]) { vis[i + 1] = 1; q[t++] = i + 1; }
  // same for up and down
}
for (let i = 0; i < N; i++) if (grid[i] === 0 && !vis[i]) { grid[i] = 1; filled++; }

Why this works: it handles any number of enemies and any fence shape with one pass over the grid, and there is no polygon maths to get wrong.

Decision 2: pixel look from a handful of tokens

The board is drawn on a canvas as chunky cells, and each level look is a small set of colour tokens per theme. A new look is a few lines of data, not new drawing code. The pixel font is built in multiples of 9px so text stays crisp.

Decision 3: music with WebAudio, scheduled ahead

A setInterval timer is not accurate enough to play notes on time. So a 25 ms timer only schedules notes up to 0.18 s ahead on the audio clock, and the audio clock plays them precisely.

function musicTick() {
  if (!M.on || !AC) return;
  const T = TRACKS[M.track], sp = 60 / T.bpm / 4;
  if (M.nextT < AC.currentTime - .5) M.nextT = AC.currentTime + .05;
  while (M.nextT < AC.currentTime + .18) {
    musicStep(T, M.step, M.nextT);
    M.nextT += sp; M.step = (M.step + 1) % (T.bars.length * 16);
  }
}

The - .5 line is the guard. Browsers throttle timers in background tabs. Without it, the scheduler wakes up far behind the clock and plays a burst of catch-up notes. With it, a stalled scheduler skips ahead and resumes in time.

What broke

The last two came from a reader's comment on the first version of this project. Review from strangers found things my own testing missed.

The bug that was hardest to see

If an enemy overlapped your fence while you were invincible, the cell it stood on became fence. The flood started on a wall, found no open cells, and the enemy's region was treated as unreachable. The game then filled it in and took the enemy's territory for you.

for (const [dx, dy] of [[0,0],[-1,0],[1,0],[0,-1],[0,1]]) {
  const s = idx(cx + dx, cy + dy);
  if (grid[s] === 0) { /* seed here */ }
}

Seeding from the cell and its four neighbours fixes it. The lesson: a flood fill is only as correct as its starting cells.

FAQ

Does it work offline? Yes. It is one file with no network calls.

Does it work on phones? Swipe to move. Portrait and landscape layouts are both handled, but I have only tested them in emulation so far.

Can I fork it? Yes, it is MIT licensed.

How do I win a level? Claim 70% of the board without losing all three lives.

Try it and break it

Play it at https://fenceline.nitinsijwali.com. If something looks wrong on your phone or browser, open an issue at https://github.com/nsijwali/fenceline/issues with your device and what you saw. Those reports are the most useful thing you can send.

What else I'm building

yamlreel is a Python tool that turns one YAML file into a finished video: https://github.com/nsijwali/yamlreel