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 | "WIDTHxHEIGHT" |
x | Exit | Extension for custom data | Varies |
Event Examples
json
[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"]
Timestamp Behavior
- •Timestamps are relative to recording start (first event is 0.0)
- •Measured in seconds with millisecond precision
- •Used for playback timing and navigation
Calculating Absolute Time
bash
/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
Parsing Examples
Extract Header with jq
bash
/usr/bin/env bash << 'HEADER_EOF' head -1 recording.cast | jq '.' HEADER_EOF
Get Recording Duration
bash
/usr/bin/env bash << 'DURATION_EOF' head -1 recording.cast | jq -r '.duration // "unknown"' DURATION_EOF
Count Events by Type
bash
/usr/bin/env bash << 'COUNT_EOF' tail -n +2 recording.cast | jq -r '.[1]' | sort | uniq -c COUNT_EOF
Extract All Output Events
bash
/usr/bin/env bash << 'OUTPUT_EOF' tail -n +2 recording.cast | jq -r 'select(.[1] == "o") | .[2]' OUTPUT_EOF
Find Markers
bash
/usr/bin/env bash << 'MARKERS_EOF' tail -n +2 recording.cast | jq -r 'select(.[1] == "m") | "\(.[0])s: \(.[2])"' MARKERS_EOF
Get Event at Specific Time
bash
/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
Large File Considerations
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 |
Memory-Efficient Streaming
bash
/usr/bin/env bash << 'STREAM_EOF' # Stream process large files jq --stream -n 'fromstream(1|truncate_stream(inputs))' recording.cast | head -1000 STREAM_EOF
Use asciinema convert
For very large files, convert to plain text first:
bash
asciinema convert -f txt recording.cast recording.txt
This strips ANSI codes and produces clean text (typically 950:1 compression).
TodoWrite Task Template
code
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
Post-Change Checklist
After modifying this skill:
- • Event code table matches asciinema v2 specification
- • Parsing examples use heredoc wrapper for bash compatibility
- • Large file guidance reflects actual performance characteristics
- • All jq commands tested with sample .cast files