yt-film

yt-film：從靜止圖片製作的敘事影片

一個專為故事影片設計的生產線：使用者從 Claude 編寫的指南中製作約 150 張靜止圖片，Claude 根據這些圖片編寫劇本，語音朗讀，然後 Python 引擎 讓每張圖片隨著文字動起來。參考影片是 Chadwick 範例（examples/chadwick/，卡內基的女兒：那位冒充安德魯·卡內基秘密女兒、借走數百萬美元的女性）：它的圖片、劇本、語音、配樂、鏡頭列表以及 70 秒的效果測試影片（examples/chadwick/video/chadwick_effects_test.mp4）展示了所有技巧。

REPO 指的是此技能所在的資料夾（也就是這個檔案所在的位置）。PY 指的是它的 Python 直譯器：macOS/Linux 上是 REPO/.venv/bin/python，Windows 上是 REPO\.venv\Scripts\python.exe。始終從專案的 tools/ 資料夾，使用 PY 來執行引擎指令。如果 .venv 不存在，請先設定：按照 references/install.md 中的 安裝操作手冊（給 Claude 用） 逐步進行（在進行系統範圍安裝前先詢問；使用者會自己貼上他們的 API 金鑰）。

基本規則

• 未經使用者同意，絕不進行渲染。 使用 stills.py 進行檢查（約 30 秒內生成一張聯絡表）。批次渲染、預覽、結尾和最終合成需要幾分鐘到幾小時：說明你要渲染的內容以及可能需要多久時間，然後等待肯定的回覆。不要重新渲染任何已渲染過的內容，除非它已更改且使用者希望如此。
• 每個專案向使用者詢問一次他們的路線：使用哪個圖片工具（references/image-generation.md）、語音（Gemini TTS 或他們自己的：references/voice.md）、音樂（Lyria 或他們自己的：references/music.md）、他們的利基市場和頻道名稱，以及三個能讓他們的頻道與眾不同的選擇：圖片風格（開場：水粉、平面編輯、黑色電影、粉筆、漫畫、故事書、藍圖，或他們自己的；有或沒有角色）、引擎外觀（YTF_LOOK：gouache、clean、noir、chalk、comic、storybook、blueprint；look.json 用於單一值）以及格式（story、explainer、countdown、rise-fall、storytime、kids、summary、case-study、news）：請參考 references/art-styles.md、references/formats.md。不要預設使用範例的柔和真實故事風格；如果使用者沒有偏好，用一個簡短的表格顯示選項，並推薦一個適合他們利基市場的風格。
• 使用者的利基市場是他們自己的：不要引導他們去歷史或範例的主題。範例是作為技巧的參考，而不是主題的模板。
• Windows：使用正斜線的路徑可以運作；長時間的作業在背景執行；速度設定在 references/performance.md 中。永遠不要預設只有 macOS 才有的工具。
• 除了 .env 檔案之外，不要在檔案中儲存 API 金鑰。只有在使用者同意後，才下載真實的照片或音效檔案（說明檔案、來源、大小和授權）。

技術棧

工作	工具	位置
研究	網路搜尋，附帶來源的驗證事實清單；標記無法確認的內容	OUTLINE.md
圖片	使用者的圖片工具，根據 Claude 的指南	IMAGE_GUIDE.md（+ 給 API 用的 IMAGE_PROMPTS.jsonl）、incoming/
劇本	Claude，根據圖片指南編寫，每個段落一個 ## 部分，附帶 [SHOTS: …] 備註	SCRIPT.md
語音	Gemini TTS（Orus 語音，慢速朗讀 → 1.25 倍速，限制停頓長度）或 使用者的音訊，透過 import_voice.py 匯入	tools/voice.py、tools/import_voice.py
文字時間戳	Whisper：mlx-whisper（Apple Silicon）或 faster-whisper（Windows/Intel/Linux）	voice/<batch>_words.json
音樂	Lyria（Gemini API），每個區段一首提示，或 使用者已授權的曲目	tools/music.py → audio/music/
電影引擎	Python（OpenCV、Pillow、NumPy、SciPy），無 After Effects	tools/film.py、fx2.py、seq.py、signature.py、wr.py、kit.py
鏡頭列表	seq.py 上每個批次一個檔案，根據該批次的文字時間觸發	tools/<story>.py + tools/shots_bN.py
渲染	平行處理，根據機器規模調整，低優先順序	tools/render_all.py
結尾	使用者自己製作的動畫簽名（範例：cta.py）	renders/cta.mp4
最終合成	批次 + 結尾，一首連續的配樂，−14 LUFS / −2 dBTP	tools/final.py
配音	預設為西班牙語 + 法語：Gemini 翻譯 + TTS，以約 3 分鐘為單位處理，配合英語時間槽	tools/dub.py
縮圖	使用者的圖片工具，根據指南	references/thumbnails.md

