XLBen/archival-film

Archival film（档案影像）

実在のアーカイブ資料からコードレンダリングされたストーリーフィルム。すべてのフレームは計算されます（ヘッドレスChrome上のWebGL、適宜Python）。そのため、結果は再現可能で、キャプションは正確で、すべてのソースはライセンス確認済みです。ユーザーが方向性を指示します。references/style-canon.mdにはこれまでにユーザーが求めたすべてが保存されています——最初に読んでください。それがデフォルト設定よりも優先されます。

デフォルト（ユーザーが変更を求めた場合のみ変更）

中国語、縦1080×1920、約3分＋メインカット後のクレジット。ナレーションあり（Edgeニューラル音声、深い男性ドキュメンタリートーン、1.2倍速——ユーザーの範囲は1.1～1.25倍）でキャプションを読み上げます。音楽：1つのストックライブラリトラックをフィルム全体に使用、クレジット含む。納品＝MP4＋デザインカバー＋DouyinおよびXiaohongshu向けコピー。 メモリ：すべてのレンダリング/キャプチャ/モデルプロセスを合わせて、最大でRAMの4分の1（8 GB → 2 GB）を使用。処理が遅くなっても構いません。

セットアップ（マシンごとに1回、その後フィルムごとに1回）

• sh scripts/setup.sh → ~/.cache/archival-film/：Python 3.11のvenv（$AF/py：numpy、pillow、onnxruntime、edge-tts）、深度モデル、タイプライター録音、WebGL用のnodeパッケージ。プロジェクトフォルダの外に置かれるため、プロジェクトをクリーンにしてもツールが壊れることはありません。フォント：PROJECT=~/.cache/archival-film/assets sh scripts/fetch_fonts.sh classic。
• sh scripts/new_project.sh <dir> → plates/ depth/ music/ sfx/ footage/ out/ prev/ web/ フォルダを持つプロジェクトフォルダ、リンクされたfonts/typewriter/node_modules、webキット、film.pyテンプレートを作成。スクリプトは PROJECT=<dir> FILM=film $AF/py <skill>/scripts/<script>.py … のように実行します。

クイックテストモード

ユーザーが短い試作品（「随便做个10s试试」、サンプル、スキルのテスト）を求めた場合、4つのチェックポイントをスキップし、それ以外（実素材、事実、ナレーション、サウンド、ルック）はすべて維持し、納品時にユーザーに代わって行った選択を伝えてください。10秒の実例は templates/film_collage_example.py（＋ templates/cuts_example.json）にあります。

ワークフロー — ユーザーとの4つのチェックポイント

