asciinema-player

asciinema-player

ターミナルセッションの録画（.cast ファイル）を、再生コントロールをすべて備えた専用の iTerm2 ウィンドウで再生します。クリーンなウィンドウを開くため、デフォルトの配置を回避して、集中して視聴できます。

プラットフォーム：macOS のみ（iTerm2 が必要です）

自己進化型スキル：このスキルは使用するたびに改善されます。手順に誤りがある場合、パラメーターが変わっている場合、または回避策が必要だった場合は、先延ばしにせず、ただちにこのファイルを修正してください。実際に再現できる問題がある場合にのみ更新してください。

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

以下の場合にこのスキルを使用してください。

• iTerm2 で .cast 録画を再生する場合
• ブラウザーの制限を受けずにセッション録画を確認する場合
• ブラウザープレーヤーがクラッシュする大容量の録画（>100MB）を扱う場合
• ターミナルセッションをデモまたは確認する場合

---

ブラウザーではなく iTerm2 を使う理由

項目	ブラウザープレーヤー	iTerm2 CLI
大容量ファイル（>100MB）	クラッシュ（メモリ制限）	ディスクからストリーミング
メモリ使用量	700MB のファイルで 2-4GB	最小限
起動時間	遅い（ダウンロード＋解析）	即時
ネイティブな操作感	Web ベース	本物のターミナル

判断：大容量の録画を確実に再生する方法は、iTerm2 CLI だけです。

---

必要条件

コンポーネント	必須	インストール方法
iTerm2	はい	brew install --cask iterm2
asciinema CLI	はい	brew install asciinema

注：このスキルは macOS 専用です。Linux ユーザーは、ターミナルで asciinema play を直接実行してください。

---

ワークフローのフェーズ（すべて必須）

重要：すべてのフェーズが必須です。フェーズを省略しないでください。各判断ポイントでは必ず AskUserQuestion を使用してください。

フェーズ 0：事前確認

目的：iTerm2 と asciinema がインストールされていることを確認します。

ステップ 0.1：依存関係を確認する

# Check iTerm2 is installed
ls -d /Applications/iTerm.app 2>/dev/null && echo "iTerm2: OK" || echo "iTerm2: MISSING"

# Check asciinema CLI
which asciinema && asciinema --version

ステップ 0.2：状態を報告し、インストールを確認する

依存関係が不足している場合は、必ず AskUserQuestion を使用してください。

Question: "Required dependencies are missing. Install them?"
Header: "Setup"
Options:
  - Label: "Install all (Recommended)"
    Description: "Will install: {list of missing: iTerm2, asciinema}"
  - Label: "Cancel"
    Description: "Abort - cannot proceed without dependencies"

ステップ 0.3：不足している依存関係をインストールする（確認済みの場合）

# Install iTerm2
brew install --cask iterm2

# Install asciinema CLI
brew install asciinema

---

フェーズ 1：ファイルの選択（必須）

目的：再生する録画を見つけて選択します。

ステップ 1.1：録画を検索する

# Search for .cast files in common locations
fd -e cast . --max-depth 5 2>/dev/null | head -20

