VHS
Write terminal GIFs as code for integration testing and demoing your CLI tools.
The above example is generated from VHS (View Tape).
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
In the file, write commands to perform on the terminal.
View Documentation for a list of all the possible commands.
# Render the output GIF to demo.gif
Output demo.gif
# Set up a 1200x600 terminal with 46px font size.
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 written the commands to perform, save and exit the file. And, run
the VHS tool on the file.
vhs < demo.tape
All done! You should see a new file called demo.gif
(or whatever you named
the Output
) in the directory.
More examples are in the examples/
folder.
Installation
Note
VHS requires ttyd
and ffmpeg
to be installed.
Use a package manager:
# macOS or Linux
brew install vhs ttyd ffmpeg
# Arch Linux (btw)
yay -S vhs ttyd ffmpeg
# Nix
nix-env -iA nixpkgs.vhs nixpkgs.ttyd nixpkgs.ffmpeg
Or, use docker:
docker run 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
:
go install github.com/charmbracelet/vhs@latest
Teams
If you are a team using VHS, reach out to vt100@charm.sh
to set up a VHS rendering server with an ssh
interface to avoid any local
setup for your team.
ssh vhs.charm.sh < demo.tape > demo.gif
Commands
For documentation on the command line, run:
vhs manual
Keys
Key commands take an optional @time
and repeat count
.
For example, the following presses the Left
key 5 times with a 500
millisecond delay between each keystroke.
Left@500ms 5
Settings
The Set
command allows you to change aspects of the terminal, such as the
font settings, window dimensions, and output GIF location.
Setting commands must be set at the top of the tape file. Any setting (except
TypingSpeed
) command that is set after a non-setting or non-output command
will be ignored.
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
Type
The Type
command allows you to type in the terminal and emulate key presses.
This is useful for typing commands or interacting with the terminal.
The command takes a string argument with the characters to type.
Type "Whatever you want"
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 frames/ # .png frames
Keys
Backspace
Press the backspace key with the Backspace
command.
Backspace 18
Ctrl
Press a control sequence 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 3
Left 10
Right 10
Tab
Press the tab key with the Tab
command.
Tab@500ms 2
Space
Press the space bar with the Space
command.
Space 10
Settings
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 Height
Set the height of the terminal with the Set Height
command.
Set Height 600
Set Height 1000
Set Width
Set the width of the terminal with the Set Width
command.
Set Width 1200
Set Width 2000
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 overridden 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", "purple": "#aa7ff0", "cyan": "#43c1be", "white": "#ffffff", "brightBlack": "#535178", "brightRed": "#ef6487", "brightGreen": "#5eca89", "brightYellow": "#fdd877", "brightBlue": "#65aef7", "brightPurple": "#aa7ff0", "brightCyan": "#43c1be", "brightWhite": "#ffffff", "background": "#29283b", "foreground": "#b3b0d6", "selectionBackground": "#3d3c58", "cursorColor": "#b3b0d6" }
Set Padding
Set the padding (in pixels) of the terminal frame with the Set Padding
command.
Set Padding 0
Set Framerate
Set the rate at which VHS captures frames with the Set Framerate
command.
Set Framerate 60
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
Hide
The Hide
command allows you to specify that the following commands should not
be shown in the output.
Hide
This command can be helpful for doing any setup and clean up 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'
Show
The Show
command allows you to specify that the following commands should
be shown in the output. Since this is the default case, the show command will
usually be seen with the Hide
command.
Hide
Type "You won't see this being typed."
Show
Type "You will see this being typed."
Feedback
We’d love to hear your thoughts on this project. Feel free to drop us a note!
License
MIT
Part of Charm.
Charm热爱开源 • Charm loves open source