Vhs Recording

VHS Recording Skill

Generate professional terminal recordings from VHS tape files.

When To Use

• Recording terminal sessions with VHS tape scripts
• Creating terminal demo recordings for documentation

When NOT To Use

• Browser-based workflows - use scry:browser-recording instead
• Non-terminal demos or GUI applications

Overview

VHS converts declarative tape files into animated GIFs of terminal sessions. Tape files define commands, timing, and terminal appearance.

Required TodoWrite Items

- Locate and validate tape file
- Check VHS installation status
- Execute VHS recording
- Verify output GIF creation

Module Reference

• See modules/tape-syntax.md for VHS tape file directives
• See modules/execution.md for recording workflow details

Workflow

Phase 1: Validate Tape File

1. Confirm tape file exists at specified path 2. Read tape file contents 3. Verify required directives:

• Output directive specifies GIF destination
• At least one action command (Type, Enter, etc.)

Phase 2: Check VHS Installation

which vhs && vhs --version

If not installed:

# Linux/WSL
go install github.com/charmbracelet/vhs@latest

# macOS
brew install charmbracelet/tap/vhs

# Also requires ttyd and ffmpeg

Phase 3: Execute Recording

vhs <tape-file.tape>

VHS will: 1. Parse tape file directives 2. Launch virtual terminal (ttyd) 3. Execute commands with timing 4. Capture frames 5. Encode to GIF using ffmpeg

Phase 4: Verify Output

1. Check GIF file exists at Output path 2. Verify file size is non-zero 3. Report success with output location

Exit Criteria

• GIF file created at specified Output path
• File size indicates successful recording (typically >50KB)
• No error messages from VHS execution

Troubleshooting

Common Issues

If vhs is not found, verify that your Go bin directory is in your PATH (typically ~/go/bin). If the recording fails to start, ensure ttyd and ffmpeg are installed, as VHS depends on them for terminal emulation and video encoding. For "permission denied" errors when writing the GIF, check that the output directory exists and is writable.

VHS Execution Guide

Pre-flight Checks

VHS Installation

# Check if installed
which vhs

# Check version
vhs --version

Dependencies

VHS requires:

• ttyd: Terminal emulator for web
• ffmpeg: Video/image encoding

# Verify dependencies
which ttyd ffmpeg

Installation

# Go (recommended)
go install github.com/charmbracelet/vhs@latest

# macOS
brew install charmbracelet/tap/vhs

# Arch Linux
yay -S vhs

# Nix
nix-env -iA nixpkgs.vhs

Tape File Validation

Check tape file before execution:

# Verify file exists
test -f tape-file.tape && echo "Found" || echo "Missing"

# Check for Output directive
rg -q "^Output" tape-file.tape && echo "Has output" || echo "No output directive"
# fallback: grep -q "^Output" tape-file.tape

# Validate syntax (dry run)
vhs validate tape-file.tape

Environment Setup

Terminal Environment

VHS creates an isolated terminal. Set environment variables in the tape:

Set Env "HOME" "/home/user"
Set Env "PATH" "/usr/local/bin:/usr/bin:/bin"
Set Env "TERM" "xterm-256color"

Working Directory

VHS runs from the directory containing the tape file. For different directories:

Hide
Type "cd /path/to/project"
Enter
Sleep 500ms
Show

Running VHS

Basic Execution

vhs tape-file.tape

With Options

# Publish to vhs.charm.sh (public)
vhs tape-file.tape --publish

# Output to specific location
vhs tape-file.tape -o custom-output.gif

Batch Recording

# Record all tape files
for tape in *.tape; do
  vhs "$tape"
done

Error Handling

Common Issues

ttyd not found

# Install ttyd
go install github.com/aspect-build/aspect-cli/pkg/ttyd@latest
# Or via package manager

ffmpeg errors

# validate ffmpeg is installed with required codecs
ffmpeg -version

Permission denied

# Check write permissions for output directory
ls -la "$(dirname output.gif)"

Empty output

• Verify commands produce visible output
• Increase Sleep times after commands
• Check terminal dimensions fit content

Debug Mode

# Verbose output
VHS_DEBUG=1 vhs tape-file.tape

WSL2 Considerations

Graphics Support

VHS in WSL2 may require:

• WSLg enabled (Windows 11+)
• X server for older Windows 10

Path Handling

Use Linux-style paths in tape files:

# Correct
Output /home/user/output.gif

