wehub/charmbracelet--vhs

Fork 0

Files

T

wehub-resource-sync 74683d0295

build / build (push) Failing after 0s

Details

lint / lint (push) Failing after 0s

Details

build / snapshot (push) Failing after 0s

Details

nightly / nightly (push) Failing after 1s

Details

docs: make Chinese README the default

2026-07-13 10:10:19 +00:00

24 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

VHS

以代码形式编写终端 GIF，用于集成测试和演示你的 CLI 工具。

上面的示例由 VHS 生成（查看源码）。

教程

要开始使用，请安装 VHS，并创建一个新的 .tape 文件。

vhs new demo.tape

使用你喜欢的 $EDITOR 打开 .tape 文件。

vim demo.tape

Tape 文件由一系列命令组成。这些命令是 VHS 在其虚拟终端上执行的指令。要查看所有可用命令，请参阅命令参考。

# Where should we write the GIF?
Output demo.gif

# Set up a 1200x600 terminal with 46px font.
Set FontSize 46
Set Width 1200
Set Height 600

# Type a command in the terminal.
Type "echo 'Welcome to VHS!'"

# Pause for dramatic effect...
Sleep 500ms

# Run the command by pressing enter.
Enter

# Admire the output for a bit.
Sleep 5s

完成后，保存文件并将其输入 VHS。

vhs demo.tape

全部完成！你应该会在目录中看到名为 demo.gif 的新文件（或你命名的 Output）。

更多示例请参阅 examples/ 目录。

安装

Note

VHS 需要安装 ttyd 和 ffmpeg，并确保它们在你的 PATH 上可用。

使用包管理器：

# macOS or Linux
brew install vhs

# Arch Linux (btw)
pacman -S vhs

# Nix
nix-env -iA nixpkgs.vhs

# Windows using scoop
scoop install vhs

或者，使用 Docker 直接运行 VHS（已包含依赖）：

docker run --rm -v $PWD:/vhs ghcr.io/charmbracelet/vhs <cassette>.tape

或者，直接下载：

Packages 提供 Debian 和 RPM 格式
Binaries 提供适用于 Linux、macOS 和 Windows 的版本

或者，使用 go 安装：

go install github.com/charmbracelet/vhs@latest

Windows、Debian、Ubuntu、Fedora、RHEL、Void 安装说明

Debian / Ubuntu

# Debian/Ubuntu
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
# Install ttyd from https://github.com/tsl0922/ttyd/releases
sudo apt update && sudo apt install vhs 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
# Install ttyd from https://github.com/tsl0922/ttyd/releases
sudo yum install vhs ffmpeg

Void

sudo xbps-install vhs

Windows

winget install charmbracelet.vhs
# or scoop
scoop install vhs

录制 Tape

VHS 可以根据你的终端操作生成 tape 文件！

要录制到 tape 文件，请运行：

vhs record > cassette.tape

执行你想要的任何操作，然后 exit 终端会话以停止录制。你可能需要手动编辑生成的 .tape 文件，以添加设置或修改操作。然后，你可以生成 GIF：

vhs cassette.tape

发布 Tape

VHS 允许你将 GIF 发布到我们的服务器，以便与朋友和同事轻松分享。指定要分享的文件，然后使用 publish 子命令将其托管到 vhs.charm.sh。输出会提供通过浏览器、HTML 和 Markdown 分享 GIF 的链接。

vhs publish demo.gif

VHS 服务器

VHS 内置了 SSH 服务器！当你自行托管 VHS 时，可以像本地安装一样访问它。VHS 将能够访问主机上的命令和应用程序，因此你无需在自己的机器上安装它们。

要启动服务器，请运行：

vhs serve

配置选项

VHS_PORT：监听的端口（1976）
VHS_HOST：监听的主机（localhost）
VHS_GID：运行服务器时使用的组 ID（当前用户的 GID）
VHS_UID：运行服务器时使用的用户 ID（当前用户的 UID）
VHS_KEY_PATH：要使用的 SSH 密钥路径（.ssh/vhs_ed25519）
VHS_AUTHORIZED_KEYS_PATH：authorized keys 文件路径（为空，可公开访问）

然后，只需通过 ssh 从另一台机器访问 VHS：

ssh vhs.example.com < demo.tape > demo.gif

VHS 命令参考

Note

你可以在命令行中使用 vhs manual 查看所有 VHS 文档。

VHS 命令有几种基本类型：

Output <path>：指定文件输出
Require <program>：为 tape 文件指定所需程序
Set <Setting> Value：设置录制参数
Type "<characters>"：模拟输入
Left Right Up Down：方向键
Backspace Enter Tab Space：特殊按键
ScrollUp ScrollDown：滚动终端视口
Ctrl[+Alt][+Shift]+<char>：按下 Control + 键和/或修饰键
Sleep <time>：等待一定时间
Wait[+Screen][+Line] /regex/：等待特定条件
Hide：在输出中隐藏命令
Show：停止在输出中隐藏命令
Screenshot：截取当前帧
Copy/Paste：从剪贴板复制和粘贴文本
Source：从另一个 tape 导入命令
Env <Key> Value：设置环境变量

