papercut-build

Papercut のビルド

Remotion プロジェクトをゼロから作成するのではなく、ライブラリを使って各エピソードをビルドします。library/README.md を一度読んでください。

事前確認

• インストール：Standard または Full が必要です。ライブラリ、node 20 以降、npm、ffmpeg、Python ツール（numpy、Pillow、soundfile）、音声レンダリング用の Chrome または Chromium が必要です。papercut-explainer にあるコマンドで確認してください。不足しているものがある場合は、./install.sh --doctor を実行し、papercut-setup に引き継いでください。
• ライブラリ：$PAPERCUT_LIB、それがなければ ~/.config/papercut-explainer/config.env 内の PAPERCUT_LIB= の行、それもなければ一度だけ確認してください。ライブラリがまったくない場合は、../papercut-explainer/references/remotion-recipes.md のスケッチをもとにビルドしてください。
• Remotion のベストプラクティススキル（Remotion プラグインの remotion-best-practices、または npx skills add remotion-dev/skills -g -y -a <your harness id>。install.sh --mode standard でもインストールされます）を最初に読み込み、マークアップ、字幕、Studio に関するルーティングに従ってください。
• 先行ステージで作成した papercut/STORYBOARD.md と narration/script.json が必要です。
• ツールチェーン全体のスモークテスト：library/tools/selftest.sh は、一時フォルダーに examples/hello-reel/ をビルドし、静止画を 1 枚レンダリングします。

1. スキャフォールド

$PAPERCUT_LIB/new_episode.sh <series-dir> NN-slug CompId [out-name]

<series>/episodes/NN-slug/{research,narration/voice,papercut} にテンプレートプロジェクトと、キットを同期したコピーを src/lib/ に作成します。node_modules は $DONOR、それがなければ最新の兄弟エピソードから取得し、それもなければ npm i でインストールします。<series>/papercut-assets/ が存在する場合は、デフォルトのテクスチャと小道具に重ねて適用します。

先行ステージで research/、narration/script.json、papercut/STORYBOARD.md が作成されているため、フォルダーはすでに存在する場合があります。スクリプトは既存ファイルにマージし、ファイルを上書きすることはありません。papercut/package.json が存在する場合（すでにスキャフォールド済みの場合）にのみ停止します。

プロジェクト内の src/lib/ は決して編集しないでください。これはスナップショットなので、ライブラリが変更された後も古いエピソードは同じようにレンダリングされます。ライブラリを修正してから、papercut/sync_kit.sh で再同期してください。

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

ストーリーボードをもとに、papercut/episode.json を記入します。

• scenes：[["S01Hook", "l1_hook", 0], ["S02Name", "l2_name", "called"], ...]（シーン ID、ナレーション行 ID、インデックスとしての最初の単語、または完全一致する単語）。
• banners：{"S01Hook": "TAKEAWAY IN CAPS"}。hook については papercut-hook を参照してください。cuts は Camera / Cut テーブルのカット列です。bed、whipScene、cutSfx、gaps（行の後に追加する間、秒単位）も設定します。

次に、タイミングのステップまで papercut-voice を実行します（最後に build_vo.py と timing_md.py が実行されます）。その後、papercut/ から次を実行します。

python3 $PAPERCUT_LIB/papercut/stubs.py        # src/scenes/index.ts + a stub per scene

build_vo.py は 1.2 秒未満のシーンにフラグを立てます。その場合は隣のシーンと結合してください。timing_md.py は STORYBOARD.md の Timing セクションに絶対フレーム数と単語キューを書き込み、エージェントが plan.json を開かなくても済むようにします。

3. アセット

../papercut-explainer/references/asset-prompts.md に従ってください。背景と複雑な静的な小道具には画像ツール（透明 PNG を出力できるものなら何でも）、キャラクター、すべてのテキスト、タグ、ゲージ、ボタン、UI にはコードを使います。生成画像にテキストを含めないでください。画像ツールがない場合は、ペーパーフィルターを使ってすべての小道具をコードで作成してください。スタイルは十分に保てます。背景にはライブラリの <Backdrop> セット（library/papercut/public/bg/backdrops/_sheet.jpg）を使ってください。ライブラリにない場所が必要なエピソードに限り、新しい背景を生成してください。証拠スクリーンショットは node $PAPERCUT_LIB/tools/capture.mjs <url> public/proof/x.png で作成し、キットの RealShot で表示します。

