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.
asciinema.org is now running the latest server and web player code and thus it fully supports this new format.
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.
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:
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
When replaying the asciicast in terminal with asciinema play
demo.cast, you can now press space to
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