From d8f84d99f4376b3a2fef3556220aa27fb8b2be3b Mon Sep 17 00:00:00 2001 From: Marcin Kulik Date: Wed, 25 Feb 2015 15:26:38 +0100 Subject: [PATCH] Document asciicast file format --- README.md | 12 ++++----- doc/asciicast-v1.md | 62 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 6 deletions(-) create mode 100644 doc/asciicast-v1.md diff --git a/README.md b/README.md index 2f70fb7..53f942a 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ If you want to install it in other location: asciinema cli is composed of multiple (sub)commands, similar to `git`, `rails` or `brew`. -If you run `asciinema` with no arguments, help will be displayed showing all +If you run `asciinema` with no arguments help message is displayed showing all available commands. In addition to this, you can run any asciinema command with the `-h` switch @@ -71,11 +71,11 @@ Recording finishes when you exit the shell (hit Ctrl+D or type the process exits. If the `filename` argument is given then the resulting recording (called -*asciicast*) is saved to a local file. It can later be replayed with `asciinema -play ` and/or uploaded to asciinema.org with `asciinema upload -`. If the `filename` argument is omitted then (after asking for -confirmation) the resulting asciicast is uploaded to asciinema.org for further -playback in the browser. +[asciicast](doc/asciicast-v1.md)) is saved to a local file. It can later be +replayed with `asciinema play ` and/or uploaded to asciinema.org with +`asciinema upload `. If the `filename` argument is omitted then +(after asking for confirmation) the resulting asciicast is uploaded to +asciinema.org for further playback in the browser. `ASCIINEMA_REC=1` is added to recorded process environment variables. This can be used by your shell's config file (`.bashrc`, `.zshrc`) to alter the diff --git a/doc/asciicast-v1.md b/doc/asciicast-v1.md new file mode 100644 index 0000000..faa3323 --- /dev/null +++ b/doc/asciicast-v1.md @@ -0,0 +1,62 @@ +# asciicast file format (version 1) + +asciicast file is JSON file containing meta-data like duration or title of the +recording, and the actual content printed to terminal's stdout during +recording. + +## Attributes + +Every asciicast includes the following set of attributes: + +* `version` - set to 1, +* `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, +* `stdout` - array of "frames", see below. + +### Frame + +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](http://www.ietf.org/rfc/rfc4627.txt), 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...`. + +## Example asciicast + +A very short asciicast may look like this: + + { + "version": 1, + "width": 80, + "height": 24, + "duration": 1.515658795, + "command": "/bin/zsh", + "title": "", + "env": { + "TERM": "screen-256color", + "SHELL": "/bin/zsh" + }, + "stdout": [ + [ + 0.248848, + "\u001b[1m\u001b[3m%\u001b[23m\u001b[1m\u001b[0m" + ], + [ + 0.001376, + "\r\u001b[0m\u001b[23m\u001b[24m\u001b[J\u001b[34" + ] + ] + }