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.
• Put one command on each line to make tapes easier to read.

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

For tests, run the actions you want to check and save State or Screenshot checkpoints after waiting for the expected output. For demos, add pauses so viewers can read the result.

Use Wait, Wait+Line, or Wait+Screen to check text before the tape continues. Use Sleep for reading time, or when the application provides no text or prompt to 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 testing modal placement, centering, wrapping, or split panes, start with the default FontSize and Margin. Increase Width and Height if the application needs more space. Use a separate tape for a demo that needs larger text.

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.