Toon Reel

Toon Reel は何をしますか？

あなたはトゥーンリールエンジンを使って短編アニメストーリーを監督・制作しています。すべてはPythonです。 キャラクター、セット、ライト、カメラはすべてコードで表現され、すべてのフレームは時間Tの純粋関数です。 タイムラインエディタもキーフレームUIもありません。あなたはデータ（キー、ショットテーブル）を記述し、フレームを確認します。

エンジンのレイアウト（維持してください。相対インポートはこれに依存しています）:

tools/toon/            エンジン: toon.py（レンダラー）、rig.py（キャラクター）、anim.py（タイミング）、cast/ props/ sets/（キット）
tools/                  sound.py（キューからのステム）、mix_check.py（音声明瞭度）、finish.py（-14 LUFS 出力）、
                        thumb.py（カバー）、find_phrases.py（ナレーションテイク内のフレーズ時間）
episodes/starter/toon  テンプレート：「The Lamp」、12.5秒、4ショット、1部屋、1人。これをコピーして開始。
episodes/window/toon   完全な例：「The Man at the Window」、50秒、13ショット、2つの世界とどんでん返し。
episodes/jeff, episodes/smilingman   完全な例とキットがインポートするサポートモジュール（単独実行不可）

コマンド。 以下のpythonはrequirements.txtがインストールされたインタプリタを意味します（Windowsではpy）。 エピソード固有のスクリプト（reel.py、build_tl.py、finalize.py）はエピソードフォルダepisodes/<name>/toonから実行します。 ツールはプロジェクトルートから実行します: python tools/sound.py episodes/<name>/toon。

最初に: エンジンを見つけるかセットアップする

プラグインのインストールフォルダではなく、ユーザー自身のプロジェクトフォルダで作業してください（プラグインはアップデート時に置き換えられます）。

1. 作業フォルダにすでにtools/toon/toon.pyがあれば、それを使用します。
2. そうでなければ、エンジンはこのスキルに同梱されています。そのルートは、このスキルのベースディレクトリの2つ上のフォルダです （<skill dir>/../..: tools/、episodes/、requirements.txt、.gitignoreが含まれます）。これら4つを作業フォルダにコピーし、 レイアウトを維持し、コピーしたことをユーザーに伝えます。そのフォルダにtools/がない場合（スキルが単体でコピーされた場合）、 代わりにhttps://github.com/wlr2/toon-reel-engineをクローンします。
3. pip install -r requirements.txt を実行し、ffmpeg -versionが動作することを確認します（5.1以降）。キャプションにはArial Black、 またはTOON_FONTに太めのサンセリフ.ttfを設定する必要があります。
4. 何かを構築する前にセットアップを確認します。episodes/starter/toonから: python build_tl.py を実行し、続けて python reel.py --frame 5.0 が review/_f5.00.png を書き出すことを確認します。

順序は固定です

脚本 -> タイムライン -> キャストシート + セットフレーム -> ブロッキング -> チェック（2ラウンド） -> プレビュー -> マスター -> サウンド -> 仕上げ -> ポスト。

マスターレンダリングは、チェックに合格しログが記録されるまで開始しません。アニメーション化する前に、ユーザーにキャラクターシート と1つのセットフレーム、そしてフル解像度のプレビューの前にラベル付きキーフレームシートを表示します。何かにお金を使う前に（有料TTS、有料SFX、クラウドレンダリング） ユーザーに確認してください。

1. 脚本（references/script.md）

10ステップの方法: 最も具体的な矛盾から始め、1つの主要な問いかけ、一連の結果、数秒ごとの変化、 スピーチとアニメーションに適した書き方、動く中盤、価値ある結末と署名行を最後に、誠実なフレーミング（クリーピーパスタの場合は「あるインターネットホラー物語」）、 時間指定のショットテーブル、そしてリテンション編集。ユーザーが脚本やビートシートを渡した場合、ユーザーの言葉と仕様がここでのどのルールよりも優先されます。 彼らのセリフを書き換えることはせず、変更案を提案し、変更する箇所を引用してください。

成果物: SCRIPT.md（3つのフック + 選択、完全なナレーション、時間指定のショットテーブル、単語数）とscript.py。

2. タイムライン、そして音声

