From 0d35dba6b6a9221e90c51ff6bc8984cce13278ea Mon Sep 17 00:00:00 2001 From: Marcin Kulik Date: Wed, 10 Jan 2024 12:16:50 +0100 Subject: [PATCH] Link asciicast format docs to latest versions on docs.asciinema.org --- doc/asciicast-v1.md | 65 +------------- doc/asciicast-v2.md | 204 +------------------------------------------- 2 files changed, 2 insertions(+), 267 deletions(-) diff --git a/doc/asciicast-v1.md b/doc/asciicast-v1.md index de55223..75c9288 100644 --- a/doc/asciicast-v1.md +++ b/doc/asciicast-v1.md @@ -1,64 +1 @@ -# 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. - -Version 1 of the format was used by the asciinema recorder versions 1.0 up to 1.4. - -## 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.515658, - "command": "/bin/zsh", - "title": "", - "env": { - "TERM": "xterm-256color", - "SHELL": "/bin/zsh" - }, - "stdout": [ - [ - 0.248848, - "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n" - ], - [ - 1.001376, - "I am \rThis is on the next line." - ] - ] - } +Moved to [https://docs.asciinema.org/manual/asciicast/v1/](https://docs.asciinema.org/manual/asciicast/v1/). diff --git a/doc/asciicast-v2.md b/doc/asciicast-v2.md index ae9ab40..039836e 100644 --- a/doc/asciicast-v2.md +++ b/doc/asciicast-v2.md @@ -1,203 +1 @@ -# asciicast file format (version 2) - -asciicast v2 file is [newline-delimited JSON](http://jsonlines.org/) file where: - -* __first line__ contains header (initial terminal size, timestamp and other - meta-data), encoded as JSON object, -* __all following lines__ form an event stream, _each line_ representing a - separate event, encoded as 3-element JSON array. - -Example file: - -```json -{"version": 2, "width": 80, "height": 24, "timestamp": 1504467315, "title": "Demo", "env": {"TERM": "xterm-256color", "SHELL": "/bin/zsh"}} -[0.248848, "o", "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n"] -[1.001376, "o", "That was ok\rThis is better."] -[1.500000, "m", ""] -[2.143733, "o", "Now... "] -[4.050000, "r", "80x24"] -[6.541828, "o", "Bye!"] -``` - -Suggested file extension is `.cast`, suggested media type is -`application/x-asciicast`. - -## Header - -asciicast header is JSON-encoded object containing recording meta-data. - -### Required header attributes: - -#### `version` - -Must be set to `2`. Integer. - -#### `width` - -Initial terminal width (number of columns). Integer. - -#### `height` - -Initial terminal height (number of rows). Integer. - -### Optional header attributes: - -#### `timestamp` - -Unix timestamp of the beginning of the recording session. Integer. - -#### `duration` - -Duration of the whole recording in seconds (when it's known upfront). Float. - -#### `idle_time_limit` - -Idle time limit, as given via `-i` option to `asciinema rec`. Float. - -This should be used by an asciicast player to reduce all terminal inactivity -(delays between frames) to maximum of `idle_time_limit` value. - -#### `command` - -Command that was recorded, as given via `-c` option to `asciinema rec`. String. - -#### `title` - -Title of the asciicast, as given via `-t` option to `asciinema rec`. String. - -#### `env` - -Map of captured environment variables. Object (String -> String). - -Example env: - -```json -"env": { "SHELL": "/bin/bash", "TERM": "xterm-256color" } -``` - -> Official asciinema recorder captures only `SHELL` and `TERM` by default. All -> implementations of asciicast-compatible terminal recorder should not capture -> any additional environment variables unless explicitly permitted by the user. - -#### `theme` - -Color theme of the recorded terminal. Object, with the following attributes: - -- `fg` - normal text color, -- `bg` - normal background color, -- `palette` - list of 8 or 16 colors, separated by colon character. - -All colors are in the CSS `#rrggbb` format. - -Example theme: - -```json -"theme": { - "fg": "#d0d0d0", - "bg": "#212121", - "palette": "#151515:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#d0d0d0:#505050:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#f5f5f5" -} -``` - -> A specific technique of obtaining the colors from a terminal (using xrdb, -> requesting them from a terminal via special escape sequences etc) doesn't -> matter as long as the recorder can save it in the above format. - -## Event stream - -Each element of the event stream is a 3-tuple encoded as JSON array: - - [time, code, data] - -Where: - -* `time` (float) - indicates when the event happened, represented as the number - of seconds since the beginning of the recording session, -* `code` (string) - specifies type of event, one of: `"o"`, `"i"`, `"m"`, `"r"` -* `data` (any) - event specific data, described separately for each event - code. - -For example, let's look at the following line: - - [1.001376, "o", "Hello world"] - -It represents: - -* output (code `o`), -* of text `Hello world`, -* which happened `1.001376` sec after the start of the recording session. - -### Supported event codes - -This section describes the event codes supported in asciicast v2 format. - -The list is open to extension, and new event codes may be added in both the -current and future versions of the format. For example, we may add new event -code for text overlay (subtitles display). - -A tool which interprets the event stream (web/cli player, post-processor) should -ignore (or pass through) event codes it doesn't understand or doesn't care -about. - -#### "o" - output, data written to a terminal - -Event of code `"o"` represents printing new data to a terminal. - -`data` is a string containing the data that was printed. It must be valid, UTF-8 -encoded JSON string as described in [JSON RFC section -2.5](http://www.ietf.org/rfc/rfc4627.txt), with any non-printable Unicode -codepoints encoded as `\uXXXX`. - -#### "i" - input, data read from a terminal - -Event of code `"i"` represents character typed in by the user, or more -specifically, raw data sent from a terminal emulator to stdin of the recorded -program (usually shell). - -`data` is a string containing captured ASCII character representing a key, or a -control character like `"\r"` (enter), `"\u0001"` (ctrl-a), `"\u0003"` (ctrl-c), -etc. Like with `"o"` event, it's UTF-8 encoded JSON string, with any -non-printable Unicode codepoints encoded as `\uXXXX`. - -> Official asciinema recorder doesn't capture keyboard input by default. All -> implementations of asciicast-compatible terminal recorder should not capture -> it either unless explicitly requested by the user. - -#### "m" - marker - -Event of code `"m"` represents a marker. - -When marker is encountered in the event stream and "pause on markers" -functionality of the player is enabled, the playback should pause, and wait for -the user to resume. - -`data` can be used to annotate a marker. Annotations may be used to e.g. -show a list of named "chapters". - -#### "r" - resize - -Event of code `"r"` represents terminal resize. - -Those are captured in response to `SIGWINCH` signal. - -`data` contains new terminal size (columns + rows) formatted as -`"{COLS}x{ROWS}"`, e.g. `"80x24"`. - -## Notes on compatibility - -Version 2 of asciicast file format solves several problems which couldn't be -easily fixed in the old format: - -* minimal memory usage when recording and replaying arbitrarily long sessions - - disk space is the only limit, -* when the recording session is interrupted (computer crash, accidental close of - terminal window) you don't lose the whole recording, -* it's real-time streaming friendly. - -Due to file structure change (standard JSON => newline-delimited JSON) version 2 -is not backwards compatible with version 1. Support for v2 has been added in: - -* [asciinema terminal recorder](https://github.com/asciinema/asciinema) - 2.0.0 -* [asciinema web player](https://github.com/asciinema/asciinema-player) - 2.6.0 -* [asciinema server](https://github.com/asciinema/asciinema-server) - v20171105 - tag in git repository +Moved to [https://docs.asciinema.org/manual/asciicast/v2/](https://docs.asciinema.org/manual/asciicast/v2/).