# Avoid Windows paths
# Output C:\Users\...

Performance

WSL2 disk I/O to Windows filesystem is slow. Keep tapes and outputs on Linux filesystem:

# Good: Linux filesystem
/home/user/recordings/

# Slow: Windows mount
/mnt/c/Users/...

Font Availability

Install fonts in WSL2:

sudo apt install fonts-jetbrains-mono
fc-cache -fv

Output Verification

After recording:

# Check file exists and has content
ls -la output.gif

# Verify file type
file output.gif

# Check dimensions (requires ImageMagick)
identify output.gif | head -1

Integration with Documentation

Move outputs to documentation directories:

# Move to docs
mv output.gif docs/images/

# Update markdown references
# ![Demo](images/output.gif)

VHS Tape Syntax Reference

Metadata Comments

Custom metadata annotations for documentation integration:

# @title: Command Demo
# @description: Demonstrates the CLI workflow
# @step: 1
# @docs-brief: Quick overview for documentation
# @book-detail: Extended explanation for book chapters

Output Directive

Specifies the output file path (required):

Output demo.gif

Supported formats: .gif, .mp4, .webm

Set Directives

Configure terminal appearance and behavior:

# Typography
Set FontSize 14
Set FontFamily "JetBrains Mono"

# Dimensions
Set Width 1200
Set Height 600

# Appearance
Set Theme "Dracula"
Set Padding 20
Set Margin 10
Set MarginFill "#674EFF"
Set BorderRadius 8

# Timing
Set TypingSpeed 50ms
Set Framerate 60

# Environment
Set Env "TERM" "xterm-256color"
Set Env "PS1" "$ "

# Window
Set Shell "bash"
Set WindowBar Colorful
Set WindowBarSize 40

Action Commands

Type

Types text into the terminal:

Type "echo 'Hello World'"
Type@50ms "slower typing"

Enter

Sends Enter key (execute command):

Enter

Sleep

Pause for duration:

Sleep 500ms
Sleep 2s

Key Combinations

Ctrl+C
Ctrl+D
Ctrl+L
Escape
Tab
Backspace
Up
Down
Left
Right
Space

Screenshot

Capture a still frame:

Screenshot output.png

Hide/Show

Control visibility of actions:

Hide
Type "secret setup commands"
Enter
Show

Best Practices

Echo vs Commands

NEVER use `echo` to simulate or replace real command output. Echo should only be used for:

• Printing explanatory messages or headers
• Simple text output demonstrations
• Comments that need to appear in the terminal

ALWAYS prefer actual commands that demonstrate functionality:

# BAD: Simulating output with echo
Type "echo 'tool-a, tool-b, tool-c'"
Enter

# GOOD: Using the actual command
Type "my-cli --list-tools"
Enter

If a command doesn't exist to show what you need, consider: 1. Adding a flag or subcommand to the CLI being demonstrated 2. Using the actual data source (file, API, etc.) 3. Rethinking what the demo should show

Rationale: Tutorials should demonstrate real functionality. Echoing data teaches users nothing about the actual tool and may become stale as the tool evolves.

MCP Tool Demonstrations

When demonstrating MCP (Model Context Protocol) functionality, show how tools are used within the host environment (e.g., Claude Code) rather than calling CLI equivalents:

# POOR: Using CLI instead of MCP
Type "skrills metrics"

# BETTER: Explain MCP tool usage
Type "# In Claude Code, ask: 'Show me skill statistics'"
Type "# Claude calls the skill-metrics MCP tool automatically"

Advanced Features

Split Panes

Create multi-pane layouts:

Split
Type@left "echo 'Left pane'"
Enter@left
Type@right "echo 'Right pane'"
Enter@right

Source

Include other tape files:

Source common-setup.tape

Require

validate programs are available:

Require echo
Require git

Complete Example

# @title: Git Status Demo
# @description: Shows git status workflow
# @step: 1

Output git-demo.gif

Set FontSize 16
Set Width 1000
Set Height 400
Set Theme "Catppuccin Mocha"
Set TypingSpeed 75ms

Hide
Type "cd ~/project"
Enter
Sleep 500ms
Show

Type "git status"
Sleep 500ms
Enter
Sleep 2s

Type "git add ."
Sleep 500ms
Enter
Sleep 1s

Type "git commit -m 'Update docs'"
Sleep 500ms
Enter
Sleep 2s