NaxFur/duo-sketch-reel

デュオスケッチリール（ギーク＋Claude）

ギークが慌て、Claude（オレンジ色のロボット）が無表情で答える3Dスケッチ。セット、両方のリグ、演技、照明、カメラ、モニター、オーバーレイ、スコア、効果音まですべてが手続き的にBlenderで構築され、1エピソードにつき1つのstoryboard.jsonから生成されます。新しいエピソードはデータであってコードではありません。画像や動画の生成は一切行いません。

エピソードはフォルダです：<任意のディレクトリ>/<YYYY-MM-DD>_<スラッグ>/ の中に storyboard.json と research.md を置きます。パイプラインは他のすべて（assets/、project/、renders/、final.mp4、cover.png、qa/）をこのフォルダに書き込みます。リポジトリの examples/ に完成した2つのエピソードがあります。コピーして始めてください。

ワークフロー（順番に、スキップしないこと）

1. トピック（5分）。開発者やAIに関連する共感できる悩みと、開発者が今日使える1つのヒント。ジョークは視聴者がAIをどう使うかについてであり、ツールについてではありません。ルールとアイデアバンクは references/retention.md。
2. リサーチ → research.md：画面上・音声・キャプションに登場するすべての事実にURLと確認日を付けて、一次情報源（公式ドキュメント、README、ソースコード）から取得。スケッチの創作部分（時間、数、名前）は「Fiction」セクションに分ける。確認できないものは削除し、その旨を明記する。
3. スクリプト＋ストーリーボード → storyboard.json（サンプルをコピーして書き換える）。スキーマと語彙は references/storyboard.md。目標：30〜40秒、10〜14行、最初の単語は0.5秒以内、1.5〜3秒ごとにカット、ギークが始め、Claudeが締め、最後のフレームが最初のフレームにループバックする。
4. 無料ドラフト（macOS）：pipeline.sh <エピソード> --say stills（システム音声、クレジットなし）。renders/stills/sheet.jpg（各ビート終端の1フレーム）を確認。フレーミングやオーバーレイの衝突を修正して再実行。macOS以外の場合：--say をスキップし、先にテイクを録音または生成（ステップ5）してから stills を実行。
5. 音声。各行ごとに1つの音声ファイルを assets/audio/dialogue_raw/<ビートID>.mp3（L01.mp3、...）に配置。リファレンスエピソードでは、ElevenLabs eleven_v4 と2つのライブラリ音声（ギーク = "Quinn - Soft Nerd Boy"、Claude = "Sarcastic Nigel"）を使用し、各ビートの tts にオーディオタグ（例：[deadpan] It was ugly.）を記述。ClaudeのElevenLabsコネクタを使う場合：まず1行あたりの推定（タグを含む1文字あたり約1クレジット）、次に1行ごとに1回生成し、各テイクを content_url からダウンロード。11〜14行のエピソードで約700〜900クレジット。自分で録音したものでも同じファイル名で機能します。
6. 実際のビルド＋静止画：pipeline.sh <エピソード> stills。project/whisper_check.txt にスクリプトと聞こえたテキストの各行比較が出力されます（比率 < 0.8 は要確認）。テイクは say ドラフトより長いので、シートをもう一度確認してください。
7. 最終版：pipeline.sh <エピソード> final（16サンプル、3ワーカー、MシリーズMacで1フレーム約3秒：38秒のリールで約1時間。バックグラウンドで実行）。final.mp4、Bフックバリアント final_b.mp4、cover.png をレンダリングし、qa.py を実行 → qa/report.md（Blocking: none と表示されること）。

絶対ルール

• キャラクター：ギークとClaudeを再デザインしないこと（engine/scene/nerd.py、mascot.py）。Claudeには口がない：体のスクワッシュ、バウンス、目、腕で「話す」。
• スケッチはストーリーを創作してもよいが（それがコメディ）、製品機能、数値、ベンチマーク、引用を創作してはならない。
• 見せ場（スタンプ、キー、チェックマークなど）は、それが示す単語の0.2〜0.3秒前に配置し、最後の単語には決して配置しない。
• 有料音声の前に無料ドラフト、最終レンダリングの前に静止画。

ファイル

• pipeline.sh <エピソード> [--say] [build|stills|draft|final]
• engine/scene/ Blender側：build_scene.py（エントリ）、animate.py（ストーリーボードからの演技/照明/カメラ）、env.py セット、nerd.py、mascot.py、lights.py、tl.py（アンカー、スクリプトと共有）。
• engine/scripts/：build_timeline.py（テイク→タイムライン＋whisper単語＋リップシンク）、make_screens.py（モニターテンプレート）、make_overlay.py（フック、字幕、アイテム、タイトルカード、captions.srt）、make_audio.py + synth.py（スコア/効果音）、master_audio.py（-14 LUFS）、stills.py、draft.sh、render_final.sh、encode.sh、make_cover.py、cover_title.py、qa.py、make_textures.py。
• ツールとパス（環境変数、macOSデフォルト）：BLENDER（Blender 5.xバイナリ）、DUO_PYTHON（numpy、scipy、soundfile、pillowがインストールされたPython、デフォルト ~/.venvs/duo-reel/bin/python）、WHISPER_MODEL（whisper.cppモデル、デフォルト ~/whisper-models/ggml-medium.en.bin）、PATH上の whisper-cli と ffmpeg、フォント DUO_FONT_DISPLAY / DUO_FONT_MONO / DUO_FONT_SANS / DUO_FONT_EMOJI。
• references/storyboard.md（スキーマ、すべてのプリセット）、references/retention.md（フック/構造/トピック）、references/lessons.md（過去の失敗事例）。