Mirrors/asciinema
1
0
Fork 0
mirror of https://github.com/asciinema/asciinema.git synced 2025-12-16 11:48:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update v2 format doc

Browse Source
This commit is contained in:
Marcin Kulik
2017-11-19 17:58:36 +01:00
parent d9a15e4c10
commit cebc33ca1f
1 changed files with 38 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
doc/asciicast-v2.md
View File

@@ -1,40 +1,31 @@
# asciicast file format (version 2) # asciicast file format (version 2)
asciicast v2 file asciicast v2 file is [newline-delimited JSON](http://jsonlines.org/) file where:
is [NDJSON (newline delimited JSON)](https://github.com/ndjson/ndjson-spec) file
where:
* __first line__ contains header (initial terminal size, timestamp and other * __first line__ contains header (initial terminal size, timestamp and other
meta-data), encoded as JSON object, meta-data), encoded as JSON object,
* __all subsequent lines__ form an event stream, _each line_ representing a * __all following lines__ form an event stream, _each line_ representing a
separate event stream item, encoded as JSON array. separate event, encoded as 3-element JSON array.
By making the event stream a first class concept in the v2 format we get the Example file:
following benefits:
* it enables live, incremental writing to a file during recording (with v1 ```json
format the final recording JSON can only be written as a whole after finishing {"version": 2, "width": 80, "height": 24, "timestamp": 1504467315, "title": "Demo", "env": {"TERM": "xterm-256color", "SHELL": "/bin/zsh"}}
the recording session), [0.248848, "o", "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n"]
* it allows the players to start the playback as soon as they read the meta-data [1.001376, "o", "That was ok\rThis is better."]
line (contrary to v1 format which requires reading the whole file), [2.143733, "o", " "]
* whether you're recording to a file or streaming via UNIX pipe or WebSocket the [6.541828, "o", "Bye!"]
data representation is the same. ```
## Header ## Header
asciicast header is JSON-encoded object containing recording meta-data. asciicast header is JSON-encoded object containing recording meta-data.
Example header:
```json
{"version": 2, "width": 80, "height": 24, "timestamp": 1504467315, "title": "Vim tutorial #1", "env": {"TERM": "xterm-256color", "SHELL": "/bin/zsh"}}
```
### Required header attributes: ### Required header attributes:
#### `version` #### `version`
Must be set to `2`. Must be set to `2`. Integer.
#### `width` #### `width`
@@ -82,9 +73,9 @@ Example env:
} }
``` ```
Official asciinema recorder captures only `SHELL` and `TERM` by default. All > Official asciinema recorder captures only `SHELL` and `TERM` by default. All
implementations of asciicast-compatible terminal recorder should not capture any > implementations of asciicast-compatible terminal recorder should not capture
additional environment variables unless explicitly permitted by the user. > any additional environment variables unless explicitly permitted by the user.
#### `theme` #### `theme`
@@ -106,9 +97,9 @@ Example theme:
} }
``` ```
A specific technique of obtaining the colors from a terminal (using xrdb, > 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 > requesting them from a terminal via special escape sequences etc) doesn't
as long as the recorder can save it in the above format. > matter as long as the recorder can save it in the above format.
## Event stream ## Event stream
@@ -120,7 +111,7 @@ Where:
* `time` (float) - indicates when this event happened, represented as the number * `time` (float) - indicates when this event happened, represented as the number
of seconds since the beginning of the recording session, of seconds since the beginning of the recording session,
* `event-type` (string) - one of: `"o"`, `"i"`, `"size"`, * `event-type` (string) - one of: `"o"`, `"i"`,
* `event-data` (any) - event specific data, described separately for each event * `event-data` (any) - event specific data, described separately for each event
type. type.
@@ -157,7 +148,7 @@ non-printable Unicode codepoints encoded as `\uXXXX`.
#### "i" - data read from stdin #### "i" - data read from stdin
Event of type `"i"` represents character(s) typed in (or pasted) by the user, or Event of type `"i"` represents character(s) typed in by the user, or
more specifically, data sent from terminal emulator to stdin of the recorded more specifically, data sent from terminal emulator to stdin of the recorded
shell. shell.
@@ -165,22 +156,26 @@ shell.
event, it's UTF-8 encoded JSON string, with all non-printable Unicode codepoints event, it's UTF-8 encoded JSON string, with all non-printable Unicode codepoints
encoded as `\uXXXX`. encoded as `\uXXXX`.
_Note: Official asciinema recorder doesn't capture stdin by default. All > Official asciinema recorder doesn't capture stdin by default. All
implementations of asciicast-compatible terminal recorder should not capture it > implementations of asciicast-compatible terminal recorder should not capture
either unless explicitly permitted by the user._ > it either unless explicitly permitted by the user.
#### "size" - terminal resize (planned?) ## Notes on compatibility
TODO Version 2 of asciicast file format solves several problems which couldn't be
easily fixed in the old format:
not supported by current versions of the recorder and players * 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.
## Complete asciicast v2 example 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:
A very short asciicast v2 file looks like this: * [asciinema terminal recorder](https://github.com/asciinema/asciinema) - 2.0
(to be released, currently on development branch)
{"version": 2, "width": 80, "height": 24, "timestamp": 1504467315, "title": "Demo", "env": {"TERM": "xterm-256color", "SHELL": "/bin/zsh"}} * [asciinema web player](https://github.com/asciinema/asciinema-player) - 2.6.0
[0.248848, "o", "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n"] * [asciinema server](https://github.com/asciinema/asciinema-server) - v20171105
[1.001376, "o", "This is overwritten\rThis is better."] tag in git repository
[2.143733, "o", " "]
[6.541828, "o", "Bye!"]