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

Link asciicast format docs to latest versions on docs.asciinema.org

Browse Source
This commit is contained in:
Marcin Kulik
2024-01-10 12:16:50 +01:00
parent 121a105b1a
commit 0d35dba6b6
2 changed files with 2 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
doc/asciicast-v1.md
View File

@@ -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/).

204
doc/asciicast-v2.md
View File

@@ -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/).