CLI Demo Generator

プロフェッショナルなアニメーション化された CLI デモを作成します。完全自動から画素単位の手動制御まで、4 つのアプローチから選択できます。

クイックスタート

最もシンプルな方法 — コマンドを指定すれば GIF が得られます:

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif

自己ブートストラップデモ — 状態を自動的にクリーンアップする繰り返し可能なレコーディング:

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif \
  --bootstrap "npm uninstall my-package 2>/dev/null" \
  --speed 2

重要: VHS パーサーの制限事項

VHS の Type 文字列には $、\"、またはバッククォートを含めることはできません。これらはパースエラーを引き起こします:

# 失敗 — VHS パーサーが特殊文字を拒否
Type "echo \"hello $USER\""
Type "claude() { command claude \"$@\"; }"

回避策: コマンドを base64 エンコードして、実行時にデコード:

# 1. 複雑なコマンドをエンコード
echo 'claude() { command claude "$@" 2>&1 | grep -v "noise"; }' | base64
# 出力: Y2xhdWRlKCkgey4uLn0K

# 2. テープで使用
Type "echo Y2xhdWRlKCkgey4uLn0K | base64 -d > /tmp/wrapper.sh && source /tmp/wrapper.sh"

このパターンは出力フィルタリング、関数定義、シェルの特殊文字を含むあらゆるコマンドに不可欠です。

アプローチ

1. 自動生成 (推奨)

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "command1" -c "command2" \
  -o output.gif \
  --title "My Demo" \
  --theme "Catppuccin Latte" \
  --font-size 24 \
  --width 1400 --height 600

フラグ	デフォルト	説明
-c	必須	含めるコマンド (繰り返し可能)
-o	必須	出力 GIF パス
--title	なし	開始時に表示されるタイトル
--theme	Dracula	VHS テーマ名
--font-size	16	フォントサイズ (ポイント)
--width	1400	ターミナル幅 (ピクセル)
--height	700	ターミナル高さ (ピクセル)
--bootstrap	なし	隠されたセットアップコマンド (繰り返し可能)
--filter	なし	出力から削除する正規表現パターン
--speed	1	再生速度倍率 (gifsicle を使用)
--no-execute	false	.tape のみを生成

スマートなタイミング: install/build/test/deploy → 3 秒、ls/pwd/echo → 1 秒、その他 → 2 秒。

2. バッチ生成

1 つの設定から複数のデモを生成:

# demos.yaml
demos:
  - name: "Install"
    output: "install.gif"
    commands: ["npm install my-package"]
  - name: "Usage"
    output: "usage.gif"
    commands: ["my-package --help", "my-package run"]

python3 ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py demos.yaml --output-dir ./gifs

3. インタラクティブ記録

ライブターミナルセッションを記録:

bash ${CLAUDE_SKILL_DIR}/scripts/record_interactive.sh output.gif --theme "Catppuccin Latte"
# 自然にコマンドを入力し、完了時に Ctrl+D

asciinema が必要です (brew install asciinema)。

4. 手動テープファイル

最大限の制御のため、テープを直接作成します。テンプレートは assets/templates/ にあります:

• basic.tape — シンプルなコマンド シーケンス
• interactive.tape — タイピング シミュレーション
• self-bootstrap.tape — 隠されたセットアップで自動クリーニングするデモ (繰り返し可能なデモに推奨)

高度なパターン

これらのパターンは本番環境での使用に基づいています。詳細は references/advanced_patterns.md を参照してください。

自己ブートストラップデモ

前の状態をクリーンアップし、環境をセットアップし、すべてを視聴者から隠すデモ:

Hide
Type "cleanup-previous-state 2>/dev/null"
Enter
Sleep 2s
Type "clear"
Enter
Sleep 500ms
Show

Type "the-command-users-see"
Enter
Sleep 3s

Hide → コマンド → clear → Show のシーケンスが重要です。clear はターミナルバッファをワイプして、隠されたコマンドが GIF に漏れないようにします。

出力ノイズフィルタリング

冗長な出力を生成するコマンドからノイズの多い行をフィルタリング:

# 隠された部分: ノイズをフィルタリングするラッパー関数を作成
Hide
Type "echo <base64-encoded-wrapper> | base64 -d > /tmp/w.sh && source /tmp/w.sh"
Enter
Sleep 500ms
Type "clear"
Enter
Sleep 500ms
Show

# 表示される部分: クリーンコマンド、フィルタリングされた出力
Type "my-noisy-command"
Enter
Sleep 3s

フレーム検証

記録後、キーフレームを抽出して GIF コンテンツを検証:

# 特定の位置でフレームを抽出
ffmpeg -i demo.gif -vf "select=eq(n\,100)" -frames:v 1 /tmp/frame.png -y 2>/dev/null

# フレームを表示 (Claude が画像を読み込める)
# /tmp/frame.png で Read ツールを使用してコンテンツを検証

後処理スピードアップ

再記録なしで gifsicle を使用してレコーディングをスピードアップ:

# 2 倍速 (フレーム遅延を半減)
gifsicle -d2 original.gif "#0-" > fast.gif

# 1.5 倍速
gifsicle -d4 original.gif "#0-" > faster.gif

テンプレートプレースホルダーパターン

テープファイルをプレースホルダーで汎用的に保ち、ビルド時に置換:

# テープファイル内
Type "claude plugin marketplace add MARKETPLACE_REPO"

# ビルドスクリプト内
sed "s|MARKETPLACE_REPO|$DETECTED_REPO|g" template.tape > rendered.tape
vhs rendered.tape

タイミングとサイジング リファレンス

コンテキスト	幅	高さ	フォント	期間
README/ドキュメント	1400	600	16-20	10-20 秒
プレゼンテーション	1800	900	24	15-30 秒
コンパクト埋め込み	1200	600	14-16	10-15 秒
ワイド出力	1600	800	16	15-30 秒

詳細なガイドラインについては references/best_practices.md を参照してください。

トラブルシューティング

問題	解決方法
VHS がインストールされていない	brew install charmbracelet/tap/vhs
gifsicle がインストールされていない	brew install gifsicle
GIF が大きすぎる	サイズを縮小するか、スリープ時間を短縮するか、--speed 2 を使用
テキストが折り返される/改行される	--width を増加させるか、--font-size を減少させる
$ または \" で VHS パースエラー	base64 エンコーディングを使用 (上記の重要セクション参照)
隠されたコマンドが GIF に漏れる	Show の前に clear + Sleep 500ms を追加
コマンドが前のコマンド終了前に実行される	Sleep の期間を増加させる

依存関係

必須: VHS (brew install charmbracelet/tap/vhs)

オプション: gifsicle (スピードアップ)、asciinema (インタラクティブ記録)、ffmpeg (フレーム検証)、PyYAML (バッチ YAML 設定)