Back to Details

asciinema-player

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

asciinema-player

asciinema播放器

Play terminal session recordings (.cast files) in a dedicated iTerm2 window with full playback controls. Opens a clean window (bypasses default arrangements) for distraction-free viewing.
Platform: macOS only (requires iTerm2)
在独立的iTerm2窗口中播放终端会话录制文件（.cast格式），并提供完整的播放控制。会打开一个干净窗口（绕过默认布局），实现无干扰观看。
平台：仅支持macOS（需要iTerm2）

When to Use This Skill

使用场景

Use this skill when:
  • Playing back .cast recordings in iTerm2
  • Reviewing session recordings without browser limitations
  • Handling large recordings (>100MB) that crash browser players
  • Demoing or reviewing terminal sessions
在以下场景使用该技能：
  • 在iTerm2中播放.cast录制文件
  • 不受浏览器限制地查看会话录制内容
  • 处理超过100MB、会导致浏览器播放器崩溃的大型录制文件
  • 演示或审核终端会话

Why iTerm2 Instead of Browser?

为什么选择iTerm2而非浏览器？

AspectBrowser PlayeriTerm2 CLI
Large files (>100MB)Crashes (memory limit)Streams from disk
Memory usage2-4GB for 700MB fileMinimal
Startup timeSlow (download + parse)Instant
Native feelWeb-basedTrue terminal
Decision: iTerm2 CLI is the only reliable method for large recordings.
对比项浏览器播放器iTerm2命令行工具
大文件（>100MB）崩溃（内存限制）从磁盘流式加载
内存占用700MB文件占用2-4GB内存占用极少
启动时间缓慢（下载+解析）即时启动
原生体验基于网页纯正终端环境
结论：对于大型录制文件，iTerm2命令行工具是唯一可靠的播放方式。

Requirements

依赖要求

ComponentRequiredInstallation
iTerm2Yes
brew install --cask iterm2
asciinema CLIYes
brew install asciinema
Note: This skill is macOS-only. Linux users should run 
asciinema play
directly in their terminal.
组件是否必需安装方式
iTerm2是
brew install --cask iterm2
asciinema命令行工具是
brew install asciinema
注意：该技能仅支持macOS。Linux用户可直接在终端中运行
asciinema play
命令。

Workflow Phases (ALL MANDATORY)

工作流阶段（全部为必填步骤）

IMPORTANT: All phases are MANDATORY. Do NOT skip any phase. AskUserQuestion MUST be used at each decision point.
重要提示：所有阶段均为必填，请勿跳过任何步骤。在每个决策点必须使用AskUserQuestion交互。

Phase 0: Preflight Checks

阶段0：预检检查

Purpose: Verify iTerm2 and asciinema are installed.
目的：验证iTerm2和asciinema是否已安装。

Step 0.1: Check Dependencies

步骤0.1：检查依赖

bash
undefined
bash
undefined

Check iTerm2 is installed

检查iTerm2是否安装

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

Check asciinema CLI

检查asciinema命令行工具

which asciinema && asciinema --version
undefined
which asciinema && asciinema --version
undefined

Step 0.2: Report Status and Ask for Installation

步骤0.2：报告状态并询问是否安装

MANDATORY AskUserQuestion if any dependency is missing:
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"
若存在缺失依赖，必须触发AskUserQuestion：
问题: "缺少必需的依赖组件，是否安装？"
标题: "设置"
选项:
  - 标签: "全部安装（推荐）"
    描述: "将安装：{缺失组件列表：iTerm2, asciinema}"
  - 标签: "取消"
    描述: "终止操作 - 无依赖组件无法继续"

Step 0.3: Install Missing Dependencies (if confirmed)

步骤0.3：安装缺失的依赖（若用户确认）

bash
undefined
bash
undefined

Install iTerm2

安装iTerm2

brew install --cask iterm2
brew install --cask iterm2

Install asciinema CLI

安装asciinema命令行工具

brew install asciinema

---
brew install asciinema

---

Phase 1: File Selection (MANDATORY)

阶段1：文件选择（必填）

Purpose: Discover and select the recording to play.
目的：查找并选择要播放的录制文件。

Step 1.1: Discover Recordings

步骤1.1：查找录制文件

bash
undefined
bash
undefined

Search for .cast files in common locations

在常用位置搜索.cast文件

