映画風3D動画 (Cinematic 3D video)

Claudeは直接動画のピクセルを生成することはできませんが、3Dシーンをコードとして記述し、1フレームずつレンダリングしてエンコードすることはできます。このスキルがそのパイプラインです。

scene (HTML + Three.js)  -- window.seek(t) -->  scripts/render.mjs  -->  headless Chrome screenshots  -->  ffmpeg  -->  MP4

render.mjsはリアルタイムで録画する代わりに仮想クロックを進めます。そのため、どのマシンでも同じ結果が得られ、重いシーンでもカクつくことはなく、単にレンダリングが遅くなるだけです。これが、シーンが時間の純粋関数でなければならない理由です（「シーンのルール」を参照）。

1. まずツールを確認する

node -v        # 22以上（render.mjsは組み込みWebSocketを使用）
ffmpeg -version

Chrome、Edge、またはChromiumがインストールされている必要があります（自動検出されます。CHROME_PATHで上書き可能）。Three.jsはシーンによってCDNから読み込まれるため、レンダリングするマシンはインターネットに接続されている必要があります（Three.jsをベンダー化した場合は除く。references/troubleshooting.md参照）。ツールが不足している場合は、正確にインストール手順をユーザーに伝え、アドホックな回避策を考えようとせずに停止してください。Blenderは写実的なパスでのみ必要です。

マシンが新しい場合は、依存関係なしのスモークテストを一度実行してください。これにより、Chrome、WebGL、ffmpegがすべて動作することが確認できるため、後の問題はシーン側にあると切り分けられます。

node <skill-dir>/scripts/render.mjs <skill-dir>/templates/smoke-test.html --out smoke.mp4 --duration 2 --width 640 --height 360

2. ワークフロー

要件を1～2文で確定する: 被写体、ムード、長さ、アスペクト比、テキスト、オーディオ。ユーザーが曖昧にしている場合は、自分でデフォルトを決めて、その選択を伝えます：1920x1080、30fps、8～12秒、暗い背景、1つのメインオブジェクト、1つのカメラムーブ、1つのタイトル。縦型（TikTok/Reels/Shorts）は1080x1920です。開始前に複数の質問をすることはめったに価値がありません。最初のレンダリングが最良の質問です。
スターターから始める。 templates/starter/を作業ディレクトリにコピー（cp -r）し、index.htmlを編集します。これにはレンダラー、トーンマッピング、スタジオ反射、ブルーム、シャドウ、シード付きパーティクル、カメラパス、HTMLタイトルオーバーレイ、タイムラインフックがすでに含まれています。メインオブジェクト、パレット、カメラパス、テキストを置き換え、配管部分はそのまま維持します。
動画をレンダリングする前に静止画を確認する。 最も動きのある瞬間にフルサイズで数フレームをレンダリングして開きます（PNGを確認）：
```
node <skill-dir>/scripts/render.mjs my-video/index.html --stills 0,2,4,6,7.5 --out my-video/stills
```
ここで構図、露出、色、テキストの視認性を修正します。静止画は1～2秒で完了しますが、フルレンダリングには数分かかります。
一度レンダリングする。 設定を選択し、動画全体をレンダリングします：
```
node <skill-dir>/scripts/render.mjs my-video/index.html --out my-video/video.mp4 --width 1920 --height 1080 --fps 30 --scale 2
```
--scale 2は2倍の解像度でレンダリングしてからダウンスケールするため、ギラギラしたエッジを除去できます（最終レンダリングのみ有効）。長時間のレンダリングはバックグラウンドで実行し、進捗をポーリングすることで、ユーザーが沈黙したターミナルを見つめることがないようにします。
ログではなくファイルを検証する。 ffprobeで時間、サイズ、fpsを確認し、MP4から2～3フレームを抜き出して（ffmpeg -ss 3 -i video.mp4 -frames:v 1 check.png）目視確認します。その後、MP4とシーンフォルダをユーザーに引き渡し、修正できるようにします。
修正はシーンを変更して再レンダリングします。--start/--endを使用して、特定の瞬間を反復する間、範囲を限定して再レンダリングします。

3. シーンのルール（とその理由）

