Tape Files

A tape is a small script that describes one terminal session. It names output artifacts, configures the terminal, starts a shell in a PTY, sends text and keys, waits for stable terminal states, and optionally writes checkpoint screenshots or state JSON.

Start here for authoring concepts. Use the Tape Reference for the exact command surface and Examples for copyable tapes.

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"

File Structure

Most tapes follow this order:

1. Declare Output files.
2. Declare Require checks for external commands used by the tape.
3. Apply Env and Set startup configuration.
4. Run terminal actions such as Type, key presses, waits, screenshots, and state captures.
5. Hide trailing cleanup with Hide, then type exit if the shell should close cleanly.

Startup commands must appear before runtime commands. This is intentional: Betamax needs to know the shell argv, terminal dimensions, theme, environment, and output requirements before it starts the PTY or creates capture state.

Tokenization

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

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

Blank lines are ignored. Lines whose trimmed form starts with # are comments. Multiple commands may appear on one line, which is useful for compact generated tapes:

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

For hand-written tapes, one command per line is usually easier to review.

Synchronization

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

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

Use Wait+Line or bare Wait for prompts. Use Wait+Screen for command output, full-screen TUIs, and text that may not be on the cursor line. Use regex waits when the output contains changing numbers, paths, durations, or identifiers.

Hidden Work

Hide and Show are visibility controls, not execution controls. Hidden commands still run in the PTY, still update terminal state, and can still be waited on. They simply do not append frames to animated outputs.

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

Type "my-cli --demo"
Enter
Wait+Screen "Ready"

Show immediately captures the current terminal frame. That avoids a visible flicker from a hidden shell prompt to the 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

For testing, pair a wait with a checkpoint state file. For documentation, 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 explicitly when a tape depends on shell syntax:

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

Shell argv is split with shell-like rules, so a single Set Shell string can contain the program and arguments.