fd -e cast . --max-depth 5 2>/dev/null | head -20
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
undefined
ls -lh ~/scripts/tmp/.cast 2>/dev/null ls -lh ~/.local/share/asciinema/.cast 2>/dev/null ls -lh ./tmp/*.cast 2>/dev/null
undefined

Step 1.2: Get File Info

步骤1.2：获取文件信息

bash
undefined
bash
undefined

Get file size and line count for selected file

获取选中文件的大小和事件行数

ls -lh {file_path} wc -l {file_path}
undefined
ls -lh {file_path} wc -l {file_path}
undefined

Step 1.3: Present File Selection (MANDATORY AskUserQuestion)

步骤1.3：展示文件选择（必须触发AskUserQuestion）

If user provided path directly, confirm:
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"
If no path provided, discover and present options:
Question: "Which recording would you like to play?"
Header: "Recording"
Options:
  - Label: "{filename} ({size})"
    Description: "{line_count} events"
  - ... (up to 4 most recent)
若用户直接提供文件路径，进行确认：
问题: "是否播放该录制文件？"
标题: "确认"
选项:
  - 标签: "是，播放{filename}"
    描述: "{size}，{line_count}个事件"
  - 标签: "选择其他文件"
    描述: "浏览其他录制文件"
若用户未提供路径，查找并展示可选文件：
问题: "你想播放哪个录制文件？"
标题: "录制文件"
选项:
  - 标签: "{filename}（{size}）"
    描述: "{line_count}个事件"
  - ...（最多展示4个最新文件）

Phase 2: Playback Settings (MANDATORY)

阶段2：播放设置（必填）

Purpose: Configure playback options before launching iTerm2.
目的：在启动iTerm2前配置播放选项。

Step 2.1: Ask Playback Speed (MANDATORY AskUserQuestion)

步骤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"
If "Custom" selected, ask for speed value (use Other option for numeric input).
问题: "选择播放速度："
标题: "速度"
选项:
  - 标签: "2倍速（快速）"
    描述: "适合审核，可查看全部内容"
  - 标签: "6倍速（极快）"
    描述: "快速浏览长会话"
  - 标签: "16倍速（超快）"
    描述: "快速 skim 700MB以上的大文件"
  - 标签: "自定义"
    描述: "输入自定义速度倍数"
若选择“自定义”，询问具体速度值（使用其他选项进行数值输入）。

Step 2.2: Ask Additional Options (MANDATORY AskUserQuestion)

步骤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)"
问题: "选择附加播放选项："
标题: "选项"
多选: 是
选项:
  - 标签: "限制空闲时间（2秒）"
    描述: "将暂停时长限制为最多2秒（推荐）"
  - 标签: "循环播放"
    描述: "播放结束后自动重启"
  - 标签: "调整终端大小"
    描述: "匹配录制文件的终端尺寸"
  - 标签: "标记点暂停"
    描述: "在标记点自动暂停（适合演示）"

Phase 3: Launch in iTerm2

阶段3：在iTerm2中启动播放

Purpose: Open clean iTerm2 window and start playback.
目的：打开干净的iTerm2窗口并开始播放。

Step 3.1: Build Command

步骤3.1：构建命令

Construct the 
asciinema play
command based on user selections:
bash
undefined
根据用户选择构建
asciinema play
命令：
bash
undefined

Example with all options

包含所有选项的示例

asciinema play -s 6 -i 2 -l -r /path/to/recording.cast

**Option flags:**

- `-s {speed}` - Playback speed
- `-i 2` - Idle time limit (if selected)
- `-l` - Loop (if selected)
- `-r` - Resize terminal (if selected)
- `-m` - Pause on markers (if selected)
asciinema play -s 6 -i 2 -l -r /path/to/recording.cast

**选项标识说明**：

- `-s {speed}` - 播放速度
- `-i 2` - 空闲时间限制（若选中）
- `-l` - 循环播放（若选中）
- `-r` - 调整终端大小（若选中）
- `-m` - 标记点暂停（若选中）

Step 3.2: Launch iTerm2 Window

步骤3.2：启动iTerm2窗口

Use AppleScript to open a clean window (bypasses default arrangements):
bash
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'
使用AppleScript打开干净窗口（绕过默认布局）：
bash
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'

Step 3.3: Display Controls Reference

步骤3.3：展示控制快捷键参考

markdown
undefined
markdown
undefined

Playback Started

播放已启动

Recording: 
{filename}
Speed: {speed}x Options: {options_summary}
录制文件: 
{filename}
速度: {speed}倍速 选项: {选项摘要}

Keyboard Controls

键盘控制

KeyAction
Space
Pause / Resume
Ctrl+C
Stop playback
.
Step forward (when paused)
]
Skip to next marker (when paused)
按键操作
Space
暂停 / 继续
Ctrl+C
停止播放
.
单步前进（暂停时）
]
跳转到下一个标记点（暂停时）

Tips

提示

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

---
  • 随时按
    Space
    暂停
  • 使用
    .
    逐帧查看
  • 完成后按
    Ctrl+C
    退出

---

TodoWrite Task Template (MANDATORY)

TodoWrite任务模板（必填）

Load this template into TodoWrite before starting:
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
开始前请将此模板加载到TodoWrite：
1. [预检] 检查iTerm2是否安装
2. [预检] 检查asciinema命令行工具是否安装
3. [预检] AskUserQuestion：是否安装缺失的依赖（若需要）
4. [预检] 安装依赖组件（若用户确认）
5. [选择] 获取文件信息（大小、事件数）
6. [选择] AskUserQuestion：确认文件选择
7. [设置] AskUserQuestion：选择播放速度
8. [设置] AskUserQuestion：选择附加选项（多选）
9. [启动] 构建asciinema play命令
10. [启动] 执行AppleScript打开iTerm2
11. [启动] 展示控制快捷键参考

CLI Options Reference

命令行选项参考

OptionFlagValuesDescription
Speed
-s
0.5, 1, 2, 6, 16...Playback speed multiplier
Idle limit
-i
seconds (e.g., 2)Cap idle/pause time
Loop
-l
(flag)Continuous loop
Resize
-r
(flag)Match terminal to recording size
Markers
-m
(flag)Auto-pause at markers
Quiet
-q
(flag)Suppress info messages
选项标识取值范围描述
速度
-s
0.5, 1, 2, 6, 16...播放速度倍数
空闲时间限制
-i
秒数（如2）限制空闲/暂停时长
循环播放
-l
（开关标识）持续循环播放
调整终端大小
-r
（开关标识）匹配终端与录制文件尺寸
标记点暂停
-m
（开关标识）在标记点自动暂停
静默模式
-q
（开关标识）抑制信息提示

AppleScript Reference

AppleScript参考

Open Clean iTerm2 Window (No Default Arrangement)

打开干净的iTerm2窗口（无默认布局）

applescript
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
Why this works: 
create window with default profile
creates a fresh window, bypassing any saved window arrangements.
applescript
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
会创建一个全新窗口，绕过任何已保存的窗口布局。

One-liner for Bash

Bash单行命令

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

Troubleshooting

故障排除

"Device not configured" error

"Device not configured"错误

Cause: Running 
asciinema play
from a non-TTY context (e.g., Claude Code's Bash tool)
Fix: Use AppleScript to open a real iTerm2 window (this skill does this automatically)
原因：在非TTY环境中运行
asciinema play
（例如Claude Code的Bash工具）
解决方法：使用AppleScript打开真实的iTerm2窗口（本技能会自动执行此操作）

Recording plays too fast/slow

播放速度过快/过慢

Fix: Use the speed AskUserQuestion to select appropriate speed:
  • 2x for careful review
  • 6x for quick scan
  • 16x for ultra-fast skim of very long recordings
解决方法：通过AskUserQuestion选择合适的速度：
  • 2倍速：适合仔细审核
  • 6倍速：适合快速浏览
  • 16倍速：适合超快 skim 超长录制文件

iTerm2 not opening

iTerm2无法打开

Cause: iTerm2 not installed or AppleScript permissions not granted
Fix:
  1. Install iTerm2: 
    brew install --cask iterm2
  2. Grant permissions: System Settings → Privacy & Security → Automation → Allow Terminal/Claude to control iTerm2
原因：iTerm2未安装或未授予AppleScript权限
解决方法：
  1. 安装iTerm2：
    brew install --cask iterm2
  2. 授予权限：系统设置 → 隐私与安全性 → 自动化 → 允许终端/Claude控制iTerm2

Large file (>500MB) considerations

大文件（>500MB）注意事项

The CLI player streams from disk, so file size doesn't cause memory issues. However:
  • Very long recordings may benefit from higher speeds (6x, 16x)
  • Use 
    -i 2
    to skip idle time
  • Consider splitting very long recordings
命令行播放器从磁盘流式加载文件，因此文件大小不会导致内存问题。但需注意：
  • 超长录制文件可选择更高速度（6倍速、16倍速）
  • 使用
    -i 2
    跳过空闲时间
  • 考虑拆分超长录制文件

Post-Change Checklist

修改后检查清单

After modifying this skill:
  1. Preflight checks verify iTerm2 and asciinema
  2. AskUserQuestion phases use proper multiSelect where applicable
  3. AppleScript uses heredoc wrapper for bash compatibility
  4. Speed options match CLI capability (-s flag)
  5. TodoWrite template matches actual workflow phases
修改本技能后，请检查：
  1. 预检检查可验证iTerm2和asciinema
  2. AskUserQuestion阶段在需要时启用多选
  3. AppleScript使用heredoc包装以兼容bash
  4. 速度选项与命令行工具的-s标识能力匹配
  5. TodoWrite模板与实际工作流阶段一致

Reference Documentation

参考文档