• script.py は PHRASES（各行の配置場所、テキスト、赤いキーワード用の[word]を含むキャプションチャンク）と MARKS（ストーリービートを秒単位で示し、ショットの境界となる）を保持します。
• python build_tl.py は timeline.json（total、marks、lines）を書き出します。リールはtimeline.jsonのみを読み取ります。 スターターでは、オーディオが存在する前に動作します。フレーズ長は単語数から推定されるため、最初に絵をブロックできます。
• 音声は話者ごとに1テイク、48 kHzモノラルで、任意のTTSまたはマイクから取得します（このリポジトリには同梱されていません。ElevenLabs は有料、Kokoroは無料でローカル実行可能）。テイクを引き伸ばして収めることは絶対にしないでください。代わりにビートをカットします。TTSに送信するテキストでは数字を単語で表記します。
• python tools/find_phrases.py take.wav はテイク内の各フレーズの (start, end) を出力します。それらを PHRASES に配置し、build_tl.py を再実行します。フレーズを切り出し、配置し、audio/narration.wav を書き出します。 その後、各ショットを再確認します。実際のフレーズ長は推定値とは異なる可能性があります。
• 同梱されている build_tl.py ファイルは1人のナレーターを処理します。複数の話者の場合は、話者ごとに1テイクを維持し、各フレーズに 話者を追加します（build_tl.py の小さな変更）。
• TikTok向けの罵り言葉: 別のステムでビープ音にし、キャプションではアスタリスクを付けます（f***ing）。

3. エピソードファイル（references/engine.md）

ファイル	役割
script.py	セリフ、キャプションチャンク、マーク
build_tl.py	timeline.json（+ audio/narration.wav）
looks.py	キャスト: 各ルックは rig.LOOK 内の辞書
scenes.py	世界: セットジオメトリ、ライト、時間Tにおける各人の位置、演技トラック
reel.py	SHOTS、キャプション、render(T)、チェック、レンダリングコマンド
cues.py	tools/sound.py 用のサウンドイベント
finalize.py	ステムをミックスし、レンダリングにマルチプレックスし、tools/finish.py を実行

新しいエピソードを開始するには、episodes/starter/toon をコピーして episodes/<name>/toon にします。その reel.py、build_tl.py および finalize.py は汎用的でそのまま使用できます。script.py、looks.py、scenes.py、 SHOTS テーブル、cues.py を置き換えます。episodes/window/toon からは開始しないでください。その reel.py、cues.py およびチェックは そのストーリー（2つのミラーリングされた世界、名前付きマーク、カスタムどんでん返しカメラ）に配線されています。テクニック（テクスチャ、被写界深度、 世界ごとの顔キー、ガラスに触れる手、世界間のクロスフェード）についてはこれを読んでください。より大きなエピソードでは、scenes.py から演技を acting.py に移動します。

世界には2つのメソッドが必要です: draw(fr, cam, T)はすべてを描画し{pid: rig.draw result}を返し、cast(T)は [(pid, look, pose)]を返します。pid はこのエピソードにおける人物のIDです（例：「nora」）。場所ごとに1つの世界と1つのタイムライン。 ショットはカメラのみを選択します。

4. ルック（references/look.md）

丸みを帯びたシンプルな形状、やや大きい頭、大きな表情豊かな目、マットなマテリアル、ソフトな3段階シェーディングと ベースカラーに濃いアウトライン。各キャラクターは脚本に基づいて独自のシルエット、顔、パレットを取得します（別のリールのキャラクターを リカラーすることは禁止）。アニメーション化する前にモデルシートを作成します。tools/toon から: python -m cast.sheet ../../episodes/<name>/toon/looks.py <look> （プロジェクトルートに assets/kit/cast/<look>.png を書き出します。 3番目の引数としてパスを指定することもできます）。

5. ライティング（references/lighting.md）

すべての場所で3層: クールな環境（青紫の夜はディテールを保持）、各顔にソフトなキーライト（上前方から、ランプや窓に動機づけられる）、 そして暖かい実用的な光源を数か所に配置し、その近くを照らします。顔はフレーム内で最も明確にし、背景はその周りで少し暗く、 コントラストを低くします。足元、家具の下、触れ合う手の下にコンタクトシャドウ。場所ごとに1つのライト設定。方向、色、露出はカットをまたいで 一定。ブルーム、光るアウトライン、押しつぶされた黒は禁止。天候（雨、雪、風）は、ストーリーに天候がある場合、静かな瞬間にアニメーション化します。

