2.0 Published on 18 Feb 2018 by Marcin Kulik

I’m very happy to announce the release of asciinema 2.0!

It’s been 3 years since 1.0 (time flies!), and during this period many ideas have been brought to life through series of minor releases. This time the scope and importance of the changes required major version bump.

Below we’ll go through all the changes in detail, you can also read the CHANGELOG for a shorter version.

asciicast v2 file format

asciinema 2.0 saves recordings in new asciicast v2 format. It’s based on newline-delimited JSON spec, and enables incremental writing and reading of the recording.

It solves several problems which couldn’t be easily fixed in the old format. Mainly:

Due to file structure change (standard JSON => newline-delimited JSON) version 2 is not backwards compatible with version 1. Support for v2 recordings has already been added in asciinema web player (2.6.0) and asciinema server (v20171105 tag in git repository). These will handle both v1 and v2 playback nicely, older versions of the recorder, player and server won’t be able to play v2 recordings though.

asciinema.org is now running the latest server and web player code and thus it fully supports this new format.

Terminal-to-terminal streaming

Previous versions of asciinema supported in-terminal playback by piping in the recording to its stdin:

cat /path/to/asciicast.json | asciinema play -
ssh user@host cat asciicast.json | asciinema play -

While useful in some scenarios, the whole recording had to be read into memory before starting the playback (you can’t easily parse JSON partially). New format, being stream friendly, allows starting the playback immediately after receiving the header line.

For example, you can now do terminal-to-terminal streaming via a named Unix pipe:

mkfifo /tmp/demo.pipe

# viewing terminal
asciinema play /tmp/demo.pipe

# recording terminal
asciinema rec /tmp/demo.pipe

Or stream terminal over the network with netcat:

# viewing terminal (hostname: node123)
asciinema play <(nc -l localhost 9999)

# recording terminal
asciinema rec >(nc node123 9999)

With new --raw recording mode (more on that below) you don’t even need asciinema installed on the viewing machine:

# viewing terminal (hostname: node123)
nc -l localhost 9999

# recording terminal
asciinema rec --raw >(nc node123 9999)

Appending to existing recording

You can now append new session to an existing asciicast file. This can be useful when you want to take a break when recording.

Start recording:

asciinema rec demo.cast

When you need a break, press <ctrl+d> to finish recording. Then when you’re ready to continue run:

asciinema rec --append demo.cast

You can do this as many times as you want.

Raw recording mode

You can now save raw stdout output, without timing information or other metadata, to a file:

asciinema rec --raw output.txt

The output file produced in this case is not in asciicast format, and is exactly like the one produced by script command (without timing file).

You can then use cat to print the result of the whole session:

cat output.txt

Stdin (keystroke) recording

Stdin recording allows for capturing of all characters typed in by the user in the currently recorded shell:

asciinema rec --stdin demo.cast

This may be used to display pressed keys during playback in asciinema-player (not implemented yet!). Because it’s basically a key-logging (scoped to a single shell instance), it’s disabled by default, and has to be explicitly enabled via --stdin option.

Pausing playback

When replaying the asciicast in terminal with asciinema play demo.cast, you can now press space to pause/resume. When paused, you can use . (dot key) to step through the recording, a frame at a time, which can be very useful during presentations! And, as before, ctrl+c will exit.

New cat command

While asciinema play <filename> replays the recorded session using timing information saved in the asciicast, asciinema cat <filename> dumps the full output (including all escape sequences) of the recording to a terminal immediately.

When you have existing recording, this command:

asciinema cat existing.cast >output.txt

produces the same result as recording raw output with:

asciinema rec --raw output.txt


I’m especially happy about the first class support for real-time, incremental recording. It’s not only important for the features introduced with this release, but it nicely prepares the ground for other live streaming options (directly to web player, or indirectly to web player via asciinema-server). This will most likely be an area where the most focus will go in the future.

Some of the native packages have already been updated (thanks to awesome package maintainers!), the rest will hopefully follow soon. See installation docs for detailed instructions for you system.

Enjoy better terminal recording and sharing!

comments powered by Disqus