product-video
実際の画面録画 + イベントログ -> 宣言的計画 (YAML) -> pvk render -> コンタクトシート -> 最終出力。
スクリプトはタイミング、ズーム、オーバーレイ、オーディオを処理します。あなたはストーリーボードを書き、計画を記述し、フレームを確認します。
PVK=~/.claude/skills/product-video/bin/pvk # または `pip install -e ~/.claude/skills/product-video` 後に `pvk`
使用タイミング
| ユーザーが望むもの | 作成するもの | 最初に読むもの |
|---|---|---|
| ユーザーに機能やアプリ全体を学んでほしい（「ビデオ hướng dẫn」、チュートリアル、オンボーディング） | チュートリアル：1〜3分のチャプター、その後 pvk join | references/storyboard.md |
| 製品やリリースへの注目を集めたい（「ビデオ quảng cáo」、プロモ、ローンチ、ティーザー） | プロモ：ビートに合わせた30〜45秒の16:9カット | references/storyboard.md |
| 短いWebアプリのデモやバグ再現クリップ | web-videoスキルのみ | - |
厳格なルール
- 実際のアプリ、サンプルデータ。 実際の製品を、現実的で架空のサンプルデータを使って撮影します。モックアップは使用せず、実際の顧客データ、シークレット、本番アカウントは絶対に使用しないでください（
references/privacy.md）。 - まずストーリーボード、次に承認。 ストーリーボードを平易な言葉で書き、撮影前に承認を得てください。
- プロジェクトのデザイン。 プロジェクトで
theme initを実行し、結果をデザインガイドと照合してください。 - 音楽と効果音は必須。 すべての動画にBGMとUIサウンドを付け、-16 LUFSでマスタリングします。
- 下書き、確認、そして最終版。
--draft --checkでレンダリングし、すべてのコンタクトシートを開き、修正してから--finalを実行します。 - オーナーの承諾なしに、マシンの外に出してはならない（アップロード、投稿、課題への添付）。
- セキュリティ、キーチェーン、サインインダイアログを操作してはならない。 それらはユーザーに任せてください。
ステップ0. セットアップ（マシンごとに1回）
$PVK doctor # ffmpeg、Python 3.11+、パッケージ、Chromium、フォント、オプションツール
python3 -m pip install -r ~/.claude/skills/product-video/requirements.txt && python3 -m playwright install chromium
$PVK fonts # Inter、Playfair Display、JetBrains Mono（OFL）を ~/.cache/product-video にダウンロード
$PVK sfx gen && $PVK music beds
$PVK selftest # バンドルされたデモから短いチャプターとプロモをレンダリング（約1分）
不足しているツール：インストールコマンドを表示して確認を取ってください。自動でインストールしないでください。
ステップ1. プロジェクトからテーマを作成
cd <video-folder> # 例: <project>/video（出力をgitの管理外に）
$PVK theme init --repo <project> --out theme.json
$PVK fonts --theme theme.json
$PVK overlay chapter title="プレビュー" --theme theme.json --out preview.png # 確認
デザインガイドがさらに指示する場合（references/theme.md）、theme.jsonの色、フォント、brand、logoを手動で修正します。
ステップ2. ストーリーボード
チュートリアル：ユーザーが学ぶ必要のあるタスクごとに1チャプター。各チャプター＝チャプターカード、3〜8個の番号付きキャプションを含む映像、リキャップカード。プロモ：5〜8個のハイライト、それぞれ短いヘッドラインカード＋2〜4秒の映像モーメント、エンドカード。表（時間、画面、キャプション、音）として書き、承認を得てください。詳細：references/storyboard.md。
ステップ3. キャプチャ
| 製品 | 方法 |
|---|---|
| ネイティブmacOSアプリ | scene.py を作成（examples/scene_native.py 参照）、次に $PVK capture native scene.py --app "アプリ名" --out takes/s1 --rehearse、その後 --rehearse なしで実行 |
| Webアプリ | web-videoで録画（record.py --slug x）、次に $PVK capture import video-out/x/v1 --name w1 |
| その他 | takes/<name>/ に raw.mp4 と events.json（references/plan-format.md 参照）を配置 |
| まだアプリがない/試しているだけ | $PVK demo --out takes/demo |
各テイクの前に：サンプルデータをロードし、通知をオフにし（おやすみモード）、古いトーストを閉じ、ウィンドウサイズを固定します。
各テイクの後：$PVK check popups takes/s1 と $PVK check grab takes/s1 grab.png 1 5 9 で確認します。
macOSの落とし穴（Mission Controlキー、CmdとCtrl、実際のポインター、HUD）：references/pitfalls.md。
ステップ4. 計画
examples/tutorial.yaml または examples/promo.yaml をテイクの隣にコピーして編集します。映像クリップの時間は、テイクのevents.jsonからのソース秒です。ボックスはソースピクセルです。完全な形式：references/plan-format.md。
$PVK render ch01.yaml --only-plan # 高速：out/plan/ch01.md にすべてのクリップ、キャプション、ズーム、サウンド、警告がリストされます
すべての警告（短いキャプション、重複、ズームにまたがるコールアウト、2桁のステップ番号）を修正します。
ステップ5. 下書きと確認
$PVK render ch01.yaml --draft --check # 720p；out/drafts/ch01.mp4 + out/check/ch01/contact-*.png
$PVK render ch01.yaml --frames 3.2,7.5 # 出力時刻の静止画、詳細確認用
$PVK promo promo.yaml --draft --check # プロモ：同じエンジン、ビートグリッドにスナップされたカット
すべてのコンタクトシートを開きます（PNGを読んでください）。確認項目：キャプションが読みやすく、アクションを覆い隠していないか、ズームが正しい位置にあるか、OSのポップアップや残ったトーストがないか、カーソルがクリック位置にあるか、カードのスペルが正しいか、ラウドネスが約-16 LUFSか。修正は最大3回のパスまで。その後、下書きとシートをユーザーに見せます。
ステップ6. 最終版と完全カット
$PVK render ch01.yaml --final # 1080p、out/final/ch01.mp4
$PVK join out/final/tutorial.mp4 out/final/ch0*.mp4
$PVK check out/final/tutorial.mp4
レポート：ファイルパス、長さ、ラウドネス、確認できなかったこと（ミックスは聞き取れないため、その旨を伝えてください）。
音楽とサウンド
music: bed:soft-piano | bed:ambient | bed:promo は合成BGM（自作、無料）。ライセンス曲の場合：$PVK music fetch（入手先）、その後 $PVK music add track.mp3 --title ... --author ... --source URL --license ...（-20 LUFSに正規化、music/LICENSES.md に記録）。サードパーティのトラックをコミットしないでください。
SFXマップ、ダッキング、ラウドネス：references/audio.md。
参考文献
references/storyboard.md：チュートリアルとプロモの違い、チャプター構成、キャプションの書き方、ビートカットreferences/plan-format.md：すべての計画キー、events.jsonの形式、タイムライン計算references/theme.md：theme.json、theme init、フォント（OFL）、ロゴreferences/audio.md：BGM、ライセンス曲、SFXマップ、ラウドネス目標references/capture.md：ネイティブmacOSキャプチャ、web-videoインポート、テイクのレイアウトreferences/pitfalls.md：実際のプロジェクトで起こったすべての問題とその修正references/privacy.md：データと共有ルール