Reference for asciinema v3 NDJSON format. TRIGGERS - cast format, asciicast spec, event codes, cast header, cast structure, parse cast file. Use when understanding or parsing .cast files.
This skill is limited to using the following tools:
Reference documentation for the asciinema v3 .cast file format (asciicast v2 specification).
Platform: All platforms (documentation only)
Asciinema v3 uses NDJSON (Newline Delimited JSON) format:
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 |
{
"version": 2,
"width": 120,
"height": 40,
"timestamp": 1703462400,
"duration": 3600.5,
"title": "Claude Code Session",
"env": { "SHELL": "/bin/zsh", "TERM": "xterm-256color" }
}
Each event after the header is a 3-element array:
[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 | "WIDTHxHEIGHT" |
x | Exit | Extension for custom data | Varies |
[0.5, "o", "$ ls -la\r\n"]
[1.2, "o", "total 48\r\n"]
[1.3, "o", "drwxr-xr-x 12 user staff 384 Dec 24 10:00 .\r\n"]
[5.0, "m", "file-listing-complete"]
[10.5, "r", "80x24"]
/usr/bin/env bash << 'CALC_TIME_EOF'
HEADER_TIMESTAMP=$(head -1 recording.cast | jq -r '.timestamp')
EVENT_OFFSET=1234.5 # From event array
ABSOLUTE=$(echo "$HEADER_TIMESTAMP + $EVENT_OFFSET" | bc)
date -r "$ABSOLUTE" # macOS
# date -d "@$ABSOLUTE" # Linux
CALC_TIME_EOF
/usr/bin/env bash << 'HEADER_EOF'
head -1 recording.cast | jq '.'
HEADER_EOF
/usr/bin/env bash << 'DURATION_EOF'
head -1 recording.cast | jq -r '.duration // "unknown"'
DURATION_EOF
/usr/bin/env bash << 'COUNT_EOF'
tail -n +2 recording.cast | jq -r '.[1]' | sort | uniq -c
COUNT_EOF
/usr/bin/env bash << 'OUTPUT_EOF'
tail -n +2 recording.cast | jq -r 'select(.[1] == "o") | .[2]'
OUTPUT_EOF
/usr/bin/env bash << 'MARKERS_EOF'
tail -n +2 recording.cast | jq -r 'select(.[1] == "m") | "\(.[0])s: \(.[2])"'
MARKERS_EOF
/usr/bin/env bash << 'TIME_EOF'
TARGET_TIME=60 # seconds
tail -n +2 recording.cast | jq -r "select(.[0] >= $TARGET_TIME and .[0] < $((TARGET_TIME + 1))) | .[2]"
TIME_EOF
For recordings >100MB:
| File Size | Line Count | Approach |
|---|---|---|
| <100MB | <1M | jq streaming works fine |
| 100-500MB | 1-5M | Use --stream flag, consider ripgrep |
| 500MB+ | 5M+ | Convert to .txt first with asciinema |
/usr/bin/env bash << 'STREAM_EOF'
# Stream process large files
jq --stream -n 'fromstream(1|truncate_stream(inputs))' recording.cast | head -1000
STREAM_EOF
For very large files, convert to plain text first:
asciinema convert -f txt recording.cast recording.txt
This strips ANSI codes and produces clean text (typically 950:1 compression).
1. [Reference] Identify .cast file to analyze
2. [Header] Extract and display header metadata
3. [Events] Count events by type (o, i, m, r)
4. [Analysis] Extract relevant event data based on user need
5. [Navigation] Find markers or specific timestamps if needed
After modifying this skill: