This is a complete rewrite of asciinema in Rust, upgrading the recording file format, introducing terminal live streaming, and bringing numerous improvements across the board.
Thanks to all the contributors who helped making it better, specifically @xfgusta, @gnachman, @mustafamohsen. Very special thanks to @moritzdietz for feedback, testing and fixes! Last but not least, thanks to @storpool for sponsoring work on several features that landed in this release.
Below is an overview of the most notable changes since 2.4.
New features
stream command
The new stream command enables terminal session live streaming, providing local mode (built-in HTTP server) and remote mode (relaying via asciinema server).
Local mode uses built-in HTTP server, allowing viewing of the stream on trusted networks (e.g. LAN). In this mode no data is sent anywhere, except to the viewers' browsers, for which you need to open a firewall port. The CLI bundles latest version of asciinema player, and uses it to connect to the stream from the page served by the built-in server.
$ asciinema stream --local
::: asciinema session started
::: Live streaming at http://127.0.0.1:37881
::: Press <ctrl+d> or type 'exit' to end
$ _
Remote mode publishes the stream through asciinema server (either asciinema.org or a self-hosted one), which acts as a relay, delivering the stream to the viewers at a shareable URL.
$ asciinema stream --remote
::: asciinema session started
::: Live streaming at https://asciinema.org/s/TQGS82DwiBS1bYAY
::: Press <ctrl+d> or type 'exit' to end
$ _
If you self-host asciinema server, and have automatic stream recording enabled, you can have a record of all your local sessions ready to be browsed and replayed.
You can use --local and --remote modes together as well. Check out asciinema stream --help for all options.
More details about how asciinema server implements streaming can be read here.
session command
The new session command allow for simultaneous recording and streaming. It's a more generic version of rec and stream combined.
$ asciinema session -l -r -o demo.cast`
::: asciinema session started
::: Recording to demo.cast
::: Live streaming at http://127.0.0.1:43829
::: Live streaming at https://asciinema.org/s/SG82TQYDbYAwiB1S
::: Press <ctrl+d> or type 'exit' to end
$ _
Check out asciinema session --help for all options.
convert command
The new convert command performs recording conversion between asciicast versions, and allows exporting to plain text log or raw output.
You can convert asciicast v2 recording to asciicast v3 format like this (v3 output is default):
asciinema convert demo-v2.cast demo-v3.cast
Or, you can convert asciicast v3 recording to asciicast v2 format like this:
You can also export a recording to a plain text log view, without any escape sequences, color information, just pure text as if you copied terminal's contents into a clipboard at the end of the session:
asciinema convert demo.cast demo.txt
The output format is inferred to be txt from the file extension, but you can be explicit about it:
asciinema convert -f txt demo.cast demo.log
Check out asciinema convert --help for all options.
asciicast v3 file format
The new asciicast v3 file format is the new default output format for rec, session and convert commands.
Notable changes in this new format:
it uses relative timestamps (intervals) for events, while v2 used absolute time (since session start) - this makes edits substantially easier
the header has been restructured, grouping related things together, e.g. all terminal related metadata is now under term
it supports new "x" (exit) event type for storing session exit status
it supports line comments with # character
Terminal theme capture
asciinema can now capture the actual terminal theme and save it in the recording file header under term.theme.
This is done by querying a terminal for colors using OSC 4, OSC 10 and OSC 11 sequences. It works on terminals that support the above queries, which is most these days.
asciinema player uses the saved theme when it's present in the recording file, falling back to its default built-in theme otherwise.
Plain text output
The plain text output mentioned earlier with the convert command can also be used with rec and the new session command.
Similarly, this output format is inferred from the .txt file extension, and can be explicitly selected with --output-format txt.
Note that, it's always possible to convert from asciicast to txt, but not in the reverse order because plain text output loses all metadata and timing information. Therefore it's typically better to default to asciicast output.
Improvements
Server URL prompt
When using a command that integrates with asciinema server (upload, stream, auth) for the first time, a new server URL prompt is shown, pre-filled with https://ascinema.org.
This lets you choose an asciinema server instance explicitly and intentionally. Handy for self-hosted scenarios. The choice is saved for future invocations.
If the server URL is preconfigured, either via config file or ASCIINEMA_SERVER_URL environment variable, then the prompt is not shown. The configuration also takes precedence over the URL entered at the prompt.
Automatic creation of parent directories
When recording to a file inside a non-existing directory, that directory (and all its parents) is now automatically created.
This is useful for example when you want to record all your terminal sessions automatically with a shell config like this:
# the very end of .bashrc
if [ -z "$ASCIINEMA_SESSION" ]; then
exec asciinema rec ~/sessions/$(date '+%Y/%m/%d/%H-%M-%S')-$$.cast
fi
Here asciinema will create directories for years, months and days that are present in the output path.
Improved built-in documentation
The --help messages have been significantly improved, containing detailed information about the effect and context for every option/flag. Make sure to use the long form --help instead of short h - the former is much more detailed!
The new man pages contain similar amount of information as the --help output. They can be generated by setting ASCIINEMA_GEN_DIR to a desired man page output directory when building asciinema from source. See the README for details.
Shell auto-completion
Shell auto-completion files for bash, zsh and fish can now be generated at build time as well. Like with man page generation, this is done by setting ASCIINEMA_GEN_DIR.
Breaking changes
This major release is a good occasion for rethinking things and correcting mistakes from the past. We tried to keep it to a minimum though!
No automatic uploads anymore
Since the very first version of asciinema, the filename argument to asciinema rec was optional (this is historical, I talk about this more in the blog post). When not present, the recording was saved to a tmp file, uploaded to asciinema.org, then automatically deleted.
This now changed - the filename is always required, and the rec command no longer has upload capability.
To publish a recording to asciinema.org or a self-hosted asciinema server, use the explicit asciinema upload <filename>.
asciicast v3 as the new default output file format
This may or may not be a breaking change for you. If you don't use any custom tooling around asciicast files, then you probably won't see a difference, as both the asciinema server and player support the new format already.
If you do use your own or community-provided tooling that reads asciicast files, then you may want to use --output-format asciicast-v2 with the rec command for backward compatibility.
Changed behavior of the cat command
The cat command in asciinema 2.x dumped the raw terminal output from one or more recording files. It both exported (converted) and concatenated.
In 3.0, the cat command only concatenates. It expects at least two arguments, and outputs a new recording in the file format matching that of the first input file.
You can use asciinema convert --output-format raw for the 2.x behavior.
New config file format and location
The user configuration file, previously at ~/.config/asciinema/config, has been moved to to ~/.config/asciinema/config.toml, and its format changed from "ini-style" to TOML.
The most notable changes are:
the api section has been renamed to server
the record section has been renamed to session - the session for the rec, stream and session commands can now be configured there