Charmbracelet VHS Best Practices

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.

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

Rule Categories by Priority

config-

deps-

cmd-

timing-

output-

visual-

ci-

advanced-

Quick Reference

1. Configuration Structure (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

2. Dependency Management (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

3. Command Syntax (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

4. Timing & Synchronization (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

5. Output Optimization (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

6. Visual Quality (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

7. CI/Automation (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

8. Advanced Patterns (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

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