vhs

VHS

Note: This is a fork of the original charmbracelet/vhs that adds native SVG output support and additional features. Features specific to this fork are marked with 🚀.

Write terminal GIFs as code for integration testing and demoing your CLI tools.

The above example was generated with VHS (view source) and demonstrates the crisp, scalable SVG output.

Fork Features 🚀

This fork extends the original VHS with:

• Native SVG Output: Generate scalable, animated SVGs that are often smaller than GIFs
  • Why? Modern web browsers and documentation platforms benefit from vector graphics that scale perfectly on any display while using less bandwidth
• Window Bar Customization:
  • Custom window titles with Set WindowBarTitle
  • Custom title fonts with Set WindowBarFontFamily and Set WindowBarFontSize
  • Why? Professional demos and documentation often need branded or contextual window titles
• Enhanced CLI Options:
  • --no-svg-opt: Control SVG optimization
  • --debug-console: Enable browser console logging for debugging
  • Why? Better developer experience for troubleshooting and fine-tuning output

SVG vs GIF Comparison 🚀

GIF Output	SVG Output
File size: 275KB Fixed resolution Pixelated when scaled No text selection	File size: 549KB Infinitely scalable Crystal clear at any size Text is selectable

Try zooming in on both images above to see the difference in quality!

Note: File sizes vary by content. Simple recordings with few colors often result in smaller SVGs, while complex outputs like neofetch with many colors may produce larger SVGs due to the need to preserve exact positioning and styling of each character.

Tutorial

To get started, install VHS and create a new .tape file.

vhs new demo.tape

Open the .tape file with your favorite $EDITOR.

vim demo.tape

Tape files consist of a series of commands. The commands are instructions for VHS to perform on its virtual terminal. For a list of all possible commands see the command reference.

# 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

Once you've finished, save the file and feed it into VHS.

vhs demo.tape

All done! You should see a new file called demo.gif (or whatever you named the Output) in the directory.

For more examples see the examples/ directory.

Installation

[!NOTE] VHS requires ttyd and ffmpeg to be installed and available on your PATH.

Use a package manager:

# 🚀 Install this fork with SVG support (macOS or Linux)
brew trust --cask agentstation/tap/vhs
brew install --cask agentstation/tap/vhs

# Original VHS (without SVG support)
brew install vhs

# Arch Linux (btw)
pacman -S vhs

# Nix
nix-env -iA nixpkgs.vhs

# Windows using scoop
scoop install vhs

Or, use Docker to run VHS directly, dependencies included:

# 🚀 This fork
docker run --rm -v $PWD:/vhs ghcr.io/agentstation/vhs <cassette>.tape

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

Or, download it:

• Packages are available in Debian and RPM formats
• Binaries are available for Linux, macOS, and Windows

Or, just install it with go:

# 🚀 Install this fork with SVG support
go install github.com/agentstation/vhs@latest

# Original VHS
go install github.com/charmbracelet/vhs@latest

# Debian/Ubuntu
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
# Install ttyd from https://github.com/tsl0922/ttyd/releases
sudo apt update && sudo apt install vhs ffmpeg

echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
# Install ttyd from https://github.com/tsl0922/ttyd/releases
sudo yum install vhs ffmpeg

sudo xbps-install vhs

winget install charmbracelet.vhs
# or scoop
scoop install vhs

Use --browser-path to select the browser executable for capture:

vhs --browser-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" demo.tape

You can also set VHS_BROWSER_PATH. The command-line option takes precedence. If both values are empty, VHS uses automatic browser discovery.

Use --svg-font-file or VHS_SVG_FONT_FILE to load an exact font into the capture browser and SVG output. This option overrides Set FontFamily. Supported file extensions are .woff2, .woff, .ttf, and .otf. Use a font whose license permits embedding.

For SVG output, a single installed family set with Set FontFamily also embeds automatically when fc-match is available. VHS loads that selected face before measuring the terminal. A separate named WindowBarFontFamily embeds its own face. Generic families and comma-separated fallback stacks keep their existing behavior.

With optional FontTools pyftsubset, optimized SVG output includes a smaller font with the displayed terminal, cursor, and title glyphs. If subsetting is unavailable or fails, VHS embeds the full selected face. If discovery is unavailable, capture continues with a diagnostic. An explicit font file takes priority and retains its exact bytes without subsetting.

Record Tapes

VHS has the ability to generate tape files from your terminal actions!

To record to a tape file, run:

vhs record > cassette.tape

