charmbracelet/vhs

# VHS

编写终端 GIF 以用于集成测试和演示你的 CLI 工具。 上述示例是使用 VHS 生成的（[查看源码](./examples/neofetch/neofetch.tape)）。 ## 教程 要开始，请[安装 VHS](#installation) 并创建一个新的 `.tape` 文件。 ``` vhs new demo.tape ``` 用你喜欢的 `$EDITOR` 打开 `.tape` 文件。 ``` vim demo.tape ``` 磁带文件由一系列[命令](#vhs-command-reference)组成。 这些命令是 在虚拟终端上执行 VHS 操作的指令。欲了解所有可能的命令，请参见[命令参考](#vhs-command-reference)。 ``` # 我们应该在哪里写 GIF？ Output demo.gif # 设置一个 1200x600 终端，字体为 46px。 Set FontSize 46 Set Width 1200 Set Height 600 # 在终端中输入命令。 Type "echo 'Welcome to VHS!'" # 暂停以产生戏剧效果... Sleep 500ms # 按下回车运行命令。 Enter # 稍作欣赏输出。 Sleep 5s ``` 完成后，保存文件并将其输入 VHS。 ``` vhs demo.tape ``` 大功告成！你应该会看到一个名为 `demo.gif` 的新文件（或者你命名的 `Output`）在当前目录中。 更多示例请查看 [`examples/`](https://github.com/charmbracelet/vhs/tree/main/examples) 目录。 ## 安装 使用软件包管理器： ``` # macOS 或 Linux brew install vhs # Arch Linux（顺便一提） pacman -S vhs # Nix nix-env -iA nixpkgs.vhs # 使用 scoop 的 Windows scoop install vhs ``` 或者，使用 Docker 直接运行 VHS（包含依赖项）： ``` docker run --rm -v $PWD:/vhs ghcr.io/charmbracelet/vhs .tape ``` 或者，直接下载它： - [软件包][releases] 以 Debian 和 RPM 格式提供 - [二进制文件][releases] 适用于 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 # 从 https://github.com/tsl0922/ttyd/releases 安装 ttyd 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 # 从 https://github.com/tsl0922/ttyd/releases 安装 ttyd sudo yum install vhs ffmpeg ``` - Void ``` sudo xbps-install vhs ``` - Windows ``` winget install charmbracelet.vhs # 或 scoop scoop install vhs ```

## 录制磁带 VHS 具备从你的终端操作生成磁带文件的能力！ 要录制磁带文件，请运行： ``` vhs record > cassette.tape ``` 执行你想要的操作，然后退出终端会话以停止录制。 你可能需要手动编辑生成的 `.tape` 文件以添加设置或修改操作。 接着，你可以生成 GIF： ``` vhs cassette.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`：授权密钥文件路径（空，允许公开访问）

