Tape Files

A tape file describes one terminal capture session. It lists outputs, startup settings, terminal actions, waits, checkpoints, and metadata in the order Betamax should execute them.

File Structure

Most tapes divide into three parts:

1. Outputs, requirements, environment, and startup settings.
2. Ordered terminal actions such as typing, key presses, and waits.
3. Optional screenshots, state captures, hidden cleanup, and shell exit.

Output examples/output/basic.gif
Require printf

Set Shell "bash"
Set Theme "Aardvark Blue"
Set Width 900
Set Height 480
Set FontSize 28

Type "printf 'hello\n'"
Enter
Wait+Screen "hello"

Notes

Startup commands must appear before runtime commands because Betamax needs the shell, terminal dimensions, theme, environment, and output requirements before PTY startup.

Tokenization

Tapes use shell-like tokenization for each non-comment line. Quote strings that contain spaces, newlines, regex characters, ANSI escapes, or shell syntax.

• Blank lines are ignored.
• Lines whose trimmed form starts with # are comments.
• Multiple commands may appear on one line.
• One command per line is usually easier to review by hand.

Type "printf 'hello from betamax\n'"
Wait+Screen "hello from betamax"
Wait+Screen "/item-[0-9]+/"

Type "printf 'done\n'"
Enter
Wait+Screen "done"

Token Rules

• Quote values with spaces.
• Use regex waits for changing output.
• Keep generated tapes compact only when review does not matter.

Synchronization

Prefer waits over long sleeps. A sleep records whatever happens for a fixed amount of time; a wait records until expected terminal text exists or the timeout expires.

Type "cargo test --quiet"
Enter
Wait+Screen "test result:"

Tip

Use Wait+Screen for command output and full-screen TUIs.

Validation And Review Media

Most tapes have one primary job. Validation tapes exercise a user journey, wait for semantic screen state, and write focused State or Screenshot checkpoints for assertions. Example and review-media tapes make a stable state readable for humans in a GIF, video, or PR artifact.

Waits are assertions and synchronization points. Use Wait, Wait+Line, or Wait+Screen to name the state that must exist before the tape continues. Sleeps are presentation pacing after that state is true, unless the application has no semantic text or prompt that Betamax can wait for.

Type "my-app --demo"
Enter
Wait+Screen "Ready"
Screenshot target/review/ready.png
Sleep 500ms

Pacing

• Use 300-500 ms before submission when a GIF should feel human.
• Use 300-700 ms after simple UI transitions.
• Use 1.5-2.5 seconds for stable simple screens.
• Use reading-time-based holds for dense output.
• Use 4-5 seconds only for final GIF states or equivalent review endpoints.

Presentation And Layout Proof

Larger FontSize, Margin, window bars, and border radius are presentation choices. They make a demo easier to read, but they also change the terminal grid and available layout space.

When a tape proves modal placement, centering, wrapping, or split-pane behavior, start with the default FontSize and Margin. Increase Width and Height when the proof needs a wider canvas. Use a separate review-media tape when the same journey also needs zoomed presentation.

Set Width 1600
Set Height 900
Wait+Screen "Preview"
Screenshot target/layout/proof.png

Hidden Work

Hide and Show are visibility controls, not execution controls. Hidden commands still run in the PTY, update terminal state, and can be waited on.

Hide
Type "cargo build --quiet"
Enter
Wait
Show

Remember

Show immediately captures the current terminal frame, avoiding a visible flicker from setup work to useful output.

Outputs During A Tape

Output describes final artifacts written after execution. Screenshot and State write checkpoint artifacts immediately at their position in the tape.

Wait+Screen "Saved profile"
Screenshot target/snapshots/profile.png
State target/snapshots/profile.state.json

Review

Pair a GIF with a final PNG or checkpoint screenshot so reviewers can inspect one frame without opening an animation.

Shell Defaults

For common shells such as bash, zsh, and fish, Betamax starts a clean recording-oriented environment where possible. The default prompt behavior aims for VHS-like output: a simple > prompt rather than host-specific prompts such as bash-5.3$.

Set Shell "bash"
Set Shell "zsh -f"
Set Shell "fish --private"

Compatibility

See Differences From VHS for the compatibility boundary.