Introduction and usage of Ascinema in python

68747470733a2f2f61736369696e656d612e6f72672f612f34323338332e706e67.png Asciinema 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.

  • when the recording session is interrupted (computer crash, accidental close of terminal window) you no longer lose the whole recording,
  • minimal memory usage when recording and replaying long sessions - disk space is the only limit now,
  • it’s real-time streaming friendly (more on that below).

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. 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 scriptcommand (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



Boostlog is an online community for developers
who want to share ideas and grow each other.

Delete an article

Deleted articles are gone forever. Are you sure?