vhs

# 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 | 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-` | ## Quick Reference ### 1. Configuration Structure (CRITICAL) - [`config-settings-order`](references/config-settings-order.md) - Place all settings before commands - [`config-output-first`](references/config-output-first.md) - Declare output at file start - [`config-shell-explicit`](references/config-shell-explicit.md) - Explicitly set shell type - [`config-typing-speed-global`](references/config-typing-speed-global.md) - Set global TypingSpeed early - [`config-dimensions-explicit`](references/config-dimensions-explicit.md) - Set explicit terminal dimensions - [`config-comments-document`](references/config-comments-document.md) - Use comments to document tape structure ### 2. Dependency Management (CRITICAL) - [`deps-require-early`](references/deps-require-early.md) - Use Require for dependency validation - [`deps-require-order`](references/deps-require-order.md) - Place Require before settings - [`deps-require-all`](references/deps-require-all.md) - Require all external commands - [`deps-system-requirements`](references/deps-system-requirements.md) - Verify system dependencies ### 3. Command Syntax (HIGH) - [`cmd-type-syntax`](references/cmd-type-syntax.md) - Use correct Type command syntax - [`cmd-enter-explicit`](references/cmd-enter-explicit.md) - Always follow Type with Enter - [`cmd-key-repeat`](references/cmd-key-repeat.md) - Use key repeat counts - [`cmd-ctrl-combinations`](references/cmd-ctrl-combinations.md) - Use Ctrl combinations for terminal control - [`cmd-hide-show`](references/cmd-hide-show.md) - Use Hide/Show for sensitive operations - [`cmd-env-variables`](references/cmd-env-variables.md) - Use Env for environment variables - [`cmd-screenshot`](references/cmd-screenshot.md) - Use Screenshot for static captures - [`cmd-multiline-type`](references/cmd-multiline-type.md) - Handle multiline commands properly ### 4. Timing & Synchronization (HIGH) - [`timing-sleep-after-enter`](references/timing-sleep-after-enter.md) - Add Sleep after commands for output - [`timing-wait-pattern`](references/timing-wait-pattern.md) - Use Wait for dynamic command completion - [`timing-type-speed-override`](references/timing-type-speed-override.md) - Override TypingSpeed for emphasis - [`timing-sleep-units`](references/timing-sleep-units.md) - Use explicit time units - [`timing-final-sleep`](references/timing-final-sleep.md) - End recordings with final Sleep - [`timing-natural-pauses`](references/timing-natural-pauses.md) - Add natural pauses between actions - [`timing-wait-timeout`](references/timing-wait-timeout.md) - Set appropriate Wait timeouts - [`timing-playback-speed`](references/timing-playback-speed.md) - Use PlaybackSpeed for final adjustments ### 5. Output Optimization (MEDIUM-HIGH) - [`output-format-selection`](references/output-format-selection.md) - Choose output format based on use case - [`output-framerate`](references/output-framerate.md) - Optimize framerate for file size - [`output-dimensions-optimize`](references/output-dimensions-optimize.md) - Right-size terminal dimensions - [`output-loop-offset`](references/output-loop-offset.md) - Use LoopOffset for seamless loops - [`output-multiple-formats`](references/output-multiple-formats.md) - Generate multiple output formats - [`output-relative-paths`](references/output-relative-paths.md) - Use relative paths for portability ### 6. Visual Quality (MEDIUM) - [`visual-font-readable`](references/visual-font-readable.md) - Choose readable font settings - [`visual-theme-selection`](references/visual-theme-selection.md) - Select appropriate theme - [`visual-window-decoration`](references/visual-window-decoration.md) - Add window decorations for polish - [`visual-spacing`](references/visual-spacing.md) - Adjust letter and line spacing - [`visual-padding-margin`](references/visual-padding-margin.md) - Use padding and margins effectively - [`visual-cursor-visibility`](references/visual-cursor-visibility.md) - Ensure cursor visibility ### 7. CI/Automation (MEDIUM) - [`ci-github-action`](references/ci-github-action.md) - Use official VHS GitHub Action - [`ci-auto-commit`](references/ci-auto-commit.md) - Auto-commit generated assets - [`ci-golden-files`](references/ci-golden-files.md) - Use golden files for integration testing - [`ci-matrix-builds`](references/ci-matrix-builds.md) - Generate platform-specific demos - [`ci-caching`](references/ci-caching.md) - Cache VHS dependencies in CI ### 8. Advanced Patterns (LOW) - [`advanced-source-include`](references/advanced-source-include.md) - Use Source for reusable tape components - [`advanced-clipboard`](references/advanced-clipboard.md) - Use Copy and Paste for complex input - [`advanced-recording-live`](references/advanced-recording-live.md) - Record live sessions then edit - [`advanced-server-mode`](references/advanced-server-mode.md) - Use server mode for remote access ## How to Use Read individual reference files for detailed explanations and code examples: - [Section definitions](references/_sections.md) - Category structure and impact levels - [Rule template](assets/templates/_template.md) - Template for adding new rules ## Reference Files | File | Description | |------|-------------| | [AGENTS.md](AGENTS.md) | Complete compiled guide with all rules | | [references/_sections.md](references/_sections.md) | Category definitions and ordering | | [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules | | [metadata.json](metadata.json) | Version and reference information |