Skip to content
Betamax

Overview

Betamax turns tape files into terminal artifacts for documentation and tests. A tape describes one terminal session: outputs, requirements, shell settings, typed text, key presses, waits, screenshots, and state snapshots.

The runtime starts a real PTY, feeds terminal bytes into libghostty-vt, renders frames in process with cosmic-text and swash, and writes the requested artifacts. GIF, PNG, screenshot, state JSON, and frame outputs stay inside the Rust process. MP4 and WebM output uses ffmpeg as the video encoder.

Betamax follows the common VHS tape-authoring shape, but it keeps a smaller Ghostty-first architecture. It does not start a browser, terminal server, xterm.js, or ttyd; does not implement VHS’s serve, record, or publish workflows; and parses Source without executing it.

Output Types

Section titled “Output Types”

The same tape model can produce documentation media, review artifacts, and terminal-testing snapshots:

OutputUse case
GIFREADME demos, release notes, and docs pages
PNGFinal-frame previews and static screenshots
MP4 and WebMVideo embeds when GIF size or playback quality matters
Screenshot checkpointsIntermediate frames at meaningful moments in a tape
State JSONTerminal-testing snapshots with viewport, scrollback, and style spans
Frame directoriesDebugging and custom post-processing

Final Output artifacts are written after the tape finishes. Screenshot and State commands write checkpoint artifacts at their position in the tape.

Captions and keyboard overlays are presentation-only media annotations. Presentation Overlays covers captions, on-screen key chips, and placement tradeoffs for visual outputs, so review labels can explain a workflow without changing state JSON.

Tape Model

Section titled “Tape Model”

Most tapes have the same shape:

  1. Output commands declare final artifacts.
  2. Require commands check external programs before terminal work starts.
  3. Set and Env commands configure the shell, environment, dimensions, theme, timing, and frame styling.
  4. Runtime commands type text, press keys, paste content, wait for terminal state, hide or reveal frame capture, and write checkpoint artifacts.

Wait commands match the terminal state reported by libghostty-vt. Wait and Wait+Line match the current cursor line; Wait+Screen matches visible viewport text. That makes a tape depend on terminal output instead of a fixed sleep whenever the next frame has an observable condition.

Documentation Captures

Section titled “Documentation Captures”

Quick Start covers installation and the first rendered tape. Tape Files explains tape structure, tokenization, waits, hidden work, outputs, and shell defaults. Input And Keys covers printable text, navigation keys, shortcuts, interrupts, and on-screen key overlays. Examples maps each checked-in tape to the behavior it demonstrates.

Generated Media Storage covers where rendered files belong when a repository needs stable README media, review artifacts, CI outputs, or web-hosted documentation assets.

Output And Styling Reference

Section titled “Output And Styling Reference”

Outputs documents output commands, checkpoint behavior, frame directories, and the ffmpeg boundary for video files. Themes And Styling covers copied Ghostty themes, theme lookup, terminal dimensions, font size, padding, margin, fill, window bars, border radius, framerate, and playback speed.

The Tape Reference is the exact command surface: supported outputs, settings, defaults, runtime commands, ignored VHS commands, and CLI subcommands.

Terminal Testing

Section titled “Terminal Testing”

Betamax can act as a terminal-testing harness for CLIs and TUIs. A test tape can run an interactive program, wait for expected text, capture screenshots at checkpoints, and write state JSON for snapshot assertions.

Terminal Testing explains the workflow. State JSON documents the snapshot format: viewport rows, optional scrollback, cursor position, terminal dimensions, default style, and non-default style spans.

Compatibility

Section titled “Compatibility”

Betamax currently supports macOS and Linux. Windows is not supported because the upstream libghostty-vt-sys native build does not support Windows.

Video output requires ffmpeg on PATH. Other output formats do not require an external encoder.

Next Pages

Section titled “Next Pages”