asciinema-cast-format

# asciinema-cast-format

Reference documentation for the asciinema v3 .cast file format (asciicast v2 specification).

> **Platform**: All platforms (documentation only)

---

## Format Overview

Asciinema v3 uses NDJSON (Newline Delimited JSON) format:

- Line 1: Header object with recording metadata
- Lines 2+: Event arrays with timestamp, type, and data

---

## Header Specification

The first line is a JSON object with these fields:

| Field       | Type   | Required | Description                                 |
| ----------- | ------ | -------- | ------------------------------------------- |
| `version`   | int    | Yes      | Format version (always 2 for v3 recordings) |
| `width`     | int    | Yes      | Terminal width in columns                   |
| `height`    | int    | Yes      | Terminal height in rows                     |
| `timestamp` | int    | No       | Unix timestamp of recording start           |
| `duration`  | float  | No       | Total duration in seconds                   |
| `title`     | string | No       | Recording title                             |
| `env`       | object | No       | Environment variables (SHELL, TERM)         |
| `theme`     | object | No       | Terminal color theme                        |

### Example Header

```json
{
  "version": 2,
  "width": 120,
  "height": 40,
  "timestamp": 1703462400,
  "duration": 3600.5,
  "title": "Claude Code Session",
  "env": { "SHELL": "/bin/zsh", "TERM": "xterm-256color" }
}
```

---

## Event Codes

Each event after the header is a 3-element array:

```json
[timestamp, event_type, data]
```

| Code | Name   | Description                 | Data Format          |
| ---- | ------ | --------------------------- | -------------------- |
| `o`  | Output | Terminal output (stdout)    | String               |
| `i`  | Input  | Terminal input (stdin)      | String               |
| `m`  | Marker | Named marker for navigation | String (marker name) |
| `r`  | Resize | Terminal resize event