Create an animated GIF of your console sessions

animate all the things

When I write articles, sometimes I feel the need to show how the commands behave interactively, not only the sequence of commands you have to type.
It’s easier to understand by looking at an animation, than reading “when you hit TAB <this happens>”.

For example, can you explain how the emmet plugin for VIM works, better than this, using only words?

emmet plugin for VIM

Fortunately, the solution is pretty easy.

You need a few open source tools, if you’re on a Mac, like me, you should already have installed Homebrew, and Imagemagick (brew install imagemagick).

To record your sessions, you need ttyrec (brew install ttyrec on Mac).

usage: ttyrec [-u] [-e command] [-a] [file]

OPTIONS
      -a     Append the output to file or ttyrecord, rather than overwriting it.

      -u     With this option, ttyrec automatically calls uudecode(1) and  saves  its  output  when  uuencoded  data
             appear on the session.  It allow you to transfer files from remote host.  You can call ttyrec with this
             option, login to the remote host and invoke uuencode(1) on it for the file you want to transfer.

      -e command
             Invoke command when ttyrec starts.

file is the name of the file that will be used to record the session. If no file name is given, ttyrecord will be used.

A new session is started as soon as you launch ttyrec and is automatically saved when you close the session with CTRL+D or exit.

To replay an already saved session, use

ttyplay [-s SPEED] [-n] [-p] file

OPTIONS
      -s SPEED
             multiple the playing speed by SPEED (default is 1).

      -n     no wait mode.  Ignore the timing information in file.

      -p     peek another person's tty session.

Let’s see how it looks

ttyrec session

Now that we have a recorded sessions, we need to convert it to an animated GIF.

We’ll use ttygif for the task.

There’s no installer for it, you must compile it from the sources

$ git clone https://github.com/icholy/ttygif.git
$ cd ttygif
$ make

Once make is done, you will find some executable files in the folder

-rwxr-xr-x   1 maks  staff    881 Nov  5 16:08 concat.sh
-rwxr-xr-x   1 maks  staff    829 Nov  5 16:08 concat_osx.sh
-rwxr-xr-x   1 maks  staff  14836 Nov  5 16:08 ttygif

In my setup I’ve linked ttygif to /usr/local/bin and concat.sh (concat_osx.sh in case you’re on a Mac) to /usr/local/bin/ttyconcat to avoid name clashes.

Creating the gif is a two steps process: first you launch ttygif <recfile> to generate a sequence of PNGs, then you launch the ttyconcat script we linked before and it automatically creates the animated GIF for you.

Optionally you can pass and output filename to ttyconcat, if omitted the image will be saved as output.gif.

If you are a prefectionist, there’s an optional final step, install gifsicle (brew install gifsicle) and give your animation the final touches.

I usually add a fixed delay between frames, make it loop forever and optimize the size with this command line

gifsicle --delay=10 --loop=0 -O3 < in.gif > out.gif

More otpions can be found on the gifsicle man page.

Leave a Reply

wpDiscuz