> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/charmbracelet/vhs) · [上游 README](https://github.com/charmbracelet/vhs/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 # VHS

以代码形式编写终端 GIF，用于集成测试和演示你的 CLI 工具。 上面的示例由 VHS 生成（[查看源码](./examples/neofetch/neofetch.tape)）。 ## 教程 要开始使用，请[安装 VHS](#installation)，并创建一个新的 `.tape` 文件。 ```sh vhs new demo.tape ``` 使用你喜欢的 `$EDITOR` 打开 `.tape` 文件。 ```sh vim demo.tape ``` Tape 文件由一系列[命令](#vhs-command-reference)组成。这些命令是 VHS 在其虚拟终端上执行的指令。要查看所有可用命令，请参阅[命令参考](#vhs-command-reference)。 ```elixir # 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。 ```sh vhs demo.tape ``` 全部完成！你应该会在目录中看到名为 `demo.gif` 的新文件（或你命名的 `Output`）。 更多示例请参阅 [`examples/`](https://github.com/charmbracelet/vhs/tree/main/examples) 目录。 ## 安装 > [!NOTE] > VHS 需要安装 [`ttyd`](https://github.com/tsl0922/ttyd) 和 [`ffmpeg`](https://ffmpeg.org)，并确保它们在你的 `PATH` 上可用。 使用包管理器： ```sh # 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（已包含依赖）： ```sh docker run --rm -v $PWD:/vhs ghcr.io/charmbracelet/vhs .tape ``` 或者，直接下载： - [Packages][releases] 提供 Debian 和 RPM 格式 - [Binaries][releases] 提供适用于 Linux、macOS 和 Windows 的版本 或者，使用 `go` 安装： ```sh go install github.com/charmbracelet/vhs@latest ```

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

- Debian / Ubuntu ```sh # 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 ```sh 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 ```sh sudo xbps-install vhs ``` - Windows ```sh winget install charmbracelet.vhs # or scoop scoop install vhs ```

[releases]: https://github.com/charmbracelet/vhs/releases ## 录制 Tape VHS 可以根据你的终端操作生成 tape 文件！ 要录制到 tape 文件，请运行： ```bash vhs record > cassette.tape ``` 执行你想要的任何操作，然后 `exit` 终端会话以停止录制。你可能需要手动编辑生成的 `.tape` 文件，以添加设置或修改操作。然后，你可以生成 GIF： ```bash vhs cassette.tape ``` ## 发布 Tape VHS 允许你将 GIF 发布到我们的服务器，以便与朋友和同事轻松分享。指定要分享的文件，然后使用 `publish` 子命令将其托管到 `vhs.charm.sh`。输出会提供通过浏览器、HTML 和 Markdown 分享 GIF 的链接。 ```bash vhs publish demo.gif ``` ## VHS 服务器 VHS 内置了 SSH 服务器！当你自行托管 VHS 时，可以像本地安装一样访问它。VHS 将能够访问主机上的命令和应用程序，因此你无需在自己的机器上安装它们。 要启动服务器，请运行： ```sh 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： ```sh ssh vhs.example.com < demo.tape > demo.gif ``` ## VHS 命令参考 > [!NOTE] > 你可以在命令行中使用 `vhs manual` 查看所有 VHS 文档。 VHS 命令有几种基本类型： - [`Output `](#output)：指定文件输出 - [`Require `](#require)：为 tape 文件指定所需程序 - [`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)：按下 Control + 键和/或修饰键 - [`Sleep `](#sleep)：等待一定时间 - [`Wait[+Screen][+Line] /regex/`](#wait)：等待特定条件 - [`Hide`](#hide)：在输出中隐藏命令 - [`Show`](#show)：停止在输出中隐藏命令 - [`Screenshot`](#screenshot)：截取当前帧 - [`Copy/Paste`](#copy--paste)：从剪贴板复制和粘贴文本 - [`Source`](#source)：从另一个 tape 导入命令 - [`Env Value`](#env)：设置环境变量 ### Output `Output` 命令允许你指定渲染的位置和文件格式。你可以在 tape 文件中指定多个输出，它们将被渲染到相应位置。 ```elixir 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 命令之前。 ```elixir # 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。 ```elixir Set Shell fish ``` #### 设置字体大小 使用 `Set FontSize ` 命令设置字体大小。 ```elixir Set FontSize 10 Set FontSize 20 Set FontSize 40 ``` #### 设置字体族 使用 `Set FontFamily ""` 命令设置字体族。 ```elixir Set FontFamily "Monoflow" ``` #### 设置宽度 使用 `Set Width` 命令设置终端宽度。 ```elixir Set Width 300 ``` #### 设置高度 使用 `Set Height` 命令设置终端高度。 ```elixir Set Height 1000 ``` #### 设置字间距 使用 `Set LetterSpacing` 命令设置字母间距（tracking）。 ```elixir Set LetterSpacing 20 ``` #### 设置行高 使用 `Set LineHeight` 命令设置行间距。 ```elixir Set LineHeight 1.8 ``` #### 设置打字速度 ```elixir Set TypingSpeed 500ms # 500ms Set TypingSpeed 1s # 1s ``` 设置每次按键的打字速度（单位为秒）。例如，打字速度为 `0.1` 时，每输入一个字符之间会有 `0.1s`（`100ms`）的延迟。 也可以按命令使用 `@` 语法覆盖此设置。 ```elixir Set TypingSpeed 0.1 Type "100ms delay per character" Type@500ms "500ms delay per character" ``` #### 设置主题 使用 `Set Theme` 命令设置终端主题。主题值应为包含 base 16 颜色以及前景色和背景色的 JSON 字符串。 ```elixir 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" } ``` 也可以按名称设置主题： ```elixir Set Theme "Catppuccin Frappe" ``` 运行 `vhs themes` 可查看完整列表，或在 [THEMES.md](./THEMES.md) 中查看。 #### 设置内边距 使用 `Set Padding` 命令设置终端边框的内边距（单位为像素）。 ```elixir Set Padding 0 ``` #### 设置外边距 使用 `Set Margin` 命令设置视频的外边距（单位为像素）。 ```elixir Set Margin 60 Set MarginFill "#6B50FF" ``` #### 设置窗口栏 使用 `Set WindowBar` 命令设置终端窗口的窗口栏类型（Colorful、ColorfulRight、Rings、RingsRight）。 ```elixir Set WindowBar Colorful ``` #### 设置圆角半径 使用 `Set BorderRadius` 命令设置终端窗口的圆角半径（单位为像素）。 ```elixir # 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 捕获帧的速率。 ```elixir Set Framerate 60 ``` #### 设置播放速度 设置最终渲染的播放速度。 ```elixir 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 的第一帧（通常用于预览）更有趣。 ```elixir Set LoopOffset 5 # Start the GIF at the 5th frame Set LoopOffset 50% # Start the GIF halfway through ``` #### Set Cursor Blink 设置光标是否闪烁。默认启用。 ```elixir Set CursorBlink false ``` ### Type 使用 `Type` 模拟按键。也就是说，你可以使用 `Type` 在终端中脚本化输入。Type 命令既适合输入命令，也适合在终端中与提示符和 TUI（终端用户界面）交互。该命令接受一个字符串参数，表示要输入的字符。 你可以通过 [`Set TypingSpeed`](#set-typing-speed) 设置标准输入速度，并在特定位置用 `@time` 参数覆盖。 ```elixir # Type something Type "Whatever you want" # Type something really slowly! Type@500ms "Slow down there, partner." ``` 用反引号转义单引号和双引号。 ```elixir Type `VAR="Escaped"` ``` ### Keys Key 命令接受可选的 `@time` 和可选的重复 `count`，用于每隔 `` 间隔重复按键。 ``` Key[@] [count] ``` #### Backspace 使用 `Backspace` 命令按下退格键。 ```elixir Backspace 18 ``` #### Ctrl 你可以通过 `Ctrl` 命令访问 Control 修饰键并发送控制序列。 ```elixir Ctrl+R ``` #### Enter 使用 `Enter` 命令按下回车键。 ```elixir Enter 2 ``` #### Arrow Keys 使用 `Up`、`Down`、`Left`、`Right` 命令按下任意方向键。 ```elixir Up 2 Down 2 Left Right Left Right Type "B" Type "A" ``` #### Tab 使用 `Tab` 命令输入制表符。 ```elixir Tab@500ms 2 ``` #### Space 使用 `Space` 命令按下空格键。 ```elixir Space 10 ``` #### Page Up / Down 使用 `PageUp` 或 `PageDown` 命令按下 Page Up / Page Down 键。 ```elixir PageUp 3 PageDown 5 ``` #### Scroll Up / Down 使用 `ScrollUp` 和 `ScrollDown` 直接滚动终端视口。两个命令都使用与其他可重复按键命令相同的可选 `@time` 和重复次数形式：`ScrollUp[@] [count]`。 ```elixir ScrollUp 10 ScrollDown 4 ScrollDown@100ms 12 ``` ### Wait `Wait` 命令允许你等待屏幕上出现某些内容。当你需要等待某事完成（即使不知道需要多久），同时又想在录制中包含它（例如旋转指示器或加载状态）时，这会很有用。该命令接受一个正则表达式作为参数，并可选择设置等待时长，以及是检查整个屏幕还是仅检查最后一行（范围）。 ```elixir Wait Wait /World/ Wait+Screen /World/ Wait+Line /World/ Wait@10ms /World/ Wait+Line@10ms /World/ ``` 默认正则表达式为 `/>$/`，等待超时为 `15s`，默认范围为 `Line`。 ### Sleep `Sleep` 命令允许你在不与终端交互的情况下继续捕获帧。当你需要等待某事完成，同时又想在录制中包含它（例如旋转指示器或加载状态）时，这会很有用。该命令接受以秒为单位的数字参数。 ```elixir Sleep 0.5 # 500ms Sleep 2 # 2s Sleep 100ms # 100ms Sleep 1s # 1s ``` ### Hide `Hide` 命令指示 VHS 停止捕获帧。适用于暂停录制以执行隐藏的命令。 ```elixir Hide ``` 该命令有助于执行录制 GIF 所需的任何设置和清理工作，例如构建二进制文件的最新版本，并在演示录制完成后删除该二进制文件。 ```elixir 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` 命令之后很有用，可恢复输出画面的帧录制。 ```elixir Hide Type "You won't see this being typed." Show Type "You will see this being typed." ``` ### Screenshot `Screenshot` 命令捕获当前帧（png 格式）。 ```elixir # At any point... Screenshot examples/screenshot.png ``` ### Copy / Paste `Copy` 和 `Paste` 从剪贴板复制和粘贴字符串。 ```elixir Copy "https://github.com/charmbracelet" Type "open " Sleep 500ms Paste ``` ### Env `Env` 命令通过键值对设置环境变量。 ```elixir Env HELLO "WORLD" Type "echo $HELLO" Enter Sleep 1s ``` ### Source `source` 命令允许你执行来自另一条 tape 的命令。 ```elixir Source config.tape ``` --- ## Continuous Integration 你可以将 VHS 接入 CI 流水线，通过官方 VHS GitHub Action 保持 GIF 与代码同步更新： > [⚙️ charmbracelet/vhs-action](https://github.com/charmbracelet/vhs-action) VHS 也可用于集成测试。使用 `.txt` 或 `.ascii` 的输出 来生成黄金文件（golden files）。将这些文件存放在 git 仓库中，以确保 多次运行磁带文件时不会出现 diff。 ```elixir Output golden.ascii ``` ## 语法高亮 面向支持 tree-sitter 语法高亮的编辑器，现已提供 `.tape` 文件的 tree-sitter 语法： > [🌳 charmbracelet/tree-sitter-vhs](https://github.com/charmbracelet/tree-sitter-vhs) 在 Neovim、Emacs 等编辑器中效果很好！ ## 参与贡献 请参阅 [参与贡献][contribute]。 [contribute]: https://github.com/charmbracelet/vhs/contribute ## 反馈 我们很想听听你对本项目的想法。欢迎随时给我们留言！ - [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