asciinema/agg

agg - asciinema gif generator

agg is a command-line tool for generating animated GIF files from terminal session recordings.

It supports conversion from asciicast files produced by asciinema recorder. It uses Kornel Lesiński's excellent gifski library to produce optimized, high quality GIF output with accurate frame timing.

Example GIF file generated with agg:

Notable features:

• conversion of asciicast recordings (v1, v2, v3) to animated GIF files,
• input from local files, stdin, or HTTP(S) URLs (e.g. asciinema.org recording links),
• high-quality, optimized GIF output with accurate frame timing via the gifski encoder,
• multiple built-in color themes (asciinema, dracula, monokai, github-dark, github-light, kanagawa, nord, solarized-dark, solarized-light, gruvbox-dark, and more),
• custom ad-hoc themes specified as hex color triplets,
• automatic use of the recording's embedded theme when present,
• configurable font families with sensible cross-platform defaults and implicit fallbacks for symbols, including automatic Nerd Font symbols rendering,
• configurable font size and line height,
• additional font directory support via --font-dir for fonts outside standard system locations,
• color emoji rendering with support for Apple Color Emoji, Noto Color Emoji, and other common emoji fonts,
• two selectable rendering backends: swash (default) and resvg,
• adjustable playback speed,
• idle time limiting to skip periods of inactivity,
• frame selection by time ranges, discrete positions, markers, percentages, and event indexes,
• looped or single-pass playback,
• configurable FPS cap and last-frame duration,
• terminal size override (cols/rows) for re-rendering at a different geometry.

Check out the agg docs for installation and usage overview.

Building

Building from source requires Rust compiler (1.86.0 or later) and Cargo package manager. You can install both with rustup.

To download source code, build agg binary and install it in $HOME/.cargo/bin run:

cargo install --git https://github.com/asciinema/agg

You need to ensure $HOME/.cargo/bin is in your shell's $PATH.

Alternatively, you can manually download source code and build agg binary with:

git clone https://github.com/asciinema/agg
cd agg
cargo build --release

This produces an executable file in release mode (--release) at target/release/agg. There are no other build artifacts so you can copy the binary to a directory in your $PATH.

Building with Docker

Alternatively, if you have Docker, Podman or another Docker-compatible tool installed you can use it to build agg container image. This doesn't require Rust toolchain installed on your machine.

Build the image with the following command:

docker build -t agg .

Then run agg like this:

docker run --rm -u $(id -u):$(id -g) -v $PWD:/data agg demo.cast demo.gif

If you use Podman in root-less mode:

podman run --rm -v $PWD:/data agg demo.cast demo.gif

Consulting

If you're interested in customization of agg or any other asciinema component to for your corporate needs, check asciinema consulting services.

License

© 2022 Marcin Kulik.

All code is licensed under the GPL, v3 or later. See LICENSE file for details.