---

name: asciinema-cast-format description: 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. allowed-tools: Read, Bash

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:

Example Header

Copy{
  "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:

Copy[timestamp, event_type, data]

Event Examples

Copy[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

Copy/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

Copy/usr/bin/env bash << 'HEADER_EOF'
head -1 recording.cast | jq '.'
HEADER_EOF

Get Recording Duration

Copy/usr/bin/env bash << 'DURATION_EOF'
head -1 recording.cast | jq -r '.duration // "unknown"'
DURATION_EOF

Count Events by Type

Copy/usr/bin/env bash << 'COUNT_EOF'
tail -n +2 recording.cast | jq -r '.[1]' | sort | uniq -c
COUNT_EOF

Extract All Output Events

Copy/usr/bin/env bash << 'OUTPUT_EOF'
tail -n +2 recording.cast | jq -r 'select(.[1] == "o") | .[2]'
OUTPUT_EOF

Find Markers

Copy/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

Copy/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:

Memory-Efficient Streaming

Copy/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:

Copyasciinema convert -f txt recording.cast recording.txt

This strips ANSI codes and produces clean text (typically 950:1 compression).

---

TodoWrite Task Template

Copy1. [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:

1. Event code table matches asciinema v2 specification
2. Parsing examples use heredoc wrapper for bash compatibility
3. Large file guidance reflects actual performance characteristics
4. All jq commands tested with sample .cast files

---

Reference Documentation

• asciinema asciicast v2 Format
• asciinema CLI Usage
• jq Manual