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.

See Generated Media Storage for guidance on keeping rendered media out of source control and publishing stable documentation assets.

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.

Use Presentation Overlays when generated visual media should explain a workflow step or review checkpoint without changing terminal behavior. Captions render on visual outputs only; they do not appear in state JSON. Captions share a bottom presentation row with keyboard overlay chips when both are active.

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.

Validation And Review Artifacts

Validation artifacts should be easy to assert automatically. Prefer State checkpoints or final state JSON for the behavioral contract, and add checkpoint screenshots when the visual frame helps debug failures.

Review-media artifacts should be easy for a human to inspect. Pair animated GIF or video output with a final PNG or a checkpoint screenshot whose path describes the state, so reviewers can cite one stable frame without scrubbing an animation. Place checkpoint outputs immediately after a semantic wait:

Wait+Screen "Profile saved"
State target/snapshots/profile-saved.json
Screenshot target/review/profile-saved.png
Sleep 2s

In review media, sleeps after waits are presentation pacing. Use 300-700 ms after simple transitions, 1.5-2.5 seconds for stable simple screens, and 4-5 seconds only for final review endpoints. Dense output needs a reading-time-based hold instead of a fixed one-size pause.

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.

Captions

Captions annotate rendered media without changing the terminal session. They are useful when a GIF or screenshot needs to explain hidden setup, a review checkpoint, or a step in a TUI flow. See Presentation Overlays for keyboard chips and placement tradeoffs. Keep semantic checks in waits and state outputs; captions are presentation metadata.

When a tape uses captions, Betamax reserves a bottom presentation row before deriving the terminal grid. Captions render below the terminal canvas instead of covering terminal rows. They are left-aligned with the terminal frame edge and remain single-line; if a caption needs to share space with right-aligned keyboard overlay chips, Betamax truncates it with ... instead of wrapping. Caption glyphs are clipped to their reserved width as a final guard for font fallback and unusually wide characters.

Caption "Step 1: prepare the review frame"
Hide
Type "my-app --demo"
Enter
Wait+Screen "Ready"
Show
Sleep 700ms

Caption "Step 2: capture the ready state"
Screenshot target/snapshots/ready.png
State target/snapshots/ready.json

Caption ""
Sleep 300ms

The caption remains active until the next Caption command. Use Caption "" before later frames that should not have an overlay. Quote caption text that contains spaces.

Caption has no duration and does not capture a frame by itself. It changes the caption used by the next rendered visual frame: animation frames captured during later Sleep, Wait, typing, keys, Show, or final-frame output, and checkpoint screenshots captured by Screenshot. If the terminal is already stable and only the caption changed, add Sleep after Caption so GIF and video outputs hold that caption for a visible amount of time.

Captions render on visual outputs: GIF, PNG, MP4, WebM, frame directories, and screenshots. They do not appear in state JSON or change final output dimensions.