Agent skill

asciinema-cast-format

Asciinema v3 .cast file format reference. TRIGGERS - cast format, asciicast spec, event codes, parse cast file.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/asciinema-cast-format

SKILL.md

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

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:

  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

Didn't find tool you were looking for?

Be as detailed as possible for better results