asciinema/doc/asciicast-v2.md

asciicast file format (version 2)

asciicast v2 file is NDJSON (newline delimited JSON) file where:

• first line contains meta-data (duration, terminal size etc), encoded as JSON object,
• all subsequent lines contain stream data, each line representing single stream element (event), encoded as JSON array.

Meta-data

Every asciicast v2 includes the following meta-data:

• version - set to 2,
• width - terminal width (number of columns),
• height - terminal height (number of rows),
• duration - total duration of asciicast as floating point number,
• command - command that was recorded, as given via -c option to rec,
• title - title of the asciicast, as given via -t option to rec,
• env - map of environment variables useful for debugging playback problems.

Example meta-data line:

{ "version": 2, "width": 80, "height": 24, "duration": 1.515658, "command": "/bin/zsh", "title": null, "env": { "TERM": "xterm-256color", "SHELL": "/bin/zsh" } }

Stream data

TODO: explain

[ time, event-type, event-data ]

TODO: explain

[ 1.001376, "o", "Hello world" ]

"o" event - print to stdout

TODO: change this section to reflect new structure

Frame represents an event of printing new data to terminal's stdout. It is a 2 element array containing delay and data.

Delay is the number of seconds that elapsed since the previous frame (or since the beginning of the recording in case of the 1st frame) represented as a floating point number, with microsecond precision.

Data is a string containing the data that was printed to a terminal in a given frame. It has to be valid, UTF-8 encoded JSON string as described in JSON RFC section 2.5, with all non-printable Unicode codepoints encoded as \uXXXX.

For example, frame [5.4321, "foo\rbar\u0007..."] means there was 5 seconds of inactivity between previous printing and printing of foo\rbar\u0007....

Complete asciicast v2 example

A very short asciicast v2 file looks like this:

{ "version": 2, "width": 80, "height": 24, "duration": 1.515658, "command": "/bin/zsh", "title": null, "env": { "TERM": "xterm-256color", "SHELL": "/bin/zsh" } }
[ 0.248848, "o", "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n" ]
[ 1.001376, "o", "This is overwritten\rThis is better." ]
[ 0.143733, "o", " " ]
[ 0.541828, "o", "Bye!" ]