Output

Output 命令允许你指定渲染的位置和文件格式。你可以在 tape 文件中指定多个输出，它们将被渲染到相应位置。

Output out.gif
Output out.mp4
Output out.webm
Output frames/ # a directory of frames as a PNG sequence

Require

Require 命令允许你为 tape 文件指定依赖项。如果 $PATH 中缺少所需程序，这些依赖项有助于尽早失败，因为可以确定 VHS 执行将无法按预期工作。

Require 命令必须在 tape 文件顶部定义，位于任何非 setting 或非 output 命令之前。

# A tape file that requires gum and glow to be in the $PATH
Require gum
Require glow

Settings

Set 命令允许你更改终端的全局属性，例如字体设置、窗口尺寸和 GIF 输出位置。

Setting 必须在 tape 文件顶部设置。任何在非 setting 或非 output 命令之后应用的设置（TypingSpeed 除外）都将被忽略。

设置 Shell

使用 Set Shell <shell> 命令设置 shell。

Set Shell fish

设置字体大小

使用 Set FontSize <number> 命令设置字体大小。

Set FontSize 10
Set FontSize 20
Set FontSize 40

设置字体族

使用 Set FontFamily "<font>" 命令设置字体族。

Set FontFamily "Monoflow"

设置宽度

使用 Set Width 命令设置终端宽度。

Set Width 300

设置高度

使用 Set Height 命令设置终端高度。

Set Height 1000

设置字间距

使用 Set LetterSpacing 命令设置字母间距（tracking）。

Set LetterSpacing 20

设置行高

使用 Set LineHeight 命令设置行间距。

Set LineHeight 1.8

设置打字速度

Set TypingSpeed 500ms # 500ms
Set TypingSpeed 1s    # 1s

设置每次按键的打字速度（单位为秒）。例如，打字速度为 0.1 时，每输入一个字符之间会有 0.1s（100ms）的延迟。

也可以按命令使用 @<time> 语法覆盖此设置。

Set TypingSpeed 0.1
Type "100ms delay per character"
Type@500ms "500ms delay per character"

设置主题

使用 Set Theme 命令设置终端主题。主题值应为包含 base 16 颜色以及前景色和背景色的 JSON 字符串。

Set Theme { "name": "Whimsy", "black": "#535178", "red": "#ef6487", "green": "#5eca89", "yellow": "#fdd877", "blue": "#65aef7", "magenta": "#aa7ff0", "cyan": "#43c1be", "white": "#ffffff", "brightBlack": "#535178", "brightRed": "#ef6487", "brightGreen": "#5eca89", "brightYellow": "#fdd877", "brightBlue": "#65aef7", "brightMagenta": "#aa7ff0", "brightCyan": "#43c1be", "brightWhite": "#ffffff", "background": "#29283b", "foreground": "#b3b0d6", "selection": "#3d3c58", "cursor": "#b3b0d6" }

也可以按名称设置主题：

Set Theme "Catppuccin Frappe"

运行 vhs themes 可查看完整列表，或在 THEMES.md 中查看。

设置内边距

使用 Set Padding 命令设置终端边框的内边距（单位为像素）。

Set Padding 0

设置外边距

使用 Set Margin 命令设置视频的外边距（单位为像素）。

Set Margin 60
Set MarginFill "#6B50FF"

设置窗口栏

使用 Set WindowBar 命令设置终端窗口的窗口栏类型（Colorful、ColorfulRight、Rings、RingsRight）。

Set WindowBar Colorful

设置圆角半径

使用 Set BorderRadius 命令设置终端窗口的圆角半径（单位为像素）。

# You'll likely want to add a Margin + MarginFill if you use BorderRadius.
Set Margin 20
Set MarginFill "#674EFF"
Set BorderRadius 10

设置帧率

使用 Set Framerate 命令设置 VHS 捕获帧的速率。

Set Framerate 60

设置播放速度

设置最终渲染的播放速度。

Set PlaybackSpeed 0.5 # Make output 2 times slower
Set PlaybackSpeed 1.0 # Keep output at normal speed (default)
Set PlaybackSpeed 2.0 # Make output 2 times faster

Set Loop Offset

设置 GIF 循环开始的偏移量。这样可以让 GIF 的第一帧（通常用于预览）更有趣。

Set LoopOffset 5 # Start the GIF at the 5th frame
Set LoopOffset 50% # Start the GIF halfway through

Set Cursor Blink

设置光标是否闪烁。默认启用。

Set CursorBlink false

Type

使用 Type 模拟按键。也就是说，你可以使用 Type 在终端中脚本化输入。Type 命令既适合输入命令，也适合在终端中与提示符和 TUI（终端用户界面）交互。该命令接受一个字符串参数，表示要输入的字符。

你可以通过 Set TypingSpeed 设置标准输入速度，并在特定位置用 @time 参数覆盖。

# Type something
Type "Whatever you want"

# Type something really slowly!
Type@500ms "Slow down there, partner."

用反引号转义单引号和双引号。

