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 3.0 and later.

It's based on newline-delimited JSON.

First line, encoded as JSON object, represents the header, which contains metadata, such as initial terminal size, timestamp, etc.

All following lines form the 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:

{"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!"]

asciicast header is JSON-encoded object containing recording metadata.

Complete header example, pretty formatted for readability:

{
  "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:

{"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:

{
  "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:

{"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, with any non-printable Unicode codepoints encoded as \uXXXX.

Example:

[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:

[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 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:

[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}".

[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
asciinema player v3.10.0
asciinema server v202505xx

asciicast v3¶

Header¶

version¶

term¶

cols¶

rows¶

type¶

version¶

theme¶

timestamp¶

idle_time_limit¶

command¶

title¶

env¶

Event stream¶

Supported event codes¶

o - output, data written to a terminal¶

i - input, data read from a terminal¶

m - marker¶

r - resize¶

File extension¶

Media type (MIME)¶

Note on compatibility¶

`version`¶

`term`¶

`cols`¶

`rows`¶

`type`¶

`version`¶

`theme`¶

`timestamp`¶

`idle_time_limit`¶

`command`¶

`title`¶

`env`¶