motion-build（ペーパーカットエピソードビルド）

Papercut ビルド

Remotion プロジェクトをゼロから書く代わりに、ライブラリを使ってすべてのエピソードを構築します。$MOTION_LIB/core/README.md を一度読んでください。

事前確認

• インストール: Standard または Full。ライブラリ、Node 20+、npm、ffmpeg、Python ツール（numpy, Pillow, soundfile）、およびオーディオレンダリング用の Chrome または Chromium が必要です。motion-explainer のコマンドで確認してください。不足があれば ./install.sh --doctor を実行し、motion-setup に引き継いでください。
• ライブラリ: $MOTION_LIB、または ~/.config/motion-explainer/config.env の MOTION_LIB= 行、または一度だけユーザーに確認してください。ライブラリがまったくない場合は、$MOTION_LIB/style/$MOTION_STYLE/remotion/RECIPES.md のスケッチからビルドします。
• まず Remotion エンジン用に Remotion ベストプラクティススキルを読み込んでください（remotion-best-practices、Remotion プラグインから、または npx skills add remotion-dev/skills -g -y -a <あなたのハーネスID>; install.sh --mode standard でこれを行います）。そして、マークアップ、キャプション、Studio 用のルーティングに従ってください。kyfram の場合は、代わりに kyfram スキルを読み込んでください。
• 以前の段階からの video/STORYBOARD.md と narration/script.json が必要です。
• ツールチェーン全体のスモークテスト: $MOTION_LIB/core/tools/selftest.sh が examples/hello-reel/ をテンポラリフォルダにビルドし、1フレームをレンダリングします。

1. スキャフォールド & エンジン確認

エピソードプロジェクトは、intake / motion-strategy の段階ですでにスキャフォールドされているはずです。video/episode.json で記録された engine を確認してください:

• まだスキャフォールドされていない場合は、ユーザーに確認し（remotion、fframes、または kyfram）、以下を実行してください:

  $MOTION_LIB/new_episode.sh <シリーズディレクトリ> NN-スラッグ CompId [出力名] --engine remotion|fframes|kyfram
  

• video/ からのプレビューコマンド:

  • fframes: cargo run --release -- preview（または CLI のインストール: cargo install --locked cargo-fframes）
  • kyfram: 一度レンダリングし、その後 kyfram view out/cache/kyfram/build/<Scene>.lgv（コンパイル済みスクリプト: 前奏 + 生成ヘッダー + シーン）
  • remotion: npx remotion studio（または npm run dev）

• fframes: エピソードプロジェクトは Rust クレートです（media/、src/main.rs）。cargo run --release -- render または $MOTION_LIB/core/tools/render.sh でレンダリングします。

• kyfram: エピソードプロジェクトは .lgv スクリプトです（scenes/、media/fonts/、src/plan.json）。$MOTION_LIB/core/tools/render.sh でレンダリングします（シーンごとにキャッシュし、連結します）。最初に kyfram スキルを呼び出してください。

• remotion: React プロジェクトです（src/、package.json）。npx remotion render <CompId> out/<出力>.mp4 または render.sh でレンダリングします。

2. 計画: episode.json、音声、タイミング

ストーリーボードから video/episode.json を埋めてください:

• scenes: [["S01Hook", "l1_hook", 0], ["S02Name", "l2_name", "called"], ...]（シーンID、ナレーション行ID、最初の単語をインデックスまたは正確な単語として）
• banners: {"S01Hook": "大文字のTAKEAWAY"}。hook: motion-hook を参照。cuts: Camera / Cut テーブルのカット列。bed、whipScene、cutSfx、gaps（行の後の追加ビート、秒単位）

次に、motion-voice をそのタイミングステップまで実行してください（build_vo.py と timing_md.py で終了します）。その後、video/ から:

python3 $MOTION_LIB/core/tools/stubs.py        # エンジンに基づいてマルチファイルシーンスタブを生成

build_vo.py は 1.2 秒未満のシーンにフラグを立てます。その場合は隣のシーンにマージしてください。timing_md.py は STORYBOARD.md のタイミングセクション（絶対フレームと単語キュー）を書き込むので、エージェントが plan.json を開く必要はありません。

3. アセット

$MOTION_LIB/style/$MOTION_STYLE/docs/asset-prompts.md に従ってください: 背景や複雑な静的プロップには画像ツール（透明PNGを出力するもの）、キャラクター、すべてのテキスト、タグ、ゲージ、ボタン、UI にはコードを使用します。生成画像内にテキストを入れないでください。画像ツールがない場合は、ペーパーフィルターを使ってすべてのプロップをコードで構築します。スタイルは維持されます。背景: ライブラリの <Backdrop> セット（style/$MOTION_STYLE/remotion/public/bg/backdrops/_sheet.jpg）を使用します。エピソードにライブラリにない場所が必要な場合のみ、新しい背景を生成します。プルーフスクリーンショット: node $MOTION_LIB/core/tools/capture.mjs <url> public/proof/x.png で取得し、キットの RealShot で表示します。

4. シーン（厳格なマルチファイルアーキテクチャ）

すべてのシーンを1つのファイルに入れないでください。 各シーンは、並列エージェント作業、独立したテスト、クリーンなgit差分を可能にするために、独自の分離されたファイルに存在する必要があります。

video/episode.json から engine を確認してください:

Remotion の場合（engine: "remotion"）

• ファイル構造:
  • src/scenes/<Scene>.tsx（例: S01Hook.tsx、S02Name.tsx）— シーンごとに正確に1ファイル。
  • src/scenes/<Scene>.parts.tsx（オプション）— そのシーンのプライベートサブコンポーネント用。
  • src/scenes/index.ts — レジストリ配列 SCENES。stubs.py によって自動管理されます。ここにシーンの本体をインライン化しないでください。

1. HOOK ブロックから、自分で src/scenes/S01Hook.tsx に S01Hook を最初に構築します。これはエージェントが一致させる参照シーンです（キュー定数、カメラ、クランプされた interpolate）。
2. 残りをシーンエージェントに並行して渡します。シーンごとにグループ化します（各エージェント2〜3シーン）。ブリーフは style/$MOTION_STYLE/remotion/AGENT_BRIEF.md です。
3. ファイル所有権: エージェントは src/scenes/<Scene>.tsx、オプションの <Scene>.parts.tsx、および tools/cue_sheet.d/<Scene>.json のみを書き込みます。他のシーンや index.ts を編集しないでください。
4. エージェントは style/$MOTION_STYLE/remotion/CATALOG.md と $MOTION_LIB/core/audio/CATALOG.md を読み込みます。

fframes の場合（engine: "fframes"）

• ファイル構造:
  • src/scenes/<scene_snake>.rs（例: s01_hook.rs、s02_name.rs）— シーンごとに正確に1ファイル。その構造体と impl Scene for <Scene> を定義します。
  • src/scenes/mod.rs — stubs.py によってすべてのシーンモジュールを自動登録します（pub mod s01_hook; pub use s01_hook::*;）。
  • src/main.rs / lib.rs — Video::define_scenes() を介してシーンをマウントするだけです。main.rs 内にシーンの描画コードを書かないでください。

1. 最初に参照シーンとして s01_hook.rs を構築します。
2. 残りのシーンをエージェントに並行して渡します（各エージェントは src/scenes/<scene_snake>.rs のみを所有します）。
3. TSX コンポーネントの代わりに、利用可能なカメラ、セット、プロップ構造体について style/$MOTION_STYLE/fframes/src/ を読み込んでください。

kyfram の場合（engine: "kyfram"）

• ファイル構造:
  • scenes/<Scene>.lgv（例: S01Hook.lgv）— シーンごとに正確に1スクリプト。シェイプのみ。
  • レンダラーは $MOTION_LIB/core/kyfram/lgv/core.lgv、style/$MOTION_STYLE/kyfram/PRELUDE.lgv、および生成されたヘッダー（SCENE_ID、BANNER、DUR、FPSR、CAPS、および scene() 呼び出し）を先頭に追加するため、シーンは scene() を呼び出したり、その duration やキャプションキューをハードコードしたり、ヘルパーを再宣言したりしてはなりません。

1. kyfram スキルを呼び出します。自分で最初に参照シーンとして S01Hook.lgv を構築し、bash $MOTION_LIB/core/tools/render.sh と bash $MOTION_LIB/core/tools/qa.sh hook 0-<N> 6 0.3 6 で確認します。
2. 残りのシーンをエージェントに並行して渡します（各エージェントは scenes/<Scene>.lgv のみを所有します）。ブリーフには kyfram スキルを指定します。
3. エージェントはトークンと家具（drawRoom、drawHero、drawBanner、drawCaptions）について style/$MOTION_STYLE/kyfram/PRELUDE.lgv を読み込み、正確なコンパイル済みスクリプトについてはレンダリング後の out/cache/kyfram/build/<Scene>.lgv を読み込みます。
4. SFX と BGM の配線は以下の Remotion フローに従います。render.sh --voice は、そのファイルが存在すれば public/vo/voiceover.wav を mp4 に多重化します。

ビルドルール: 1080x1920、30 fps。シーンはキットのトランジションシリーズで連鎖します。グローバルレイヤー: VOと音楽の <Audio>、テープバナーの <Boil>、<WordTagCaptions>、<GrainOverlay>。すべてのプロップは <Paper> でラップされ、エントランスは <PopIn> を使用し、各シーンはストーリーボードカメラ内で実行されます。CSSアニメーションは使用しないでください。下部20%はクリアに保ってください。隣接するシーンが同じ背景を共有しないようにしてください。デフォルトのヒーローは箱型のオレンジ色のクリーチャーです（トークン C.hero #D67354、シェード C.heroLo #A9553B、エイリアス you）。アクセサリーとネームピルでキャストを区別します。

5. サウンド

$MOTION_LIB/core/audio/sfx/*.js から名前でSFXを選び、$MOTION_LIB/core/audio/beds/*.json からプリセットでBGMを選びます。kyfram の場合は、最初に kyfram スキルを呼び出し、各シーンのSFX行を tools/cue_sheet.d/<Scene>.json に書き込みます。これは fframes や Remotion と同じ共有サウンドパイプラインを所有します。video/ から:

python3 $MOTION_LIB/core/tools/cues.py && node $MOTION_LIB/core/audio/render.mjs

cues.py はエージェントの行を tools/cues.json にマージし、エアサウンドが2.5秒あたり1つを超える場合にメモを出力します。render.mjs は public/audio/music.wav と fx.wav を書き込みます。

6. レンダリング

プレビュー: cargo run --release -- preview（fframes）、npx remotion studio（remotion）、または kyfram view out/cache/kyfram/build/<Scene>.lgv（kyfram）。要求された場合のみレンダリングし、常にラッパーを介して行います。ラッパーは episode.json からエンジンを選択します:

$MOTION_LIB/core/tools/render.sh        # -> out/<out>.mp4

フラグ: --workers N（デフォルト3）、--conc N、--force、--keep。各シーンはキャッシュされるため、修正後は変更されたシーンのみが再レンダリングされます。キット、計画、音声、またはキャプションの変更はすべてを再レンダリングします。最初の実行では Remotion のヘッドレス Chrome がダウンロードされ、out/cache は数GBの ProRes を消費します。

1つのシーンを修正または再構築するには: src/scenes/<Scene>.tsx を編集し、motion-qa で確認してから、render.sh を再度実行します。

7. 収穫（エピソード後）

python3 $MOTION_LIB/core/tools/harvest.py .       # video/ から; 読み取り専用レポート
python3 $MOTION_LIB/core/tools/catalog.py         # 両方のカタログを再生成

キットの修正、再利用可能なコンポーネント、新しいSFX、および繰り返し発生するビートを library/HARVEST.md の説明に従って昇格させ、library/CHANGELOG.md にエントリを追加します。

• 動きが固かったり濁っていたりする場合は、$MOTION_LIB/style/$MOTION_STYLE/docs/motion-principles.md で該当する原則とそのキットヘルパーを確認してください。

引き渡し

次は motion-qa です。これはプロジェクトの静止画と STORYBOARD.md を読み取ります。ビルド中はシーンごとに、最終レンダリング前にはリール全体に対して1回実行してください。投稿後は、motion-strategy が事後分析を実行します。