Type `VAR="Escaped"`

Keys

Key 命令接受可选的 @time 和可选的重复 count，用于每隔 <time> 间隔重复按键。

Key[@<time>] [count]

Backspace

使用 Backspace 命令按下退格键。

Backspace 18

Ctrl

你可以通过 Ctrl 命令访问 Control 修饰键并发送控制序列。

Ctrl+R

Enter

使用 Enter 命令按下回车键。

Enter 2

Arrow Keys

使用 Up、Down、Left、Right 命令按下任意方向键。

Up 2
Down 2
Left
Right
Left
Right
Type "B"
Type "A"

Tab

使用 Tab 命令输入制表符。

Tab@500ms 2

Space

使用 Space 命令按下空格键。

Space 10

Page Up / Down

使用 PageUp 或 PageDown 命令按下 Page Up / Page Down 键。

PageUp 3
PageDown 5

Scroll Up / Down

使用 ScrollUp 和 ScrollDown 直接滚动终端视口。两个命令都使用与其他可重复按键命令相同的可选 @time 和重复次数形式：ScrollUp[@<time>] [count]。

ScrollUp 10
ScrollDown 4
ScrollDown@100ms 12

Wait

Wait 命令允许你等待屏幕上出现某些内容。当你需要等待某事完成（即使不知道需要多久），同时又想在录制中包含它（例如旋转指示器或加载状态）时，这会很有用。该命令接受一个正则表达式作为参数，并可选择设置等待时长，以及是检查整个屏幕还是仅检查最后一行（范围）。

Wait
Wait            /World/
Wait+Screen     /World/
Wait+Line       /World/
Wait@10ms       /World/
Wait+Line@10ms  /World/

默认正则表达式为 />$/，等待超时为 15s，默认范围为 Line。

Sleep

Sleep 命令允许你在不与终端交互的情况下继续捕获帧。当你需要等待某事完成，同时又想在录制中包含它（例如旋转指示器或加载状态）时，这会很有用。该命令接受以秒为单位的数字参数。

Sleep 0.5   # 500ms
Sleep 2     # 2s
Sleep 100ms # 100ms
Sleep 1s    # 1s

Hide

Hide 命令指示 VHS 停止捕获帧。适用于暂停录制以执行隐藏的命令。

Hide

该命令有助于执行录制 GIF 所需的任何设置和清理工作，例如构建二进制文件的最新版本，并在演示录制完成后删除该二进制文件。

Output example.gif

# Setup
Hide
Type "go build -o example . && clear"
Enter
Show

# Recording...
Type 'Running ./example'
...
Enter

# Cleanup
Hide
Type 'rm example'
Enter

Show

Show 命令指示 VHS 重新开始捕获帧。在 Hide 命令之后很有用，可恢复输出画面的帧录制。

Hide
Type "You won't see this being typed."
Show
Type "You will see this being typed."

Screenshot

Screenshot 命令捕获当前帧（png 格式）。

# At any point...
Screenshot examples/screenshot.png

Copy / Paste

Copy 和 Paste 从剪贴板复制和粘贴字符串。

Copy "https://github.com/charmbracelet"
Type "open "
Sleep 500ms
Paste

Env

Env 命令通过键值对设置环境变量。

Env HELLO "WORLD"

Type "echo $HELLO"
Enter
Sleep 1s

Source

source 命令允许你执行来自另一条 tape 的命令。

Source config.tape

Continuous Integration

你可以将 VHS 接入 CI 流水线，通过官方 VHS GitHub Action 保持 GIF 与代码同步更新：

⚙️ charmbracelet/vhs-action

VHS 也可用于集成测试。使用 .txt 或 .ascii 的输出来生成黄金文件（golden files）。将这些文件存放在 git 仓库中，以确保多次运行磁带文件时不会出现 diff。

Output golden.ascii

语法高亮

面向支持 tree-sitter 语法高亮的编辑器，现已提供 .tape 文件的 tree-sitter 语法：

🌳 charmbracelet/tree-sitter-vhs

在 Neovim、Emacs 等编辑器中效果很好！

参与贡献

请参阅参与贡献。

反馈

我们很想听听你对本项目的想法。欢迎随时给我们留言！

许可证

MIT

属于 Charm.

Charm热爱开源 • Charm loves open source

24 KiB Raw Permalink Blame History Unescape Escape

VHS

教程

安装

录制 Tape

发布 Tape

VHS 服务器

VHS 命令参考

Output

Require

Settings

设置 Shell

设置字体大小

设置字体族

设置宽度

设置高度

设置字间距

设置行高

设置打字速度

设置主题

设置内边距

设置外边距

设置窗口栏

设置圆角半径

设置帧率

设置播放速度

Set Loop Offset

Set Cursor Blink

Type

Keys

Backspace

Ctrl

Enter

Arrow Keys

Tab

Space

Page Up / Down

Scroll Up / Down

Wait

Sleep

Hide

Show

Screenshot

Copy / Paste

Env

Source

Continuous Integration

语法高亮

参与贡献

反馈

许可证

24 KiB

Raw Permalink Blame History