XLBen/archival-film

Archival film (档案影像)

程式碼渲染的檔案故事影片，使用真實的檔案素材。每一幀都是透過運算生成（在無頭 Chrome 中的 WebGL，或使用 Python），因此結果可重現、字幕精確無誤，且每個素材來源都經過授權檢查。使用者主導品味；references/style-canon.md 記錄了使用者所有曾要求的風格——請優先閱讀它，它會覆蓋你的預設值。

預設值（僅在使用者要求時才更改）

中文、1080×1920 直式、約 3 分鐘 + 主體剪輯後的片尾。啟用旁白（Edge 神經語音，深沉紀錄片男聲，1.2 倍速——使用者可接受的範圍為 1.1–1.25 倍），朗讀螢幕上的字幕。音樂：整部影片使用一首免版稅曲庫音樂，包含片尾。交付成果 = MP4 + 設計封面 + 抖音與小紅書文案。 記憶體限制：所有渲染/捕捉/模型程序合計最多使用四分之一 RAM（8 GB → 2 GB）。速度慢是可以接受的。

設置（每台機器一次，然後每部影片一次）

• sh scripts/setup.sh → ~/.cache/archival-film/：包含 Python 3.11 虛擬環境（$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/、字型/打字機/node_modules 的連結、網頁套件以及 film.py 範本。執行腳本的方式為 PROJECT=<dir> FILM=film $AF/py <skill>/scripts/<script>.py …。

快速測試模式

當使用者要求製作短暫的測試（「隨便做個10s試試」、樣例、技能測試）時，跳過四個檢查點，保留其他所有內容（真實素材、事實、旁白、音效、視覺風格），並在交付時說明你代替他們做了哪些選擇。一個可運作的 10 秒範例位於 templates/film_collage_example.py（+ templates/cuts_example.json）。

工作流程——使用者的四個檢查點

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. 音樂、色調、視覺風格、聲音 — 從 references/style-menu.md 中提出 2–3 種適合主題的視覺風格、一個大膽簡潔的色板（每個時代 1–2 種強烈顏色 + 黑色 + 紙色；在真實的粗略靜止畫面上展示，而不僅僅是色塊）、整部影片使用一首在網上找到的免版稅曲庫音樂（Kevin MacLeod / FMA / CC0 — references/audio.md；古典樂僅在使用者要求時代音樂時使用；切勿在段落之間更換歌曲——「全局用一個bgm」）其情緒/驅動力需合適（用 scripts/beats.py 測量；商業/科技主題使用輕快的節奏）、以及語音試聽（scripts/narrate.py --audition）。 → 檢查點 2：音樂 + 色板（+ 視覺風格與聲音）。
5. 時間安排 — 使用 Kit.music_bed()（→ scripts/music_edit.py）來配合這首音樂；生成旁白（scripts/narrate.py），修正它報告的任何超時問題，將打字聲音與語音同步（apply_narration）；將剪輯和重拍放在音樂的起始點上。
6. 畫面 — 預設為剪報動畫（collage animation），閱讀 references/collage.md：使用 scripts/cutout.py 將素材切割成碎片（剪刀剪下的人物、撕下的剪報、真實新聞標題、地圖區域），在 film.py 中將這些碎片以 COLLAGE 方式進行動畫（關鍵幀、印刷質感照片/半色調/斑點/填充/墨水/色彩、撕裂、生長、震動、搖晃），使用 scripts/export_web.py 匯出，使用 web/collage.js 渲染。使用一種有意義的重點色，切勿使用統一的棕褐色。在合適的地方加入其他技術（references/style-menu.md 色板；web/example_opening.js 中的破碎與點狀組合，references/looks.md 中的 Python 列印質感）。連續鏡頭的 web/journey.js 已被拒絕作為預設（references/webgl.md）。僅以黑白→彩色的效果進行著色，並予以註明。 使用 scripts/collage_kit.py 來撰寫（字幕來自語音、碎片落在重拍上、按到達時間堆疊）。 或者使用現代特效模組製作影片（web/fx.js、references/fx.md）：點陣變形、傳真照片、暗房效果、動態文字、調查板、影片蒙太奇 + 木刻版畫動態遮罩、墨水流體、像素排序、點雲、人物肖像，加上 hold 和 SVG 引導標記。首先撰寫鏡頭清單——每行：觀眾應該看到的一個主體、在哪裡、提示詞（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 的 78 轉唱片和現場錄音、帶 API 密鑰的 Freesound；記錄授權，自動修剪到 sfx/bank.json）。密集設計：Kit.sfx_events() 在每次碎片著陸和撕裂時放入紙張拍打/猛摔/撕裂聲（Kit.fx_sfx_events() 為特效影片做同樣的事：嗖嗖聲、傳真機、傾倒/潑濺聲、投影機、故障、風聲、按鍵聲）；為每個段落加入環境背景音和劇情內聲音；從公共領域唱片中加入歷史人物聲音（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）

• 僅使用真實的檔案素材；程式碼效果作用於其上。不包含建模對象，不包含自行繪製的徽章。
• 為陌生人講述一個清晰的故事；透過事實展示小人物 vs 大事件，而非說教；不包含 AI 口號；大型文字排版來自原始素材。
• 動畫師的思維：是碎片在移動，而不是鏡頭（飛越式的鏡頭被認為是「爛完了」）；像報紙剪報一樣剪裁素材；不使用推近然後切換；不使用全屏色彩閃爍作為過渡。
• 具有意義的強烈色彩強調——絕不使用統一的棕褐色/黃色覆蓋所有內容；切實地使用效果。
• 每個鏡頭都有一個主體，效果將視線引導到主體上，並落在命名該主體的詞語上——效果是這句台詞的動詞，絕不是為了效果本身或堆砌素材；之間使用簡單的停頓。SVG 僅用於引導標記，絕不用來繪製圖畫。
• 豐富且令人印象深刻的效果——但不繁複，是精煉的裝飾（「太精致」已被拒絕）。先鋒派優於裝飾性。
• 整部影片使用一首通用的免版稅背景音樂（CC BY / CC0，網上找到的），其情緒合適——古典音樂感覺「怪」；旁白語速 1.1–1.25 倍；無「叮」聲；打字機按逐字元方式打字，無鈴聲；密集的實體音效。
• 字幕完整顯示並保持到下一句台詞；色調大膽簡潔；後續的碎片疊加在上面。
• 字幕顯示在實心的底板上，在手機上可讀；一個強烈的主題色；片尾在主體剪輯之後。
• 重製版本與早期版本不共享任何內容（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（為下一個補丁輪次準備的開放項目）。