Examples

The repository examples are intentionally small. They are smoke tests for core behavior and copyable starting points for your own tapes. Render all examples from a checkout with:

mise run render-examples

Some examples drive other programs, such as cargo-binstall and btop. Their Require lines stop the render with the missing program’s name; install it and rerun.

Generated files are written under examples/output and copied to target/betamax-examples for local inspection. The previews on this page are hosted as GitHub Release assets; curated site previews may also live under site/public/assets with Git LFS. See Generated media storage for the full storage guidance.

Example index

The ratatui-diff-* tapes drive an external viewer: set BETAMAX_DIFF_VIEWER to a built ratatui-diff binary before running them.

Getting started

Tape	Demonstrates	Docs
quick-start.tape	installing, help, new, and nested run	Quick start
basic.tape	typing, waits, theme, window bar, border radius	Tape files
hide-show.tape	hidden setup and hidden trailing cleanup	Hidden work
source.tape	sharing commands between tapes with Source	Source

Input and waits

Tape	Demonstrates	Docs
waits.tape	line, screen, regex, and default prompt waits	Wait commands
keys.tape	key commands, repeats, editing, and interrupt	Input and keys
clipboard-env.tape	Env, Copy, and Paste	Tape reference
mouse-input.tape	clicks, drags, and wheel input decoded by a real program	Mouse commands
viewport-scroll.tape	ScrollUp and ScrollDown through scrollback	Scrolling

Outputs

Tape	Demonstrates	Docs
outputs.tape	GIF, PNG, JSON, screenshot, state, frame directory	Outputs
screenshot.tape	screenshots and terminal state JSON	Checkpoints
scrollback.tape	scrollback-inclusive state JSON	State JSON
webp.tape	lossless WebP animation with uneven holds	WebP encoding
video.tape	GIF, MP4, and WebM from one capture	Video encoding
video-timing.tape	frame timing in GIF and MP4 output	Video encoding

Text rendering

Tape	Demonstrates	Docs
text-styles.tape	ANSI styles, truecolor, and styled state spans	State JSON
text-decorations.tape	underline and strikethrough	State JSON
faint-text.tape	faint (SGR 2) text on dark and light backgrounds	Themes and layout
cell-graphics.tape	box drawing and block elements that join across cells	Fonts
themes.tape	copied Ghostty themes and palette mapping	Theme lookup
sp-night.tape	bundled SP Night theme in a custom frame	SP Night themes

Window styling

Tape	Demonstrates	Docs
presets-default.tape	the same scene with Default; also presets-framed, -bare, -inset, -default-0.1	Presets
layout.tape	padding, margin, fill, window bar, radius	Window styling
rows-columns.tape	terminal size in cells with Columns/Rows	Sizing in cells
margin-gradient.tape	linear gradient backdrop	Margin and backdrop
margin-sides.tape	per-side margins in CSS shorthand order	Per-side margins
margin-image.tape	an image as the backdrop	Images
margin-transparent.tape	transparent backdrop in PNG, WebP, and GIF	Transparency
margin-transparent-caption.tape	captions and chips over a transparent backdrop	Transparency
window-chrome.tape	bar color, title, border, corners, shadow	Window styling
window-bar-color.tape	window bar color	Window bar
window-title.tape	a static window title	Window titles
window-title-from-app.tape	OSC titles from the app and the tape	Window titles
window-border.tape	window border	Border, corners, and shadow
window-shadow.tape	drop shadow	Border, corners, and shadow
window-cell-boundaries.tape	borders and corners around whole terminal cells	Border, corners, and shadow

Presentation overlays

Tape	Demonstrates	Docs
captions.tape	captions for review media	Presentation overlays
keyboard-overlay.tape	keyboard chips; also -top-left, -top-right, -bottom-left	Keyboard overlays
presentation-overlays.tape	captions plus keyboard overlay layout	Presentation overlays
overlays.tape	captions and chips on the default preset	Presentation overlays

Testing a real app

Tape	Demonstrates	Docs
btop.tape	a full-screen TUI with braille graphs	Require
ratatui-diff-ux.tape	selecting and copying in a Ratatui diff viewer	Visual development
ratatui-diff-mouse.tape	mouse selection in the diff viewer	Visual development
ratatui-diff-multi-file.tape	navigation, scrolling, and resize across files	Visual development
ratatui-diff-resize.tape	redraw after Resize	Resize
ratatui-diff-unicode.tape	wrapped Unicode selection	Visual development
ci-interaction.tape	paste and edit, proved by state JSON	GitHub Action
ci-playback.tape	hidden setup with measured playback holds	GitHub Action

Preview GIFs

These previews come from the example tapes above.

Quick start

quick-start.tape shows the full first-run path: install check, help output, creating a starter tape, inspecting it, running it, and listing the generated GIF.

btop

btop.tape records btop, a full-screen system monitor that redraws constantly with truecolor gradients, braille graphs, and box drawing. It walks the process list, hides and restores the network box, and opens the main menu. The tape starts with Require btop, so it fails before recording when btop is not installed.

Basic

basic.tape is the smallest useful demo: it sets a portable shell, chooses Aardvark Blue, types one command, waits for the result, and hides shell cleanup.

Hide and show

hide-show.tape runs setup without recording it. Setup updates terminal state, and Show starts the animation with the prepared screen.

Captions

captions.tape annotates rendered media without changing the terminal session. Caption changes are presentation metadata: waits and state outputs keep matching the terminal itself. Captions render in a reserved presentation row below the terminal canvas.

Keyboard overlay

keyboard-overlay.tape shows typed commands and key presses as compact labels over generated media. See Presentation overlays for overlay modes and placement. Labels appear when input is queued and linger briefly after typing, which keeps review GIFs readable without turning the overlay into a permanent command log.

presentation-overlays.tape combines captions and keyboard overlay chips. The caption is left-aligned with the terminal frame, key chips are right-aligned, and long captions are truncated with ... rather than wrapped over the chips. Caption glyphs are clipped to their reserved width as a final guard for font fallback and unusually wide characters.

Themes

themes.tape shows ANSI colors mapped through a bundled Ghostty theme. Use betamax themes to list the names available to Set Theme.

Video

video.tape writes GIF, MP4, and WebM from one capture. The GIF is encoded in process; MP4 and WebM are handed to ffmpeg.

Example patterns

Use examples/outputs.tape when checking artifact behavior. It writes a GIF, a PNG, final state JSON, a PNG frame directory, a checkpoint screenshot, and checkpoint state JSON.

Use examples/scrollback.tape and examples/text-styles.tape when evaluating terminal testing. Together they exercise the parts of state JSON that matter for snapshot tests: viewport text, scrollback text, default style, non-default style table entries, and styled spans.

Use examples/waits.tape when debugging timing. It shows the three wait targets and a custom WaitPattern, which is usually preferable to adding sleeps.