vhs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Charmbracelet VHS Best Practices

Charmbracelet VHS 终端录制最佳实践

Comprehensive best practices guide for VHS terminal recordings, maintained by Charmbracelet. Contains 47 rules across 8 categories, prioritized by impact to guide creation of professional, portable, and optimized terminal demos.

这是由Charmbracelet维护的VHS终端录制综合最佳实践指南。包含8个类别共47条规则，按影响优先级排序，指导你创建专业、可移植且经过优化的终端演示。

When to Apply

适用场景

Reference these guidelines when:

Writing new VHS tape files
Creating terminal demos for documentation
Setting up CI/CD for automated GIF generation
Optimizing recording file size and quality
Troubleshooting tape file issues
Reviewing tape files for best practices

参考本指南的场景包括：

编写新的VHS tape文件
为文档创建终端演示
搭建用于自动生成GIF的CI/CD流程
优化录制文件的大小和质量
排查tape文件问题
审核tape文件是否符合最佳实践

Rule Categories by Priority

按优先级划分的规则类别


config-
deps-
cmd-
timing-
output-
visual-
ci-
advanced-

Priority	Category	Impact	Prefix
1	Configuration Structure	CRITICAL	`config-`
2	Dependency Management	CRITICAL	`deps-`
3	Command Syntax	HIGH	`cmd-`
4	Timing & Synchronization	HIGH	`timing-`
5	Output Optimization	MEDIUM-HIGH	`output-`
6	Visual Quality	MEDIUM	`visual-`
7	CI/Automation	MEDIUM	`ci-`
8	Advanced Patterns	LOW	`advanced-`


config-
deps-
cmd-
timing-
output-
visual-
ci-
advanced-

优先级	类别	影响程度	前缀
1	配置结构	关键	`config-`
2	依赖管理	关键	`deps-`
3	命令语法	高	`cmd-`
4	时序与同步	高	`timing-`
5	输出优化	中高	`output-`
6	视觉质量	中	`visual-`
7	CI/自动化	中	`ci-`
8	高级模式	低	`advanced-`

Quick Reference

快速参考

1. Configuration Structure (CRITICAL)

1. 配置结构（关键）

```
config-settings-order
```
- Place all settings before commands
```
config-output-first
```
- Declare output at file start
```
config-shell-explicit
```
- Explicitly set shell type
```
config-typing-speed-global
```
- Set global TypingSpeed early
```
config-dimensions-explicit
```
- Set explicit terminal dimensions
```
config-comments-document
```
- Use comments to document tape structure

```
config-settings-order
```
- 所有配置项需置于命令之前
```
config-output-first
```
- 在文件开头声明输出配置
```
config-shell-explicit
```
- 明确设置Shell类型
```
config-typing-speed-global
```
- 尽早设置全局打字速度
```
config-dimensions-explicit
```
- 设置明确的终端尺寸
```
config-comments-document
```
- 使用注释说明tape文件结构

2. Dependency Management (CRITICAL)

2. 依赖管理（关键）

```
deps-require-early
```
- Use Require for dependency validation
```
deps-require-order
```
- Place Require before settings
```
deps-require-all
```
- Require all external commands
```
deps-system-requirements
```
- Verify system dependencies

```
deps-require-early
```
- 使用Require验证依赖项
```
deps-require-order
```
- 将Require置于配置项之前
```
deps-require-all
```
- 声明所有外部命令依赖
```
deps-system-requirements
```
- 验证系统依赖项

3. Command Syntax (HIGH)

3. 命令语法（高）

```
cmd-type-syntax
```
- Use correct Type command syntax
```
cmd-enter-explicit
```
- Always follow Type with Enter
```
cmd-key-repeat
```
- Use key repeat counts
```
cmd-ctrl-combinations
```
- Use Ctrl combinations for terminal control
```
cmd-hide-show
```
- Use Hide/Show for sensitive operations
```
cmd-env-variables
```
- Use Env for environment variables
```
cmd-screenshot
```
- Use Screenshot for static captures
```
cmd-multiline-type
```
- Handle multiline commands properly

```
cmd-type-syntax
```
- 使用正确的Type命令语法
```
cmd-enter-explicit
```
- 始终在Type命令后添加Enter
```
cmd-key-repeat
```
- 使用按键重复计数
```
cmd-ctrl-combinations
```
- 使用Ctrl组合键控制终端
```
cmd-hide-show
```
- 对敏感操作使用Hide/Show命令
```
cmd-env-variables
```
- 使用Env设置环境变量
```
cmd-screenshot
```
- 使用Screenshot进行静态捕获
```
cmd-multiline-type
```
- 正确处理多行命令