專案存放在 YTF_WORKSPACE（預設為 ~/yt-film-projects/<story>/）中，由 PY REPO/scripts/new_project.py <story> 建立，該指令會將引擎複製到 tools/ 中並建立所有資料夾。設定儲存在 .env（專案優先，然後是 REPO）：GEMINI_API_KEY、YTF_CHANNEL、語音/模型名稱、速度調節旋鈕（.env.example 列出所有項目）。engine/ytf.py 會在任何作業系統上找到字型、金鑰、Whisper 以及共享的美術資源。

工作順序

0. 如果未指定，挑選一個故事：3–5 個候選方案，並進行缺口檢查（references/story-finding.md）。使用其格式和外觀初始化專案：PY REPO/scripts/new_project.py <name> --format <format> --look <look>（將格式的骨架模板寫入 OUTLINE.md、將 YTF_FORMAT 和 YTF_LOOK 寫入 .env）。在編寫完整指南之前，先用 stills.py 在兩張圖片上測試新風格（references/art-styles.md，最後一節）。
1. 故事與事實：進行研究；OUTLINE.md 包含來源。標記任何未經證實的內容，並在之後用文字繞過去（「據報導」），絕不能將其陳述為事實。決定鉤子（references/hooks.md：絕不能與使用者最近三部影片的鉤子類型相同）。然後在 OUTLINE.md 的頂部寫下故事主幹（references/storytelling.md）：影片回答的一個問題，以及 8–12 個由「所以」/「但是」連接的節拍；在影片約 15% 處出現第一個錯誤的行為或決定時刻；每個主要人物有一到兩個背景故事段落。在製作圖片指南之前先展示給使用者看。
2. 先製作圖片指南（references/image-guide.md，為使用者的路線編寫）。它遵循故事主幹以及影片的敘述方式（展示，然後繪製：每個節拍的列標明它所服務的臺詞以及在臺詞上或之後繪製的內容）。目標是約 150 張圖片：風格卡、演員表、約 100 個場景鏡頭（包括各種景別：W 廣角、M 中景、F 臉部特寫作為 EDIT、D 細節、P 視點）、6 個帶有 _lines 版本的場景、12 張草圖頁 + _lines、約 10 個空白的故事物件（「基底」：筆記本、舊地圖、卡片、分類帳、信封、電報、報紙）。準確的檔名和資料夾。一致性規則：references/consistency.md。
3. 隨著圖片分批到達進行檢查（手、臉、時代細節、無文字、形狀：圖片大約是 16:9，並被中心裁切為 2:1，所以任何重要內容都不能在非常頂部/底部）。手動下載：scripts/sort_images.py。然後在引擎像素中製作網格頁面（COLS=4 PY tools/egrid.py out.png IMG ...），並在編寫鏡頭之前，繪製每張圖片的煙囪、燈、蠟燭、呼吸和靜止區域。
4. 根據圖片編寫劇本。 使用每一張生成的圖片；將每個段落對應到它的鏡頭，並執行未使用圖片檢查（範例：examples/chadwick/tools/script_check.py），然後執行 PY tools/story_check.py（口述日期、場景轉換開場、[DRIVE] 段落出現的位置、每個批次的接縫）以及 references/storytelling.md 中的檢查（複述、15%、但是/因此、無堆疊的解說、5–7 個口述日期、展示 → 繪製）。無長度限制：完整且從容地講述故事（每分鐘約 150 字；Chadwick：1,780 字 → 12 分鐘）。以使用者的按讚/訂閱呼籲結束。
5. 語音：Gemini（先使用 voice.py --test，然後批次處理；使用 --pace 和 SPEEDS，讓每個批次保持在約 140–160 wpm）或使用者的音訊（import_voice.py --full | --passages | --batches）。設定 BATCHES（4–7 個段落，每個約 65–100 秒，在故事進展中切斷；只在幕間切換 2–3 次；在一個批次的開始不要重新引入任何內容）和 GAPS。在為其編寫鏡頭之前，先列印每個批次的文字（Whisper 會誤聽名稱並將數字寫成數字形式：根據它實際寫出的內容來觸發）。
6. 音樂：5–7 個提示（music.py，或使用者在 audio/music/ 中的檔案）；在 final.py 的 MUSIC 中將提示對應到批次。
7. 每個批次使用 seq.py 建立鏡頭列表（references/engine.md、examples/chadwick/tools/）：一個電影模組（<story>.py，類似 chad.py）包含 LIVE 表格（每張圖片的動態圖層）和地圖設定；每個 shots_bN.py 是大約 60 行的 S.at(time, scene(...)/page(...)/drawin(...)/map_shot(...))。使用 PY tools/stills.py bN 檢查每個批次，並在渲染任何內容之前查看聯絡表。
8. 渲染（經使用者同意）：PY tools/render_all.py 會平行執行所有批次，一次執行的數量取決於機器可用的記憶體（每個渲染約需 1.5 GB；一旦記憶體耗盡，同時執行更多批次會變慢）；在修正之後，使用 render_all.py b3 b7 或 --changed。在獨立視窗中啟動它，這樣關閉 Claude 就不會停止它，並在渲染速度慢或電腦延遲時（特別是 Windows）遵循 references/performance.md。先在兩個影格上測試新的轉場或效果（後期崩潰會浪費渲染成果）。
9. 每個頻道一次結尾（references/cta.md），然後 最終合成 PY tools/final.py；在 MP4 上檢查長度、fps、響度（−14 LUFS，峰值 ≤ −1.5 dB）以及取樣靜止畫面（references/final-render.md）。
10. 配音（references/dubs.md）和 縮圖（references/thumbnails.md），如果需要。

