# VHS — Record Terminal Sessions as GIFs and Videos

> VHS by Charmbracelet lets you write terminal recordings as code. Define commands in a .tape file, and VHS generates beautiful GIFs, MP4s, or WebMs — perfect for documentation, README demos, and project showcases.

## Install

Save as a script file and run:

# VHS — Record Terminal Sessions as GIFs and Videos

## Quick Use
```bash
# Install VHS
brew install vhs
# Requires ttyd and ffmpeg

# Create a tape file
cat > demo.tape << 'EOF'
Output demo.gif
Set FontSize 18
Set Width 800
Set Height 400

Type "echo Hello, World!"
Enter
Sleep 1s
Type "ls -la"
Enter
Sleep 2s
EOF

# Record
vhs demo.tape
# Creates demo.gif
```

## 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
```tape
# 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
```

```bash
# 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
| Feature | VHS | asciinema | Terminalizer | ttygif |
|---|---|---|---|---|
| Approach | Code (tape files) | Record live | Record live | Record live |
| Reproducible | Yes (deterministic) | No | No | No |
| Output Format | GIF, MP4, WebM | asciicast, GIF | GIF, MP4 | GIF |
| Customization | Extensive | Player theme | Config file | Limited |
| CI Integration | Excellent | Possible | Possible | Limited |
| Edit After Recording | Edit .tape file | Re-record | Re-record | Re-record |
| Best For | Docs/README demos | Live sharing | GIF generation | Simple GIFs |

## 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

---
Source: https://tokrepo.com/en/workflows/10b32515-373d-11f1-9bc6-00163e2b0d79
Author: Script Depot