4. Timing & Synchronization (HIGH)

4. 时序与同步（高）

```
timing-sleep-after-enter
```
- Add Sleep after commands for output
```
timing-wait-pattern
```
- Use Wait for dynamic command completion
```
timing-type-speed-override
```
- Override TypingSpeed for emphasis
```
timing-sleep-units
```
- Use explicit time units
```
timing-final-sleep
```
- End recordings with final Sleep
```
timing-natural-pauses
```
- Add natural pauses between actions
```
timing-wait-timeout
```
- Set appropriate Wait timeouts
```
timing-playback-speed
```
- Use PlaybackSpeed for final adjustments

```
timing-sleep-after-enter
```
- 命令执行后添加Sleep等待输出
```
timing-wait-pattern
```
- 使用Wait等待动态命令完成
```
timing-type-speed-override
```
- 临时覆盖打字速度以突出重点
```
timing-sleep-units
```
- 使用明确的时间单位
```
timing-final-sleep
```
- 录制结尾添加最终Sleep
```
timing-natural-pauses
```
- 在操作之间添加自然停顿
```
timing-wait-timeout
```
- 设置合适的Wait超时时间
```
timing-playback-speed
```
- 使用PlaybackSpeed进行最终调整

5. Output Optimization (MEDIUM-HIGH)

5. 输出优化（中高）

```
output-format-selection
```
- Choose output format based on use case
```
output-framerate
```
- Optimize framerate for file size
```
output-dimensions-optimize
```
- Right-size terminal dimensions
```
output-loop-offset
```
- Use LoopOffset for seamless loops
```
output-multiple-formats
```
- Generate multiple output formats
```
output-relative-paths
```
- Use relative paths for portability

```
output-format-selection
```
- 根据使用场景选择输出格式
```
output-framerate
```
- 优化帧率以减小文件大小
```
output-dimensions-optimize
```
- 合理设置终端尺寸
```
output-loop-offset
```
- 使用LoopOffset实现无缝循环
```
output-multiple-formats
```
- 生成多种输出格式
```
output-relative-paths
```
- 使用相对路径提升可移植性

6. Visual Quality (MEDIUM)

6. 视觉质量（中）

```
visual-font-readable
```
- Choose readable font settings
```
visual-theme-selection
```
- Select appropriate theme
```
visual-window-decoration
```
- Add window decorations for polish
```
visual-spacing
```
- Adjust letter and line spacing
```
visual-padding-margin
```
- Use padding and margins effectively
```
visual-cursor-visibility
```
- Ensure cursor visibility

```
visual-font-readable
```
- 选择易读的字体设置
```
visual-theme-selection
```
- 选择合适的主题
```
visual-window-decoration
```
- 添加窗口装饰提升精致度
```
visual-spacing
```
- 调整字符和行间距
```
visual-padding-margin
```
- 有效使用内边距和外边距
```
visual-cursor-visibility
```
- 确保光标可见

7. CI/Automation (MEDIUM)

7. CI/自动化（中）

```
ci-github-action
```
- Use official VHS GitHub Action
```
ci-auto-commit
```
- Auto-commit generated assets
```
ci-golden-files
```
- Use golden files for integration testing
```
ci-matrix-builds
```
- Generate platform-specific demos
```
ci-caching
```
- Cache VHS dependencies in CI

```
ci-github-action
```
- 使用官方VHS GitHub Action
```
ci-auto-commit
```
- 自动提交生成的资源文件
```
ci-golden-files
```
- 使用基准文件进行集成测试
```
ci-matrix-builds
```
- 生成特定平台的演示
```
ci-caching
```
- 在CI中缓存VHS依赖项

8. Advanced Patterns (LOW)

8. 高级模式（低）

```
advanced-source-include
```
- Use Source for reusable tape components
```
advanced-clipboard
```
- Use Copy and Paste for complex input
```
advanced-recording-live
```
- Record live sessions then edit
```
advanced-server-mode
```
- Use server mode for remote access

```
advanced-source-include
```
- 使用Source引入可复用的tape组件
```
advanced-clipboard
```
- 使用Copy和Paste处理复杂输入
```
advanced-recording-live
```
- 先录制实时会话再进行编辑
```
advanced-server-mode
```
- 使用服务器模式实现远程访问

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

Section definitions - 类别结构和影响级别说明
Rule template - 添加新规则的模板

Reference Files

参考文件

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义和排序说明
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息