アクティベーションコントラクト
ユーザーがセルシェーディングされた3D解説クリップ（平らな色、黒い輪郭、オブジェクトのポップイン、移動カメラ、大きなキャプション）を要求した場合、「Stupy Doo」スタイルのビデオを再現したい場合、またはテキストからBlenderで図をアニメーション化するよう依頼された場合に読み込みます。
ハードルール
- ビジュアルを画像/ビデオAIモデルで生成してはいけません。ルックはBlenderでレンダリングされた3Dジオメトリ＋フリースタイルアウトラインです。
- Blenderバイナリ:
~/.local/bin/blender（5.1.x、ユーザーインストール）。常に-b -Pでヘッドレス実行します。 - ストーリーボードが唯一の真実の情報源です:
storyboard.json（スキーマはreferences/storyboard-schema.mdにあり）。JSONを編集し、再レンダリングします。.blendファイルを手動で編集してはいけません。 - フルビデオをレンダリングする前に必ず確認します:
--stillsを3〜5回レンダリングし、コンタクトシートを作成し、それを読み、重なりやカメラ外のオブジェクトを修正します。 - キャプションとオーディオは後処理（
mix.py、captions.py）であり、Blenderテキストオブジェクトでは決してありません。 - SFXは
audioセクションのaction:参照を介してアクションタイムに配置され、アクションが存在する場合に手動で秒数を入力することはありません。 - ナレーションはスペイン語で中立的に保ちます。UI/キャプションのコピーはユーザーの言語に従います。
- クリップは短く保ちます：ストーリーボードあたり8〜30秒。長いビデオの場合はffmpeg concatでクリップを連結します。
決定ゲート
| ニーズ | 実施事項 |
|---|---|
| ナレーション付きビデオ | 最初にナレーション、それに合わせてキャプションをタイミング調整、次にアニメーション。voice-video（tts.py）でaudio.narrationに音声を設定。 |
| SFX / 音楽 | audioセクション: action:参照付きのナレーション、音楽、SFX。プレースホルダーはassets/sfx/に、CC0ソースはそのREADMEに。 |
| 提供された音楽 | スチル前にbeats.py snap storyboard.json --music track.mp3 --writeを実行。 |
| 簡単なルック確認 | --preview --stills t1,t2,t3（半分の解像度、8サンプル）。 |
| 最終レンダリング | --previewなし。デフォルトは1080x1920、30fps。 |
| オブジェクトがプレハブにない | プレハブ: box、plane、cylinder、sphere、panel、panel_row、cable、device、car、charger、transformer、cloud、tree、pole。それ以外はプリミティブまたはmodel（glb/obj）。 |
| フレームが安っぽく見える | ショットあたり1つの主題、カメラは8〜13m、tree/pole/cloudの装飾、ケーブルはdrawしてからflow。references/style-notes.mdを参照。 |
| 手動調整が必要 | --blendを追加し、Blender UIでout/scene.blendを開く。 |
実行手順
references/storyboard-schema.mdとreferences/style-notes.mdを読みます。<workdir>/storyboard.jsonを出力する小さなgen.pyを書きます：z=0の地面プレーン上のオブジェクト、ショット（それぞれ1つの主題）、アクション、キャプション、post、audio。- スチル:
~/.local/bin/blender -b -P ~/.claude/skills/toon-explainer/assets/build.py -- storyboard.json out --preview --stills 1,3,5。Pillowでコンタクトシートを作成し、それを読みます。 - JSONでフレーミングとタイミングを修正します。すべてのショットが明確に読めるまで手順3を繰り返します。
- プレビュービデオ: 同じコマンドを
--previewのみで実行。out/raw.mp4をffprobeで確認します（duration、fps）。 - オーディオ（
audioがある場合）:python3 ~/.claude/skills/toon-explainer/assets/mix.py storyboard.json out/mix.wav。キュー表を読みます。 - キャプションと多重化:
python3 ~/.claude/skills/toon-explainer/assets/captions.py storyboard.json out/raw.mp4 out/final.mp4 --audio out/mix.wav（またはaudioがない場合は--audio narration.wav）。 - 最終:
--previewを削除し、手順5〜7を再実行。out/final.mp4をxdg-openで開きます。
出力コントラクト
storyboard.jsonのパス、out/final.mp4のパス、duration、解像度、および画面に表示されている内容をショットごとに1行で返します。レンダリング時間を報告します。まだ実装されていないもの（リップシンク、マルチクリップ連結）をリストします。
リファレンス
references/storyboard-schema.md— JSONスキーマ、プレハブ、アクション、カメラ規則。references/style-notes.md— 参照ルック、Blender 5の落とし穴、安っぽいカットを修正したもの、サウンドデザイン。references/external/— MITコピー: EL4CTEOblender-stylized-npr、arjun988camera-cinematography。assets/toonlib.py— bpyライブラリ（マテリアル、プレハブ、カメラ、アニメーション）。assets/build.py— ストーリーボードからBlenderレンダリングへ。assets/mix.py—audioセクションを1つのWAVに（ダッキング音楽、SFXキュー）。assets/beats.py— ビート検出＋アクションタイムのスナップ。assets/sfx/— プレースホルダーSFX、CC0ソース。assets/captions.py— ffmpegキャプション＋オーディオ多重化。assets/storyboard.example.json— 太陽光ルーフトップの例、9秒。