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.

• 🖼️ 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

Then run it as either termtosvg or python3 -m termtosvg.

[!IMPORTANT] The install name and the command name differ, on purpose. You install termtosvg-ng but you run termtosvg; the import package is termtosvg too.

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.

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:

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

# 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.

Credits

termtosvg was created by Nicolas Bedos, who wrote the recorder, the rendering engine and the template system. This repository continues from that work.

Licensed under the BSD 3-Clause License.