Back to Details

asciinema-cast-format

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

asciinema-cast-format

Asciinema Cast格式参考文档

Reference documentation for the asciinema v3 .cast file format (asciicast v2 specification).
Platform: All platforms (documentation only)
Asciinema v3 .cast文件格式（即asciicast v2规范）的参考文档。
平台: 所有平台（仅为文档）

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
使用本技能的场景：
  • 解析或检查.cast文件结构
  • 理解NDJSON头部和事件格式
  • 构建读取或写入.cast文件的工具
  • 调试录制问题或格式错误
  • 学习asciicast v2规范

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
Asciinema v3采用NDJSON（换行分隔JSON）格式：
  • 第1行：包含录制元数据的头部对象
  • 第2行及以后：包含时间戳、类型和数据的事件数组

Header Specification

头部规范

The first line is a JSON object with these fields:
FieldTypeRequiredDescription
version
intYesFormat version (always 2 for v3 recordings)
width
intYesTerminal width in columns
height
intYesTerminal height in rows
timestamp
intNoUnix timestamp of recording start
duration
floatNoTotal duration in seconds
title
stringNoRecording title
env
objectNoEnvironment variables (SHELL, TERM)
theme
objectNoTerminal color theme
第一行是一个JSON对象，包含以下字段：
字段名类型是否必填描述
version
整数是格式版本（v3录制始终为2）
width
整数是终端宽度（列数）
height
整数是终端高度（行数）
timestamp
整数否录制开始的Unix时间戳
duration
浮点数否总时长（秒）
title
字符串否录制标题
env
对象否环境变量（如SHELL、TERM）
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" }
}
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]
CodeNameDescriptionData Format
o
OutputTerminal output (stdout)String
i
InputTerminal input (stdin)String
m
MarkerNamed marker for navigationString (marker name)
r
ResizeTerminal resize event
"WIDTHxHEIGHT"
x
ExitExtension for custom dataVaries
头部之后的每个事件都是一个包含3个元素的数组：
json
[timestamp, event_type, data]
代码名称描述数据格式
o
输出终端输出（stdout）字符串
i
输入终端输入（stdin）字符串
m
标记用于导航的命名标记字符串（标记名称）
r
调整大小终端窗口大小调整事件
"WIDTHxHEIGHT"
x
扩展自定义数据扩展格式各异

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"]
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
  • 时间戳是相对于录制开始时间的（第一个事件为0.0）
  • 以秒为单位，精确到毫秒
  • 用于播放计时和导航

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

date -d "@$ABSOLUTE" # Linux

CALC_TIME_EOF

---
CALC_TIME_EOF

---

Parsing Examples

解析示例

Extract Header with jq

使用jq提取头部

bash
/usr/bin/env bash << 'HEADER_EOF'
head -1 recording.cast | jq '.'
HEADER_EOF
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
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
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
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
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
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 SizeLine CountApproach
<100MB<1Mjq streaming works fine
100-500MB1-5MUse 
--stream
flag, consider ripgrep
500MB+5M+Convert to .txt first with asciinema
对于大于100MB的录制文件：
文件大小行数处理方法
<100MB<100万jq流式处理运行正常
100-500MB100万-500万使用
--stream
参数，考虑使用ripgrep
500MB+500万+先使用asciinema转换为.txt格式

Memory-Efficient Streaming

内存高效的流式处理

bash
/usr/bin/env bash << 'STREAM_EOF'
bash
/usr/bin/env bash << 'STREAM_EOF'

Stream process large files

Stream process large files

jq --stream -n 'fromstream(1|truncate_stream(inputs))' recording.cast | head -1000 STREAM_EOF
undefined
jq --stream -n 'fromstream(1|truncate_stream(inputs))' recording.cast | head -1000 STREAM_EOF
undefined

Use asciinema convert

使用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).
对于超大文件，先转换为纯文本：
bash
asciinema convert -f txt recording.cast recording.txt
这会去除ANSI代码并生成干净的文本（通常压缩比为950:1）。

TodoWrite Task Template

TodoWrite任务模板

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
1. [参考] 确定要分析的.cast文件
2. [头部] 提取并显示头部元数据
3. [事件] 按类型统计事件数量（o、i、m、r）
4. [分析] 根据用户需求提取相关事件数据
5. [导航] 如有需要，查找标记或特定时间点

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
修改本技能后：
  1. 事件代码表与asciinema v2规范一致
  2. 解析示例使用heredoc包装以保证bash兼容性
  3. 大文件处理指南反映实际性能特征
  4. 所有jq命令均已通过示例.cast文件测试

Reference Documentation

参考文档

Troubleshooting

故障排除

IssueCauseSolution
jq parse errorInvalid NDJSON in .cast fileCheck each line is valid JSON with 
jq -c .
Header missing durationRecording in progressDuration added when recording ends
Unknown event typeCustom extension eventCheck for 
x
type events (extension data)
Timestamp out of orderCorrupted fileEvents should be monotonically increasing
Large file jq timeoutFile too big for in-memoryUse 
--stream
flag or convert to .txt first
Markers not foundNo markers in recordingMarkers are optional; not all recordings have them
Wrong version numberOlder cast formatThis skill covers v2 format (asciinema v3+)
Empty output from tailFile has only headerRecording may be empty or single-line
问题原因解决方案
jq解析错误.cast文件中存在无效的NDJSON使用
jq -c .
检查每一行是否为有效的JSON
头部缺少duration字段录制尚未完成录制结束后会自动添加时长
未知事件类型自定义扩展事件检查是否为
x
类型事件（扩展数据）
时间戳顺序混乱文件损坏事件时间戳应单调递增
大文件jq超时文件过大无法放入内存使用
--stream
参数或先转换为.txt格式
未找到标记录制中未添加标记标记为可选功能；并非所有录制都包含标记
版本号错误较旧的cast格式本技能仅覆盖v2格式（对应Asciinema v3及以上版本）
tail命令输出为空文件仅有头部录制可能为空或只有单行