.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "TERMTOSVG" "1" "July 2019" "" ""
.hy
.SS NAME
.PP
termtosvg - record terminal sessions as standalone SVG animations
.SS SYNOPSIS
.PP
\f[B]termtosvg\f[R] [output_path] [-c COMMAND] [-D DELAY] [-g GEOMETRY]
[-m MIN_DURATION] [-M MAX_DURATION] [-s] [-t TEMPLATE] [\[en]help]
.PP
\f[B]termtosvg record\f[R] [output_path] [-c COMMAND] [-g GEOMETRY] [-h]
.PP
\f[B]termtosvg render\f[R] \f[I]input_file\f[R] [output_path] [-D DELAY]
[-m MIN_DURATION] [-M MAX_DURATION] [-s] [-t TEMPLATE] [-h]
.SS DESCRIPTION
.PP
termtosvg makes recordings of terminal sessions in animated SVG format.
.SS COMMANDS
.PP
The default behavior of termtosvg is to render an SVG animation of a
shell session.
If no output filename is provided, a random temporary filename will be
automatically generated.
.SS termtosvg record
.PP
Record a terminal session in asciicast v2 format.
The recording is a text file which contains timing information as well
as what was displayed on the screen during the terminal session.
It may be edited to alter the timing of the recording or the information
displayed on the screen of the terminal.
.SS termtosvg render
.PP
Render an animated SVG from a recording in asciicast v1 or v2 format.
This allows rendering in SVG format of any recording made with
asciinema.
Rendering of still frames is also possible.
.SS OPTIONS
.SS -c, \[en]command=COMMAND
.PP
Specify the program to record with optional arguments.
COMMAND must be a string listing the program to execute together will
all arguments to be made available to the program.
For example \f[V]--command=\[aq]python -h\[aq]\f[R] would make termtosvg
record the usage of the Python interpreter.
If this option is not set, termtosvg will record the program specified
by the $SHELL environment variable or \f[V]/bin/sh\f[R].
.SS -D, \[en]loop-delay=DELAY
.PP
Duration of the delay between two consecutive loops of the animation in
milliseconds.
.SS -g, \[en]screen-geometry=GEOMETRY
.PP
Geometry of the terminal screen used for rendering the animation.
The geometry must be given as the number of columns and the number of
rows on the screen separated by the character \[lq]x\[rq].
For example \[lq]82x19\[rq] for an 82 columns by 19 rows screen.
.SS -h, \[en]help
.PP
Print usage and exit
.SS -m, \[en]min-frame-duration=MIN_DURATION
.PP
Set the minimum duration of a frame in milliseconds.
Frames lasting less than MIN_DURATION milliseconds will be merged with
consecutive frames.
The default behavior of termtosvg is to produce a frame for each update
of the terminal screen, but when recording commands that update the
screen very frequently this can cause animations filesize to blow up.
Enforcing a minimum frame duration helps reduces the number of frame of
the animations, and thus helps control the size of animation.
MIN_DURATION defaults to 1 millisecond.
.SS -M, \[en]max-frame-duration=MAX_DURATION
.PP
Set the maximum duration of a frame to MAX_DURATION milliseconds.
Frames lasting longer than MAX_DURATION milliseconds will simply see
their duration reduced to MAX_DURATION.
.SS -t, \[en]template=TEMPLATE
.PP
Set the SVG template used for rendering the SVG animation.
TEMPLATE may either be one of the default templates
(base16_default_dark, dracula, gjm8_play, gjm8_single_loop, gjm8,
powershell, progress_bar, putty, solarized_dark, solarized_light,
terminal_app, ubuntu, window_frame_js, window_frame_powershell,
window_frame, xterm) or a path to a valid template.
.SS -s, \[en]still-frames
.PP
Output still frames in SVG format instead of an animated SVG.
If this option is specified, output_path refers to the destination
directory for the frames.
.SS SVG TEMPLATES
.PP
Templates make it possible to customize the SVG animation produced by
termtosvg in a number of ways including, but not limited to:
.IP \[bu] 2
Specifying the color theme and font used for rendering the terminal
session
.IP \[bu] 2
Adding a custom terminal window frame to the animation to make it look
like a real terminal
.IP \[bu] 2
Adding JavaScript code to pause the animation, seek to a specific frame,
etc
.PP
See termtosvg-templates(5) for more details.
.SS ENVIRONMENT
.PP
In case the \f[V]--command\f[R] option is not specified, termtosvg will
spawn the shell specified by the SHELL environment variable, or
\f[V]/bin/sh\f[R] if the variable is not set.
.SS EXAMPLES
.PP
Record a terminal session and produce an SVG animation named
\f[V]animation.svg\f[R]:
.IP
.nf
\f[C]
termtosvg animation.svg
\f[R]
.fi
.PP
Record a terminal session and render it using a specific template:
.IP
.nf
\f[C]
termtosvg -t \[ti]/templates/my_template.svg
\f[R]
.fi
.PP
Record a specific program such as IPython with the pretty printing
option:
.IP
.nf
\f[C]
termtosvg -c \[aq]ipython --pprint\[aq]
\f[R]
.fi
.PP
Record a terminal session with a specific screen geometry:
.IP
.nf
\f[C]
termtosvg -g 80x24 animation.svg
\f[R]
.fi
.PP
Record a terminal session in asciicast v2 format:
.IP
.nf
\f[C]
termtosvg record recording.cast
\f[R]
.fi
.PP
Render an SVG animation from a recording in asciicast format
.IP
.nf
\f[C]
termtosvg render recording.cast animation.svg
\f[R]
.fi
.PP
Enforce both minimal and maximal frame durations
.IP
.nf
\f[C]
termtosvg -m 17 -M 2000
\f[R]
.fi
.PP
Specify a 2 seconds delay between animation loops
.IP
.nf
\f[C]
termtosvg -D 2000
\f[R]
.fi
.PP
Render still frames instead of an animated SVG using a specific template
.IP
.nf
\f[C]
termtosvg -s -t gjm8_play
\f[R]
.fi
.SH AUTHORS
Nicolas Bedos.