1. ブリーフィング — トピック、長さ、制約事項。リメイクの場合、以前のバージョンで使用したものすべてをリストアップし、それらを避けてください（references/narrative.md § リメイク）。
2. 事実と素材 — 出典付き事実リスト；ライセンスを確認して素材を検索・ダウンロード（references/sourcing.md、scripts/cands.py、scripts/fetch_commons.py）；必要に応じてフッテージと修復（references/enhancement.md）；深度マップ（scripts/depth.py）；グリッド目盛り付きコンタクトシート。
3. スクリプト — 知らない人向けにマーケターのように設計する（references/narrative.md）：最初の3秒で矛盾を含む前提、最後に回収される未解決の疑問、未知の名前/場所のアンカー、視聴者の代役、20～30秒ごとのエスカレーション、スピーチ予算内で音読できるように書かれたキャプション（references/narration.md）。 → チェックポイント1：スクリプト。 キャプション全文、フック、未解決の疑問、予定タイトル/カバーの約束を示す。絵の作業の前に承認を待つ。
4. 音楽、パレット、ルック、音声 — 被写体に合った2～3のルックを references/style-menu.md から提案、大胆でシンプルなパレット（時代ごとに1～2の強い色＋黒＋紙；実際のラフな静止画で示す、スウォッチだけではない）、1つのストックライブラリトラックをフィルム全体に使用、オンラインで見つける（Kevin MacLeod / FMA / CC0 — references/audio.md；時代音楽が必要な場合のみクラシック；セクション間での曲変更は禁止 — 「全局用一个bgm」）ムード/ドライブが合っていること（scripts/beats.pyで測定；ビジネス/テック向けは軽快）、音声オーディション（scripts/narrate.py --audition）。 → チェックポイント2：音楽＋パレット（＋ルックと音声）。
5. タイミング — Kit.music_bed()（→ scripts/music_edit.py）で1つのトラックに合わせる；ナレーションを生成（scripts/narrate.py）、報告されたすべてのオーバーランを修正、音声にタイピングを同期（apply_narration）；音楽のオンセットにカットとヒットを配置。
6. 絵 — デフォルトはコラージュアニメーション（剪报画）、references/collage.mdを読む：scripts/cutout.pyで素材をピースに切り（ハサミで切ったフィギュア、引き裂かれたクリッピング、実際の見出し、地図領域）、ピースをアニメーション（カメラは動かさない）COLLAGEとしてfilm.py内で（キーフレーム、プリントルック photo/halftone/spot/fill/ink/color、tear、grow、jolt、wobble）、scripts/export_web.pyでエクスポート、web/collage.jsでレンダリング。意味のあるスポットカラー1色、均一なセピアは禁止。他のテクニックを適宜追加（references/style-menu.mdパレット；シャッターとドットアセンブリはweb/example_opening.js、Pythonプリントルックはreferences/looks.md）。連続カメラweb/journey.jsはデフォルトとして却下されています（references/webgl.md）。カラー化はB&W→カラー効果としてのみ、クレジット付き。 scripts/collage_kit.pyで記述（音声からのキャプション、ビートに着地するピース、到着順にスタック）。 または、モダンエフェクトモジュールからフィルムを作成する（web/fx.js、references/fx.md）：ドットモーフ、ワイヤーフォト、暗室、キネティックタイポ、調査ボード、フッテージモンタージュ＋木版ロトスコープ、インクフルイド、ピクセルソート、ポイントクラウド、キャラクターポートレート、さらにholdとSVGガイドマーク。最初にショットリストを書く — 各行ごとに：見るべき1つの被写体、場所、キューワード（Kit.W）、効果が視線をそこに導く方法、その効果がその行に意味する理由；意味がない場合はhold。効果はキューワードでピークに達し、クリーンな被写体に解決する（「特效要有明确的视觉引导，而不是堆砌素材」）。scripts/fx_plan.py → Kit.fx_cuts()で記述、scripts/fx_sheet.py（seeが最初に見えるものか？）で各フレームをチェックしてからレンダリング。モダン/ビジネス/テックの被写体には、チェックポイント2でコラージュの隣に提案する。 → チェックポイント3：静止画/サンプル。 主要静止画のコンタクトシートと10～20秒のサンプル（音声付き）を送信。またはメモリが厳しい場合やユーザーが全体を見たい場合にはラフカット（scripts/rough.py、約150 MB）としてフィルム全体を送信。
7. サウンド — すべての効果音は、scripts/fetch_sfx.pyでオンラインで見つけた実際の録音（Commons、Internet Archive 78sおよびフィールド録音、キー付きFreesound；ライセンス記録、自動トリミングでsfx/bank.jsonに）。密度の高いデザイン：Kit.sfx_events()はすべての着地と引き裂きに紙の叩く/バタン/引き裂く音を配置（Kit.fx_sfx_events()はエフェクトフィルムでも同様：ひゅー、ラジオファックス、注ぐ/バシャ、プロジェクター、グリッチ、風、キー）；セクションごとにアンビエンスベッドとダイジェティックサウンドを追加；PDレコードからの時代音声（references/audio.md、scripts/sfx_build.py）。 → チェックポイント4：サウンドリスト。 最終レンダリングの前に、効果音と時代音声のリストを時間と出典と共に送信する。
8. レンダリングとミックス — scripts/run_chunks.py（メモリ予算内、失敗したチャンクは再実行）、連結、その後scripts/mixdown.py --voice …（音声ダッキング、−14 LUFS / −1 dBTP）。
9. 納品 — 確認（references/verification.md）、その後MP4、カバー、プラットフォームコピーを送信（references/platform-copy.md）；ユーザーがスマートフォンからフォローする場合、30 MB未満の720pプレビューも。

