README

congif
======

This is  an experimental tool  that generates GIF animations  of console
sessions.  Like  scriptreplay(1),  it  reads the  output  of  script(1),
including timing information. Unlike  scriptreplay(1), congif parses the
session dialogue and encodes it as a GIF animation that can be viewed on
graphical programs (e.g. web browsers).


Limitations
-----------

Only dialogues generated  for the Linux console can  be correctly parsed
by congif.  This means that  if your  $TERM environment variable  is not
"linux" then  it probably won't  work. You  can manually set  $TERM when
calling script(1), but  then your terminal may not  work correctly while
the session is recorded. It's  recommended that you record your sessions
on  the  Linux  console  itself,  or on  a  terminal  emulator  that  is
compatible with console_codes(4).

congif needs  to know  the terminal  size used  during the  execution of
script(1) and this size must be constant per session (i.e. if you resize
the terminal while recording a  session, congif won't work). By default,
congif assumes  that the terminal  size of the  session is equal  to the
current terminal size. Use the options -w  and -h if you need to specify
a different size.


Building
--------

A C99 compiler is needed. There are no library dependencies.

$ make


Usage
-----

congif [options] timings dialogue

    timings:       File generated by script(1)'s -t option
    dialogue:      File generated by script(1)'s regular output

    options:
      -o output    File name of GIF output
      -m maxdelay  Maximum delay, as in scriptreplay(1)
      -d divisor   Speedup, as in scriptreplay(1)
      -l count     GIF loop count (0 = infinite loop)
      -f font      File name of MBF font to use
      -h lines     Terminal height
      -w columns   Terminal width
      -c on|off    Show/hide cursor
      -q           Quiet mode (don't show progress bar)
      -v           Verbose mode (show parser logs)


Fonts
-----

For  simplicity, congif  uses a  custom font  format, MBF.  The font
misc-fixed [1], included in this distribution, is used by default.

For  more  information on  the  MBF  format,  see the  mbf-util  [2]
project. It  includes a  bdf2mbf tool that  converts fonts  from the
popular BDF format to the MBF format.


Examples
--------

Recording a session:
$ script -t 2> foo.t foo.d

Generating a GIF file with defaults (creates "con.gif"):
$ congif foo.t foo.d

Generating a faster version:
$ congif -d3 -m1 -o fast.gif foo.t foo.d


Copying
-------

All of the source code and documentation for congif is released into the
public domain and provided without warranty of any kind.


Links
-----

[1] http://www.cl.cam.ac.uk/~mgk25/ucs-fonts.html
[2] https://github.com/lecram/mbf-util