EVP

EVP is a CLI tool to make beautiful terminal recordings.

Warning

EVP is still a work in progress and there will be breaking changes without warning.

You create a .tape file and run evp demo.tape to produce smooth, high quality, portable GIF or SVG demos. EVP is a rewrite of VHS with some key improvements.

See it in action below:

VHS comparison

EVP is extends VHS in these ways:

• Significantly faster. No more skipped frames when creating demos in GitHub Actions!
  • Frames are written to the GIF file as the recording session runs.
  • When the recording finishes, the GIF file is instantly ready.
• Animated SVGs:
  • Super crisp demos
  • You can select and copy text from the SVG as it is playing!
  • Fonts are embedded into the SVG so the demos are portable (fonts are subsetted before embedding)
  • SVG screenshots
  • Box-drawing chars are rendered as SVG shapes. Don't worry, an invisible character is written to the SVG so selecting and copying text works as expected.
• Supports Kitty extended keycodes. e.g:
  • Ctrl+Shift+Alt+Left
  • Command+Alt+PageUp
• Specify full shell path with arguments. e.g.:
  • Set Shell bash --init-file test.rc
  • Set Shell yazi you can specify any program, not just a shell!
• EVP has no runtime dependencies
  • It is a statically linked musl binary
  • A collection of useful fonts are embedded into EVP
• Mouse support: you can script mouse clicks, dragging, movement
• Set the terminal size by number of rows / cols or by number of pixels.
• Coming soon: resize support
• Coming soon: snapshot process metrics to help debug interactive use
• Coming soon: key event name overlay

Install and Usage

Quick install: install.sh

Tip

No sudo required!

curl -sSfL https://github.com/HalFrgrd/evp/releases/latest/download/install.sh | sh

After installing, you can:

• Start from a reference script, edit it, then run evp demo.tape:

  # Generate a reference script:
  evp print-ref-script > demo.tape
  # Edit the tape file with your editor (e.g. vim demo.tape), then get evp to create a gif from it:
  evp demo.tape

  If you already have a VHS script, you can run:

  evp --mimic-vhs demo.tape

• Or you can run evp record: You can record your live terminal sessions directly to a .tape file and a corresponding .gif! EVP turns your terminal into raw mode and captures all keystrokes, mouse clicks, drags, movements, and scrolling:

  # Record your session (saves to demo.tape and demo.gif by default)
  evp record
  # Customize the outputs, shell, theme, and geometry:
  evp record --output my_demo.tape --output demo.svg --shell zsh --theme "Catppuccin Mocha" --cols 100 --rows 40

  When you are done, simply exit the subshell (e.g., type exit or press Ctrl+D). EVP will write the formatted demo.tape script and demo.gif of your session! Then tweak demo.tape to your liking, and run evp demo.tape to produce a new GIF:

  

Using EVP in CI

For automated rendering in workflows, pipelines, or containers, see EVP in CI.

Technology

EVP runs a shell inside an embedded libghostty terminal. This allows us to support advanced terminal features in a headless environment such as: complex key combinations; key press and key release events; mouse input support; legacy escape codes: Kitty image protocol (comming soon!).

The SVG animations use SMIL. Fonts are embedded into the SVG using this method. A custom optimizer reduces the file size and complexity. All the text on one terminal row is rendered inside of a <text> span which helps the browser copy the right text when you select and copy from the SVG.

GIF rendering: a 256 color palette is setup at the start and reused for nearly all frames. Only minimal diffs between frames are written to the file. This yields exceptionally small GIF file sizes.

Script Reference

EVP supports a superset of VHS .tape script language. Below is a complete template of all supported commands, settings, and events in the EVP .tape script language:

