Skip to content

Commit 1122348

Browse files
CC11001100CC11001100
committed
feat: add ascii cast format document
1 parent ef63046 commit 1122348

File tree

2 files changed

+247
-0
lines changed

2 files changed

+247
-0
lines changed

‎docs/asciicast-v1.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# asciicast file format (version 1)
2+
3+
asciicast file is JSON file containing meta-data like duration or title of the
4+
recording, and the actual content printed to terminal's stdout during
5+
recording.
6+
7+
Version 1 of the format was used by the asciinema recorder versions 1.0 up to 1.4.
8+
9+
## Attributes
10+
11+
Every asciicast includes the following set of attributes:
12+
13+
* `version` - set to 1,
14+
* `width` - terminal width (number of columns),
15+
* `height` - terminal height (number of rows),
16+
* `duration` - total duration of asciicast as floating point number,
17+
* `command` - command that was recorded, as given via `-c` option to `rec`,
18+
* `title` - title of the asciicast, as given via `-t` option to `rec`,
19+
* `env` - map of environment variables useful for debugging playback problems,
20+
* `stdout` - array of "frames", see below.
21+
22+
### Frame
23+
24+
Frame represents an event of printing new data to terminal's stdout. It is a 2
25+
element array containing **delay** and **data**.
26+
27+
**Delay** is the number of seconds that elapsed since the previous frame (or
28+
since the beginning of the recording in case of the 1st frame) represented as
29+
a floating point number, with microsecond precision.
30+
31+
**Data** is a string containing the data that was printed to a terminal in a
32+
given frame. It has to be valid, UTF-8 encoded JSON string as described in
33+
[JSON RFC section 2.5](http://www.ietf.org/rfc/rfc4627.txt), with all
34+
non-printable Unicode codepoints encoded as `\uXXXX`.
35+
36+
For example, frame `[5.4321, "foo\rbar\u0007..."]` means there was 5 seconds of
37+
inactivity between previous printing and printing of `foo\rbar\u0007...`.
38+
39+
## Example asciicast
40+
41+
A very short asciicast may look like this:
42+
43+
{
44+
"version": 1,
45+
"width": 80,
46+
"height": 24,
47+
"duration": 1.515658,
48+
"command": "/bin/zsh",
49+
"title": "",
50+
"env": {
51+
"TERM": "xterm-256color",
52+
"SHELL": "/bin/zsh"
53+
},
54+
"stdout": [
55+
[
56+
0.248848,
57+
"\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n"
58+
],
59+
[
60+
1.001376,
61+
"I am \rThis is on the next line."
62+
]
63+
]
64+
}

‎docs/asciicast-v2.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# asciicast file format (version 2)
2+
3+
asciicast v2 file is [newline-delimited JSON](http://jsonlines.org/) file where:
4+
5+
* __first line__ contains header (initial terminal size, timestamp and other
6+
meta-data), encoded as JSON object,
7+
* __all following lines__ form an event stream, _each line_ representing a
8+
separate event, encoded as 3-element JSON array.
9+
10+
Example file:
11+
12+
```json
13+
{"version": 2, "width": 80, "height": 24, "timestamp": 1504467315, "title": "Demo", "env": {"TERM": "xterm-256color", "SHELL": "/bin/zsh"}}
14+
[0.248848, "o", "\u001b[1;31mHello \u001b[32mWorld!\u001b[0m\n"]
15+
[1.001376, "o", "That was ok\rThis is better."]
16+
[2.143733, "o", " "]
17+
[6.541828, "o", "Bye!"]
18+
```
19+
20+
Suggested file extension is `.cast`, suggested media type is
21+
`application/x-asciicast`.
22+
23+
## Header
24+
25+
asciicast header is JSON-encoded object containing recording meta-data.
26+
27+
### Required header attributes:
28+
29+
#### `version`
30+
31+
Must be set to `2`. Integer.
32+
33+
#### `width`
34+
35+
Initial terminal width (number of columns). Integer.
36+
37+
#### `height`
38+
39+
Initial terminal height (number of rows). Integer.
40+
41+
### Optional header attributes:
42+
43+
#### `timestamp`
44+
45+
Unix timestamp of the beginning of the recording session. Integer.
46+
47+
#### `duration`
48+
49+
Duration of the whole recording in seconds (when it's known upfront). Float.
50+
51+
#### `idle_time_limit`
52+
53+
Idle time limit, as given via `-i` option to `asciinema rec`. Float.
54+
55+
This should be used by an asciicast player to reduce all terminal inactivity
56+
(delays between frames) to maximum of `idle_time_limit` value.
57+
58+
#### `command`
59+
60+
Command that was recorded, as given via `-c` option to `asciinema rec`. String.
61+
62+
#### `title`
63+
64+
Title of the asciicast, as given via `-t` option to `asciinema rec`. String.
65+
66+
#### `env`
67+
68+
Map of captured environment variables. Object (String -> String).
69+
70+
Example env:
71+
72+
```json
73+
"env": {
74+
"SHELL": "/bin/bash",
75+
"TERM": "xterm-256color"
76+
}
77+
```
78+
79+
> Official asciinema recorder captures only `SHELL` and `TERM` by default. All
80+
> implementations of asciicast-compatible terminal recorder should not capture
81+
> any additional environment variables unless explicitly permitted by the user.
82+
83+
#### `theme`
84+
85+
Color theme of the recorded terminal. Object, with the following attributes:
86+
87+
- `fg` - normal text color,
88+
- `bg` - normal background color,
89+
- `palette` - list of 8 or 16 colors, separated by colon character.
90+
91+
All colors are in the CSS `#rrggbb` format.
92+
93+
Example theme:
94+
95+
```json
96+
"theme": {
97+
"fg": "#d0d0d0",
98+
"bg": "#212121",
99+
"palette": "#151515:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#d0d0d0:#505050:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#f5f5f5"
100+
}
101+
```
102+
103+
> A specific technique of obtaining the colors from a terminal (using xrdb,
104+
> requesting them from a terminal via special escape sequences etc) doesn't
105+
> matter as long as the recorder can save it in the above format.
106+
107+
## Event stream
108+
109+
Each element of the event stream is a 3-tuple encoded as JSON array:
110+
111+
[time, event-type, event-data]
112+
113+
Where:
114+
115+
* `time` (float) - indicates when this event happened, represented as the number
116+
of seconds since the beginning of the recording session,
117+
* `event-type` (string) - one of: `"o"`, `"i"`,
118+
* `event-data` (any) - event specific data, described separately for each event
119+
type.
120+
121+
For example, let's look at the following line:
122+
123+
[1.001376, "o", "Hello world"]
124+
125+
It represents the event which:
126+
127+
* happened 1.001376 sec after the start of the recording session,
128+
* is of type `"o"` (print to stdout, see below),
129+
* has data `"Hello world"`.
130+
131+
### Supported event types
132+
133+
This section describes the event types supported in asciicast v2 format.
134+
135+
The list is open to extension, and new event types may be added in both the
136+
current and future versions of the format. For example, we may add new event
137+
type for text overlay (subtitles display).
138+
139+
A tool which interprets the event stream (web/cli player, post-processor) should
140+
ignore (or pass through) event types it doesn't understand or doesn't care
141+
about.
142+
143+
#### "o" - data written to stdout
144+
145+
Event of type `"o"` represents printing new data to terminal's stdout.
146+
147+
`event-data` is a string containing the data that was printed to a terminal. It
148+
has to be valid, UTF-8 encoded JSON string as described
149+
in [JSON RFC section 2.5](http://www.ietf.org/rfc/rfc4627.txt), with all
150+
non-printable Unicode codepoints encoded as `\uXXXX`.
151+
152+
#### "i" - data read from stdin
153+
154+
Event of type `"i"` represents character(s) typed in by the user, or
155+
more specifically, data sent from terminal emulator to stdin of the recorded
156+
shell.
157+
158+
`event-data` is a string containing the captured character(s). Like with `"o"`
159+
event, it's UTF-8 encoded JSON string, with all non-printable Unicode codepoints
160+
encoded as `\uXXXX`.
161+
162+
> Official asciinema recorder doesn't capture stdin by default. All
163+
> implementations of asciicast-compatible terminal recorder should not capture
164+
> it either unless explicitly permitted by the user.
165+
166+
## Notes on compatibility
167+
168+
Version 2 of asciicast file format solves several problems which couldn't be
169+
easily fixed in the old format:
170+
171+
* minimal memory usage when recording and replaying arbitrarily long sessions -
172+
disk space is the only limit,
173+
* when the recording session is interrupted (computer crash, accidental close of
174+
terminal window) you don't lose the whole recording,
175+
* it's real-time streaming friendly.
176+
177+
Due to file structure change (standard JSON => newline-delimited JSON) version 2
178+
is not backwards compatible with version 1. Support for v2 has been added in:
179+
180+
* [asciinema terminal recorder](https://github.com/asciinema/asciinema) - 2.0.0
181+
* [asciinema web player](https://github.com/asciinema/asciinema-player) - 2.6.0
182+
* [asciinema server](https://github.com/asciinema/asciinema-server) - v20171105
183+
tag in git repository

0 commit comments

Comments
 (0)