アニメーションするものはすべて、tの純粋関数とし、update(t)内で設定します。Math.random()（代わりにシード付きrng()を使用）、Date.now()、clock.getDelta()、フレーム間での状態の蓄積は禁止です。レンダラーは任意の順序で任意の時刻にseekを呼び出す可能性があり、ブラウザでのプレビューは動画と完全に一致しなければなりません。
ページのコントラクトはwindow.seek(t)（同期的に描画）、window.__duration（秒）、およびwindow.__ready = true（アセット読み込み完了後）です。lib/stage.jsのinstallTimeline()がこれら3つを実行します。詳細はreferences/contract.mdを参照。
1.0を超えるHDR色は発光する。 ブルームはしきい値よりも明るいピクセルのみを拾うため、発光部分にはnew THREE.Color(hex).multiplyScalar(3..6)を使用します。通常の表面はしきい値を下回るようにします。
テキストはHTML/CSSでキャンバスの上に重ねます（スクリーンショットにはページ全体が含まれます）。どの解像度でもくっきり表示され、フォントファイルは不要で、update(t)内でプレーンなスタイル変更によってアニメーションします。
アセットは__readyを設定する前にawaitで読み込む（GLTFモデル、テクスチャ、フォント）。アセットが到着する前にレンダリングされたフレームは、動画内で恒久的な表示不良となります。
ライトは1つのストーリーにまとめる：キーライト、1～2色のリムライト、イメージベースドリフレクション。暗くてやや反射する床の上に置かれた反射性マテリアル（金属、ガラス、クリアコート）が、「ウェブデモ」ではなく「3Dアニメーション」として見える要素です。references/cinematography.mdには、カメラムーブ、テンポ、イージング、照明、色に関するレシピが記載されています。

4. 複数シーン、オーディオ、その他のフォーマット

複数シーンの動画： 各シーンを同一のサイズ、fps、エンコーダー設定で個別のMP4にレンダリングし、再エンコードせずに結合します：file 'a.mp4'行を含むlist.txtを作成し、ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4を実行します。クロスフェードは、完成したファイルをブレンドするのではなく、シーン自身のタイムライン内に配置します（一方のシーンの最後の1秒と次のシーンの最初の1秒の両方を黒/色でフェードさせる）。完成ファイルをブレンドするとすべてが2重にエンコードされます。
オーディオ： --audio track.mp3で多重化し、動画の長さにトリミングします。後でサウンドだけを変更する場合：ffmpeg -i video.mp4 -i new.mp3 -map 0:v -map 1:a -c:v copy -shortest out.mp4
GIF / WebM / 小さなコピー： 完成したMP4をffmpegで再エンコードします。フォーマット変更のために再レンダリングは決して行いません。
1つのシーンを変更する とは、そのシーンのファイル（およびクロスフェードが含まれている場合は次のシーンも）を再レンダリングすることを意味します。

5. Blenderを使用するタイミング

Blender（references/blender.md、templates/blender/render_blender.py）は、リアルタイムエンジンではうまく偽装できないものが必要な場合にのみ使用します：パストレーシングによるガラスとコースティクス、ボリューメトリックライト、サブサーフェイススキン、流体/布/煙のシミュレーション、完全に写実的なプロダクトショットなど。Blenderは1フレームあたりの処理がはるかに遅く、Blender 4+のインストールが必要です。それ以外のすべてのケースでは、Three.jsがはるかに短い時間で良い結果を得られ、反復も高速です。

リファレンスファイル

ファイル	読むべきタイミング
`references/contract.md`	シーンをゼロから書くとき、モデル/テクスチャを読み込むとき、または「__readyが設定されない」デバッグをするとき
`references/cinematography.md`	結果を美しくするため：カメラ、ライト、マテリアル、イージング、テンポ、色、テキスト、パーティクル
`references/troubleshooting.md`	黒フレーム、レンダリングが遅い、CDN/オフライン設定、Windows/macOS/Linuxの癖、異常なサイズ
`references/blender.md`	写実的またはシミュレーション作業
`scripts/render.mjs`	すべてのオプション：`node scripts/render.mjs --help`

cinematic-3d-video (映画風3D動画生成)