6. カメラ（references/camera.md）

• 2～3秒ごとにカット。各ショットは1つのアクション、1つの表情、または1つの明かしを対象とします。
• フック（0～3秒）はリールの中で最も美しい動くショット: カメラとキャラクターがフレーム1から動きます。
• まずツーショット、次にマッチングクローズアップ。クローズアップは視線の約35度以内に収めます。
• track(a, b, ease) は2つのキー (position, target, focal px, horizon) の間を1回のクリーンな移動で動かします。カメラは ターゲットの方を向きますが、チルトはできません。ターゲットの高さは無視されます。カメラの高さと horizon で上下にフレーミングします （値が小さいほどアイラインがフレーム内で高くなり、見下ろしているように見えます）。
• 画面内のすべての人物からカメラを0.45 m以上離します: rig.draw はそれより近い人物を描画しません。
• キャプション（Arial Black 66 px、白、黒ストローク、キーワード #FF4D4D）は顔や手の上に決して置きません。 ショットごとに cap=(y, size) で移動します。

7. 演技とステージング（references/acting-staging.md）

すべてのアクションはオフセット付きの連鎖です: 目 -> 頭 -> 肩 -> 体 -> 手、準備 -> 動き -> 落ち着き の順。 反応は out/snap でイーズアウト、落ち着きは back。頭と肩だけを動かす人物はデフォルトの足で立つことができます。 歩いたり体を回転させたりする人物は、ワールド空間に固定された足（rig.replant または rig.gait からの ankle_R/ankle_L）が必要で、 一度に一歩ずつ動かします。ブロッキングを始める前にステージングの教訓を読んでください。それぞれはすでに発生したグリッチです。

8. チェック: すべてのマスターの前のゲート（references/checks.md）

1. python reel.py --check -> review/reel_checks.txt 全体を読みます。スターターでは、すべての問題は ANOMALY 行です: リーチ、沈む足、過度に曲がった肘、肘と膝の反転、ジャンプ、レンズに近すぎる人物、 顔や手の上にあるキャプション。
2. python reel.py --stills -> すべてのショットの最初/中間/最後のフレーム（ラウンド1）。
3. python reel.py --sheet <SHOTS> -> すべてのフレームのコンタクトショット、歩き、回転、オクルージョン変化を 隙間のあるシートで確認（ラウンド2）。分割、飛び出る手足、頭が物を貫通、物が消えることを確認。
4. データで修正し、再実行し、各異常を review/LOG.md に記録します（追記のみ）: 時間、ショット、原因、修正、確認方法。 さらに、理由付きの承認フラグ、および検査できなかった事項。
5. コードだけから「異常なし」とは決して主張しないでください。コードは関節をチェックし、画像をチェックしません。 人が家具や互いをすり抜ける、小道具が手から消える、描画順序が間違っている、0.8 mの横ステップが開脚に見えるなどの問題は検出しません。 それらはシート上で見つけます。

9. レンダリング（エピソードフォルダから）

• python reel.py --preview --full -> review/reel_preview.mp4（1080x1920、無音）。python finalize.py preview でミックスを追加 -> review/preview.mp4。表示し、OKを得ます。
• python reel.py --master-par 12 -> video/reel_silent.mp4: 12プロセスでのマスター（コア数を使用）。

10. サウンド、ミックス、仕上げ、ポスト（references/sound-finish.md）

• cues.py、次にプロジェクトルートから python tools/sound.py episodes/<name>/toon -> 音楽、SFX、環境音 ステム。実際のものには実際の録音（CC0またはライセンスされたサンプルを assets/sfx/ に持ち込む）を使用。合成は抽象的なドローン、 ライザー、ブームにのみ使用。スターターのキューはすべて合成されているため、チェーンが動作します: これらを置き換えます。
• python tools/mix_check.py episodes/<name>/toon: すべてのセリフ行で、音声がベッドより10 dB以上大きくなければなりません （実際のナレーションテイクがあるまで、すべての行が不合格）。
• python finalize.py final（エピソードフォルダ） -> tools/finish.py -> -14 LUFS、<= -2 dBTP、H.264 High、+faststart。
• カバー画像、プロジェクトルートから: `python tools/thumb.py frame.png cover.jpg --line