Outputs

A single tape can write several artifacts from the same captured terminal session. This is useful when one run should produce a README GIF, a final-frame PNG for quick inspection, and state JSON for snapshot tests.

See the Tape Reference for extension validation and the exact command syntax.

Output	Command example	Written when	Encoder
GIF	Output demo.gif	After the tape finishes	In process
PNG final frame	Output demo.png	After the tape finishes	In process
State JSON	Output demo.json	After the tape finishes	In process
MP4	Output demo.mp4	After the tape finishes	ffmpeg
WebM	Output demo.webm	After the tape finishes	ffmpeg
Frame directory	Output target/frames	After the tape finishes	In process PNGs
Screenshot	Screenshot checkpoint.png	At that command	In process
Checkpoint state	State checkpoint.json	At that command	In process

Choosing Outputs

Use GIF for documentation and release notes. Use PNG screenshots when a human needs to review a single stable state. Use state JSON when a test should compare text, scrollback, cursor metadata, and styles without doing pixel comparisons.

Frame directories are useful when debugging capture timing or feeding rendered frames to custom tooling. The path must not have an extension; Output target/frames writes numbered PNG files under that directory.

Video Encoding

MP4 and WebM use ffmpeg as a focused encoder boundary. Terminal execution, terminal parsing, rendering, GIF encoding, PNG encoding, and state JSON writing are in process. Betamax only requires ffmpeg when the tape requests .mp4 or .webm.

Install it with:

# macOS
brew install ffmpeg

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install ffmpeg

Use Require ffmpeg if the tape should fail before doing any other work:

Output examples/output/demo.mp4
Require ffmpeg

Checkpoints

Checkpoint outputs happen in the middle of a run. They are the right tool for tests and for documenting multi-step workflows.

Type "my-app --demo"
Enter
Wait+Screen "Ready"
Screenshot target/snapshots/ready.png
State target/snapshots/ready.json

The screenshot preserves the decorated visual frame. The state JSON preserves terminal text and styles in a compact comparison format.