vhs

Charmbracelet VHS のベストプラクティス

Charmbracelet が管理する、VHS のターミナル録画に関する包括的なベストプラクティスガイドです。プロフェッショナルで、移植性と最適化に優れたターミナルデモを作成できるよう、影響度に基づいて優先順位を付けた 8 カテゴリー、47 のルールを収録しています。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• 新しい VHS テープファイルを作成するとき
• ドキュメント用のターミナルデモを作成するとき
• GIF 生成を自動化する CI/CD を設定するとき
• 録画のファイルサイズと品質を最適化するとき
• テープファイルの問題をトラブルシューティングするとき
• ベストプラクティスに沿っているかテープファイルを確認するとき

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス
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-

クイックリファレンス

1. 設定構造（CRITICAL）

• config-settings-order - すべての設定をコマンドより前に配置します
• config-output-first - ファイルの先頭で出力先を宣言します
• config-shell-explicit - シェルの種類を明示的に設定します
• config-typing-speed-global - グローバルな TypingSpeed を早い段階で設定します
• config-dimensions-explicit - ターミナルのサイズを明示的に設定します
• config-comments-document - コメントを使ってテープの構成を記述します

2. 依存関係の管理（CRITICAL）

• deps-require-early - 依存関係の検証に Require を使用します
• deps-require-order - Require を設定より前に配置します
• deps-require-all - 外部コマンドをすべて Require します
• deps-system-requirements - システムの依存関係を確認します

3. コマンド構文（HIGH）

• 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. タイミングと同期（HIGH）

• 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-format-selection - 用途に応じて出力形式を選択する
• output-framerate - ファイルサイズに合わせてフレームレートを最適化する
• output-dimensions-optimize - ターミナルのサイズを適切に調整する
• output-loop-offset - LoopOffset を使って継ぎ目のないループを作成する
• output-multiple-formats - 複数の出力形式を生成する
• output-relative-paths - 移植性を高めるため相対パスを使用する

6. ビジュアル品質（中）

• visual-font-readable - 読みやすいフォント設定を選択する
• visual-theme-selection - 適切なテーマを選択する
• visual-window-decoration - 仕上がりを高めるためウィンドウ装飾を追加する
• visual-spacing - 文字間隔と行間を調整する
• visual-padding-margin - パディングとマージンを効果的に使用する
• visual-cursor-visibility - カーソルが見えるようにする

7. CI／自動化（中）

• ci-github-action - 公式の VHS GitHub Action を使用する
• ci-auto-commit - 生成したアセットを自動コミットする
• ci-golden-files - 統合テストにゴールデンファイルを使用する
• ci-matrix-builds - プラットフォーム固有のデモを生成する
• ci-caching - CI で VHS の依存関係をキャッシュする

8. 高度なパターン（低）

• advanced-source-include - 再利用可能なテープコンポーネントに Source を使用する
• advanced-clipboard - 複雑な入力に Copy と Paste を使用する
• advanced-recording-live - ライブセッションを録画してから編集する
• advanced-server-mode - リモートアクセスにサーバーモードを使用する

使い方

詳しい説明とコード例については、各リファレンスファイルを参照してください。

• セクションの定義 - カテゴリーの構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールをまとめた完全なガイド
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報