Betamax is a Rust-first terminal capture tool in the spirit of VHS. It reads tape files, runs commands in a PTY, feeds terminal output through libghostty-vt, rasterizes frames in process with cosmic-text and swash, and writes screenshots or animations.

The goal is VHS-style output without the browser/server/xterm.js stack. The current implementation intentionally does not include serve, record, source, or publish.

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

Install the CLI with Homebrew from joshka/homebrew-tap:

brew install joshka/tap/betamax

If Homebrew requires trusted taps, trust the formula first:

brew trust --formula joshka/tap/betamax

Or install from crates.io with cargo-binstall:

cargo binstall betamax

If cargo-binstall is not installed, install it first:

cargo install cargo-binstall

Source installs are mainly for maintainers. Betamax uses the safe libghostty-vt Rust wrapper; its libghostty-vt-sys dependency fetches a pinned Ghostty source commit and runs Zig 0.15.2 to build the native VT library. In a checkout, use mise to get the pinned toolchain:

mise install
mise run install-local

Other toolchain managers can work too, including Nix or a manually installed Zig 0.15.2 on PATH. mise is the documented path because it works for this repository today. The specific Zig version is an upstream Ghostty build requirement until Ghostty supports newer Zig releases such as 0.16.

For local development or source checkouts, run from the workspace:

cargo run -- run examples/basic.tape

Render all local examples:

mise run render-examples

MP4 and WebM output require ffmpeg on PATH:

# macOS
brew install ffmpeg

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install ffmpeg

The script writes files under examples/output and copies them to target/betamax-examples for local inspection. The GIF previews below are hosted as GitHub Release assets so they can render on GitHub and crates.io without storing generated media in the source tree.

Output examples/output/basic.gif

Set Shell "bash"
Set Theme "Aardvark Blue"
Set FontSize 28
Set Width 900
Set Height 480
Set Margin 12
Set WindowBar Colorful
Set BorderRadius 8

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

Type "printf 'hello from betamax\n'"
Enter
Wait+Screen "hello from betamax"
Hide
Type "exit"
Enter

Hide and Show are useful for VHS-style tapes that hide setup or compile work and only reveal the interesting terminal state. See the Tape Reference for the full command and settings behavior.

The checked-in examples are small smoke-test tapes that demonstrate core behavior:

The video tape writes GIF, MP4, and WebM from the same captured frames. The GIF preview is shown here; the video files are generated next to it.

List available themes:

cargo run -- themes
cargo run -- themes --json

Theme lookup searches user Ghostty theme directories first, then the copied themes in crates/betamax-core/resources/ghostty/themes.

Betamax aims for the common VHS authoring flow, but the architecture is intentionally smaller and Ghostty-first. See Differences From VHS for the full comparison and remaining parity notes.

The main tradeoff today is video output: MP4 and WebM use ffmpeg as a focused encoder bridge. Terminal execution and rasterization stay in process; video container encoding does not.

Betamax can also be used as a terminal testing harness. A tape can run an interactive terminal program, wait for text on the screen, capture PNG screenshots at checkpoints, write structured terminal state, and fail when expected terminal output does not appear before a timeout.

See Terminal Testing and State JSON for the test workflow and state snapshot format.

Questions, early ideas, and examples of Betamax in real projects belong in Discussions. If Betamax helped you make a demo, test a terminal UI, document a CLI, or replace part of an existing workflow, please share a screenshot, rendered tape, repo link, or short note in Show and tell.

• Documentation Site
• Tape Reference
• Terminal Testing
• State JSON
• Differences From VHS
• Contributing
• Development
• Security Policy
• Support

The Starlight docs site lives under site/ and can be run locally with:

pnpm install
mise run docs-site-dev