asciinema-cast-format

# asciinema-cast-format

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

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

## When to Use This Skill

Use this skill when:

- Parsing or inspecting .cast file structure
- Understanding NDJSON header and event formats
- Building tools that read or write .cast files
- Debugging recording issues or format errors
- Learning the asciicast v2 specification

---

## 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          |
| ---- | ------ | ---------------------------