Recording terminal sessions using asciinema and its derivatives (Software Showcase #1)

Summary

Use asciinema for recording terminal sessions to local .cast files, replaying .cast files in a terminals, & for uploading .cast files to asciinema.org (or your own server).

• Recordings uploaded to asciinema.org can be embedded as dynamic asciinema recording iframes in HTML webpages (like those you see throughout this post!)
• On Windows, use PowerSession-rs (a drop-in replacement fork of asciinema)
• Use agg to convert asciinema recordings (.cast or web URL) to GIFs
• Use svg-term-cli to convert asciinema recordings (.cast or web URL) to animated SVGs

What are terminal session recorders?

Terminal session recorders, like asciinema ³, are CLI tools that can record (and playback recordings of) standard input/output in terminal sessions. What makes them different from just using screen recording software is that terminal session recorders run inside a terminal (instead of as a window display capture service running as a GUI program) and store the actual raw text from terminal sessions as a stream of events using a custom file format (asciicast for asciinema), which means that:

1. Recordings take up much less space compared to video files
2. You can actually copy the raw text being displayed when playing back recordings⁴ in the terminal or on the web; and
3. You can actually customize how terminal sessions look during playback by editing the recorded files or just by changing your playback settings (which means you don’t have to re-record sessions for small modifications like changing font styles)

What an asciinema recording embedded on the web looks like:

Shown: “Iterative git rebase with vim”. Source: https://asciinema.org/a/9593.

Why I care about terminal session recorders

That’s all very promising, but there’s two very specific reasons as to why I’m interested in terminal session recorders (and if you’re a software developer, you might be too):

1. I want to be able to show snippets of terminal sessions in blog posts on my website without slowing down pages by loading several videos (of which virtually all are expected to range from tens of seconds to a minute or two in length)

2. I want to be able to easily create GIFs/animated SVGs for READMEs for my projects on GitHub⁵

Why asciinema is not enough

But before we dive into those asciinema-derivatives, let’s take a quick look at what exactly asciinema has to offer (as well as how we can use it to record and playback terminal sessions).

Installation

You can install asciinema using PyPI via pip or using your package repository of choice on Linux, macOS, and FreeBSD (you can find the full list of supported OSes at docs.asciinema.org/manual/cli/installation).

> pip install asciinema

As you might’ve noticed, Windows is not listed under supported OSes. There’s a good reason for that, and we’ll get to it when we talk about PowerSession-rs.

Usage

Once you’ve got asciinema installed, there are 3 main commands:

asciinema on the web

You can view your and others’ uploaded recordings on asciinema.org (and there are quite a few cool recordings on there, from a demo of a mapping CLI to iterative git rebasing with vim). More importantly, you can embed uploaded recordings as iframes in HTML pages using some inline JavaScript as below:

<script src="https://asciinema.org/a/646222.js" id="asciicast-646222" async></script>

The resulting embedded asciinema recording:

While the look and feel of the embedded player defaults to the original uploader’s settings, you can override settings yourself using the following modifications to the inline script:

<script>
  src="https://asciinema.org/a/646222.js"
  id="..."
  data-start-at="00:40"
  data-autoplay="false"
  data-loop="true"
  data-speed="2.75"
  data-idle-time-limit="2"
  data-theme="solarized-light"
  data-poster="npt:1:23"  <!-- player preview frame timestamp -->
  data-cols="130"         <!-- terminal width -->
  data-rows="10"          <!-- terminal height -->
  data-preload="true"
  async>
</script>

Where asciinema falls flat

Usage

agg input.cast output.gif

agg https://asciinema.org/a/569727 output.gif

Where agg falls flat

To remedy that, we can use svg-term-cli, which is designed for rendering asiicast recordings to animated SVGs.

Why use animated SVGs over GIFs?

For one, animated SVGs are able to look a lot more crisp at larger resolutions than GIFs by using vector images instead of pixel based animation. Adding on to that (and why you should be using animated SVGs instead of GIFs when embedding recordings on websites), this also allows animated SVGs to have a much smaller file size, which is a very nice combination of features, making svg-term-cli almost[^wewillgettothis] the ideal tool for rendering your asciinema recordings (notable exception: you can’t rewind or copy text from recordings, making this more of a cosmetic option.).

An animated SVG generated from an asciinema recording using svg-term-cli:

Usage

After installing svg-term-cli via > npm install -g svg-term-cli(yes, this is in fact a Node.js application), you can render a local asciicast file or a recording at a URL to an animated SVG using the following:

svg-term --cast <filename/url> --out [filename]

Where svg-term-cli falls flat

Unfortunately, at the time you’re reading this, it’s been over 5 years since the last commit on the svg-term-cli project, so while it still works at the time of writing, we’re probably not going to be able to expect any of its 25 and counting open issues to be closed anytime soon (at least not until someone forks the repo and resumes maintenance for the project).

If you’re looking for a more up-to-date alternative, then there’s the Go-based termsvg, which is a functional but still early-stage CLI tool that’s able to record terminal sessions (just like asciinema) and export them to SVG¹¹.

An animated SVG generated from an asciinema recording using termsvg. Looks just as good (if not better) than one generated by svg-term-cli: