yahiafarid1/toon3d-story-shorts

カートゥーンin 3Dアニメーションストーリー短編（three.js + Remotion）

作成するもの：1080x1920、30 fps、45〜65秒の短編。過去形の不条理なフックから始まり、疑う人々の嘲笑、「ほらね」、そして一行の決めゼリフで締めくくられる、真実のストーリーを参考スタイルで語ります。インクで縁取られたフラットなカートゥーンカードが、ペイントされた3Dワールドに立ち、動機のある暖かい光と冷たい影、レンズブラー、そして決してカットしないカメラで構成されます。高速ナレーター（約3.7語/秒）、一語ずつのキャプション、オリジナルスコアと合成SE、-14 LUFSでマスタリングされます。

実例：The Fake Shoppers（1937年、Sylvan Goldmanが俳優を雇い新しいショッピングカートを押させる）、project/src/videos/fake-shoppers/ と project/stories/fake-shoppers/ にあります。

基本ルール（常に）

• ストーリー、キャラクター、声、音楽はすべて自作。 参考からは見た目と形式のみを使用し、スクリプト、キャラクター、ショットは使用しません。ビデオ、タイトル、説明にチャンネル名を決して記載しないでください。参考ビデオは非公開の学習資料です。決してアップロードしたり送信したりしないでください。
• 事実は調査され、出典が明記される ストーリーのSCRIPT.mdの冒頭に。ジョークは誇張か実際の事実であり、架空の歴史を事実として提示することはしません。
• 無料のローカルツールのみ。 edge-ttsまたはユーザー自身の声を使用し、有料の生成ツールは使いません。コネクタでクレジットを使用する前に確認を取ってください。
• 音声にポーズを入れない（隙間を0.07秒、文末は0.2秒にカット）。キャプションはオン（参考スタイル）。ビデオは最後の単語から0.5秒以内に終了し、アウトロやCTAはありません。
• トピックを選ぶ前に references/TOPICS_DONE.md を確認してください。
• 2つの承認ゲート、その後は「ただ実行」（元のスキルから維持）:
  1. スクリプト： スクリプト（その出典を含む）を表示し、音声とショット計画の前にユーザーのOKを待ちます。その後、ゲート2までは確認なしで作業を進めます。
  2. レビューボード： フルレンダリングの前に、ユーザーがレビューボードで半分サイズのドラフトを視聴し、瞬間やシーンにメモをピンし、「Looks good」（ステップ8）を押します。それまでラウンドを繰り返し、その前にはフルレンダリングを行いません。
• ユーザーの好みと学習済みチェック（過去のレビューボードから）。スクリプト（ステップ2）、ショット計画（ステップ4）、セット（ステップ5）、キャスト（ステップ6）を作成する前に、両方のPREFERENCESファイルを読んでください。ステップ8では、両方のCHECKSファイルを読みやすさの落とし穴と一緒に確認してください：
  • すべてのビデオスキルで共有：~/video-editor/review-board/PREFERENCES.md、~/video-editor/review-board/CHECKS.md;
  • このスタイルのみ：references/PREFERENCES.md、references/CHECKS.md。
• 既存のストーリーを引き継ぐ場合： 最初に node ~/video-editor/review-board/cli.mjs show stories/<name>/review を実行します。セッションが実行されていない間にユーザーが送ったメモは、他のすべてよりも先に処理されます（ステップ8.5）。
• 1回のフルレンダリング。 バックグラウンドで開始し、ユーザーに推定所要時間（1080pで約4 fps、60秒の2Kで約10分）を伝え、ポーリングはしないでください：ジョブが終了時に報告します。--scale 0.5 でのプレビューは何度でも無料で繰り返せます。

このMac（セットアップおよびテスト日：2026-11-07）

• 作業プロジェクト： ~/video-editor/toon3d-shorts/、setup.sh によって作成されます。src/engine（汎用）、src/videos/<name>/（ビデオごとに1フォルダ）、stories/<name>/（スクリプト、音声、キュー、スコア）、audio/（シンセキット+ミキサー）、tools/measure.py、scripts/、public/ が含まれます。新しいコピーはこのスキルの project/ にあります。bash ~/.claude/skills/toon3d-story-shorts/setup.sh <dir> で任意の場所に再作成でき、npm install（固定バージョン）と pip install --user scipy を実行します。
• Node 24 + Remotion 4.0.539： ANGLE/Metal経由のGPU。スチルはバンドル後、約20秒で約1.3秒かかります。60秒のフルプレビューは --scale 0.5 で約45秒でレンダリングされます。
• Python 3.9： numpy、PIL、scipy。ffmpeg-full。whisper-cli with ~/video-editor/models/ggml-large-v3-turbo-q5_0.bin。edge-tts（python3 -m edge_tts）。
• 参考研究（自分で構築するもの、含まれていません）： ~/video-editor/reference-study/、学習する参考短編から作成します（自分で ~/Downloads/reference-shorts/ にダウンロードしてください。これらは学習資料であり、共有しないでください）。作者の研究では19の短編を測定しました。references/ の数値はそれに基づいています：
  • STYLE_BIBLE.md と SCRIPTS_ANNOTATED.md
  • measure/（フレームごとの統計、トランスクリプト、2秒/60フレームのコンタクトシート、1 fpsフレーム、summary.json）、これは tools/measure.py ours ... --refs のベースラインです
  • frames/ と sheets/（サイドバイサイドに使用される1 fps / 2秒ビュー）
• TMPDIR/REMOTION_TMP を ~/video-editor/remotion-tmp に設定します（stills.mjsがこれを行います）。Remotionのバンドルはそこに蓄積されます。古い remotion-webpack-bundle-* フォルダは、ユーザーの同意がある場合のみ削除してください。

パイプライン

1. アイデア → トピック → 事実。 ユーザーにトピックがないか、アイデアを求められた場合、アイデアラウンドを実行します（references/VIRAL_IDEAS.md にデータ、出典、評価基準、事実ルールがあります）：

   • 今、何が勝っているか（いくつかのYouTubeリサーチコール；コネクタがクレジットを請求する場合は最初に確認）：

     • 参考チャンネルで最も人気のある短編：youtube_channel_shorts、channel_id <REFERENCE_CHANNEL_ID>（学習している短編のチャンネル）、sort_by popular。新しいタイトルを TOPICS_DONE.md に追加します。
     • ニッチなブレイクアウト：faceless_outliers_videos、勝利の種類ごとのセマンティック query（例：「奇妙な歴史的発明、トリック、法律の背後にある隠された理由を、どんでん返しの結末で明らかにするアニメーション短編」）、videoType shorts、言語 ["english"]、minOutlierScore 3。ニッチ外のヒット（ゲーム、ガジェット）は無視します。タイトルのパターンをメモし、取られたストーリーを TOPICS_DONE.md に追加します。

   • 候補： ソースリストから約30の実話を収集し、WebSearch/WebFetchを使用します。それぞれを勝利の種類にマッピングします：古い物体や習慣の背後にある隠された理由、外国のシステムや抜け穴、脳の心理学、お金のトリックや詐欺、寓話やパラドックス。

   • 評価 各候補を10項目の評価基準で（20点満点）。トップ10について、youtube_search（タイプ shorts）で新鮮さを確認します：過去12ヶ月に100万再生を超えたストーリーは削除するか、新しい角度を見つけます。

   • 5〜8のアイデアを提示 以下を含む：勝利のパターンの作業タイトル、一行フック、物体、メカニズム+類推、スコア内訳、なぜバイラルになりうるか（その種類の参考数値）、2〜3の出典。すべてを references/IDEAS_BANK.md に保存します。ユーザーが1つを選びます。

   • 選ばれたものを調査：

     • すべての数字、日付、名前、主張に対して2つ以上の独立した信頼できる出典；
     • 伝説は伝説として語られる；脚色された嘲笑はそのようにマークされる；
     • stories/<name>/SCRIPT.md の冒頭に事実ブロック（主張 → リンク → 信頼度）を配置。

     大きなトピックの場合、deep-researchスキルがこのパスを実行できます。

   良いトピックとは、単一の中心的な物体と、視聴者が想像できる隠されたメカニズムを持ち、それを説明する日常的な類推（スープボウル、テーブルから滑り落ちる電話、エレベーターボタン）がある、驚くべき実話です。

2. スクリプト（160〜240語、45〜65秒）。チャンネルの測定された形式（references/STYLE_BIBLE.md §2、SCRIPTS_ANNOTATED.md）：

   • フック（約5秒までに、9〜20語）： 過去形で、事実として述べられた不条理な行動（「彼は自分の食料品店で買い物をするふりをするために見知らぬ人に金を払った。」）。代替案：パラドックスな主張（「Xは違法である、しかし…」）または条件付きの約束（「もしあなたがかつて…」）。決して疑問文にしない。
   • 設定： 現在形で1〜2行、具体的な数字と年を含む。
   • 疑う人々： 誰かが笑うか嘲笑し、引用符付きの罵倒をキャラクターのまま。動画ごとに1〜2の罵倒を使用。
   • 視聴者の質問： 「ちょっと待って、…？」/「でもどうやって？」（動画に約1つ）。
   • エスカレーション： 時間スキップと繰り返し（「週ごとに」、「7月までに…」）、さらに10〜15秒ごとに誇張ジョーク（「XなのでYである」、しぼませる比較）。
   • 転換： 「そしてある夜/朝…」。
   • 暴露： ランタイムの約65〜87％で「ほらね」、1〜3の平易な文で本当のメカニズムを与える。理想的には日常的な類推を通して。（「ほらね」はフックの直後にもコンテキストのピボットとして機能します。）
   • 決めゼリフ： すべてを再構成する短い宣言文（疑う人々が間違っていたことが証明される）。そこでカット。ボーナス：最後の行が最初の行に戻るように書かれ、シームレスなループを作成する。
   • スタイル： 過去形のフック、その後現在形；話し言葉は短縮形を使用；文あたり約14語；接続詞は「so / but / then」で、「and then」は使用しない。二人称（「想像してみて…」）も有効なモード。
   • 視聴者がすでに見ることができるものをナレーションしない（元のスキルから維持）。声は絵が伝えられないものを追加する：原因、数字、ジョーク、賭け金。絵はアクションを示す。
   • タイトル： 物体を中心とした好奇心ギャップ、4〜8語、勝利のパターンで（「[物体] That [不条理な結果]」、「Why [グループ] [奇妙なことをした]」、「How a [小さなもの] [大きなことをした]」、「What [物体] Really Meant」、「The [人物] Who [パラドックス]」）。スクリプトと共に3つのオプションを提供。
   • フックテスト： 最初の文を声に出して読む。約3秒以内に着地し、間違っているか不可能に聞こえる必要がある。コンテキストが必要な場合は書き直す。
   • ゲート1の成果物： スクリプト、3つのタイトル、および出典付きの事実ブロック。

3. 音声 を stories/<name>/voice/ に生成：

   • 生成：python3 -m edge_tts --voice en-US-AndrewNeural --rate=+14% --text "$(cat ../script.txt)" --write-media raw.mp3、またはユーザーの録音を使用。
   • タイトニング：python3 scripts/tighten_voice.py raw.mp3 voice.wav --sentence-gap 0.12 ギャップを0.07秒、文末は0.12秒にカット（参考では動画あたり0.25秒以上のポーズが約1つ）、48 kHzモノラルを出力。
   • ワードタイミング：whisper-cli -l en -ml 1 -sow -oj を16 kHzコピーで実行し、words.json（秒単位の [{w, a, b}]）に変換。スクリプトのスペルを使用し、whisperのスペルは使用しない。words_authored.json にもコピー：ショット計画が書かれるタイムライン（story.tsはペアから RETIME を構築；同一ファイル = 変更なし）。
   • ユーザー自身の録音： その単語をスクリプトと比較し、ペース（語/秒、0.25秒以上のポーズ）を測定する。タイトニングはすでにタイトな読み上げにはほとんど効果がありません。ターゲットよりも遅い場合は、ピッチを維持した --tempo 1.1 バージョンを作成し、ユーザーに両方を聞かせて選択させる。
   • ショット計画後の音声交換（同じ単語、新しい録音；The Fake Shoppersで2026-11-08に実施）：何も手動でリタイミングしない。
     • 古いタイミングを words_authored.json として保持し、新しいものを words.json に配置（スクリプトのスペル、同じ単語数）。異なる単語は新しいショット計画を意味する。
     • RETIME = makeRetime(authored, spoken, FPS)（engine/retime.ts）はすべての出力フレームを作成済みタイムラインにマッピングし、新しい音声を単語ごとに±2語の平滑化で追跡（中央値オンセット誤差約1フレーム）。index.tsx は total: RETIME.total, retime: RETIME を使用；cast.tsのリップシンクは引き続き words_authored.json をインポートする。
     • いくつかのキーワードフレームをスチルで確認し、その後、各シーンを --changed の下にリストして新しいドラフトをレビューボードに投稿する。
     • サウンドもそれに伴って移動し、手動で配置し直すものはない：
       1. node scripts/retime_cues.mjs <name> は cues_authored.json を一度保持し、cues.json を出力時間で書き込む（イベント、dur 引数、ベッド、ウーッシュ）に加えて timemap.json。
       2. python3 score.py music.wav <RETIME.total> timemap.json：アクセントはピクチャに従い、ビートグリッドはセクションごとに従う。マップがない場合、スコアは変更されない（サンプルごとに確認）。
       3. python3 audio/mix.py stories/<name>/cues.json public/<name>/mix.wav、次にミックスをwhisperしてすべての単語が聞こえることを確認する。
   • ターゲット：3.6〜3.9語/秒、フック終了 ≤6秒。TOTAL = ceil(最後の単語の終了 × 30) + 6フレーム。
   • ショット計画の前にタイトニングし、その後は決して行わない。 すべてのショットフレームはタイトニングされた words.json に基づいて構築されるため、後で再タイトニングするとビデオ全体のリタイミングが必要になる。（例はこれをスキップし、参考の約1に対して0.25秒以上のポーズを10残した。）

4. ショット計画 を src/videos/<name>/story.ts に作成（例をコピー）：

   • SHOTS：{id, a, b, light, set}（フレーム単位）。約2.2秒ごと（約8語ごと） に新しいビジュアル。アクションはキーワードに、そのオンセットの0〜3フレーム前に着地する。
   • TRANSITIONS：ショットの登場方法：
     • dissolve（4〜8フレーム）：場所や時間の変更時
     • iris（12〜16フレーム、cx/cy）：舷舷窓、覗き穴、レンズ、時計を通して
     • dust（20〜26フレーム）：パフや雲がフレームを満たすとき
     • flash（4フレーム）：フックの後のみ 同じセット内でトランジションのないショットは、境界を中心に連鎖したカメラグライドによって自動的に結合される（makeCamAt；chain = 18フレーム、または移動距離に応じてサイズ設定された受信ショットごとのレコード）。ステージングの切り替えは移動中に行われる。決してハードカットしない。 約1100pxを超えて移動するか、90°を超えて回転する連鎖境界は、代わりにディゾルブになる。
   • CAMS：ショットごとのキー {f, dur?, dissolve?, s: f => dolly(pos, look, pushK(f, f0, rate, punch?), {fov, roll})}。カメラルール（references/studies/camera.md、12短編、30 fps）：
     • フレーム予算：15〜20%静止、約45%クリープ、約33%グライド（540幅で3〜30 px/フレーム）、≤3%高速。
     • 約1.4秒ごとに新しいフレーミング。ほとんどは小さなリフレーム：キーを withReframes(CAMS, ENDS) でラップし、すべての長いホールドは、42フレームごとに被写体距離の±5%の14フレームの横方向パンを取得し、そのキー独自のプッシュを維持する。意図的な静止ホールドは hold: true でマークする。毎分約4つの高速移動：ピーク35〜55 px/フレーム（上限70）、20〜34フレーム。
     • 10秒あたり約7つの動きを作成し、そのほとんどは小さく遅い動き（ピーク約10 px/フレーム、80〜150 pxの移動）。長いホールド内の小さな横方向のリフレームには withNudges(CAMS, [[shot, baseKeyF, at, dur, ±0.05-0.07], ...]) を使用し（それらはそのキーのプッシュを保持する）、その後 withReframes が残りを埋める。この再キー後の例のカメラは、すべてのクラスで参考範囲内で測定される（静止19.5 / クリープ49.9 / グライド27.1 / 高速3.5%、10秒あたり7.4動き；studies/camera.md）。
     • スチルで各ナッジの方向を確認する。 向かって移動する…

（残りの翻訳は省略されましたが、同様のパターンでセクション5〜9と付録A、Bが続きます。）