このユーザーにとって最も重要なこと（簡略版；理由はstyle-canon.mdに）

• 実在のアーカイブ素材のみ；コード効果はそれに作用する。モデル化されたオブジェクト、自作のエンブレムは禁止。
• 知らない人にとって明確なストーリー；事実によって示される大きな出来事の中の小さな個人；説教しない；AIスローガン禁止；大きなタイポグラフィックワードはソースから。
• アニメーター的思考：ピースが動き、カメラは動かない（フライスルーは「烂完了」）；新聞のコラージュのように素材を切る；ズーム＆カット禁止；全フレームのカラーフラッシュ遷移禁止。
• 意味のある強い色の強調 — 決して均一なセピア/イエローで全体を覆わない；効果を実際に使う。
• すべてのショットには、効果が視線を導く1つの被写体があり、それを名指す単語のタイミングで — 効果は行の動詞として、決して自己目的や素材を積み上げるためではなく；その間はプレーンなホールド。SVGはガイドマークのみ、絵を描くためには使わない。
• 豊かで印象的な効果 — しかし気取らず、洗練された装飾（「太精致」は却下された）。前衛的で装飾的なもの。
• 1つの汎用ストックバックグラウンドトラックをフィルム全体に使用（CC BY / CC0、オンラインで見つける）、そのムードが合っていること；クラシックは「怪」と感じられた；ナレーション1.1～1.25倍；「ding」禁止；タイプライターは打鍵ごと、ベルなし；密度の高いリアルサウンド。
• キャプションは完全で、次の行まで保持；パレットは大胆でシンプル；後のピースは上に。
• キャプションはソリッドな背景の上に、スマートフォンで読めるように；1つの強いテーマカラー；クレジットはメインカットの後。
• リメイクは以前のバージョンと何も共有しない（scripts/overlap_check.py）。

ファイル

• scripts/ — 画像：render_print.py anim.py futur.py captions.py cjkwrap.py base.py cfg.py；素材：cands.py fetch_commons.py fetch_ia.py depth.py cutout.py fetch_fonts.sh；コラージュ/エフェクトフィルム：collage_kit.py fx_plan.py fx_sheet.py rough.py；オーディオ：fetch_sfx.py beats.py onsets.py music_edit.py narrate.py sfx_build.py mixdown.py；WebGLブリッジ：export_web.py；レンダリング：run_chunks.py；チェック：contact.py grid.py overlap_check.py；環境：setup.sh new_project.sh。
• web/ — index.html（?scene=NAMEをロード）、fx.js＋fx/*.js（モダンエフェクトモジュール、fx/hold.jsプレーン画像、fx/guide.js SVGガイドマーク）、collage.js（デフォルトの切り抜きアニメーションシーン、out/timeline.jsonで駆動）、captions.js（共有キャプションスラブ）、journey.js（連続カメラシーン、デフォルトとして却下）、example_opening.js（古い手作りシーン：シャッター、ドットフィールド — その効果を再利用、カット/フラッシュは再利用しない）、capture.mjs（決定論的キャプチャ）、package.json。
• templates/film_template.py — フィルムモジュールフォーマット（ショット、キャプション、プリント仕様、サウンドイベント、クレジット）；templates/film_collage_example.py＋cuts_example.json — 完全な10秒コラージュフィルム（サンフランシスコ1906年）；templates/film_journey_example.py — その古いジャーニーバージョン。
• references/ — style-canon、narrative、narration、style-menu、collage、looks、webgl、audio、sourcing、enhancement、platform-copy、verification、known-gaps（次のパッチラウンドのための未解決項目）。