asciicast2webp

asciicast2webp converts asciicast v2 and v3 terminal recordings into animated WebP files. If possible, it preserves terminal colours, and renders captured keypresses in roughly the Emacs key notation.

The old asciicast v2 format cannot store the colour theme, in which case it defaults to black on white.

Example output can be seen at https://git.janouch.name/p/sdn

Background

First, I thought something as simple would already exist. But there’s basically only agg, which doesn’t care about keypresses, and GIF is an inefficient file format:

Format	Encoding	Tool	Filesize	Relative size
WebP	Lossless	libwebp preset 9	401884	100 %
GIF	Palette	magick	825280	205 %
APNG	Lossless	apngasm + oxipng -z	939822	234 %
GIF	Palette	gifski (used by agg)	1046027	260 %

Second, I thought this would be reasonably doable in something other than C++. Meanwhile, all the good important libraries have a C API.

Text rendering could still see some improvements, notably with Unicode box-drawing characters, and keypress parsing could learn many more sequences. I’ve already spent enough time on this project for now.

Packages

Regular releases are sporadic. git master should be stable enough.

Static Linux builds can be found here, simply place the binary somewhere in your PATH.

Building

Build-only dependencies: CMake, a C++20 compiler, pkg-config
Runtime dependencies: libvterm, Cairo, libwebp, libwebpmux, libjq, and a terminfo library (tinfo or ncursesw)

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
$ cmake --build build

Usage

Pass an input cast and an output WebP path:

$ asciicast2webp [OPTION…​] recording.cast recording.webp

Options

--font NAME, --size POINTS

Choose the terminal font and size. The defaults are monospace and 10 points.

--border PIXELS

Add space around the terminal.

--key-timeout SECONDS

Control how long captured keypresses remain visible. Use zero to hide them.

--top EM, --left EM

Position the keypress badge. Positive values measure from the top or left; negative values measure from the bottom or right.

--preset LEVEL

Choose the lossless WebP compression effort from 0 through 9. The default is 6; higher values take longer.

--near-lossless QUALITY

Enable near-lossless preprocessing from 0 through 100. The default, 100, leaves it disabled.

--duration-min MILLISECONDS

Set the shortest encoded frame duration. The default of 11 milliseconds avoids unreliable playback of very short frames in browsers. Use zero to preserve the recording’s rounded timing.

--drop-short

Drop frames shorter than --duration-min instead of lengthening them.

Run with --help for the complete command-line summary.

Contributing and Support

Use https://git.janouch.name/p/asciicast2webp to report any bugs, request features, or submit pull requests. git send-email is tolerated. If you want to discuss the project, feel free to join me at ircs://irc.janouch.name, channel #dev.

Bitcoin donations are accepted at: 12r5uEWEgcHC46xd64tt3hHt9EUvYYDHe9

License

This software is released under the terms of the 0BSD license, the text of which is included within the package along with the list of authors.