Perform any actions you want and then exit the terminal session to stop recording. You may want to manually edit the generated .tape file to add settings or modify actions. Then, you can generate the GIF:

vhs cassette.tape

Publish Tapes

VHS allows you to publish your GIFs to our servers for easy sharing with your friends and colleagues. Specify which file you want to share, then use the publish sub-command to host it on vhs.charm.sh. The output will provide you with links to share your GIF via browser, HTML, and Markdown.

vhs publish demo.gif

The VHS Server

VHS has an SSH server built in! When you self-host VHS you can access it as though it were installed locally. VHS will have access to commands and applications on the host, so you don't need to install them on your machine.

To start the server run:

vhs serve

Then, simply access VHS from a different machine via ssh:

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

VHS Command Reference

[!NOTE] You can view all VHS documentation on the command line with vhs manual.

There are a few basic types of VHS commands:

• Output <path>: specify file output
• Require <program>: specify required programs for tape file
• Set <Setting> Value: set recording settings
• Type "<characters>": emulate typing
• Left Right Up Down: arrow keys
• Backspace Enter Tab Space: special keys
• ScrollUp ScrollDown: scroll terminal viewport
• Ctrl[+Alt][+Shift]+<char>: press control + key and/or modifier
• Sleep <time>: wait for a certain amount of time
• Wait[+Screen][+Line] /regex/: wait for specific conditions
• Hide: hide commands from output
• Show: stop hiding commands from output
• Screenshot: screenshot the current frame
• Copy/Paste: copy and paste text from clipboard.
• Source: source commands from another tape
• Env <Key> Value: set environment variables

Output

The Output command allows you to specify the location and file format of the render. You can specify more than one output in a tape file which will render them to the respective locations.

Output out.gif
Output out.mp4
Output out.webm
Output out.svg   # 🚀 Native SVG output with animations
Output frames/ # a directory of frames as a PNG sequence

🚀 SVG Output (Fork Feature): This fork adds native SVG output support with significant advantages:

• Perfect Quality: Vector-based animations scale infinitely without pixelation - ideal for documentation, presentations, and high-DPI displays
• Text Selectable: Terminal text remains selectable and searchable in SVG format
• Efficient Animations: Uses CSS animations and frame deduplication for smooth playback
• Web-Friendly: SVGs can be embedded directly in HTML/Markdown and styled with CSS
• Size Optimization: Built-in optimization reduces file sizes through frame deduplication and minification

File sizes vary based on content complexity:

• Simple terminal demos: SVGs are often 50-90% smaller than GIFs
  • Example: simple-demo.gif (82KB) vs simple-demo.svg (19KB) - 77% smaller!
• Complex outputs (like neofetch with many colors): SVGs may be larger due to preserving exact text styling and background colors
  • Example: neofetch.gif (289KB) vs neofetch.svg (554KB)
• Use --no-svg-opt flag to disable optimization if needed

Require

The Require command allows you to specify dependencies for your tape file. These are useful to fail early if a required program is missing from the $PATH, and it is certain that the VHS execution will not work as expected.

Require commands must be defined at the top of a tape file, before any non- setting or non-output command.

# A tape file that requires gum and glow to be in the $PATH
Require gum
Require glow

Settings

The Set command allows you to change global aspects of the terminal, such as the font settings, window dimensions, and GIF output location.

Setting must be administered at the top of the tape file. Any setting (except TypingSpeed) applied after a non-setting or non-output command will be ignored.

Set Shell

Set the shell with the Set Shell <shell> command

Set Shell fish

Set Font Size

Set the font size with the Set FontSize <number> command.

Set FontSize 10
Set FontSize 20
Set FontSize 40

Set Font Family

Set the font family with the Set FontFamily "<font>" command

Set FontFamily "Monoflow"

Set Width

Set the width of the terminal with the Set Width command.

Set Width 300

Set Height

Set the height of the terminal with the Set Height command.

Set Height 1000

Set Columns

Set the width of the terminal in columns (character cells) with the Set Columns command. VHS derives the final pixel width from the current font settings (FontSize, FontFamily, LetterSpacing) plus Padding/Margin.

Set Columns 100

Set Columns cannot be combined with Set Width — use one or the other to control the terminal's width. It can be freely combined with Set Height or Set Rows to control height.

Set Rows

Set the height of the terminal in rows (character cells) with the Set Rows command. VHS derives the final pixel height from the current font settings (FontSize, FontFamily, LineHeight) plus Padding/Margin/WindowBar.

