asciinema 3.0：Rust 重写、asciicast v3 格式与终端实时流媒体
阅读时间: 大约 11 分钟
asciinema 3.0：Rust 重写、asciicast v3 格式与终端实时流媒体
asciinema 是最流行的开源终端会话录制工具之一：不录模糊视频，而是把终端输出（字符 + 时序 + ANSI 转义）存成文本格式，再用网页播放器回放。2025 年 9 月 15 日，作者 Marcin Kulik 发布 asciinema CLI 3.0：整体用 Rust 重写、录制格式升级到 asciicast v3、新增终端实时流媒体，并带来一批 breaking changes。本文基于官方发布博客、v3.0.0 release notes 与 server 流媒体文档做梳理。
一、背景：文本录屏解决什么问题
相比 OBS 式屏幕录像，asciinema 的产物是纯文本（.cast 文件）：体积小、可复制粘贴其中命令、可嵌入博客/文档/幻灯片，也能二次编辑。长期以来它由 Python 写成，录制后默认可一键上传到官方实例 asciinema.org 分享。3.0 的两条主线正是作者对历史包袱的修正：本地化优先（不再默认上传）与实时直播（录制之外新增流媒体）。
GitHub 仓库 asciinema/asciinema（2011 年创建，GPL-3.0 协议，访问当日约 17.9k stars、1k forks，主语言已转为 Rust），3.0.0 发布于 2025-09-15，当前文档版本已迭代到 v3.2.x。
二、Rust 重写：动机与实际收益
作者在博客里很坦诚：重写的首要原因是个人偏好——“这些年我做 Rust 的乐趣是 Python 的 100 倍，而这类涉及 syscall 与并发的代码在 Rust 里好处理得多”，并非先有性能瓶颈数据才动手。实际收益有三：启动更快、安装更简单（分发静态二进制，无需 Python 环境），以及把同为 Rust 编写的 asciinema 虚拟终端（avt）直接集成进 CLI，使许多新功能成为可能。需要注意：官方只定性描述”faster startup”，没有公布启动耗时或资源占用的对比基准。
三、asciicast v3：从绝对时间戳到相邻间隔
v2 格式为每个事件记录”距会话起点的绝对时间”，编辑录制时一旦插入、删除或修改某个事件，其后所有事件的时间戳都要联动调整，非常痛苦。v3 的主要改动是改用相邻间隔（delta/intervals）：每个事件只存与上一事件的时间差，局部增删只影响相邻区间，编辑大幅简化。其他格式变化：
- 头部重组，终端相关元数据统一收进
term对象（cols/rows/type/version/theme）； - 新增
"x"（exit）事件类型，保存会话退出状态码； - 支持以
#开头的行注释； - 新增终端主题捕获：通过 OSC 4 / OSC 10 / OSC 11 查询终端配色，存入
term.theme，播放器优先使用录制时的主题。
v3 已被 asciinema server 与 player 支持；自定义读取 cast 文件的第三方工具则需留意，3.0 可用 --output-format asciicast-v2 退回旧格式。
四、实时流媒体：local 与 remote 两种模式
3.0 新增 stream 命令，提供两种直播模式，也可同时开启：
- Local 模式（
asciinema stream --local）：CLI 内置 HTTP 服务器，观众在受信网络（如局域网）通过浏览器访问本地端口（示例为http://127.0.0.1:37881）观看；数据不发往任何外部服务，只需开放防火墙端口，CLI 内嵌最新版 player 连接流； - Remote 模式（
asciinema stream --remote）：流经 asciinema server（官方或自托管）中转，生成可分享 URL（示例https://asciinema.org/s/...）。
架构上是 producer（CLI）经 WebSocket 连到 server 的生产者端点，server 作为 relay 把事件分发给多个 consumer（player）；server 自己跑一遍虚拟终端模拟器维持完整流状态，因此新观众中途加入也能立刻看到当前屏幕，而不是只能从头看。应用层支持协议协商，涵盖 ALiS v1、asciicast v2/v3 与 raw；player 实现自适应缓冲：实时测量网络延迟、动态调整缓冲大小，在低延迟与欠载保护间取平衡。
配套还有 session 命令同时录制与直播（asciinema session -l -r -o demo.cast）；server 可把每场直播落盘转成普通录制（官方公共实例当前关闭此能力）。
五、Local-first 与破坏性变更
3.0 把”保存到本地”设为唯一默认：rec 命令必须带文件名，且不再内置上传能力；发布到 server 要显式执行 asciinema upload <filename>。作者解释这是为了消除”以为必须上传”的误解，并避免误操作泄露敏感终端内容。首次使用 upload/stream/auth 时弹出 server URL 选择框（预填 asciinema.org，可改自托管地址并保存），同时作为防止意外外泄的一道闸门。
release notes 列出的 breaking changes：
| 变更项 | 2.x 行为 | 3.0 行为 |
|---|---|---|
| 上传 | rec 可直接上传，文件名可选 | 文件名必填，rec 无上传，改用 upload |
| 默认格式 | asciicast v2 | asciicast v3（可回退 v2） |
cat 命令 | 导出 + 拼接 | 仅拼接，至少两个输入 |
| 配置文件 | ~/.config/asciinema/config（ini） | ~/.config/asciinema/config.toml（TOML），api→server、record→session、play→playback |
其余新能力：convert 命令做 v2↔v3 互转并可导出纯文本日志（txt 单向，无法转回 cast）；自动创建输出路径父目录，方便 .bashrc 全自动录会话；改进的 --help 与 man 页；构建期生成 bash/zsh/fish 补全。
六、官方口径与限制
- 公共实例限制：asciinema.org 当前关闭直播落盘，且并发直播上限为 1；官方表示要先观察资源消耗再调整，自托管 server 默认无此限制；
- Rust 重写无量化对比：作者自述主要出于开发体验，“更快”是定性说法，没有 benchmark；
- Remote 模式依赖 server 中转，纯内网零外泄场景应只用 local；
- v3 生态迁移依赖第三方工具跟进，自有脚本读 cast 需显式兼容；
- 远程直播的协议与落盘能力以自托管 server 配置为准，公共版功能可能随时变化。
七、优势与局限
优势：
- 文本格式天生轻量、可检索、可复制，比视频录屏更适合技术文档与教学；
- local-first + 显式上传，敏感终端内容不再有默认外泄路径；
- 流媒体补齐了”边讲边看”的实时场景，中途加入不花屏；
- 静态二进制安装门槛低，Rust 版并发与 syscall 处理更自然。
局限：
- 纯字符流，不记录图形界面与鼠标操作，只适合终端场景；
- 直播公共实例并发 1 路、不落盘，团队直播要自托管 server；
- breaking changes（配置格式、cat 语义、默认格式）对老自动化脚本是迁移成本；
- 实时流媒体是 3.0 新增能力，协议与体验仍在演进。
八、适合谁
- 写技术教程、FAQ、会议分享，需要把终端操作变成可嵌入文本回放的开发者；
- 想在局域网内实时带教、结对排查，又不愿把终端流出内网的团队；
- 已有自托管 asciinema server、需要把直播存档并入知识库的组织。