# Also check common locations
ls -lh ~/scripts/tmp/*.cast 2>/dev/null
ls -lh ~/.local/share/asciinema/*.cast 2>/dev/null
ls -lh ./tmp/*.cast 2>/dev/null

ステップ 1.2：ファイル情報を取得する

# Get file size and line count for selected file
ls -lh {file_path}
wc -l {file_path}

ステップ 1.3：ファイル選択肢を提示する（AskUserQuestion の使用が必須）

ユーザーがパスを直接指定した場合は、確認します。

Question: "Play this recording?"
Header: "Confirm"
Options:
  - Label: "Yes, play {filename}"
    Description: "{size}, {line_count} events"
  - Label: "Choose different file"
    Description: "Browse for other recordings"

パスが指定されていない場合は、検索して選択肢を提示します。

Question: "Which recording would you like to play?"
Header: "Recording"
Options:
  - Label: "{filename} ({size})"
    Description: "{line_count} events"
  - ... (up to 4 most recent)

---

フェーズ 2：再生設定（必須）

目的：iTerm2 を起動する前に再生オプションを設定します。

ステップ 2.1：再生速度を確認する（AskUserQuestion の使用が必須）

Question: "Select playback speed:"
Header: "Speed"
Options:
  - Label: "2x (fast)"
    Description: "Good for review, see everything"
  - Label: "6x (very fast)"
    Description: "Quick scan of long sessions"
  - Label: "16x (ultra fast)"
    Description: "Rapid skim for 700MB+ files"
  - Label: "Custom"
    Description: "Enter your own speed multiplier"

「Custom」を選択した場合は、再生速度を確認します（数値入力には Other オプションを使用してください）。

ステップ 2.2：追加オプションを確認する（AskUserQuestion の使用が必須）

Question: "Select additional playback options:"
Header: "Options"
multiSelect: true
Options:
  - Label: "Limit idle time (2s)"
    Description: "Cap pauses to 2 seconds max (recommended)"
  - Label: "Loop playback"
    Description: "Restart automatically when finished"
  - Label: "Resize terminal"
    Description: "Match terminal size to recording dimensions"
  - Label: "Pause on markers"
    Description: "Auto-pause at marked points (for demos)"

---

フェーズ 3：iTerm2 で起動する

目的：クリーンな iTerm2 ウィンドウを開き、再生を開始します。

ステップ 3.1：コマンドを組み立てる

ユーザーの選択に基づいて、asciinema play コマンドを組み立てます。

# Example with all options
asciinema play -s 6 -i 2 -l -r /path/to/recording.cast

オプションフラグ：

• -s {speed} - 再生速度
• -i 2 - アイドル時間の上限（選択した場合）
• -l - ループ再生（選択した場合）
• -r - ターミナルのサイズ変更（選択した場合）
• -m - マーカー位置で一時停止（選択した場合）

ステップ 3.2：iTerm2 ウィンドウを起動する

AppleScript を使用して、デフォルトの配置を回避するクリーンなウィンドウを開きます。

osascript -e 'tell application "iTerm2"
    create window with default profile
    tell current window
        tell current session
            write text "asciinema play -s {speed} {options} {file_path}"
        end tell
    end tell
end tell'

ステップ 3.3：コントロールのリファレンスを表示する

## Playback Started

**Recording:** `{filename}`
**Speed:** {speed}x
**Options:** {options_summary}

### Keyboard Controls

| Key      | Action                            |
| -------- | --------------------------------- |
| `Space`  | Pause / Resume                    |
| `Ctrl+C` | Stop playback                     |
| `.`      | Step forward (when paused)        |
| `]`      | Skip to next marker (when paused) |

### Tips

- Press `Space` to pause anytime
- Use `.` to step through frame by frame
- `Ctrl+C` to exit when done

---

TodoWrite タスクテンプレート（必須）

開始前にこのテンプレートを TodoWrite に読み込んでください。

1. [Preflight] Check iTerm2 installed
2. [Preflight] Check asciinema CLI installed
3. [Preflight] AskUserQuestion: install missing deps (if needed)
4. [Preflight] Install dependencies (if confirmed)
5. [Selection] Get file info (size, events)
6. [Selection] AskUserQuestion: confirm file selection
7. [Settings] AskUserQuestion: playback speed
8. [Settings] AskUserQuestion: additional options (multi-select)
9. [Launch] Build asciinema play command
10. [Launch] Execute AppleScript to open iTerm2
11. [Launch] Display controls reference

---

CLI オプションリファレンス

オプション	フラグ	値	説明
速度	-s	0.5, 1, 2, 6, 16...	再生速度の倍率
アイドル時間の上限	-i	秒数（例：2）	アイドル／一時停止時間の上限
ループ	-l	（フラグ）	連続ループ
サイズ変更	-r	（フラグ）	ターミナルを録画サイズに合わせる
マーカー	-m	（フラグ）	マーカー位置で自動一時停止
静音	-q	（フラグ）	情報メッセージを抑制

---

AppleScript リファレンス

新しい iTerm2 ウィンドウを開く（デフォルトの配置を使用しない）

tell application "iTerm2"
    create window with default profile
    tell current window
        tell current session
            write text "your command here"
        end tell
    end tell
end tell

この方法が機能する理由：create window with default profile は新しいウィンドウを作成し、保存済みのウィンドウ配置を回避します。

Bash 用のワンライナー

osascript -e 'tell application "iTerm2"
    create window with default profile
    tell current window
        tell current session
            write text "asciinema play -s 6 -i 2 /path/to/file.cast"
        end tell
    end tell
end tell'

---

トラブルシューティング

「Device not configured」エラー

原因：TTY ではないコンテキスト（例：Claude Code の Bash ツール）から asciinema play を実行しています。

対処方法：AppleScript を使って実際の iTerm2 ウィンドウを開きます（このスキルでは自動的に実行されます）。

録画の再生が速すぎる／遅すぎる

対処方法：AskUserQuestion の速度設定を使って、適切な速度を選択します。

• じっくり確認する場合は 2x
• 素早く確認する場合は 6x
• 非常に長い録画を超高速でざっと確認する場合は 16x

iTerm2 が開かない

原因：iTerm2 がインストールされていないか、AppleScript のアクセス許可が付与されていません。

対処方法：

1. iTerm2 をインストールします：brew install --cask iterm2
2. アクセス許可を付与します：システム設定 → プライバシーとセキュリティ → オートメーション → Terminal/Claude による iTerm2 の制御を許可

大容量ファイル（>500MB）に関する考慮事項

CLI プレーヤーはディスクからストリーミングするため、ファイルサイズが原因でメモリの問題が発生することはありません。ただし、次の点にご注意ください。

• 非常に長い録画では、速度を上げると便利な場合があります（6x、16x）
• -i 2 を使うと、アイドル時間をスキップできます
• 非常に長い録画は分割することを検討してください

---

変更後のチェックリスト

このスキルを変更した後：

1. 事前チェックで iTerm2 と asciinema が検証される
2. AskUserQuestion の各フェーズで、該当する場合は適切な multiSelect が使われる
3. AppleScript で Bash との互換性を確保するために heredoc ラッパーが使われる
4. 速度オプションが CLI の機能（-s フラグ）と一致する
5. TodoWrite のテンプレートが実際のワークフローの各フェーズと一致する

---

参考ドキュメント

• asciinema play の使い方
• asciinema CLI オプション
• iTerm2 AppleScript ドキュメント
• asciinema マーカー

実行後の振り返り

このスキルの実行後、タスクを終了する前に振り返ります。

0. 現在の場所を確認します。 — 編集する前に、この SKILL.md の正式なパスを確認します。
1. 何が失敗しましたか？ — 原因となった指示を修正します。
2. 期待以上にうまくいったことは何ですか？ — 推奨プラクティスに追加します。
3. 何が実態とずれていますか？ — 現状と合わなくなったスクリプト、参考資料、依存関係を修正します。
4. 記録します。 — 発生のきっかけ、修正内容、根拠を含む進化ログの項目を追加します。

先送りしないでください。次回の呼び出しでは、ここに残した状態が引き継がれます。