Overview

Betamax records terminal sessions as GIFs, screenshots, videos, and JSON snapshots. A tape file specifies the commands to run, text to type, output to wait for, and files to save. Start with Quick start to install Betamax and render your first tape.

Betamax runs commands in a PTY, parses their output with libghostty-vt, and renders frames with cosmic-text and swash. It writes images and state JSON in the Rust process. MP4 and WebM encoding uses ffmpeg.

Many commands will be familiar to VHS users. Betamax does not need a browser or terminal server. VHS’s serve, record, and publish features are not implemented. Betamax parses Source but returns an error if a tape tries to execute it.

Output types

A tape can save several formats from the same session:

Output	Use case
GIF	Animated demos in READMEs, release notes, and docs
PNG	A screenshot of the final frame
MP4 and WebM	Video embeds
Screenshot checkpoints	Images captured at specific points in a tape
State JSON	Assertions on terminal text, scrollback, cursor, and styles
Frame directories	Debugging and custom processing of individual frames

Betamax writes Output files after the tape finishes. Screenshot and State save checkpoints when the tape reaches those commands.

Captions and keyboard overlays add explanations and key labels to visual outputs. They do not change state JSON.

Tape model

1. Declare final outputs with Output.
2. Check required programs with Require.
3. Configure the shell, environment, dimensions, theme, and timing with Set and Env.
4. Type text, press keys, and wait for output. Add screenshots or state checkpoints where needed.

Wait commands check terminal text before continuing. Wait and Wait+Line match the current cursor line; Wait+Screen matches the visible viewport. Use waits when the next action depends on output from the previous one.

Writing tapes

Tape files explains syntax, waits, hidden setup, and shell defaults. Input and keys covers typing, navigation, shortcuts, and interrupts. Examples has tapes you can copy and adapt.

For exact syntax and defaults, see the tape reference. Outputs explains file formats and checkpoints. Themes and styling covers colors, fonts, dimensions, and window decoration. Generated media storage explains where to store and host the resulting files.

Testing terminal applications

A test tape can run an interactive program, wait for expected text, and save state JSON for snapshot assertions. Screenshots help you inspect failures. See Terminal testing for setup and State JSON for the snapshot format.

Compatibility

Betamax supports macOS and Linux. Windows is not supported because the upstream libghostty-vt-sys native build does not support Windows.

Video output requires ffmpeg on PATH. Other output formats do not require an external encoder.