4. シーン

1. まず、HOOK ブロックをもとに S01Hook を自分で作成します。これはエージェントが合わせる基準シーンです（キュー定数、カメラ、クランプされた interpolate）。
2. 残りはシーンごとにまとめて、シーンエージェントに並行して任せます（各エージェントに 2〜3 シーン。エージェントを増やすほど、起動時に必要なコンテキストも増えます）。ハーネス用に install.sh が配置した papercut-scene エージェントを使用してください（Claude Code ~/.claude/agents、OpenCode ~/.config/opencode/agents、Codex ~/.codex/agents、Gemini CLI ~/.gemini/agents）。汎用エージェントでも構いません。ハーネス独自の方法で起動します（Claude Code の Task ツール、opencode のサブエージェントツール、Codex のサブエージェント、Gemini のエージェントツール）。ハーネスにサブエージェントがない場合は、同じ順序と同じブリーフに従って、シーンを 1 つずつ自分で作成してください。時間はかかりますが、作業内容は変わりません。ブリーフは library/papercut/AGENT_BRIEF.md です。起動メッセージには、プロジェクトのパス、各エージェントが担当するシーンと絶対フレーム範囲、QA フォルダー名、$PAPERCUT_LIB の値を指定します。
3. ファイルの担当範囲：エージェントが書き込めるのは src/scenes/<Scene>.tsx、任意の <Scene>.parts.tsx、および tools/cue_sheet.d/<Scene>.json のみです。src/lib/**、他のシーン、index.ts、plan.json、episode.json、ストーリーボードには決して手を加えないでください。
4. エージェントにはキットのソースではなく、library/papercut/CATALOG.md と library/audio/CATALOG.md を読ませ、何か新しく描く前にコンポーネント、プロップセット、シーンテンプレート（kit/scenes/。たとえば CTA には CtaPhoneDM）を再利用させます。

ビルドルール：1080x1920、30 fps、シーンはキットのトランジション系列に沿って連結します。グローバルレイヤー：VO と音楽には <Audio>、テープで貼ったバナーには <Boil>、<WordTagCaptions>、<GrainOverlay> を使用します。すべての小道具は <Paper> でラップし、登場には <PopIn> を使用します。各シーンはストーリーボードのカメラ内で動作させます。CSS アニメーションは使用しません。下部 20% は空けておきます。隣接するシーンで背景を共有してはいけません。デフォルトの主役は、オレンジ色で箱型の生き物です（トークン C.hero #D67354、シェード C.heroLo #A9553B、エイリアス you）。アクセサリーや名前ピルで登場人物を区別します。

5. サウンド

library/audio/sfx/*.js から名前で効果音を選び、library/audio/beds/*.json からプリセットでベッドを選びます。papercut/ から実行します：

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

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

6. レンダリング

Studio でプレビューします（npx remotion studio）。指示された場合にのみレンダリングします：

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

フラグ：--workers N（デフォルト 3）、--conc N、--force、--keep。各シーンはキャッシュされるため、修正後は変更したシーンだけが再レンダリングされます。キット、プラン、音声、または字幕を変更すると、すべてが再レンダリングされます。初回実行時には Remotion のヘッドレス Chrome がダウンロードされ、out/cache は数 GB の ProRes を使用します。

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

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

python3 $PAPERCUT_LIB/tools/harvest.py .       # from papercut/; read-only report
python3 $PAPERCUT_LIB/tools/catalog.py         # regenerate both catalogs

library/HARVEST.md の説明に従って、キットの修正、再利用可能なコンポーネント、新しい効果音、繰り返し使える演出を昇格させ、library/CHANGELOG.md に項目を追加します。

• 動きがぎこちない、またはぼやけて見える場合は、../papercut-explainer/references/motion-principles.md で該当する原則とキットのヘルパーを確認します。

引き継ぎ

次は papercut-qa です。プロジェクトと STORYBOARD.md から静止画を読み込みます。制作中はシーンごとに実行し、最終レンダリングの前にリール全体でも一度実行してください。投稿後は papercut-strategy が事後分析を行います。