mcpField
R
record-tui

record-tui

github.com/antjanus创意与媒体264 次安装1 周前更新
代码仓库

关于 record-tui

这项技能指南介绍如何使用 Charmbracelet VHS 将脚本化终端录制渲染为 GIF、MP4、WebM 或 ASCII。内容涵盖 tape 编写、验证、节奏控制，以及面向 CLI 和 TUI 演示的 CI 录制流程。

主要功能

  1. 01将 .tape 脚本渲染为 GIF、MP4、WebM 或 ASCII
  2. 02脚本化终端输入、按键、等待和设置
  3. 03验证 tape 并检查渲染结果
  4. 04调整演示节奏和输出文件大小

适用场景

  1. 01为 README 制作可重复生成的 CLI 演示
  2. 02按设定节奏录制 TUI 操作过程
  3. 03在 CI 中生成终端录制内容

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/antjanus/skillbox --skill record-tui

安装后在 Claude Code 中输入/record-tui确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

reference/
CI-INTEGRATION.md
COMMAND-REFERENCE.md
EVAL.md
OPTIMIZATION.md
TEMPLATES.md

详细介绍

录制 TUI — VHS 终端录制

概述

Charmbracelet VHS 可将 .tape 脚本渲染为 GIF / MP4 / WebM / ASCII。将演示编写为代码，而不是录屏，因为应用发生变化时，.tape 可以随时重新渲染，无需人工操作，而且在 CI 中的运行方式也相同。对于不会再次运行的一次性录制，asciinema 更轻量。

设置

# macOS
brew install charmbracelet/tap/vhs ffmpeg ttyd
# Debian/Ubuntu
sudo apt install ffmpeg && sudo snap install ttyd --classic && go install github.com/charmbracelet/vhs@latest

vhs --version && ffmpeg -version && ttyd --version   # all three are required

Tape 文件结构

每条 Set 都必须放在第一条交互命令之前。放在后面的 Set 会被静默丢弃——请参阅注意事项。

Output demo.gif              # 1. output (gif/mp4/webm/ascii)
Require my-app               # 2. fail fast if the app is missing

Set Shell "bash"             # 3. settings, all grouped before any command
Set FontSize 20
Set Width 1200
Set Height 600
Set Theme "Catppuccin Frappe"
Set WindowBar Colorful
Set Padding 20
Set TypingSpeed 75ms

Hide                         # 4. hidden setup — Ctrl+L before Show
Type "export TERM=xterm-256color"
Enter
Sleep 500ms
Ctrl+L
Show

Type "my-app --demo"         # 5. visible interactions, with deliberate pauses
Sleep 500ms
Enter
Sleep 2s
Down 3                       # 6. app interaction
Enter
Sleep 3s                     # generous final frame before the loop restarts

快速参考

命令用途
Output file.gif输出文件及格式（gif/mp4/webm/ascii）；可重复指定多种格式
Require app如果程序不在 PATH 中，则报错
Set Key Value终端设置（FontSize、Width、Height、Theme、Framerate 等）
Type "text" / Type@100ms "text"模拟输入（可按每行速度输入）
Enter / Tab / Space / Escape按键
Up/Down/Left/Right（Down 3）导航，可选重复次数
Ctrl+key、Alt+key、Shift+key修饰键组合
Sleep 2s固定暂停（ms 或 s）
Wait+Screen@30s /regex/等待屏幕内容匹配，直到超时
Hide / Show控制录制画面的显示（无论显示与否，执行都会继续）
Screenshot file.png捕获当前帧
Env VAR "val" / Source other.tape设置环境变量 / 引入另一个 tape
vhs validate demo.tape    # parse-check, no rendering
vhs demo.tape             # record
vhs themes                # list themes
vhs new demo.tape         # scaffold from template

完整的命令和设置详情：reference/COMMAND-REFERENCE.md。

使用场景宽度高度字体大小
README GIF120060020
文档/教程140080018
社交媒体120063022
完整 TUI 应用160090016
紧凑型 CLI80040020

为应用录制 tape

查看应用的 --help 输出或源码，了解它如何启动、响应哪些按键，以及哪些状态值得展示。起草一个涵盖这些状态的 tape，然后依次运行 vhs validate demo.tape → vhs demo.tape → 观看渲染后的文件 → 调整。观看是关键步骤：验证只会解析语法，无法判断演示节奏是否快到让观众看不清。

