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文件
为文档创建终端演示
配置CI/CD实现GIF自动生成
优化录制文件的大小和质量
排查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	配置结构	CRITICAL	`config-`
2	依赖管理	CRITICAL	`deps-`
3	命令语法	HIGH	`cmd-`
4	时序与同步	HIGH	`timing-`
5	输出优化	MEDIUM-HIGH	`output-`
6	视觉质量	MEDIUM	`visual-`
7	CI/自动化	MEDIUM	`ci-`
8	高级模式	LOW	`advanced-`

Quick Reference

快速参考

1. Configuration Structure (CRITICAL)

1. 配置结构（CRITICAL）

```
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
```
- 提前设置全局TypingSpeed
```
config-dimensions-explicit
```
- 设置明确的终端尺寸
```
config-comments-document
```
- 使用注释说明tape文件结构

2. Dependency Management (CRITICAL)

2. 依赖管理（CRITICAL）

```
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. 命令语法（HIGH）

```
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. 时序与同步（HIGH）

```
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
```
- 局部覆盖TypingSpeed突出重点
```
timing-sleep-units
```
- 使用明确的时间单位
```
timing-final-sleep
```
- 录制末尾添加最终Sleep
```
timing-natural-pauses
```
- 在操作之间添加自然停顿
```
timing-wait-timeout
```
- 设置合理的Wait超时时间
```
timing-playback-speed
```
- 使用PlaybackSpeed做最终播放速度调整

5. Output Optimization (MEDIUM-HIGH)

5. 输出优化（MEDIUM-HIGH）

```
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. 视觉质量（MEDIUM）

```
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/自动化（MEDIUM）

```
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. 高级模式（LOW）

```
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

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

章节定义 - 类别结构和影响等级说明
规则模板 - 新增规则的模板

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	版本和参考信息