アプリトレーニングビデオ
実際のアプリケーションのプロフェッショナルなトレーニングビデオを作成します。ビデオは1920×1080 H.264、AACナレーションです。各発話文にキャプションが付き、各チャプターはカードで始まり、長い待ち時間はカットされます。再現可能で、UIが変更されたときにキャプチャとレンダリングを再実行すれば、ビデオは最新の状態になります。
仕組み:
- ストーリーボードにナレーションテキスト、チャプター、ブランディングを保持します。
narrate.pyが各セグメントをオフラインのKokoro音声で読み上げます。クラウドサービス、アカウント、費用は不要です。- キャプチャスクリプトがPlaywrightで実際のアプリを操作し（実際のマウス移動、可視カーソル、クリックリップル）、Chromeのスクリーンキャストフレームを記録し、各セグメントのナレーションが終わるまで保持します。
render.pyがクリップ、カード、キャプションバンド、ラウドネス正規化されたナレーショントラックを組み立てます。review.pyが結果をチェックし、公開前に確認するためのコンタクトシートを作成します。
スクリプトはこのファイルの隣の scripts/ にあります。ナレーションを書く前に references/storyboard.md を、キャプチャスクリプトを書く前に references/capture-guide.md を読んでください。どちらにも、よくある再録画を防ぐための教訓が書かれています。
0. 初回セットアップ
bash <skill>/scripts/setup.sh
これにより ~/.cache/app-training-video/ が作成されます（TRAINING_VIDEO_HOME で上書き可能）。以下を含みます:
- 固定パッケージを持つプライベートなPython 3.10–3.13環境
- Kokoro音声モデル（約350MB）とInter書体、SHA-256チェック済み
- Chromium
すべてのスクリプトはその環境のPython（PY=~/.cache/app-training-video/venv/bin/python）で実行し、ストーリーボードのパスを渡してください。モデルファイルが既に別の場所にある場合は、最初に MODEL_SOURCE=<dir> を実行して再利用してください。ffmpegはバンドルされています（imageio-ffmpeg）。システム全体に何もインストールされません。
1. アプリと視聴者を理解する
何かを書く前に、実際にアプリを使うか（またはユーザーガイドを読んで）以下を確認してください:
- 誰が見るのか: 新規顧客、現場スタッフ、内部ユーザー
- 習得すべき主要なワークフロー: 入力から結果まで
- 安全に表示できるデモデータ
- アプリをクリーンな状態で起動する方法: URLまたは起動コマンド、および新しいデータフォルダまたはデモアカウント
- ブランディング: 会社名、製品名、バージョン、ロゴPNG、アクセントカラー、アウトロ用の連絡先行
見つからないものがあればユーザーに尋ねてください。フルワークフローには6〜7分、単一機能には60〜90秒が適切です。
2. ストーリーボードを書く
assets/storyboard.example.json をプロジェクトの隣に storyboard.json としてコピーし、references/storyboard.md に従って記述します。要点:
- 1セグメントあたり10〜35秒のスピーチ
- チャプターは
"n · Title"形式で、各チャプターの最初のセグメントにcard: "chapter"を指定 introカードとoutroカード- 音声読み上げ用に頭字語はスペルアウトし、
caption_replacementsで表記を復元
撮影前にナレーションをユーザーに見せてください。今変更するのは安価で、後で変更するのは高価です。
3. ナレーション
$PY <skill>/scripts/narrate.py storyboard.json
各セグメントの長さを出力します。テキストが変更されたセグメントのみ再読み上げします。発音が気になる場合は、video-build/audio/ 内の1つか2つのWAVファイルを聞き、スペルを調整して再度実行してください。
4. キャプチャスクリプトを書き、実行する
scripts/capture_template.py をストーリーボードの隣に capture.py としてコピーし、スキルの scripts/ へのパスを設定します。そして、ストーリーボードの順序に従って、撮影する各セグメントに対して with rec.segment('<id>'): ブロックを1つ記述します。ブロック内で、ナレーションが説明する内容を正確に実行します:
rec.click、rec.hover、rec.type、rec.drag、rec.scroll、rec.park- 遅い処理の周りには
rec.cut()を使用し、可視の結果が現れるのを待ちます
レコーダーは空でない frames/ フォルダを拒否するため、古いフレームが混ざることはありません。
$PY capture.py storyboard.json
各セグメントの撮影時間がナレーション時間と比較して表示されます。最初の失敗ステップ、ページエラー、または撮影されなかったセグメントで実行は失敗します（ステータス incomplete）。ステップを修正し、video-build/frames/ を空にして再度実行してください。
5. レンダリングとレビュー
$PY <skill>/scripts/render.py storyboard.json
$PY <skill>/scripts/review.py storyboard.json
ビルドフォルダに出力されます:
<output_name>.mp4.srt字幕-chapters.txt（YouTubeの説明に貼り付け）-poster.jpg-timeline.json-review.jpg: 各セグメントの静止画
コンタクトシートを開いて確認し、MP4自体もスポットチェックしてください。以下を確認:
- 各セグメントで正しい画面が表示されているか
- エラーバナー、空のプロット、ダイアログの残骸がないか
- カーソルが説明中の内容を覆っていないか
- キャプションが正しく読めるか
セレクタが一致しても画面が間違っている可能性があるため、ビデオを完成と呼ぶ前には必ずこの確認が必要です。
6. 納品
ユーザーにMP4、SRT（ほとんどのプレイヤーはファイル名が一致すると自動ロードします）、およびチャプターリストを提供してください。長さとサイズにも言及してください。公開するには、MP4とSRTを一緒にアップロードしてください。storyboard.json と capture.py はプロジェクトと一緒に保管してください：次回UIが変更された後、手順4〜5（および文言が変更された場合は手順3）を再実行します。
トラブルシューティング
| 症状 | 修正方法 |
|---|---|
Need Python 3.10–3.13 | python3.12をインストールするか、setup.shを実行する前に PYTHON= を設定する |
アプリは起動したが launch() がタイムアウトする | アプリが出力をバッファリングしている：Pythonサーバーは python -u で実行するか、ready 正規表現を確認する |
| LinuxでChromiumが起動しない | $PY -m playwright install --with-deps chromium |
| ロケーターがタイムアウトするか、2つの要素にマッチする | 範囲を限定するか、exact=True を指定した get_by_role を使用する（キャプチャガイド参照） |
| セグメントがナレーションよりはるかに長い | rec.cut() の範囲外に遅い処理がある |
| 発音が間違っている | speech 内でスペルを変更し、caption_replacements ルールを追加し、narrate.pyを再実行する |
| キャプションのタイミングが合わない | キャプションのタイミングはナレーションの長さに従う：長い文を短くするか、セグメントを分割する |