# --- Output & Dependencies ---Output demo.gif# Target output file (supports .gif, .svg, .svgz, .json, .stats)Output demo.json# Multiple outputs are supported. You can use the `--ouput demo.svg` flag also.Output demo.svg# RecommendedOutput demo.svgz# gzip-compressed svg, less widely supportedOutput demo.stats# Reports some stats about the rendering processRequirecurl# Assert that curl is available on system PATHSource common.tape# Inline another tape file# --- Window & Font Settings ---Set Shell bash# Configure shell execution path (e.g. bash, zsh, fish)Set Shell bash--norc# EVP supports any command as the "shell"Set Shell yazi# You can boot right into your TUISet Theme "Catppuccin Mocha"# Apply a predefined colour theme (run `evp themes` to discover themes)Set Font "JetBrains Mono"# Monospace font family nameSet FontSize 20# Font size in pixelsSet LineHeight 1.2# Line spacing multiplierSet LetterSpacing 0# Letter spacing adjustmentSet Width 800# Terminal window width in pixelsSet Height 400# Terminal window height in pixelsSet Cols 100# Set terminal width in rows (Set Width has precedence)Set Rows 30# Set terminal height in rows (Set Height has precedence)Set Padding 10# Inner padding between terminal grid and window frameSet Margin 20# Outer margin around window frameSet MarginFill "#6B50FF"# Background colour of outer margin areaSet Framerate 30# Recording framerate in FPSSet TypingSpeed 50ms# Default speed/interval for typed text# --- Child Process Environment ---Env PS1 "$ " # Set environment variables for the shell process# --- Playback & Timeline Controls ---Sleep 1s # Pause playback for a duration (e.g. 500ms, 1.5s, 2m)Hide # Hide subsequent commands from recording outputShow # Resume recording commands to output filesScreenshot frame.png # Capture the current terminal window frame as a PNG, SVG, JSON, TXT, or ASCIIScreenshot frame.svgScreenshot frame.jsonScreenshot frame.txtScreenshot frame.ascii# --- Clipboard Controls ---Copy "texttoclipboard" # Copy a string into the system clipboardPaste # Paste current clipboard contents into terminal# --- Keyboard & Input Events ---Type "echo'hello'" # Type text at the current default TypingSpeedType@10ms "fasttyping" # Type text at an overridden speed of 10msEnter # Press key alias (equivalent to Key "Enter" / Key "Return")
Backspace5# Repeat a key alias N times (press Backspace 5 times)Ctrl+C# Press key combination modifierCtrl+Shift+Alt+Left# Even complex key codes are possible.Press Down # Explicitly hold a key down
ReleaseDown# Explicitly release a held key# --- Mouse Controls ---Click1020# Left click at column 10, row 20Shift+Click1020# Shift + Left click at column 10, row 20Ctrl+RightClick1020# Ctrl + Right click at column 10, row 20DoubleClick1020# Double click at column 10, row 20MouseMove@1.2s 00101530104040# Move cursor along a smooth Catmull-Rom spline curve passing through (0,0), (10,15), (30,10), and (40,40)MouseMove@1.2s@EaseInOutElastic0010154040# Move cursor along a spline curve with EaseInOutElastic easing curve overrideShift+Ctrl+MouseDrag@EaseInOutQuad0010154040# Left click and drag along a spline curve holding Shift+CtrlCtrl+MouseScroll1020 Up # Scroll mouse wheel Up at column 10, row 20 holding Ctrl# --- Wait / Synchronization ---
Wait/regex/# Wait for output matching regular expressionWait+Screen/regex/# Wait scanning full screen instead of only the last lineWait+Line/regex/# Explicitly wait scanning last line only (default)Wait@1s /regex/# Wait with an overridden timeout of 1s (default is 15s)Wait+Line@1s /regex/# Wait scanning last line with 1s timeout overrideWait+Screen@1s /regex/# Wait scanning full screen with 1s timeout override

Examples

See examples.md for a showcase of pre-rendered GIF animations demonstrating custom themes, layout controls, mouse input scripting, and window title bars.

Serving SVGs / SVGZs

Unfortunately, GitHub doesn't support embeddable SVGs in such a way that you can select text from the SVG.

Acknowledgments

VHS

EVP is based on the VHS project. They share little code but EVP does try use the same .tape file format.

The colour themes in assets/vhs-themes.json are taken from the VHS project and are licensed under the MIT License. See licenses/VHS-MIT.txt for the full license.

Font providers

Some fonts are embedded inside the EVP binary. See licenses in license for the full license text.