コードでプロモーション動画を作成する
概要
コード（Remotion：Reactコンポーネントをフレームごとにレンダリング）で制作されるプロモーションフィルム。以下の4つの原則に基づいて動作します。
- 1つの同期マップですべてを制御する。 映像、カメラ、音楽、効果音はすべて名前付きヒットを参照するため、1つをリタイミングするとすべてがリタイミングされます。
- カット前にキャストする。 監督は、フィルムが変更される前に選択肢を聞き、見ることができます。
- 最終版の前にプレビュー。
- すべての主張は製品に忠実であること。
最初にハウスルールを確認： 何よりも先に、ビデオリポジトリ独自のルール（README、CLAUDE.md、またはリポジトリルートの house-rules.md）を読んでください。それらが以下のデフォルト設定よりも優先されます。このフォルダ内の house-rules.example.md は、ハウスルールを作成するためのテンプレートです。
新しいフィルムのセットアップ
- 1フィルムにつき1つのブランチまたはワークツリーを使用し、ビデオ専用のリポジトリ内で行います。製品アプリ内には決して配置しません。各フィルムには専用のフォルダを作成します：
src/videos/<name>/。 - このスキルから
templates/をそのフォルダにコピーします：sections.ts：同期マップ、HITS、TRACK_BPMfilm-camera.tsx：2.5Dカメラshots.ts：ショットリストFilm.tsx：コンポジションスケルトン。ヘッダーにRoot.tsxの登録を含む
templates/render.shとscripts/*.pyをリポジトリのscripts/にコピーします。- 依存関係は、すべて同じバージョンで固定します：
remotion、@remotion/cli、@remotion/motion-blur。オーディオスクリプトの場合：ffmpeg、およびnumpyとsoundfile。 - 1つのコンポジションで、
formatプロップに基づいて両方のフォーマット（横型1920x1080、縦型1080x1920）をレンダリングします。各フォーマットは個別にレイアウトされ、レターボックスは使用しません。
ワークフロー
- ストーリーボード仕様（インストールされている場合は、スーパーパワー:ブレインストーミングスキルを使用）。これを
docs/.../YYYY-MM-DD-<name>-design.mdに書き込みます。画面上のすべての主張を製品のコードとライブフラグに対して確認し、製品と同じ表現で記述します。 - フィルム編集の前にキャスティングボード。 音声（セリフを読み上げたもの）、タイピング音、複数の音楽オプション、ルックやキャラクターのドラフトを表示します。それぞれにコード（A1、B4、M1…）を付けます。ビジュアルドラフトは小さなボードコンポジションとしてレンダリングし、ページを非公開で公開し、監督の選択を待ちます。音声、トラック、ルックを黙って選択しないでください。
- 構築。
- コピーとタイミングは設定ファイルに記述します。
- シーン、ショット、サウンドは
HITS名を参照し、生の数値は使用しません。 - カメラワーク：
camera.mdを参照してください。
- 720pプレビュー（
scripts/render.sh <Comp> <format> preview <name>-preview-vN-720p）。確認した内容、テストできなかった内容、リクエストから変更した点を報告します。 - 承認後のみ最終版： フルサイズ、両方のフォーマット。マシンがスリープすると長時間のレンダリングは停止するため、事前に電源設定を確認してください。
- フィルムのブランチにコミット。 依頼があった場合のみマージまたはプッシュします。以前のフィルムはレンダリングに影響を与えないようにしてください。
オーディオルール
| ルール | 理由 |
|---|---|
映像はミュートでレンダリングし、別途 --codec=wav でレンダリング、その後 scripts/mux.py （-15 LUFS + リミッター）で合成する。 | Remotionのレンダリング内AACは、サウンドトラック全体が43ミリ秒遅れます。 |
音楽は商用ライセンスされているか、生成されたものであり、すべてのファイルは CREDITS.md に記録されます。 | 「無料」の効果音パックの中には商用利用が許諾されていないものがあります。 |
選択したトラックに合わせるには：scripts/beatgrid.py track [bars] [arc] でBPMとダウンビートを取得します。TRACK_BPM を設定し、music-edit.py（小節全体、ダウンビートでクロスフェード）または fit-track.py（ストレートウィンドウ）でトラックをカットします。 | フィルムはトラックに合わせてリタイミングされ、その逆ではありません。 |
音声は、商用ライセンスのあるTTS（Kokoro-82MはApache-2.0）からのみ使用します。macOSの say は絶対に使用しないでください。 | say のライセンスは個人利用かつ非商用です。 |
| 効果音は決定論的に生成します。新しいサウンドは、それぞれ独自のPRNGを使用して最後に追加します。 | そうしないと、後続のすべてのファイルが変更されます。 |
レンダリングでは決して Math.random() を呼び出さないでください。代わりに film-camera.tsx の hash() を使用します。 | フレームは毎回同じようにレンダリングされる必要があります。 |
引き渡し前のQA
- 型チェック。
- ラウドネスは約 -15 LUFS、トゥルーピークは -1 dBTP 未満（
ffmpeg -af ebur128）。生のWAVピークは0.99未満に保ち、クリッピングがないようにします。 - 効果音が指定のヒットフレームに正しく配置されていること。
- QRコードが1080pと720pの両方でデコードできること。
- 変更されたすべてのセクションの静止画を両方のフォーマットでレンダリングし（Remotion
renderStill）、自分自身で確認すること。 レビュエージェントはカットエッジを見逃す可能性があり、小型で高速なモデルによるレビューは正式なレビューとはみなされません。
よくある間違い
| 間違い | 修正方法 |
|---|---|
| モーションが生のフレーム、拍、秒にキー設定されている | sections.ts に名前付きヒットを追加し、それを参照する。 |
| カメラのロールやチルトが後続のショットに漏れている | キーは引き継がれるため、フィールドをリセットする（roll: 0）。 |
| 承認前に最終版をレンダリングしてしまった | 最初に720pプレビューを送信する。 |
| 監督が聞いたり見たりしたことのない音声、トラック、ルック | 最初にキャスティングボードに載せる。 |
| オーディオ付きのシングルパスmp4 | ミュート映像、次にWAV、最後にmux。 |
複数日にわたるフィルムのスクラッチ作業を /tmp に保存している | システムがクリーンアップする。実際のワークツリーフォルダを使用する。 |
オートモードで拒否される $(...) やループを含むシェルワンライナー | ロジックをスクリプトファイルに記述する。 |