asciicast2gif is a tool for generating GIF animations from asciicast files recorded by asciinema.
Here's how the asciicast->GIF conversion is implemented.
asciicast2gif
shell script parses command line arguments and executes Node.js script
(main.js
). main.js
loads asciicast (either from remote URL or local
filesystem), generates text representation of the screen for each frame
using asciinema-player's
virtual terminal emulator, and sends it to PhantomJS-based renderer script
(renderer.js
), which saves PNG screenshots to a temporary directory. Finally,
main.js
calls ImageMagick's convert
on these PNG images to construct GIF
animation, also piping it to gifsicle
to get the final, optimized GIF file.
Note, asciicast2gif
doesn't capture screenshots at a fixed frame-rate (e.g. 30 FPS)
like alternative tools. Instead, it generates PNG files for
each screen update, and specifies delay for every image individually (convert -delay <delay-a> 0.png -delay <delay-b> 1.png -delay <delay-c> 2.png ...
). When
the screen is idle there're no screenshots generated. This saves disk space and
makes it less work for both convert
and gifsicle
, while resulting in smaller
GIF file.
Due to the multitude of build time and runtime dependencies the easiest (and recommended) way to use asciicast2gif is through asciicast2gif Docker image. If you'd rather build it yourself then follow the instructions below.
Clone the repository:
git clone --recursive https://github.com/asciinema/asciicast2gif.git
cd asciicast2gif
All further commands are assumed to be called from within the checked out directory.
Both Node.js script (main.js
) and page script used by renderer's HTML page
(page/page.js
) need to be build from
ClojureScript source code.
You need Java 8 JDK and Leiningen.
Following runtime dependencies need to be installed:
- Node.js
- PhantomJS (optional, see below)
- ImageMagick
- gifsicle
Install Node.js wrapper for PhantomJS:
npm install
If you don't have PhantomJS available in $PATH
at this point it will be
automatically downloaded during
phantomjs-prebuilt
package installation.
To build the scripts run:
lein cljsbuild once main && lein cljsbuild once page
asciicast2gif [-t theme] [-s speed] [-S scale] [-w cols] [-h rows] <input-json-path-or-url> <output-gif-path>
Following options are supported:
-t <theme> color theme, one of: asciinema, tango, solarized-dark, solarized-light, monokai (default: asciinema)
-s <speed> animation speed (default: 1)
-S <scale> image scale / pixel density (default: 2)
-w <columns> clip terminal to specified number of columns (width)
-h <rows> clip terminal to specified number of rows (height)
Example of generating GIF from asciicast URL, with default options (normal speed, double pixel density, asciinema theme):
asciicast2gif https://asciinema.org/a/118274.json demo.gif
Example of generating GIF from local asciicast file, with Solarized Dark theme,
double speed (-s 2
), single pixel density (-S 1
):
asciicast2gif -t solarized-dark -s 2 -S 1 118274.json demo.gif
You can set DEBUG=1
environment variable to make the output of the conversion
process more verbose.
You can pass extra arguments to Node.js script invocation via NODE_OPTS
environment variable.
Limit Node's heap size to 512 MB:
NODE_OPTS="--max-old-space-size=512" asciicast2gif ...
You can use asciicast2gif through official asciicast2gif Docker image (automated build on Docker Hub from this repository).
Pull the image:
docker pull asciinema/asciicast2gif
Use it like this:
docker run --rm -v $PWD:/data asciinema/asciicast2gif [options and arguments...]
You need to mount some local directory at /data
so input and output files can
be accessed by the container. Mounting current working directory ($PWD
) makes
most sense in majority of cases.
For example, generating GIF from local file, with double speed and Solarized theme:
docker run --rm -v $PWD:/data asciinema/asciicast2gif -s 2 -t solarized-dark demo.json demo.gif
Running the above, long command can get old very quickly. Creating a shell alias may be a good idea:
alias asciicast2gif='docker run --rm -v $PWD:/data asciinema/asciicast2gif'
Look at general usage instructions above for all command line arguments, options etc.
There are following alternative tools solving this problem:
Copyright © 2017 Marcin Kulik.