ウォークスルー動画は何をしますか？

実行中のWebアプリを、アプリが変更されるたびに再生成可能なナレーション付き動画に変換します。すべてローカルで動作し、ビデオ編集ソフトや有料サービスは不要です。

ナレーションテキスト -> ローカル音声 -> シーンごとにWAV＋キャプションタイミング
実際のアプリ -> Playwrightシーン -> クリップ＋マーカー時刻 -> assemble.py -> walkthrough.mp4 + .srt

この方式が有効な理由：映像は実際のアプリなので常に正確です。AI応答やページ読み込みなどの遅いステップは録画中にカットされます。各シーンで記録される「マーカー」により、アセンブラがキーモーメントを対応するナレーションに合わせることができます。

開始前の準備

不足している情報のみを質問してください：アプリの内容、動画で見せたいこと、視聴者、目標時間（2〜4分が最適）、トーン。
ツールを確認してください（詳細は references/setup.md）：Node 20+、Playwright（Chromium）、FFmpeg（xfade、zoompan、loudnorm、libx264対応）、Python 3.11 または 3.12（kokoro-onnx）。音声ファイル（約350 MB）はリポジトリ外（例：~/video-tools）にインストールします。

作業ファイルをユーザーのプロジェクトにコピーし、生成された出力をgitの管理下から除外します：

mkdir -p e2e/video-kit && cp -R <this skill>/scripts/. e2e/video-kit/ && cp <this skill>/templates/*.mjs e2e/video-kit/
printf '\ne2e/video-kit/clips/\ne2e/video-kit/vo/\ne2e/video-kit/build/\ne2e/video-kit/*.mp4\ne2e/video-kit/*.srt\ne2e/video-kit/spec.json\ne2e/video-kit/.*.json\n' >> .gitignore

スクリプトは自身の出力を自身の隣に書き出すため、ここから実行するのではなくコピーします。

references/toolkit-api.md を一度読んでください。レコーダーヘルパーと PLAN 構文について説明されています。rec.mjs、speak.py、overlays.mjs、assemble.py は書き換えないでください。ガイドが指定する部分のみを編集します。

ワークフロー：3つのゲート

各ゲートで停止し、ユーザーを待ちます。文言と構成は録画前に変更するのは簡単ですが、録画後は高くつきます。

ゲート1：ストーリーボード。 プロジェクト（ドキュメント、ルート、既存のPlaywrightテスト）を確認し、8〜12のシーンを提案します。各シーンについて：何が画面に表示されるか、ナレーション（20〜35語、平易）、どのように録画するかを示します。ユーザーがコンテキストを必要とする場合（問題、実施または監査したこと、ソリューションとスタック）は、オープニングスライドを含めます。アプリが実際に行わないことを説明しないでください。不明な場合は質問します。

ゲート2：文言と音声。 chunks.txt を scene|text 行として、各行（1行が1つのキャプションになります）を約12語以内で記述します。speak.py の PRONOUNCE に製品名や略語を追加します。python speak.py を実行し、各シーンの長さを報告します。ユーザーが確認して承認するまで録画しません。

ゲート3：録画、アセンブル、確認。

scenes.mjs にシーンを記述します（scenes.template.mjs から開始）。1クリップ1シーンで、デフォルトの計画に合わせて scene-N と命名します。1シーンずつバックグラウンドで録画します：node scenes.mjs <name>。失敗したものだけを再録画します。
スライドを使用する場合はレンダリングします（slides.template.mjs）。次に assemble.py の PLAN と LABEL を記述します：どのクリップがどのシーンで表示されるか、どのマーカーがどのナレーション行に対応するか。
python assemble.py all を実行します。walkthrough.mp4 と walkthrough.srt が書き出されます。
コンタクトシート（シーンごとに1〜2フレームをタイル状に並べたもの）で結果を確認します（個別の画像を多数確認するよりも効率的です）。名前、日付、キャプション、カットオフ、プライベート情報がないことを確認します。修正、再アセンブル、納品します。

重要なルール

プライバシー。 デモまたはテストアカウントを使用します。実際の人物、メールアドレス、電話番号、アカウント名、キー、ID、トークン、請求情報が表示される場合はぼかしまたはカバーします（opts.cover、opts.init）。パスワードは絶対に扱わないでください。ログインが必要なシーンでは、ユーザーに可視ブラウザで手動で1回サインインしてもらい（templates/auth.template.mjs）、保存されたセッションを再利用します。パスワードや2FAコードをカメラに表示したり入力したりしないでください。.env、保存済みログイン、ブラウザプロファイルをgitの管理下に置かないでください。
実際のアカウントで操作しないでください。 実際のアカウントで送信、公開、スケジュール設定、削除を行うボタンは決してクリックしないでください。ボタンの上にマウスをホバーして、その機能を説明します。
存在しない機能を説明しないでください。 コードと実際に動作するアプリが行うことだけを説明します。
音声とマイク音声はブラウザでキャプチャできません。 インターフェースを表示し、何が起こるかを説明します。
サーバーを起動する前にポートを確認し、起動したものは停止してください。 1分以上かかる処理（録画、音声、アセンブル）はバックグラウンドで実行し、ループでポーリングするのではなく、完了を待ちます。
返信は簡潔に保ってください。 実行したこと、ファイルパス、確認できなかったことを報告します。

実際の使用からの教訓

シーンを記述する前に references/lessons.md を読んでください。要約：シードデータが実際に存在することを確認する（ランダムなテストデータは古いデータと衝突する可能性があります）。遅いページが描画されたことを証明するロケーターを待つ。入力前に記憶された検索フィルターをクリアする。ポップアップを閉じる。レコードに直接リンクする。必須でない装飾はラップして、1つの失敗がシーン全体を止めないようにする。スライドの下部200pxはキャプション用に空けておく。

ファイル

scripts/rec.mjs レコーダー：グライドするカーソル、クリックリップル、ズーム、マーカー、待機をカットする think()。
scripts/speak.py ナレーションをWAVとキャプションタイミングに変換。
scripts/overlays.mjs キャプション、ラベル、タイトルカードを画像として生成。
scripts/assemble.py クリップを音声に合わせてリタイミングし、結合、オーバーレイ、音声ミックス、MP4とSRTを書き出し。
templates/ シーン、保存済みログイン、スライド、ナレーションファイルの開始点。
references/ ツールキットガイド、セットアップ、教訓。

何かが失敗した場合

音声合成が espeakng_loader/phontab: No such file で失敗：references/setup.md を参照。
テキスト待ちでシーンがタイムアウト：ページの描画が完了していないか、記憶されたフィルターがアイテムを隠している可能性があります。失敗時にスクリーンショットを撮って確認します。
動画に待機時間が表示される：遅いステップを think() でラップします。
映像と音声がずれる：シーンを再録画します。スクリプトが変更されるたびにマーカー時刻が変わるためです。

ウォークスルー動画