termtosvg

Record a terminal session and get a standalone SVG animation you can drop into any web page.

No video encoding, no player to embed, no JavaScript. The output is a single vector file where the text is still text.

Maintained by Gabor Lepsenyi · gaborl.hu

• 🖼️ Gallery of examples
• 🎨 Gallery of templates
• 📖 Manual page · Writing templates

Why SVG

The animation above is a 26-second session at 82×19 characters, in 50 KB. That is one file, and the properties that come with it are not available from a screen recording:

Installation

termtosvg runs on Linux, macOS and the BSDs, and requires Python 3.10 or later.

python3 -m venv .venv
source .venv/bin/activate
pip install termtosvg-ng

Three equivalent ways to run it — use whichever reads best to you:

termtosvg          # the historical command name
termtosvg-ng       # matches the name you installed
python3 -m termtosvg

[!IMPORTANT] Why the install name carries -ng. The plain termtosvg name on PyPI belongs to the original author and last shipped 1.1.0 in January 2020. That release predates the removal of pkg_resources from setuptools, so on Python 3.12 and later it fails at import with ModuleNotFoundError: No module named 'pkg_resources' — every command, --version included, dies immediately. termtosvg-ng is the same tool with that fixed.

The termtosvg command is kept so that existing scripts, tutorials and distro packaging continue to work unchanged. The import package is termtosvg as well.

pip install git+https://github.com/gaborini/termtosvg.git@develop

Quick start

Start recording. You land in a subshell — type as you normally would.

$ termtosvg
Recording started, enter "exit" command or Control-D to end

Leave the shell to finish:

$ exit
Recording ended, file is /tmp/termtosvg_exp5nsr4.svg

Open it in a browser to watch it, then embed it with a relative link:

![My demo](./demo.svg)

How it works

termtosvg separates capturing from drawing, which is what makes the output editable and reproducible:

                  ┌──────────────┐                   ┌──────────────┐
   your shell ──► │    record    │ ──► .cast file ──► │    render    │ ──► .svg
                  └──────────────┘   (asciicast v2)   └──────────────┘
                                            ▲                ▲
                                     hand-editable      SVG template
                                     timings & text     (theme + chrome)

Running termtosvg with no sub-command does both in one pass. Splitting them is useful because the intermediate .cast file is plain text: you can fix a typo, retime a pause, or re-render the same recording with a different theme without performing the session again.

termtosvg record demo.cast          # capture only
termtosvg render demo.cast out.svg  # draw, as often as you like

Because render reads the asciicast format (v1 and v2), it also renders recordings made with asciinema.

Command line reference

Three forms. The default records and renders in one go:

termtosvg [output_path] [-c COMMAND] [-D DELAY] [-g GEOMETRY] [-m MIN_DURATION]
          [-M MAX_DURATION] [-s] [-t TEMPLATE] [-v] [-h]

termtosvg record [output_path] [-c COMMAND] [-g GEOMETRY] [-v] [-h]

termtosvg render input_file [output_path] [-D DELAY] [-m MIN_DURATION]
                 [-M MAX_DURATION] [-s] [-t TEMPLATE] [-h]

Not every option applies to every form — render takes its geometry from the recording, so it has no -g:

¹ Unless the recording's header carries idle_time_limit, which is then used.

Durations accept a bare integer or an ms suffix — -m 17 and -m 17ms are the same. output_path is optional everywhere; a temporary file is generated when it is omitted (a directory, with --still-frames).

Templates

A template supplies the colour theme, the font, any window chrome, and how the animation is driven. Pass one by name with -t:

Colours separately from chrome

A template bundles two independent things: the colour palette and the terminal chrome (window frame, play button, progress bar). --theme lets you vary the colours without authoring a template, so any palette combines with any chrome:

termtosvg render demo.cast out.svg -t window_frame --theme dracula

--theme accepts:

auto is useful for recordings made with asciinema, which store the terminal's palette in the cast file. Recordings made by termtosvg record do not store one, so auto warns and keeps the template's colours.

A palette file uses the same shape as the asciicast theme object, so it can be copied straight out of a .cast header:

{
  "fg": "#839496",
  "bg": "#002b36",
  "palette": "#073642:#dc322f:#859900:#b58900:#268bd2:#d33682:#2aa198:#eee8d5"
}

Eight or sixteen colours are both accepted. With eight, the bright half is left as the template defined it rather than being guessed at.

Names are resolved in a fixed order — auto, then a built-in name, then a path — so an argument never means something different depending on your working directory. To load a file called dracula, write ./dracula.

Embedding, and one caveat worth knowing

Fifteen of the sixteen templates animate through pure CSS, so they play when loaded as an ordinary image — including from a Markdown ![...]() in a GitHub README.

window_frame_js is the exception: its play/pause controls need JavaScript, and browsers do not execute scripts inside an SVG loaded via <img>. Embed that one with <object> or <iframe>, or link to the file directly:

<object type="image/svg+xml" data="demo.svg"></object>

Writing your own template is documented in termtosvg-templates(5). The shipped templates under termtosvg/data/templates/ are the best starting point — copy one and edit its palette.

Recipes

# Record a specific program instead of a shell
termtosvg -c 'ipython --pprint' demo.svg

# Pin the geometry so the animation is not tied to your window size
termtosvg -g 82x19 demo.svg

# Tame a chatty command: coalesce sub-17ms frames, cap pauses at 2s
termtosvg -m 17 -M 2000 demo.svg

# Re-theme an existing recording — no need to perform it again
termtosvg render demo.cast dracula.svg -t dracula

# Keep the chrome, swap only the colours
termtosvg render demo.cast out.svg -t window_frame --theme solarized_light

# Use the palette the recording was made with (asciinema casts store one)
termtosvg render downloaded.cast out.svg --theme auto

# Render someone else's asciinema recording
termtosvg render downloaded.cast out.svg

# Still frames, e.g. to pick a thumbnail
termtosvg render demo.cast frames/ --still-frames

# Two seconds of breathing room between loops
termtosvg -D 2000 demo.svg

Compatibility

Windows shells can still be recorded — the powershell template exists for styling such recordings — but termtosvg itself must run on a POSIX host.

Development

make install   # editable install with dev extras
make tests     # unit tests with coverage
make lint      # ruff
make build     # sdist + wheel into dist/
make html      # regenerate the example gallery

make lint runs ruff check. The formatter is intentionally not enforced; see the note in pyproject.toml for why.

Rendering is deterministic, which makes it easy to prove a change did not alter output: render the casts in docs/examples/casts/ before and after, and compare bytes.

Bug reports and pull requests are welcome at github.com/gaborini/termtosvg.

Maintainer

Gabor Lepsenyi — gaborl.hu · github.com/gaborini

Licensed under the BSD 3-Clause License.

_{Originally created by Nicolas Bedos, who wrote the recorder, the rendering engine and the template system. Copyright is retained as required by the license.}