terrylica asciinema-cast-format
Reference documentation for the asciinema v3 .cast file format (asciicast v2 specification).
Platform: All platforms (documentation only)
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
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
{
"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:
[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
[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
/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
/usr/bin/env bash << 'HEADER_EOF'
head -1 recording.cast | jq '.'
HEADER_EOF
Get Recording Duration
/usr/bin/env bash << 'DURATION_EOF'
head -1 recording.cast | jq -r '.duration // "unknown"'
DURATION_EOF
Count Events by Type
/usr/bin/env bash << 'COUNT_EOF'
tail -n +2 recording.cast | jq -r '.[1]' | sort | uniq -c
COUNT_EOF
Extract All Output Events
/usr/bin/env bash << 'OUTPUT_EOF'
tail -n +2 recording.cast | jq -r 'select(.[1] == "o") | .[2]'
OUTPUT_EOF
Find Markers
/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
/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
/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:
asciinema convert -f txt recording.cast recording.txt
This strips ANSI codes and produces clean text (typically 950:1 compression).
TodoWrite Task Template
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
Reference Documentation
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| jq parse error | Invalid NDJSON in .cast file | Check each line is valid JSON with jq -c . |
| Header missing duration | Recording in progress | Duration added when recording ends |
| Unknown event type | Custom extension event | Check for x type events (extension data) |
| Timestamp out of order | Corrupted file | Events should be monotonically increasing |
| Large file jq timeout | File too big for in-memory | Use --stream flag or convert to .txt first |
| Markers not found | No markers in recording | Markers are optional; not all recordings have them |
| Wrong version number | Older cast format | This skill covers v2 format (asciinema v3+) |
| Empty output from tail | File has only header | Recording may be empty or single-line |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.