Set Rows 40

Set Rows cannot be combined with Set Height — use one or the other to control the terminal's height. It can be freely combined with Set Width or Set Columns to control width.

Set Letter Spacing

Set the spacing between letters (tracking) with the Set LetterSpacing Command.

Set LetterSpacing 20

Set Line Height

Set the spacing between lines with the Set LineHeight Command.

Set LineHeight 1.8

Set Typing Speed

Set TypingSpeed 500ms # 500ms
Set TypingSpeed 1s    # 1s

Set the typing speed of seconds per key press. For example, a typing speed of 0.1 would result in a 0.1s (100ms) delay between each character being typed.

This setting can also be overwritten per command with the @<time> syntax.

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

Set Theme

Set the theme of the terminal with the Set Theme command. The theme value should be a JSON string with the base 16 colors and foreground + background.

Set Theme { "name": "Whimsy", "black": "#535178", "red": "#ef6487", "green": "#5eca89", "yellow": "#fdd877", "blue": "#65aef7", "magenta": "#aa7ff0", "cyan": "#43c1be", "white": "#ffffff", "brightBlack": "#535178", "brightRed": "#ef6487", "brightGreen": "#5eca89", "brightYellow": "#fdd877", "brightBlue": "#65aef7", "brightMagenta": "#aa7ff0", "brightCyan": "#43c1be", "brightWhite": "#ffffff", "background": "#29283b", "foreground": "#b3b0d6", "selection": "#3d3c58", "cursor": "#b3b0d6" }

You can also set themes by name:

Set Theme "Catppuccin Frappe"

See the full list by running vhs themes, or in THEMES.md.

Set Padding

Set the padding (in pixels) of the terminal frame with the Set Padding command.

Set Padding 0

Set Margin

Set the margin (in pixels) of the video with the Set Margin command.

Set Margin 60
Set MarginFill "#6B50FF"

Set Window Bar

Set the type of window bar (Colorful, ColorfulRight, Rings, RingsRight) on the terminal window with the Set WindowBar command.

Set WindowBar Colorful

Set Window Bar Title 🚀

Set a custom title for the window bar with the Set WindowBarTitle command.

Set WindowBarTitle "My Demo"

Set Window Bar Font Family 🚀

Set a custom font family for the window bar title with the Set WindowBarFontFamily command. Falls back to FontFamily if not specified.

Set WindowBarFontFamily "Monaco"

Set Window Bar Font Size 🚀

Set a custom font size for the window bar title with the Set WindowBarFontSize command. Falls back to FontSize if not specified.

Set WindowBarFontSize 16

Set Border Radius

Set the border radius (in pixels) of the terminal window with the Set BorderRadius command.

# You'll likely want to add a Margin + MarginFill if you use BorderRadius.
Set Margin 20
Set MarginFill "#674EFF"
Set BorderRadius 10

Set Framerate

Set the rate at which VHS captures frames with the Set Framerate command.

Set Framerate 60

VHS records visible elapsed time. Hide excludes time until Show. When capture is slow, raster output repeats frames to preserve playback time. SVG output uses capture timestamps. Framerate controls the capture limit and raster playback rate.

Set Playback Speed

Set the playback speed of the final render.

Set PlaybackSpeed 0.5 # Make output 2 times slower
Set PlaybackSpeed 1.0 # Keep output at normal speed (default)
Set PlaybackSpeed 2.0 # Make output 2 times faster

Set Loop Offset

Set the offset for when the GIF loop should begin. This allows you to make the first frame of the GIF (generally used for previews) more interesting.

Set LoopOffset 5 # Start the GIF at the 5th frame
Set LoopOffset 50% # Start the GIF halfway through

Set Cursor Blink

Set whether the cursor should blink. Enabled by default.

Set CursorBlink false

ProgressBar

Add a one-pixel progress bar at the bottom of the SVG terminal viewport:

Set ProgressBar "#9B79FF"

Use a quoted #RGB, #RRGGBB, or #RRGGBBAA hex color. The bar is off by default and applies only to SVG output. It uses the terminal animation's PlaybackSpeed and LoopOffset timing.

Browsers animate the bar during playback. Static renderers such as librsvg and Inkscape display a full-width bar without playback animation.

Type

Use Type to emulate key presses. That is, you can use Type to script typing in a terminal. Type is handy for both entering commands and interacting with prompts and TUIs in the terminal. The command takes a string argument of the characters to type.

