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

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