This package has been deprecated

    Author message:

    Package no longer supported. Contact Support at for more info.


    0.2.1 • Public • Published


    asciicast2gif is a tool for generating GIF animations from asciicast files recorded by asciinema.

    How it works

    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.


    You can install asciicast2gif with npm, use it via Docker image, or build it from source.

    npm package

    To install asciicast2gif using npm run:

    npm install --global asciicast2gif

    Following runtime dependencies need to be also installed:

    Docker image

    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 below for all command line arguments, options etc.

    Note: if you want to override gifsicle options (via GIFSICLE_OPTS env var) when using Docker image you need to pass it via Docker's -e option.

    Building from source

    Clone the repository:

    git clone --recursive
    cd asciicast2gif

    All further commands are assumed to be called from within the checked out directory.

    Install build time dependencies

    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.

    Install runtime dependencies

    Following runtime dependencies need to be installed:

    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 demo.gif

    example gif 1

    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

    example gif 2

    Setting custom gifsicle options

    You can override default options passed to giflossy/gifsicle by setting GIFSICLE_OPTS environment variable.

    Default options when giflossy is installed are:

    -k 64 -O2 -Okeep-empty --lossy=80

    Default options when gifsicle is installed are:

    -k 64 -O2 -Okeep-empty

    For example to generate 16 color gif, with level 3 optimizations, set it like this:

    GIFSICLE_OPTS="-k 16 -O3"


    You can set DEBUG=1 environment variable to make the output of the conversion process more verbose.

    Tweaking conversion process

    You can pass extra arguments to Node.js script invocation via NODE_OPTS environment variable.

    Limiting node process memory usage

    Limit Node's heap size to 512 MB:

    NODE_OPTS="--max-old-space-size=512" asciicast2gif ...


    There are following alternative tools solving this problem:


    Copyright © 2017 Marcin Kulik.




    npm i asciicast2gif

    DownloadsWeekly Downloads






    Unpacked Size

    830 kB

    Total Files


    Last publish


    • sickill