vhs

command module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2022 License: MIT Imports: 33 Imported by: 0

README

VHS


Latest Release Go Docs Build Status

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

Welcome to VHS

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.

A GIF produced by the VHS code above

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"
Example of using the Type command in VHS
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
Example of pressing the Backspace key 18 times
Ctrl

Press a control sequence with the Ctrl command.

Ctrl+R
Enter

Press the enter key with the Enter command.

Enter 2
Example of pressing the Enter key twice
Arrow Keys

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

Up 2
Down 3
Left 10
Right 10
Example of pressing the arrow keys to navigate text
Tab

Press the tab key with the Tab command.

Tab@500ms 2
Example of pressing the tab key twice for autocomplete
Space

Press the space bar with the Space command.

Space 10
Example of pressing the space key
Settings
Set Font Size

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

Set FontSize 10
Set FontSize 20
Set FontSize 40
Example of setting the font size to 10 pixels Example of setting the font size to 20 pixels Example of setting the font size to 40 pixels
Set Font Family

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

Set FontFamily "Monoflow"
Example of changing the font family to 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
Example of changing the letter spacing to 20 pixels between characters
Set Line Height

Set the spacing between lines with the Set LineHeight Command.

Set LineHeight 1.8
Example of changing the line height to 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"
Example of changing the typing speed to type different words
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" }
Example of changing the theme to Whimsy
Set Padding

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

Set Padding 0
Example of setting padding to 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."
Example of typing something while hidden

Feedback

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

License

MIT


Part of Charm.

The Charm logo

Charm热爱开源 • Charm loves open source

Documentation

Overview

Package vhs keys.go defines the key map for the Type command. The `keymap` map is used to convert runes from a string into the appropriate go-rod input.

Type Hello, world!

The above command will type the string "Hello, world!" into the terminal, by converting each rune into the correct input.

Hello, world! { shift(input.KeyH), input.KeyE, ..., input.KeyD, shift(input.Digit1) }

Package vhs theme.go contains the information about a terminal theme. It stores the 16 base colors as well as the background and foreground colors of the terminal theme.

It can be changed through the Set command.

Set Theme {"background": "#171717"}

Package vhs tty.go spawns the ttyd process. It runs on the specified port and is generally meant to run in the background so that other processes (go-rod) can connect to the tty.

xterm.js is used for rendering the terminal and can be adjusted using the Set command.

Set FontFamily "DejaVu Sans Mono" Set FontSize 12 Set Padding 50

Package vhs video.go spawns the ffmpeg process to convert the frames, collected by go-rod's screenshots into the input folder, to a GIF, WebM, MP4.

MakeGIF takes several options to modify the behaviour of the ffmpeg process, which can be configured through the Set command.

Set MaxColors 256

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL