PRウォークスルー動画
プルリクエスト(PR)のナレーション付きウォークスルー動画を作成します。これは内部向けの成果物として設計されており、PRの作成者がLoom動画を作成するのと同じ利点を提供します。コードの変更を一通り説明し、何が行われたのか、なぜ行われたのかを解説することで、視聴者がPRを素早く理解できるようにします。
入力: GitHubのPR URL(例: https://github.com/tldraw/tldraw/pull/7924)。PR番号やその他の説明のみが与えられた場合は、そのPRがtldraw/tldrawリポジトリ上にあるものと見なします。
出力: 1280×720(30fps)のMP4動画。音声ナレーション、whisperでタイミング調整された黄色文字・黒背景の字幕、標準化されたイントロ/アウトロスライドが含まれ、out/pr-<番号>-walkthrough.mp4 に保存されます。
すべての中間ファイル(音声、マニフェスト、スクリプト)は、このスキルディレクトリからの相対パスで tmp/pr-<番号>/ に配置されます。このディレクトリはgitignoreの対象です。最終的な .mp4 ファイルのみが out/ に保存されます。
./scripts または ./video を参照するコマンドは、このスキルディレクトリから実行してください。
哲学
これは作成者の視点からのウォークスルーです。 目的は、PR作成者が誰かと一緒に座って変更内容を説明するのと同じです。特定のコードを示し、何が変わったのか、なぜ変わったのかを、理解が深まる順序で説明します。視聴者は、コードが何をするかだけでなく、変更をどのように捉えればよいかを理解して終わるはずです。
つまり:
- ナレーションがすべてを決定します。 まずPRの継続的な説明としてウォークスルーのナレーションを書き、その後、各瞬間に何を画面に表示して発言をサポートするかを決めます。
- コードを表示します。 デフォルトのビジュアルはコード差分またはソースファイルです。テキストスライドは例外(イントロ、簡単なトランジション、アウトロ)であり、基本ではありません。ナレーションが関数について言及するとき、視聴者はその関数を見ているべきです。
- 論理的な順序で変更をウォークスルーします。 必ずしもファイル順やコミット順ではありませんが、常に抽象的な説明ではなく具体的なコードに基づきます。
- 「何を」だけでなく「なぜ」を説明します。 画面上のコードは何が変わったかを示します。ナレーションはその理由(なぜこのアプローチなのか、どの問題を解決するのか、どのエッジケースを処理するのか)を補足します。
ワークフロー
ステップ1: PRを理解する
PRのコミット、差分、説明を読んでください。ストーリーの流れを理解します:
- これが解決する問題は何か?
- アプローチは何か?
- 主要なメカニズムは何か?
gh pr view <番号> --json title,body,commits
git log main..HEAD --oneline
git diff main..HEAD --stat
生成ファイルをスキップします。 差分を読む際、手動で編集されたものではなく自動生成されたファイルは無視してください。これらはウォークスルーに情報を追加せずノイズになります。このリポジトリでの一般的な例:
**/api-report.md,**/api-report.api.md— 生成されたAPIサーフェスレポート**/*.api.json,**/temp/*.api.json— API抽出ツールの出力apps/docs/content/reference/**— 生成されたリファレンスドキュメントpnpm-lock.yaml,package-lock.json— ロックファイル**/CHANGELOG.md— 自動生成された変更ログ- リポジトリのツールが再生成するファイル(スナップショット、スキーマダンプ、バンドルされたアセット)
ファイルが生成物かどうか不明な場合は、"DO NOT EDIT" のようなヘッダーコメントがないか、またはリポジトリにそれを生成するジェネレーターコマンドがあるかを確認してください。diff/code スライドで取り上げるファイルを選択する際、これらを除外します。
ステップ2: ナレーションを書く
ナレーションを連続したテキストとして、論理的なセグメントに分割して書きます。各セグメントはウォークスルーの一拍です — 概念、変更、または関連する変更のグループです。これを tmp/pr-<番号>/SCRIPT.md として保存します。
ナレーションは、作成者が同僚にPRを説明するように読み上げられるべきです:「さて、ここでやっていることは... 中心的な問題はXでした... 取ったアプローチはYです... この関数を見てみると...」
構成: イントロ → コンテキスト/問題 → コードウォークスルー → サマリー。スクリプト構成 を参照してください。
コミットがシンプルでうまく整理されている場合(多くの場合、名前に -clean を含むブランチ上)、コミットメッセージと説明に従ってナレーションをガイドできます。そうでない場合は、コードを調べて独自のナラティブを作成してください。前の概念に基づいて構築される順序で概念を導入します。
特、にイントロと最初のコンテンツセグメント間での冗長性を避けてください。
ステップ3: 音声とタイムスタンプを生成する
セグメントごとに1回のTTS呼び出しで、セグメントごとの音声クリップを生成します。これにより、チャンキング、アラインメント、分割を完全に回避します — 各セグメントは信頼性の高い単一のTTS呼び出しに十分短いです。
narration.json ファイルを作成し、generate-audio.sh CLIツールを実行します:
./scripts/generate-audio.sh narration.json tmp/pr-<番号>/
APIキー: リポジトリの .env ファイル(GEMINI_API_KEY)から自動的に取得されます。
ナレーションJSON形式
{
"style": "落ち着いた、安定した、プロフェッショナルな口調で、次のウォークスルーナレーションを読んでください。プルリクエストの作成者が同僚にコード変更を説明しているように、測定されたペースで話してください。",
"voice": "Iapetus",
"slides": [
"このプルリクエストは、矢印ツールにグループ認識バインディング解決を追加します...",
"中心的な問題は、ターゲットの形状が...ときに矢印のバインディングが壊れることでした",
"ArrowBindingUtil.tsのgetBindingTargetメソッドを見てみると..."
]
}
style— 音声のペルソナと話速の指示。短く具体的に保ちます。voice— Geminiの音声名(デフォルト:Iapetus)。slides— ナレーションテキストの配列。セグメントごとに1エントリ。
仕組み
- 各セグメントについて、スクリプトはプロンプト(スタイルのプリアンブル + セグメントテキスト)を作成します。
- セグメントごとに
gemini-3.1-flash-tts-previewへの1回のAPI呼び出しで、WAVクリップを直接生成します。 - 各クリップは検証され(単語数に対する時間の健全性チェック)、出力が不良の場合は自動的に再試行されます。
- 各クリップから先頭と末尾の無音がトリミングされます。
出力: セグメントごとの音声クリップ(audio-00.wav、...)と、各音声ファイル名を秒単位の時間にマッピングする durations.json ファイル。
依存関係: ffmpeg / ffprobe。標準ライブラリ以外のPythonパッケージは必要ありません。
ナレーションテキストで [pause long] や [pause medium] のマークアップタグを使用しないでください — モデルが文字通りに読み上げる可能性があります。
ステップ4: マニフェストを書く
ステップ3の各クリップの長さを確認するために durations.json を読み、音声ファイルと同じ場所に manifest.json を書きます。各スライドのエントリを順に、それぞれに type、audio、durationInSeconds を含めてリストします。
スライドタイプとそのフィールドについては references/manifest.md を参照してください。
ステップ5: 動画をレンダリングする
render.sh スクリプトを実行します:
./video/render.sh \
tmp/pr-<番号>/manifest.json \
out/pr-<番号>-walkthrough.mp4
スクリプト:
- 参照された音声/画像ファイルを
video/assets/にコピーします。 - 各音声ファイルに対してwhisper文字起こしを実行 →
video/transcripts/audio-NN.json(冪等 — 音声が既存の文字起こしより新しい場合のみ再文字起こし)。 build.mjs <manifest>を実行してvideo/index.htmlを生成します — すべてのスライドのタイミング付きクリップ、トランジションとコードフォーカスパンのためのGSAPタイムライン、whisper文字起こしから導出された開始/終了時間を持つ黄色文字・黒背景のキャプションクリップを含むhyperframes構成。- 構成をリントし、
npx hyperframes renderを使用して1920×1080のフレームをレンダリングします。 - 1280×720 / 30fpsにダウンスケールし、ffmpeg(CRF 26 + AAC 96k)で再圧縮して、小さくても鮮明な最終MP4を生成します。
依存関係: Node.js 22+、ffmpeg、Python 3(render.sh がマニフェストを解析するために使用)。hyperframes は npx --yes を介して呼び出されるため、インストール手順は不要です。Whisperはローカルで実行されます(small.enモデル、初回ダウンロード時約150MB)。
whisperによるキャプション同期
キャプションは、フレームの下部に固定された黒いピル上の黄色いテキストとして表示されます。その開始/終了時間は、単語レベルのwhisper文字起こしを5〜7単語のチャンクにグループ化し、自然なポーズ(>450msのギャップ = 文の区切り)で早めに区切ることで得られます。1つの影響として、whisperはブランド/コード名を音声的に文字起こしします — "tldraw" → "TL Draw"、"OverlayUtil" → "overlay util"。これはキャプションとしては許容範囲ですが、後でbuild.mjsの置換テーブルを介して正規化することもできます。
ファイルサイズ調整
デフォルトのレンダリングは、8分の動画で約30〜60MBを目標としています。調整するには:
render.sh内のffmpegダウンスケールステップで--crf <n>— 22はほぼロスレス、26がデフォルト、30以上ではかなり小さくなります。CRF 28〜30はドキュメント品質の結果に適した範囲です。- 1080p hyperframesレンダリングでは
-q draft --crf 30を使用して中間ファイルを小さく保ちます(いずれにせよダウンスケールが最終サイズを支配します)。
ファイル構成
最終出力はこのスキルディレクトリに配置されます。すべての中間ファイルは tmp/ に配置されます(gitignore対象):
pr-walkthrough/
├── SKILL.md # このファイル
├── scripts/ # CLIツール(チェックイン済み)
│ └── generate-audio.sh # narration.json → スライドごとのWAV + durations.json
├── video/ # Hyperframesプロジェクト(チェックイン済み)
│ ├── hyperframes.json # hyperframes設定
│ ├── meta.json # プロジェクトメタデータ
│ ├── build.mjs # manifest.json → index.html 構成
│ ├── render.sh # manifest.json → 720p MP4(フルパイプライン)
│ ├── assets/ # レンダリング時に自動生成(gitignore対象)
│ ├── transcripts/ # Whisper単語レベルJSON(gitignore対象、キャッシュ)
│ └── renders/ # 中間1080pレンダリング(gitignore対象)
├── out/ # 最終出力(gitignore対象)
│ └── pr-XXXX-walkthrough.mp4
└── tmp/ # 中間ファイル(gitignore対象)
└── pr-XXXX/
├── SCRIPT.md # ナレーションスクリプト
├── narration.json # generate-audio.shへの入力
├── durations.json # 音声ファイル名 → 秒単位の時間
├── manifest.json # render.shへの入力
└── audio-XX.wav # セグメントごとの音声クリップ
API設定
- Gemini APIキー: プロジェクトルートの
.envファイルにGEMINI_API_KEYとして保存されます。TTSと音声アラインメントに使用されます。 - TTSモデル:
gemini-3.1-flash-tts-preview - TTS音声:
Iapetus(常時)
スクリプト構成
ウォークスルーは一貫したストーリーの流れに従います。すべてのセクションが独自のセグメントを必要とするわけではありません — PRの複雑さに基づいてセクションを組み合わせるかスキップしてください。目標は合計8〜12セグメントで、大半がコードを表示することです。
イントロ(1セグメント)
イントロカード: tldrawロゴ + PRタイトル + 日付。ナレーションは、このPRが高いレベルで何をするかを一言で説明する単一の文であるべきです。まだ詳細には踏み込まないでください。
マニフェストスライドタイプ: intro。
コンテキスト(0-1セグメント)
コードに飛び込む前の簡潔な説明。このPRの前の状況はどうでしたか?どのような問題やニーズが作業の動機になりましたか?これを短く保ちます — コードウォークスルーが意味をなすための十分な枠組みを提供します。
- 具体的に: 「ターゲットの形状がグループ内にあると矢印のバインディングが壊れた」といった具合に、「バインディングに問題があった」ではありません。
- 影響を受けたコードベースの領域に名前を付けます。
最初の関連コードを表示しながらコンテキストを説明できる場合は、スタンドアロンのコンテキストセグメントをスキップし、最初のコードセグメントに組み込んでください。
マニフェストスライドタイプ: text または diff(問題のあるコードを表示する場合)。
コードウォークスルー(6-10セグメント)
動画の主要部分。実際のコード変更をウォークスルーし、特定の差分とファイルを表示しながら、何が行われたのか、なぜ行われたのかを説明します。
すべてのセグメントでコードを表示する必要があります。 変更には diff スライドを、変更されていない参照コードには code スライドを使用します。
ガイドライン:
- ファイルと関数に名前を付けます。 ナレーションのある各セグメントは、少なくとも1つの特定のファイルまたは関数を参照する必要があります。
- 差分を表示します。 各セグメントのビジュアルは、議論されている実際の差分であるべきです。
git diff main..HEAD -- path/to/fileを使用して差分を取得し、関連するハンクを抽出します。 - 理解の順序で、ファイル順ではない。 理解を構築する順序で変更を提示します。あるファイルで新しい型が定義され、別のファイルで使用されている場合、最初に定義を表示します。
- 「何を」だけでなく「なぜ」を説明します。 差分は 何が 変わったかを示します — ナレーションは理由、処理するエッジケース、検討された代替案を追加します。
- ボイラープレートはスキップしますが、言及します。 すべてのインポート変更や型エクスポートにセグメントを割り当てないでください。ただし、軽く言及します:「
index.tsにいくつかの型エクスポートも追加されています — これらは次に見る新しい型の再エクスポートにすぎません。」 - 関連する小さな変更をグループ化します。 3つのファイルすべてが同じ1行の修正を取得した場合、1つのセグメントで3つすべてをカバーできます。各ファイルに名前を付けて言及します。
サマリー(1セグメント)
PRが達成したことを簡単に要約します。これは短いまとめです — 全体的な変更を要約する1〜2文で、関連する場合は既知の制限事項や今後の作業に言及します。
マニフェストスライドタイプ: text。
アウトロ(1セグメント、無音)
tldrawロゴ、3秒の無音。常にこれを最終スライドとして含めます。
マニフェストスライドタイプ: outro、durationInSeconds: 3。
ナレーション作成のヒント
- コードについて具体的に。 「
BindingUtil.tsでは、onAfterChangeハンドラーがグループの祖先をチェックするようになりました」と言い、「バインディングシステムが更新されました」ではありません。ファイルと関数に名前を付けて、視聴者がナレーションを画面上の内容に結び付けられるようにします。 - 各セグメント = 1つの変更または密接に関連する変更のグループ。 セグメントの特定の差分を指し示せない場合、それはおそらく抽象的すぎます。
- 作成者として書く。 トーンは説明的で自然であるべきです — まるで誰かに自分の作業を説明しているかのように。「ここでの主なことは...」や「難しい部分は...」で問題ありません。
- イントロと最初のコンテンツセグメント間の冗長性を避けます。
- 表示されないファイルに言及する。 PRが15のファイルに影響を与えるが、興味深いのは6つだけの場合、残りを簡単に認めます:「残りの変更は型エクスポートとテストフィクスチャです。」
- 合計ナレーション時間は5〜7分を目指します。
チェックリスト
- すべてのPRコミットを読み、完全な差分を理解する
- SCRIPT.mdにナレーションを書く(8-12セグメント)
- セグメントごとの音声を生成する(Iapetus音声)
- durations.jsonを読み、セグメントごとの時間を取得する
- manifest.jsonを書く
- render.shを実行して動画をレンダリングする
- 出力をレビューする(字幕の同期、音声品質、全体的な流れ)
トラブルシューティング
- TTS APIエラー:
.envにGEMINI_API_KEYが設定され、有効であることを確認する - 文字起こしに時間がかかる: 初回のwhisperダウンロードは約150MB。
video/transcripts/からキャッシュをクリアして再文字起こしを強制する - レンダリングエラー:
video/hyperframes.jsonが有効であることと、依存関係(Node.js 22+、ffmpeg)がインストールされていることを確認する - 大きなファイルサイズ:
render.shで--crf 28または--crf 30を試す