使用 VHS 录制终端屏幕截图与动画

利用 VHS（来自 Charmbracelet）生成终端屏幕截图和动画 GIF/视频。

适用场景

• 为文档制作终端屏幕截图
• 录制 CLI 演示的动画 GIF
• 为命令行工具生成视频教程
• 生成一致、可复现的终端视觉效果
• 通过黄金文件对比进行集成测试

前置条件

检查安装

# 检查 vhs 是否已安装
which vhs && vhs --version

# 检查依赖项
which ttyd && which ffmpeg

安装方法

推荐：Homebrew（macOS/Linux）

brew install vhs

此命令将安装 VHS 及其所有必需依赖项（ttyd、ffmpeg）。

其他方法：

# Fedora/RHEL
echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo dnf install vhs ffmpeg
# 还需安装 ttyd：https://github.com/tsl0922/ttyd/releases

# Arch Linux
pacman -S vhs

# Docker（包含所有依赖项）
docker run --rm -v $PWD:/vhs ghcr.io/charmbracelet/vhs <cassette>.tape

基础用法

1. 创建磁带文件

vhs new demo.tape

2. 编辑磁带文件

磁带文件是描述要输入内容和录制内容的简单脚本。

3. 运行 VHS

vhs demo.tape

磁带文件语法

输出格式

Output demo.gif          # 动画 GIF
Output demo.mp4          # 视频文件
Output demo.webm         # WebM 视频
Output frames/           # PNG 序列（目录）

可以在一个磁带文件中指定多个输出。

设置（必须位于文件顶部）

# 终端尺寸
Set Width 1200
Set Height 600

# 字体设置
Set FontSize 22
Set FontFamily "JetBrains Mono"

# 外观
Set Theme "Catppuccin Mocha"
Set Padding 20
Set Margin 20
Set MarginFill "#1e1e2e"
Set BorderRadius 10
Set WindowBar Colorful

# 行为
Set Shell "bash"
Set TypingSpeed 50ms
Set Framerate 30
Set CursorBlink false

常用主题

运行 vhs themes 查看所有可用主题。流行主题包括：
- Catppuccin Mocha、Catppuccin Frappe
- Dracula
- Tokyo Night
- Nord
- One Dark

命令

转义引号

使用反引号转义引号：

Type `echo "hello world"`
Type `VAR='value'`

示例

静态截图

Output screenshot.png

Set Width 800
Set Height 400
Set FontSize 18
Set Theme "Catppuccin Mocha"
Set Padding 20

# 隐藏设置步骤
Hide
Type "clear"
Enter
Show

# 实际内容
Type "ls -la"
Enter
Sleep 500ms

Screenshot screenshot.png

动画演示 GIF

Output demo.gif

Set Width 1000
Set Height 500
Set FontSize 20
Set Theme "Dracula"
Set TypingSpeed 50ms
Set Padding 20
Set WindowBar Colorful

# 干净的开始
Hide
Type "clear"
Enter
Show

# 演示序列
Type "echo 'Hello from VHS!'"
Sleep 300ms
Enter
Sleep 1s

Type "date"
Enter
Sleep 1s

Type "echo 'That was easy!'"
Enter
Sleep 2s

带简洁提示符的 MP4 视频

Output tutorial.mp4

Set Width 1200
Set Height 600
Set FontSize 24
Set Theme "Tokyo Night"
Set Shell "bash"
Set Framerate 30

# 设置简洁、极简的提示符
Hide
Env PS1 "$ "
Type "clear"
Enter
Show

Type "# Welcome to the tutorial"
Enter
Sleep 1s

Type "git status"
Enter
Sleep 2s

Type "git log --oneline -5"
Enter
Sleep 3s

获取清晰输出的技巧

1. 隐藏设置/清理步骤

# 设置（隐藏）
Hide
Type "cd ~/project && clear"
Enter
Show

# 你的演示内容...

# 清理（隐藏）
Hide
Type "cd - && rm temp-files"
Enter

2. 使用简洁的提示符

Hide
Env PS1 "$ "
Type "clear"
Enter
Show

3. 控制时间

• 大量使用 Sleep 以提高可读性
• 输入后、按 Enter 前使用 Sleep 500ms
• 命令输出后等待 1s 到 2s
• 最后一帧后等待 2s 或更长时间

4. 输入速度

# 设置步骤使用默认速度
Set TypingSpeed 10ms

# 重要部分放慢速度
Type@100ms "Important command here"

5. 等待输出

Type "npm install"
Enter
Wait /added \d+ packages/  # 等待完成消息
Sleep 1s

6. 在关键时刻截图

Type "make build"
Enter
Wait /Build complete/
Screenshot build-success.png

文档制作工作流

1. 规划 演示序列
2. 创建 包含设置的 .tape 文件
3. 测试 运行 vhs demo.tape（生成输出）
4. 迭代 - 调整时间、尺寸、主题
5. 提交 将 .tape 文件和输出都提交到仓库

录制真实会话

你可以录制终端并生成磁带文件：

vhs record > session.tape

然后编辑生成的磁带文件以进行清理。

文件参考

查看本技能目录中的示例磁带文件：
- basic-screenshot.tape - 简单的静态截图
- demo-recording.tape - 动画 GIF 演示

资源

• VHS GitHub
• VHS 主题
• 示例磁带文件