VHS

VHS includes a built-in SSH server. When self-hosted, you can access the server as if VHS were installed locally, allowing you to run commands and applications hosted on that server to generate GIFs remotely.

1. Start the server:

   vhs serve

2. Access from a remote machine:

   ssh vhs.example.com < demo.tape > demo.gif

Server Configuration Environment Variables

Use Set TypingSpeed <time> to define the global delay between characters. You can override this for specific commands using the @<time> syntax appended to the Type command.

Set TypingSpeed 0.1
Type "100ms delay per character"
Type@500ms "500ms delay per character"

VHS tapes use a scripting language to simulate user input and timing. Use the following commands to drive the terminal:

• Type "<text>": Simulates typing the specified string into the terminal.
• Enter: Simulates pressing the Enter key.
• Space: Simulates pressing the Space bar.
• Sleep <duration>: Pauses the execution for a specified amount of time (e.g., 500ms, 2s, 5s).

Type "neofetch"
Sleep 500ms
Enter
Sleep 2s
Type "Welcome to VHS!"

You can control the visual properties of the terminal emulator within a .tape file using Set commands. Common configuration options include:

• Set TypingSpeed <duration>: Controls how fast text is typed (e.g., 75ms).
• Set FontSize <size>: Sets the terminal font size (e.g., 22).
• Set Width <pixels>: Sets the terminal width in pixels (e.g., 1300).
• Set Height <pixels>: Sets the terminal height in pixels (e.g., 650).

Set TypingSpeed 75ms
Set FontSize 22
Set Width 1300
Set Height 650

Use Hide to stop capturing frames and Show to resume. This allows you to perform setup or cleanup tasks (like building a binary or deleting files) without those actions appearing in the final video/GIF.

Output example.gif

# Setup (not recorded)
Hide
Type "go build -o example . && clear"
Enter
Show

# Recording (captured)
Type 'Running ./example'
Enter

# Cleanup (not recorded)
Hide
Type 'rm example'
Enter

You can generate .tape files automatically by recording your actual terminal session.

1. Start recording:

   vhs record > cassette.tape

2. Perform your terminal actions.
3. Type exit to stop the recording.
4. (Optional) Manually edit cassette.tape to refine settings or actions.
5. Generate the GIF from the recorded tape:

   vhs cassette.tape

VHS can be integrated into CI pipelines using the official GitHub Action: charmbracelet/vhs-action.

Additionally, VHS is suitable for integration testing by using .txt or .ascii output formats to generate 'golden files'. By storing these output files in your git repository, you can verify that subsequent runs of a .tape file produce no diffs, ensuring consistent behavior.

Output golden.ascii

VHS uses .tape files to script terminal animations. Follow these steps to create a GIF:

1. Initialize a new tape file:

   vhs new demo.tape

2. Edit the tape file: Open demo.tape in your editor and add commands (e.g., Output, Set, Type, Sleep, Enter).
3. Generate the GIF: Run the tape file through the VHS CLI.

   vhs demo.tape

Example .tape file content:

# Where should we write the GIF?
Output demo.gif

# Set up a 1200x600 terminal with 46px font.
Set FontSize 46
Set Width 1200
Set Height 600

# Type a command in the terminal.
Type "echo 'Welcome to VHS!'"

# Pause for dramatic effect...
Sleep 500ms

# Run the command by pressing enter.
Enter

# Admire the output for a bit.
Sleep 5s

VHS requires ttyd and ffmpeg to be installed and available on your PATH. You can install VHS using various package managers or via Docker.

Package Managers

• macOS/Linux (Homebrew): brew install vhs
• Arch Linux: pacman -S vhs
• Nix: nix-env -iA nixpkgs.vhs
• Windows (Scoop): scoop install vhs
• Windows (Winget): winget install charmbracelet.vhs
• Go: go install github.com/charmbracelet/vhs@latest

Docker

Run VHS directly with all dependencies included:

docker run --rm -v $PWD:/vhs ghcr.io/charmbracelet/vhs <cassette>.tape

The Options struct allows you to customize the recording environment. You can modify fields such as FontFamily, FontSize, TypingSpeed, Theme, and Video settings. Use DefaultVHSOptions() to get a baseline configuration.

Key configuration areas include:

• Typography: FontFamily, FontSize, LetterSpacing, LineHeight.
• Terminal Behavior: TypingSpeed, CursorBlink, WaitTimeout, WaitPattern.
• Video/Output: Video (framerate, dimensions, style) and Screenshot options.
• Looping: LoopOffset to adjust the start of a looping video.

opts := main.DefaultVHSOptions()
opts.FontSize = 18
opts.TypingSpeed = 100 * time.Millisecond
vhs := main.New()
vhs.Options = &opts

The Set <Setting> Value command configures global aspects of the terminal. Most settings must be administered at the top of the tape file; applying them after non-setting or non-output commands will cause them to be ignored.

Set Shell fish
Set FontSize 20
Set FontFamily "Monoflow"
Set Width 300
Set Height 1000
Set LetterSpacing 20
Set LineHeight 1.8
Set Padding 0
Set Margin 60
Set MarginFill "#6B50FF"
Set BorderRadius 10
Set WindowBar Colorful
Set Framerate 60
Set PlaybackSpeed 1.0
Set LoopOffset 5
Set CursorBlink false