外觀（範例的預設值；每個頻道選擇自己的）

• 範例：蛋頭人（蛋形頭、兩個深色橢圓眼睛、一條線的嘴巴、無鼻子/耳朵/眉毛、簡單圓潤的手）在一個符合時代的真實世界中；墨水線條 + 霧面柔和水粉；引擎外觀 gouache。其他頻道選擇自己的圖片風格、角色（或無）和引擎外觀（references/art-styles.md）；以下規則適用於所有風格。
• 引擎外觀設定添加的圖層：色調、顆粒、暗角、墨水、標籤紙、強調色、字型、繪圖音效（engine/look.py：YTF_LOOK、look.json）。當外觀已經指定了顏色或字型時（look.rgb("accent")、look.L.type_font），切勿在鏡頭檔案中硬編碼顏色或字型；一個頻道的外觀必須在一個地方進行更改。
• 沒有 2.5D、沒有剪貼圖、沒有 AI 影片。 單一圖片搭配緩和的相機移動（推近、平移、緩慢漂移）。
• 不要讓一張圖片停留太久：切換到下一個當下時刻的鏡頭（W→M→F→D→P）或切換到繪製的頁面。
• 草圖解說員是真實的繪圖，而不是圖示：從草圖頁的線稿中提取，或由引擎在程式碼擅長的地方進行繪製（準確的地圖、路線、標記、簡單的圖形）。
• 空白基底會在它們自己的媒介上被即時繪製：紙上的石墨、黑板上的粉筆、筆刷墨水、半色調照片印在報紙上、地圖上的墨水路線。
• 線條承載意義：年份的計數標記、聲波環、飄落紙張的路徑、煙霧線條、被劃掉的人物。
• 標籤（日期、地點、名稱）是水平打字的文字，使用該外觀的打字機字型（在 gouache 中使用打字機字型），一次打出一個字元，並帶有輕柔的喀噠聲。
• 物體上的文字位於該物體的真實線條上，並以其角度呈現；在其下方難以辨認的印刷文字會先被擦除（fx2.clean_text）。
• 始終有對比：不要在深色背景上放置深色物體。標籤會自動選擇奶油色/墨水色並帶有光暈。切勿在未檢查下方內容的情況下強制使用 color="ink"。
• 工具精靈很小（0.28 比例），因此永遠不會搶走焦點。

