asciinema-cast-format

asciinema-cast-format

asciinema v3 .cast 文件格式参考文档（asciicast v2 规范）。

平台：所有平台（仅文档）

自我演进技能：此技能会随着使用不断改进。如果说明有误、参数发生偏差，或需要使用变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况使用此技能：

• 解析或检查 .cast 文件结构
• 了解 NDJSON 标头和事件格式
• 构建读取或写入 .cast 文件的工具
• 调试录制问题或格式错误
• 学习 asciicast v2 规范

---

格式概述

Asciinema v3 使用 NDJSON（换行符分隔的 JSON）格式：

• 第 1 行：包含录制元数据的标头对象
• 第 2 行及之后：包含时间戳、类型和数据的事件数组

---

标头规范

第一行是一个包含以下字段的 JSON 对象：

字段	类型	必需	说明
version	int	是	格式版本（v3 录制始终为 2）
width	int	是	终端宽度（列数）
height	int	是	终端高度（行数）
timestamp	int	否	录制开始时间的 Unix 时间戳
duration	float	否	总时长（秒）
title	string	否	录制标题
env	object	否	环境变量（SHELL、TERM）
theme	object	否	终端配色主题

标头示例

{
  "version": 2,
  "width": 120,
  "height": 40,
  "timestamp": 1703462400,
  "duration": 3600.5,
  "title": "Claude Code Session",
  "env": { "SHELL": "/bin/zsh", "TERM": "xterm-256color" }
}

---

事件代码

标头之后的每个事件都是一个包含 3 个元素的数组：

[timestamp, event_type, data]

代码	名称	说明	数据格式
o	输出	终端输出（stdout）	字符串
i	输入	终端输入（stdin）	字符串
m	标记	用于导航的命名标记	字符串（标记名称）
r	调整大小	终端调整大小事件	"WIDTHxHEIGHT"
x	退出	自定义数据扩展	不定

事件示例

[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"]

---

时间戳行为

• 时间戳相对于录制开始时间（第一个事件为 0.0）
• 以秒为单位，精度为毫秒
• 用于播放计时和导航

计算绝对时间

/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

---

解析示例

使用 jq 提取标头

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

获取录制时长

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

按类型统计事件数量

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

提取所有输出事件

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

查找标记

/usr/bin/env bash << 'MARKERS_EOF'
tail -n +2 recording.cast | jq -r 'select(.[1] == "m") | "\(.[0])s: \(.[2])"'
MARKERS_EOF

获取指定时间的事件

/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

---

大文件注意事项

对于大于 100MB 的录制文件：

文件大小	行数	处理方法
<100MB	<1M	使用 jq 流式处理即可
100-500MB	1-5M	使用 --stream 标志，考虑使用 ripgrep
500MB+	5M+	先使用 asciinema 转换为 .txt

高效内存流式处理

/usr/bin/env bash << 'STREAM_EOF'
# Stream process large files
jq --stream -n 'fromstream(1|truncate_stream(inputs))' recording.cast | head -1000
STREAM_EOF

使用 asciinema convert

对于非常大的文件，请先转换为纯文本：

asciinema convert -f txt recording.cast recording.txt

这会去除 ANSI 代码并生成干净的文本（通常可达到 950:1 的压缩比）。

---

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. 事件代码表符合 asciinema v2 规范
2. 解析示例使用 heredoc 包装，以兼容 bash
3. 大文件处理建议反映实际性能特征
4. 已使用示例 .cast 文件测试所有 jq 命令

参考文档

• asciinema asciicast v2 格式
• asciinema CLI 用法
• jq 手册

---

故障排查

问题	原因	解决方案
jq 解析错误	.cast 文件中的 NDJSON 无效	使用 jq -c . 检查每一行是否为有效 JSON
标头缺少 duration	录制仍在进行	录制结束时会添加 duration
未知事件类型	自定义扩展事件	检查 x 类型事件（扩展数据）
时间戳顺序错误	文件已损坏	事件的时间戳应单调递增
大文件导致 jq 超时	文件过大，无法载入内存	使用 --stream 标志，或先转换为 .txt
未找到标记	录制中没有标记	标记是可选的；并非所有录制都有标记
版本号错误	旧版 cast 格式	此技能涵盖 v2 格式（asciinema v3+）
tail 输出为空	文件仅包含标头	录制可能为空，或仅有一行

执行后反思

此技能执行完毕后，请在结束前检查：

1. 命令是否成功？ — 如果没有，请修正导致失败的说明或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新 Usage 示例和 Parameters 表，使其保持一致。
3. 是否需要变通方案？ — 如果你必须临时采用其他方式（不同的标志、额外步骤），请更新此 SKILL.md，以便下次调用无需再次采用相同的变通方案。

仅当问题确实存在且可复现时才更新，不要根据推测更新。