起草前先限定演示范围：README GIF 展示一个工作流，时长为 10–30 秒——包含 3 到 5 个状态，每个状态停留足够长的时间以便阅读（Sleep 2s–3s）。超过 30 秒时，应删减状态或拆分为第二个 tape，而不是继续添加场景；展示一切就等于什么都没展示，GIF 体积也会随之增大。

可复制的起点（Basic CLI、Interactive TUI、Build-and-Run、Multi-Panel、CI golden file、可组合的 Source tapes）：reference/TEMPLATES.md。

示例

✅ 先输出，将设置集中放在命令上方，用 Require 检查二进制文件是否存在，输入后暂停，并在最后一帧停留较长时间：

Output demo.gif
Require my-app

Set Shell "bash"
Set FontSize 20
Set Width 1200
Set Height 600

Type "my-app status"
Sleep 500ms
Enter
Sleep 3s

❌ 同一个 tape 存在 3 个缺陷——Set Width 放在 Type 之后，因此会被丢弃；输入与执行之间没有间隔；缺少二进制文件时只会生成令人困惑的空 GIF，而不会报错：

Output demo.gif

Type "my-app status"
Enter
Set Width 1200

✅ 为启动时间不稳定的 TUI 控制节奏——等待屏幕匹配，而不是猜测 Sleep 时长：

Type "my-tui"
Enter
Wait+Screen@30s /Ready/
Down 3
Sleep 500ms
Enter
Sleep 3s

注意事项

  • 第一条命令之后的 Set 会被静默丢弃，而且 vhs validate 仍会以 0 退出。 已在 vhs 0.11.0 上验证：Type 之后的 Set FontSize 40 会以默认字号渲染，Set TypingSpeed 也一样——不存在针对特定设置的例外。务必将所有 Set 放在第一个 Type/按键命令之前，并通过查看输出进行确认，因为工具链不会报告此问题。若要在录制过程中改变打字速度，请使用逐行设置的 Type@100ms "…" 格式。
  • vhs validate 只会解析。 它不会启动应用，因此即使二进制文件缺失、按键绑定错误，或演示进度快于应用启动，这些情况也都能通过验证。添加 Require <app>，这样缺少依赖时就会明确报错，而不是渲染出空终端。
  • Type "cmd" 不会按下 Enter。 在后面显式添加 Enter，并在两者之间加入 Sleep 500ms，让观看者能在命令运行前读完它。
  • Hide 隐藏的是输出，而不是执行。 Hide 块中的命令仍会运行。在 Show 之前用 Ctrl+L 结束该块，避免残留的设置输出出现在录制开头。
  • Wait 会超时。 对于启动较慢的 TUI，应按命令提高超时时间（Wait+Screen@30s /ready/），或全局设置（Set WaitTimeout 30s），而不是用更长的 Sleep 来凑时间——在较慢的机器上，这样仍然会出错。
  • VHS 会在全新的 Shell 中录制，因此不会应用你的提示符自定义设置。 固定设置 Set Shell "bash"，以确保你的机器和 CI 中使用相同的提示符。
  • TUI 显示的颜色或换行不正确，通常是终端配置问题。 在 Hide 块中固定配置：Env TERM "xterm-256color"，再加上 Type "stty rows 50 cols 120"。
  • GIF 很快就会超过 5 MB。 GitHub 会内嵌显示它们，但会让 README 加载变慢。先尝试 Set Framerate 15——这是成本最低的优化，而且几乎不会影响流畅度；然后使用 gifsicle -O3 --lossy=80；在将尺寸缩小到影响可读性之前，改用 MP4。

优化与 CI

尺寸缩减、播放调优，以及 GIF、MP4 与 WebM 之间的选择指南：reference/OPTIMIZATION.md。在 GitHub Actions 中录制，以及将 ASCII 输出作为 UI 回归测试的基准文件：reference/CI-INTEGRATION.md。

集成

与 build-tui 配合使用——构建完 TUI 后立即录制，并将 .tape 与源文件放在一起提交，这样 GIF 就会随应用一起重新生成。如果目标是在 localhost 上运行的 Web UI，则改用 screenshot-local。

外部资源：VHS · VHS Action · 示例 · 主题 · gifsicle。

评论

支持 Markdown