標誌性動畫（全部在靜止圖片上以程式碼實現）

engine/signature.py、engine/fx2.py、鏡頭輔助工具 engine/wr.py、engine/seq.py。examples/chadwick/look/ 中每種都有一個靜止畫面範例；所有動畫效果都在效果測試影片中。

• 動態靜止畫面（圖片本身不動；圖層在其上活動）：每個煙囪冒出的粒子煙霧、寒冷中的呼吸、活生生的火焰及其投射的光線、圖片中本身找到並正在呼吸的燈（fx2.lamps）、雪、雨、落葉、閃光。不要在煙霧、蒸汽、火或水上使用像素扭曲（sg.Flow）：它會弄髒繪畫（look/flow_smear_avoid.png）。
• 只在關鍵處活動的臉部：沒有自動眨眼或表情。只有在鏡頭傳遞 act= / talk= 參數時，臉部才會有表情，而且只有具有一對匹配的眼睛的臉部才可以（sg.face_audit([...], out.jpg)：只在兩隻眼睛都被綠色環標記的地方進行表情動作）。提示：blinks、glances、widen、mouth_fx、expr（微笑、露齒笑、皺眉、O 型嘴、笑、閉眼、瞇眼…）、talk=(ta, tb)、反應標記（sweat、shake、!、?、zzz）。每個批次只有少數幾個真實的節拍，絕非裝飾。
• 空白板上的漫畫頁面（sg.Comic）：邊框自行上墨，每個面板先上墨再上色，鏡頭會瀏覽各個面板並潛入最後一個面板。每部影片兩個（鉤子、第一個大場景）。每個面板持續時間 ≥ 1.8 秒。
• 即時繪製的圖畫（fx2.Draw）：一張草圖頁按照其筆劃順序進行墨水繪製（鋼筆精靈和音效），然後其顏色渲染進去；card=True 會先在雜亂的圖片上鋪上一層柔和的奶油色底色。一張草圖頁絕不以一次顯示四個圖畫的方式呈現：每個圖畫在敘述者提到它時出現，並由箭頭和簡短的打字標籤連接。
• 解說卡（重複使用一個基底）：名稱被打出並劃掉，一個機制以一系列帶有箭頭的圖畫呈現，三個圖畫搭配三個詞語。
• 標記詞彙，根據意義選擇，每次不要使用相同的標記：底線、勾選記號、交叉、括弧、動作線條、聲波環、路線（虛線路徑 + 箭頭）、引導線（點、線、打字標籤）、計數標記；sg.Stamp（橡皮圖章的砰聲：偽造、關閉、14 年）、sg.Tag（撕破的紙標籤）、sg.Inset、sg.Flip（翻頁式）、sg.Pin、fx2.Counter（滾動的錢幣計數器）。
• 有重量的效果（每個批次少數幾個有感的時刻）：fx2.Lift（從圖片中切出一個物件並對其進行動畫處理，fill_from= 會用克隆填補空洞）、fx2.Tear（圖片被撕成兩半）、("shatter", s, (cx, cy)) 轉場、sg.Papers（翻騰的紙張）、火焰 + 打火、震動 + 砰聲、按壓閃光燈 + 快門聲、sg.Rays、sg.Haze。
• 活地圖（seq.map_shot）：真實的海岸線自行上墨，水域渲染進去，邊界以虛線繪入，湖泊和城鎮名稱被打出，一條紅色的旅行……