VHS — Record Terminal Sessions as GIFs and Videos

Introduction

VHS treats terminal recordings as code. Instead of screen recording (which produces inconsistent results), you write a .tape script that specifies exactly what to type, when to pause, and how the terminal looks. VHS replays this script in a virtual terminal and captures the output as a clean, reproducible GIF or video.

With over 19,000 GitHub stars, VHS is part of the Charmbracelet suite (makers of Bubble Tea, Lip Gloss, Glow) and has become the standard tool for creating terminal demos in project READMEs and documentation.

What VHS Does

VHS reads .tape files that contain a sequence of commands: Type (simulate typing), Enter, Sleep, and configuration directives (font size, colors, window size). It runs these in a headless terminal emulator, records the output frame by frame, and renders the result as GIF, MP4, or WebM.

Architecture Overview

[.tape File]
Declarative recording script
Type, Enter, Sleep, Set
        |
   [VHS Engine (Go)]
   Parses tape file
   Controls virtual terminal
        |
   [ttyd + headless browser]
   Terminal emulator
   renders each frame
        |
   [ffmpeg]
   Encodes frames to
   GIF, MP4, or WebM
        |
   [Output]
   demo.gif / demo.mp4
   Ready for README

Self-Hosting & Configuration

# demo.tape — full-featured example
Output demo.gif

# Terminal settings
Set FontSize 16
Set FontFamily "JetBrains Mono"
Set Width 1200
Set Height 600
Set Theme "Dracula"
Set Padding 20
Set Framerate 30

# Simulate a development workflow
Type "git status"
Enter
Sleep 1s

Type "go test ./..."
Enter
Sleep 3s

Type "go build -o myapp"
Enter
Sleep 1s

Type "./myapp serve --port 8080"
Enter
Sleep 2s

# Special keys
Ctrl+C
Sleep 500ms

Type "echo Done!"
Enter
Sleep 1s

# Output formats
vhs demo.tape                    # default: GIF
vhs demo.tape -o demo.mp4        # MP4 video
vhs demo.tape -o demo.webm       # WebM video

# Multiple outputs
# Add to tape file:
# Output demo.gif
# Output demo.mp4

# Validate tape file
vhs validate demo.tape

# Create tape from template
vhs new demo.tape

Key Features

• Recordings as Code — declarative .tape scripts, version-controllable
• Multiple Formats — GIF, MP4, WebM output
• Customizable — font, theme, window size, framerate, padding
• Reproducible — same script always produces the same recording
• Special Keys — Ctrl, Alt, Tab, Arrow keys, and more
• Themes — built-in terminal themes (Dracula, Monokai, etc.)
• CI/CD Ready — generate recordings in CI pipelines
• No Screen Recording — no manual recording or editing needed

Comparison with Similar Tools

FAQ

Q: VHS vs asciinema — which should I use? A: VHS for reproducible, scripted recordings (perfect for READMEs and docs). asciinema for recording actual terminal sessions with real output and sharing via asciinema.org.

Q: Can I use my actual shell and tools? A: Yes. VHS runs commands in a real shell. Any tool installed on your system works — your actual git, go, npm, etc. The output is from real command execution.

Q: How do I make smaller GIFs? A: Reduce Width/Height, lower Framerate (15 is often sufficient), and keep recordings short. Use MP4/WebM for longer recordings — they are much smaller than GIFs.

Q: Can I use VHS in GitHub Actions? A: Yes. Install VHS in your CI, run "vhs demo.tape", and commit or upload the generated GIF. This keeps your README demos always up-to-date with the latest code.

Sources

• GitHub: https://github.com/charmbracelet/vhs
• Documentation: https://github.com/charmbracelet/vhs#readme
• Created by Charmbracelet
• License: MIT