然后，通过 `ssh` 从另一台机器访问 VHS： ``` ssh vhs.example.com < demo.tape > demo.gif ``` ## VHS 命令参考 有一些基本的 VHS 命令类型： - [`Output `](#output)：指定文件输出 - [`Require `](#require)：指定磁带文件所需的程序 - [`Set Value`](#settings)：设置录制设置 - [`Type ""`](#type)：模拟按键输入 - [`Left`](#arrow-keys) [`Right`](#arrow-keys) [`Up`](#arrow-keys) [`Down`](#arrow-keys)：方向键 - [`Backspace`](#backspace) [`Enter`](#enter) [`Tab`](#tab) [`Space`](#space)：特殊键 - [`ScrollUp`](#scroll-up--down) [`ScrollDown`](#scroll-up--down)：滚动终端视口 - [`Ctrl[+Alt][+Shift]+`](#ctrl)：按下控制键和/或修饰键 - [`Sleep `](#sleep)：等待一段时间 - [`Wait[+Screen][+Line] /regex/`](#wait)：等待特定条件 - [`Hide`](#hide)：隐藏命令输出 - [`Show`](#show)：停止隐藏命令输出 - [`Screenshot`](#screenshot)：截图当前帧 - [`Copy/Paste`](#copy--paste)：从剪贴板复制和粘贴文本 - [`Source`](#source)：从另一个磁带加载命令 - [`Env Value`](#env)：设置环境变量 ### 输出 `Output` 命令允许你指定渲染的位置和文件格式。 你可以在一个磁带文件中指定多个输出，它们将分别渲染到对应位置。 ``` Output out.gif Output out.mp4 Output out.webm Output frames/ # a directory of frames as a PNG sequence ``` ### 要求 `Require` 命令允许你指定磁带文件的依赖项。 这在所需程序不在 `$PATH` 中时非常有用，可以尽早失败，并确保 VHS 执行不会按预期工作。 `Require` 命令必须定义在磁带文件的开头，在任何非设置或非输出命令之前。 ``` # 一个需要 gum 和 glow 在 $PATH 中的磁带文件 Require gum Require glow ``` ### 设置 `Set` 命令允许你更改终端的全局设置，例如字体设置、窗口尺寸和 GIF 输出位置。 设置必须在磁带文件开头进行管理。除了 `TypingSpeed` 之外，任何在非设置或非输出命令之后应用的设置都将被忽略。 #### 设置 Shell 使用 `Set Shell ` 命令设置 Shell。 ``` Set Shell fish ``` #### 设置字体大小 使用 `Set FontSize ` 命令设置字体大小。 ``` Set FontSize 10 Set FontSize 20 Set FontSize 40 ``` #### 设置字体族 使用 `Set FontFamily ""` 命令设置字体族。 ``` Set FontFamily "Monoflow" ``` #### 设置宽度 使用 `Set Width` 命令设置终端宽度。 ``` Set Width 300 ``` #### 设置高度 使用 `Set Height` 命令设置终端高度。 ``` Set Height 1000 ``` #### 设置字符间距 使用 `Set LetterSpacing` 命令设置字符间距（跟踪）。 ``` Set LetterSpacing 20 ``` #### 设置行高 使用 `Set LineHeight` 命令设置行间距。 ``` Set LineHeight 1.8 ``` #### 设置打字速度 ``` Set TypingSpeed 500ms # 500ms Set TypingSpeed 1s # 1s ``` 设置每秒按键数。例如，打字速度为 `0.1` 会在每个字符输入之间产生 `0.1s`（100 毫秒）的延迟。 此设置也可以通过 `@` 语法在每个命令中重写。 ``` Set TypingSpeed 0.1 Type "100ms delay per character" Type@500ms "500ms delay per character" ``` #### 设置主题 使用 `Set Theme` 命令设置终端主题。主题值应为包含基础 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](./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` 命令设置终端窗口的边框半径（像素）。 ``` # 如果你使用 BorderRadius，可能需要添加 Margin + MarginFill 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 ``` #### 设置循环偏移 设置 GIF 循环开始偏移。这可以让 GIF 的第一帧（通常用于预览）更有趣。 ``` Set LoopOffset 5 # Start the GIF at the 5th frame Set LoopOffset 50% # Start the GIF halfway through ``` #### 设置光标闪烁 设置光标是否闪烁。默认启用。 ``` Set CursorBlink false ``` ### 类型 使用 `Type` 命令模拟按键输入。你可以用 `Type` 在终端中编写脚本。`Type` 既可用于输入命令，也可用于与提示符和终端中的 TUI 交互。命令参数为要输入的字符串。 你可以使用 [`Set TypingSpeed`](#set-typing-speed) 设置标准打字速度，并通过 `@` 参数在特定位置覆盖它。 ``` # 输入一些内容 Type "Whatever you want" # 输入得非常慢！ Type@500ms "Slow down there, partner." ``` 转义单引号和双引号使用反引号。 ``` Type `VAR="Escaped"` ``` ### 按键 按键命令支持可选的 `@time` 和可选的重复 `count`，用于按间隔 `` 重复按键。 ``` Key[@] [count] ``` #### 退格 使用 `Backspace` 命令按下退格键。 ``` Backspace 18 ``` #### Ctrl 你可以使用 `Ctrl` 命令访问控制修饰符并发送控制序列。 ``` Ctrl+R ``` #### 回车 使用 `Enter` 命令按下回车键。 ``` Enter 2 ``` #### 方向键 使用 `Up`、`Down`、`Left`、`Right` 命令按下任意方向键。 ``` Up 2 Down 2 Left Right Left Right Type "B" Type "A" ``` #### Tab 使用 `Tab` 命令输入制表符。 ``` Tab@500ms 2 ``` #### 空格键 使用 `Space` 命令按下空格键。 ``` Space 10 ``` #### Page Up / Page Down 使用 `PageUp` 或 `PageDown` 命令按下 Page Up / Page Down 键。 ``` PageUp 3 PageDown 5 ``` #### 滚动 使用 `ScrollUp` 和 `ScrollDown` 命令直接滚动终端视口。 这两个命令都使用与其它可重复按键命令相同的 `@` 和重复计数格式：`ScrollUp[@] [count]`。 ``` ScrollUp 10 ScrollDown 4 ScrollDown@100ms 12 ``` ### 等待 `Wait` 命令允许你等待屏幕上出现特定内容。 这在需要等待某项操作完成时非常有用，即使你不确定需要多长时间，也可以在录制中包含它（如显示加载状态）。 命令接受一个正则表达式作为参数，并可选地设置等待时长以及是否检查整个屏幕或仅最后一行（作用域）。 默认正则表达式为 `/>$/`，等待超时时间为 `15s`，默认作用域为 `Line`。 ### 睡眠 `Sleep` 命令允许你在不操作终端的情况下继续捕获帧。 这在需要等待某项操作完成时非常有用，同时将其包含在录制中（如显示加载状态）。 命令接受一个以秒为单位的数字参数。 ``` Sleep 0.5 # 500ms Sleep 2 # 2s Sleep 100ms # 100ms Sleep 1s # 1s ``` ### 隐藏 `Hide` 命令指示 VHS 停止捕获帧。这对于暂停录制以执行隐藏命令非常有用。 ``` Hide ``` 此命令有助于执行录制 GIF 所需的任何设置和清理操作，例如构建二进制文件并在录制完成后将其删除。 ``` Output example.gif # 设置 Hide Type "go build -o example . && clear" Enter Show # 录制中... Type 'Running ./example' ... Enter # 清理 Hide Type 'rm example' Enter ``` ### 显示 `Show` 命令指示 VHS 重新开始捕获帧。这在 `Hide` 命令之后非常有用，用于恢复帧录制以生成输出。 ``` Hide Type "You won't see this being typed." Show Type "You will see this being typed." ``` ### 截图 `screenshot` 命令捕获当前帧（PNG 格式）。 ``` # 在任何时候... Screenshot examples/screenshot.png ``` ### 复制 / 粘贴 `Copy` 和 `Paste` 命令复制并粘贴剪贴板中的字符串。 ``` Copy "https://github.com/charmbracelet" Type "open " Sleep 500ms Paste ``` ### 环境 `Env` 命令通过键值对设置环境变量。 ``` Env HELLO "WORLD" Type "echo $HELLO" Enter Sleep 1s ``` ### 来源 `soure` 命令允许你从另一个磁带执行命令。 ``` Source config.tape ``` ## 持续集成 你可以将 VHS 集成到 CI 流水线中，以保持 GIF 与官方 VHS GitHub 动作同步。 VHS 也可用于集成测试。使用 `.txt` 或 `.ascii` 输出生成黄金文件。将这些文件存储在 Git 仓库中，以确保多次运行磁带文件时没有差异。 ``` Output golden.ascii ``` ## 语法高亮 有一个用于 `.tape` 文件的 tree-sitter 语法可供编辑器使用，以支持语法高亮。 它与 Neovim、Emacs 等工具配合良好！ ## 贡献 请参见[贡献指南]()。 ## 反馈 我们非常乐意听取你对这个项目的意见！ - [Twitter](https://twitter.com/charmcli) - [The Fediverse](https://mastodon.social/@charmcli) - [Discord](https://charm.sh/chat) ## 许可证 [MIT](https://github.com/charmbracelet/vhs/raw/main/LICENSE) 是 [Charm](https://charm.sh) 的一部分。 Charm 热爱开源 • Charm loves open source