Skip to content

asciicast v2

asciicast v2 is a file format for terminal sessions recorded by asciinema CLI 2.x.

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.

asciicast v2 file looks like this:

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

asciicast header is JSON-encoded object containing recording metadata.

Complete header example, pretty formatted for readability:

{
  "version": 2,
  "width": 80,
  "height": 24,
  "timestamp": 1504467315,
  "duration": 123.45,
  "command": "/bin/bash",
  "title": "Demo",
  "idle_time_limit": 2,
  "env": {
    "SHELL": "/bin/bash",
    "TERM": "xterm-256color"
  },
  "theme": {
    "fg": "#d0d0d0",
    "bg": "#212121",
    "palette": "#151515:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#d0d0d0:#505050:#ac4142:#7e8e50:#e5b567:#6c99bb:#9f4e85:#7dd6cf:#f5f5f5"
  }
}

Minimal header example:

{"version": 2, "width": 80, "height": 24}

Required header attributes:

version

Format version number. Must be set to 2. Integer.

width

Terminal width, i.e. number of columns. Integer.

height

Terminal height, i.e. 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 a maximum of idle_time_limit value.

command

Command that was recorded, as given via -c option to asciinema rec. String.

title

Title of the recording, as given via -t option to asciinema rec. String.

env

A map of captured environment variables. Object (String -> String).

Example 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 requested 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, 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, such as using xrdb (on Linux).

Event stream

Each element of the event stream is a 3-tuple encoded as JSON array:

[time, code, data]

Where:

  • time (float) - time since the beginning of the recording session (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 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 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
[10.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 v2 file format enables incremental, real-time writing to disk, which was not possible with v1 format. The main benefits are:

  • minimal memory usage when recording and replaying arbitrarily long sessions - disk space is the only limit,
  • when the recording session is interrupted (e.g. computer crash, accidental close of terminal window) you don't lose the whole recording,
  • it's real-time streaming friendly.

However, due to file structure change (standard JSON => newline-delimited JSON) version 2 is not backward compatible with version 1.

Support for asciicast v2 has been added in: