🎬 showreel

One CLI to turn terminal recordings into everything.

Reads asciicast v1 / v2 / v3 (including asciinema 3.x recordings that most tools can't touch). Writes animated SVG, MP4 / WebM / MKV with real chapters, GIF / APNG, a self-contained HTML player, transcripts, subtitles and more — with vhs-style beauty presets on top.

uv tool install showreel

This is not a video and not a GIF — it's a single animated SVG. It is typing itself character by character right now: watch the loading bar fill in place and the cursor run ahead of the text. One .svg file, zero JavaScript, exported with one command.

showreel svg demo.cast -o demo.svg --preset pretty --chrome "showreel demo" \
  --watermark "made with showreel" --typewriter 50 --cursor-blink 530

Prefer pixels? The same recording as a GIF

Built for humans and AI agents. Every text command prints to stdout, every file command prints its path, showreel info gives stable JSON — and ships with a skill that teaches coding agents how to drive it.

Why

You recorded your terminal with asciinema — a perfect .cast file. Now what? asciinema itself has no SVG/video export, and the existing converters are stuck in the past:

showreel keeps the good ideas (agg's knob set, svg-term's CSS animation, termtosvg's window frames, vhs's aesthetics) in one dependency-light Python tool.

Install

uv tool install showreel        # fast
pipx install showreel           # classic
pip install showreel            # boring

Needs Python ≥ 3.10. Video/GIF/APNG export needs ffmpeg on PATH (brew install ffmpeg / apt install ffmpeg).

Quick start

asciinema rec demo.cast              # record something

showreel info demo.cast               # metadata + markers as JSON
showreel svg demo.cast                # → demo.svg   self-contained animated SVG
showreel video demo.cast              # → demo.mp4   H.264 with chapters
showreel gif demo.cast                # → demo.gif   palette-optimized, loops
showreel html demo.cast               # → demo.html  offline player, no CDN
showreel all demo.cast -o out/        # → everything + manifest.json

Text commands (text, md, subs, chapters) print content to stdout unless you pass -o; file commands print the output path. Progress goes to stderr, exit codes are 0/1 — pipe freely.

Commands

Examples — one recording, every format

Everything below lives in examples/ and was produced by two commands (see examples/README.md for the exact ones). The animated SVG at the top of this page is examples/demo.svg — the same file your terminal exports.

Then compare the same recording across formats:

Time control (every command)

--start 10 --end 25   # trim; pre-start history still shapes the first frame
--from-marker build --to-marker deploy   # agg-style marker selection (exact or unique prefix)
--speed 2             # faster playback
--idle-limit 3        # compress pauses longer than 3s

Make it beautiful

One flag for the full look, or compose your own:

showreel gif demo.cast -o demo.gif --preset pretty --chrome "deploy" --watermark "@you"

Chapters, properly

Touch the m key during asciinema rec (v3) and showreel turns markers into:

• Matroska/MOV chapters inside MKV/MP4 — VLC, mpv and IINA show them, seeking is instant;
• YouTube chapter lists (0:00 entry added automatically, as YouTube requires);
• WebVTT chapter tracks and JSON;
• seek buttons in the exported HTML player.

No markers? --chapters auto:30 (video) or chapters --auto 30 cuts one every 30 seconds.

For AI agents 🤖

showreel ships with a ready-made skill — copy skills/showreel/SKILL.md into your agent's skill directory (or point it at this repo) and it will know how to: convert recordings, extract timestamped transcripts for context, cut clips by marker, and embed demos in docs. Highlights agents rely on:

showreel info rec.cast                 # stable JSON schema
showreel text rec.cast --mode timed    # [hh:mm:ss] ANSI-free transcript on stdout
showreel all rec.cast -o out/          # deterministic names + sha256 manifest
cat rec.cast | showreel gif - -o r.gif # stdin works

Exit codes 0/1, progress on stderr, paths/content on stdout. The full contract lives in AGENTS.md — for building showreel and for driving it.

How the SVG works

Each output event is replayed through the pyte terminal emulator; the screen is diffed row by row, and every changed row becomes a <g> group — background <rect> plus styled runs — popped in by a declarative SMIL <set> at the event's timestamp. Every glyph gets an absolute x position on the cell grid, so nothing shifts or jitters regardless of the viewer's fonts. The cursor is a live element: it follows the typing inside per-event visibility windows, then settles at the prompt and blinks forever. Later rows paint over earlier ones, so history accumulates like a real terminal. One file, zero JavaScript, plays anywhere SVG animates — browsers, <img> tags, README embeds.

Limitations

• The emulator keeps the header's terminal size; mid-recording resizes are recorded but not re-flowed.
• Full-screen TUI apps (vim, htop) can render with artifacts — pyte doesn't swap the alternate screen buffer.
• WebM carries no chapters (not in the spec) — use MKV/MP4.
• No emoji font fallback in rendered frames yet.

Development

git clone https://github.com/forcewake/showreel && cd showreel
uv sync                # deps + editable install
uv run pytest          # test suite (ffmpeg tests auto-skip)

Architecture and hard-won gotchas are documented in AGENTS.md. PRs welcome — especially new themes and output formats.

Acknowledgements

• asciinema by Marcin Kulik — the recording format and the reference agg
• pyte — the terminal emulator core
• vhs — the aesthetics bar this project steals from, openly

License

MIT © Pavel Nasovich