You can set the standard typing speed with Set TypingSpeed and override it in places with a @time argument.

# Type something
Type "Whatever you want"

# Type something really slowly!
Type@500ms "Slow down there, partner."

Escape single and double quotes with backticks.

Type `VAR="Escaped"`

Keys

Key commands take an optional @time and optional repeat count for repeating the key press every interval of <time>.

Key[@<time>] [count]

Backspace

Press the backspace key with the Backspace command.

Backspace 18

Ctrl

You can access the control modifier and send control sequences with the Ctrl command.

Ctrl+R

Enter

Press the enter key with the Enter command.

Enter 2

Arrow Keys

Press any of the arrow keys with the Up, Down, Left, Right commands.

Up 2
Down 2
Left
Right
Left
Right
Type "B"
Type "A"

Tab

Enter a tab with the Tab command.

Tab@500ms 2

Space

Press the space bar with the Space command.

Space 10

Page Up / Down

Press the Page Up / Down keys with the PageUp or PageDown commands.

PageUp 3
PageDown 5

Scroll Up / Down

Scroll the terminal viewport directly with ScrollUp and ScrollDown. Both commands use the same optional @time and repeat count shape as other repeatable key commands: ScrollUp[@<time>] [count].

ScrollUp 10
ScrollDown 4
ScrollDown@100ms 12

Wait

The Wait command allows you to wait for something to appear on the screen. This is useful when you need to wait on something to complete, even if you don't know how long it'll take, while including it in the recording like a spinner or loading state. The command takes a regular expression as an argument, and optionally allows you to set the duration to wait and if you want to check the whole screen or just the last line (the scope).

Wait
Wait            /World/
Wait+Screen     /World/
Wait+Line       /World/
Wait@10ms       /World/
Wait+Line@10ms  /World/

The default regular expression is />$/, the wait timeout is 15s, and the default scope is Line.

Sleep

The Sleep command allows you to continue capturing frames without interacting with the terminal. This is useful when you need to wait on something to complete while including it in the recording like a spinner or loading state. The command takes a number argument in seconds.

Sleep 0.5   # 500ms
Sleep 2     # 2s
Sleep 100ms # 100ms
Sleep 1s    # 1s

Hide

The Hide command instructs VHS to stop capturing frames. It's useful to pause a recording to perform hidden commands.

Hide

This command is helpful for performing any setup and cleanup required to record a GIF, such as building the latest version of a binary and removing the binary once the demo is recorded.

Output example.gif

# Setup
Hide
Type "go build -o example . && clear"
Enter
Show

# Recording...
Type 'Running ./example'
...
Enter

# Cleanup
Hide
Type 'rm example'
Enter

Show

The Show command instructs VHS to begin capturing frames, again. It's useful after a Hide command to resume frame recording for the output.

Hide
Type "You won't see this being typed."
Show
Type "You will see this being typed."

Screenshot

The Screenshot command captures the current frame (png format).

# At any point...
Screenshot examples/screenshot.png

Copy / Paste

The Copy and Paste copy and paste the string from clipboard.

Copy "https://github.com/charmbracelet"
Type "open "
Sleep 500ms
Paste

Env

Env command sets the environment variable via key-value pair.

Env HELLO "WORLD"

Type "echo $HELLO"
Enter
Sleep 1s

Source

The source command allows you to execute commands from another tape.

Source config.tape

CLI Options 🚀

This fork adds several command-line options to enhance VHS functionality:

Output Control

# Disable SVG minification, short class names, and automatic font subsetting
# Optimization is enabled by default
vhs demo.tape --no-svg-opt

# Specify multiple output formats
vhs demo.tape -o out.gif -o out.svg -o out.mp4

Debugging

# Enable browser console logging for debugging
vhs demo.tape --debug-console

Continuous Integration

You can hook up VHS to your CI pipeline to keep your GIFs up-to-date with the official VHS GitHub Action:

⚙️ charmbracelet/vhs-action

VHS can also be used for integration testing. Use the .txt or .ascii output to generate golden files. Store these files in a git repository to ensure there are no diffs between runs of the tape file.

Output golden.ascii

Syntax Highlighting

There’s a tree-sitter grammar for .tape files available for editors that support syntax highlighting with tree-sitter:

🌳 charmbracelet/tree-sitter-vhs

It works great with Neovim, Emacs, and so on!

Contributing

See contributing.

Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note!

• Twitter
• The Fediverse
• Discord

License

MIT

Part of Charm.

Charm 热爱开源 • Charm loves open source