asciinema-cast-format

asciinema-cast-format

asciinema v3 の .cast ファイル形式（asciicast v2 仕様）のリファレンスドキュメントです。

プラットフォーム：すべてのプラットフォーム（ドキュメントのみ）

自己進化型スキル：このスキルは使用を通じて改善されます。説明に誤りがある場合、パラメーターが変わった場合、または回避策が必要になった場合は、先送りせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使用する場面

以下の場合にこのスキルを使用します。

• .cast ファイルの構造を解析または調査する
• NDJSON のヘッダーおよびイベント形式を理解する
• .cast ファイルを読み書きするツールを構築する
• 録画の問題や形式エラーをデバッグする
• asciicast v2 仕様を学ぶ

---

形式の概要

Asciinema v3 では、NDJSON（改行区切り JSON）形式を使用します。

• 1 行目：録画メタデータを含むヘッダーオブジェクト
• 2 行目以降：タイムスタンプ、タイプ、データを含むイベント配列

---

ヘッダー仕様

1 行目は、次のフィールドを含む 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. 解析例で bash との互換性を確保するためのヒアドキュメントラッパーを使用している
3. 大容量ファイルに関する指針が実際のパフォーマンス特性を反映している
4. すべての jq コマンドをサンプルの .cast ファイルでテストしている

リファレンスドキュメント

• asciinema asciicast v2 フォーマット
• asciinema CLI の使用方法
• jq マニュアル

---

トラブルシューティング

問題	原因	解決策
jq の解析エラー	.cast ファイル内の NDJSON が無効	各行が有効な JSON であることを jq -c . で確認します
ヘッダーに duration がない	録画中	録画が終了すると duration が追加されます
不明なイベントタイプ	カスタム拡張イベント	x タイプのイベント（拡張データ）がないか確認します
タイムスタンプの順序が不正	ファイルの破損	イベントは単調増加している必要があります
大きなファイルで jq がタイムアウト	ファイルが大きすぎてメモリに収まらない	--stream フラグを使用するか、先に .txt に変換します
マーカーが見つからない	録画にマーカーがない	マーカーは任意です。すべての録画に含まれるわけではありません
バージョン番号が不正	古い cast フォーマット	このスキルが対象とするのは v2 フォーマットです（asciinema v3+）
tail の出力が空	ファイルにヘッダーしかない	録画が空、または1行のみの可能性があります

実行後の振り返り

このスキルの実行後、終了する前に確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラー表を修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーター表を更新して合わせてください。
3. 回避策が必要でしたか？ — 別のフラグや追加手順など、工夫が必要だった場合は、次回の実行時に同じ回避策が不要になるよう、この SKILL.md を更新してください。

実際に再現できる問題がある場合に限って更新してください。推測だけでは更新しないでください。