Introduce asciicast v3 format

Author: ku1ik

docs/manual/asciicast/v3.md

@@ -0,0 +1,325 @@
+# asciicast v3
+
+!!! warning
+
+    While this new file format is mostly fleshed out, there still may be small
+    changes made to it before the final release of the asciinema CLI 3.0.
+
+asciicast v3 is a file format for terminal sessions recorded by [asciinema
+CLI](../cli/index.md) 3.0 and later.
+
+It's based on [newline-delimited JSON](http://jsonlines.org/).
+
+First line, encoded as JSON object, represents [the header](#header), which
+contains metadata, such as initial terminal size, timestamp, etc.
+
+All following lines form [the event stream](#event-stream). _Each line_
+represents a separate event, encoded as 3-element JSON array.
+
+Lines starting with `#` character are treated as comments and ignored for most
+intends and purposes. The first line of the file must not be a comment.
+
+asciicast v3 file looks like this:
+
+``` json
+{"version": 3, "term": {"cols": 80, "rows": 24, "type": "xterm-256color"}, "timestamp": 1504467315, "title": "Demo", "env": {"TERM": "xterm-256color", "SHELL": "/bin/zsh"}}
+# event stream follows the header
+[0.248848, "o", "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n"]
+[1.001376, "o", "That was ok\rThis is better."]
+[3.500000, "m", ""]
+[0.143733, "o", "Now... "]
+# terminal window resized to 90 cols and 30 rows
+[2.050000, "r", "90x30"]
+[1.541828, "o", "Bye!"]
+```
+
+## Header
+
+asciicast header is JSON-encoded object containing recording metadata.
+
+Complete header example, pretty formatted for readability:
+
+```json
+{
+  "version": 3,
+  "term": {
+    "cols": 80,
+    "rows": 24,
+    "type": "xterm-256color",
+    "version": "VTE(7802)",
+    "theme": {
+      "fg": "#d0d0d0",
+      "bg": "#212121",
+      "palette": "#151515:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#d0d0d0:#505050:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#f5f5f5"
+    }
+  },
+  "timestamp": 1509091818,
+  "idle_time_limit": 2,
+  "command": "/bin/bash",
+  "title": "Demo",
+  "env": {
+    "SHELL": "/bin/bash"
+  }
+}
+```
+
+Minimal header example:
+
+```json
+{"version": 3, "term": {"cols": 80, "rows": 24}}
+```
+
+Below list contains all attributes supported in the header. Attributes not
+marked as required may be omitted from the header, as seen in the minimal
+example above.
+
+### `version`
+
+Format version number.
+
+Must be set to `3`.
+
+__Required__ field.
+
+Type: integer
+
+
+### `term`
+
+Terminal information.
+
+__Required__ field.
+
+Type: object with the following attributes:
+
+#### `cols`
+
+Terminal width, i.e. number of columns.
+
+__Required__ field.
+
+Type: integer
+
+#### `rows`
+
+Terminal height, i.e. number of rows.
+
+__Required__ field.
+
+Type: integer
+
+#### `type`
+
+Terminal type, e.g. xterm-256color.
+
+Type: string
+
+#### `version`
+
+Terminal version as reported by XTVERSION OSC query.
+
+Type: string
+
+#### `theme`
+
+Color theme of the recorded terminal.
+
+Type: object, with the following attributes (all required):
+
+- `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, pretty formatted for readability:
+
+```json
+{
+  "fg": "#d0d0d0",
+  "bg": "#212121",
+  "palette": "#151515:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#d0d0d0:#505050:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#f5f5f5"
+}
+```
+
+!!! note
+
+    asciinema CLI captures the original terminal theme automatically (since
+    v3.0).
+
+    If you're implementing an asciicast-compatible recorder, then you can
+    retrieve the colors from the terminal via OSC sequences (this is how
+    asciinema recorder does it). However, you can also use another technique,
+    or even hard-code the colors of your favorite theme.
+
+### `timestamp`
+
+Unix timestamp of the beginning of the recording session.
+
+Type: integer
+
+### `idle_time_limit`
+
+Idle time limit, as given via `-i` option to `asciinema rec`.
+
+Type: float
+
+This should be used by an asciicast player to reduce all terminal inactivity
+(delays between frames) to a maximum of `idle_time_limit` value.
+
+### `command`
+
+Command that was recorded, as given via `-c` option to `asciinema rec`.
+
+Type: string
+
+### `title`
+
+Title of the recording, as given via `-t` option to `asciinema rec`.
+
+Type: string
+
+### `env`
+
+A map of captured environment variables.
+
+Type: object (String -> String).
+
+Example env:
+
+```json
+{"SHELL": "/bin/bash", "TERM": "xterm-256color"}
+```
+
+> Official asciinema recorder captures only `SHELL` variable by default. All
+> implementations of asciicast-compatible terminal recorder should not capture
+> any additional environment variables unless explicitly requested by the user.
+
+## Event stream
+
+Each element of the event stream is a 3-tuple encoded as JSON array:
+
+    [interval, code, data]
+
+Where:
+
+* `interval` (float) - time interval from the previous event (in seconds),
+* `code` (string) - event type code, 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 previous event.
+
+### Supported event codes
+
+This section describes the event codes supported in asciicast v3 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 (a player or a 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 with 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`.
+
+Example:
+
+```json
+[5.0, "o", "hello"]
+```
+
+#### i - input, data read from a terminal
+
+Event with 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`.
+
+Example:
+
+```json
+[5.0, "i", "h"]
+```
+
+!!! note
+
+    asciinema CLI 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 with code `"m"` represents a marker.
+
+[Markers](../cli/markers.md) can act as breakpoints or be used for playback navigation and
+automation.
+
+`data`, which specifies a label, is optional (can be empty string). Labels may
+be used to e.g. create a list of named "chapters".
+
+Example:
+
+```json
+[5.0,  "m", ""] // unlabeled marker
+[3.0, "m", "Configuration"] // labeled marker
+```
+
+#### r - resize
+
+Event with 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}"`.
+
+```json
+[5.0, "r", "100x50"]
+```
+
+## File extension
+
+Suggested file extension is `.cast`.
+
+## Media type (MIME)
+
+Suggested media type is `application/x-asciicast`.
+
+## Note on compatibility
+
+asciicast v3 file format is not backward compatible with asciicast v1/v2 due to
+the header schema changes and use of relative time (intervals) in the event
+stream (even though v1 uses relative time too).
+
+However, the changes between v2 and v3 are relatively small when compared with
+the changes between v1 and v2. Both v2 and v3 use the same newline-delimited
+JSON format, with the first line being the header, and the following lines
+being the event stream. Also, aside from time/intervals, both v2 and v3 use the
+same notation and event codes for the event stream.
+
+Support for asciicast v3 has been added in:
+
+* asciinema cli [v3.0](https://github.com/asciinema/asciinema/releases/tag/v3.0.0-rc.4)
+* asciinema player [v3.10.0](https://github.com/asciinema/asciinema-player/releases/tag/v3.10.0-rc.1)
+* asciinema server [v202505xx](https://github.com/asciinema/asciinema-server/releases/tag/v202504xx)

mkdocs.yml

@@ -92,6 +92,7 @@ nav:
       - manual/agg/installation.md
       - manual/agg/usage.md
     - FILE FORMAT:
+      - manual/asciicast/v3.md
       - manual/asciicast/v2.md
       - manual/asciicast/v1.md
   - FAQ: faq.md