yingwang/inktofilm

inktofilm 是做什麼的？

將一個自然語言提示視為完整的起點。使用者無需編寫程式碼、執行命令、理解模型或準備劇本。

使用者體驗

• 從使用者的點子開始。當缺少重要的創作方向時，做出一個強而有力的預設值或提供一個簡潔的概念供批准；只問那些會實質改變電影的問題。
• 代理程式代為執行設定、規劃、生成、評估、重試和編輯。除非使用者要求，否則不揭露內部命令、提供者承載或實作細節。
• 當持續時間和格式未指定時，預設為一個完整的 30 秒、16:9 的電影短片或預告片。對於長片或影集，首先建立一個經過批准的短片概念驗證，然後以章節或劇集的形式繼續，並配備共享的角色和世界聖經。

私有設定與付費生成

使用現有的 InkToFilm 檢出（checkout）。否則，從 https://github.com/yingwang/inktofilm 準備一個專案本機檢出和專案本機環境；請勿修改不相關的系統配置。在開始製作前，驗證 FFmpeg、FFprobe 和 fal 用戶端；inktofilm doctor 會報告缺少哪些項目。

1. 在流程環境中尋找 FAL_KEY，然後在專案本機的 .env 中尋找。CLI 只讀取環境變數，因此將檔案載入到執行它的 shell 中，例如使用 set -a; . ./.env; set +a，並且切勿列印該值。
2. 如果缺少，請向使用者索取一次他們的 fal API 金鑰。當可用的登入瀏覽器時，提議建立並複製一個 API 範圍的金鑰，並在明確批准後使用，而不是讓使用者在聊天中暴露它。
3. 切勿回顯、記錄、摘要、放入提示或提交金鑰。僅將其儲存在一個被忽略的本機 .env 檔案中，權限設為 0600，並在提交或推送之前驗證 Git 忽略了該檔案。
4. 讀取目前的提供者定價，估算生成的秒數和重試配額，陳述一個嚴格的支出上限，並在第一次付費請求之前立即獲得確認。在超過批准的限額之前停止。fal 對 MiniMax H3 Max 按生成的秒數計費，對靜態影像按 nano-banana 計費，因此一個包含靜態影像和幾次重試的五鏡頭 30 秒電影通常花費幾美元；請查閱模型頁面以獲取當前費率，而不是假設。

製作電影

使用運行此技能的代理程式進行創意和評判工作，並使用 fal MiniMax H3 Max 作為預設的影片生成器，同時尊重使用者明確選擇的任何模型。

• 在 Claude Code 中，您既是規劃者也是評審。自行編寫劇本、計劃和測試套件，並按照以下階段進行，以便在影片額度花費之前先審視每個影像。要評判一個鏡頭，使用 inktofilm frames 取樣評估器使用的相同均勻間隔的畫格，直接檢查它們，編寫已審查的逐個案例結果 JSON，並使用 inktofilm run suite.json --semantic-results 重播它。僅對取樣畫格中可見的內容進行評分，並在結果來源中記錄您自己的模型名稱。
• 在 Codex 中，CLI 的內建整合透過已驗證的 Codex CLI 執行相同的工作：inktofilm run --semantic-codex 用於評判，以及 inktofilm produce 的預設規劃者和評審。
• 當使用者希望運行無人值守完成時，將評判交給 CLI 而不是在迴圈中進行：inktofilm run --semantic-claude 或 inktofilm produce --judge-claude，這只需要 Claude Code 和一個 fal 金鑰。當您已經在場時，建議在迴圈中進行評判，因為它會花費一個模型而不是兩個，而且您可以注意到沒有斷言恰好詢問到的內容。
• 任何其他模型都可以透過 JSON stdin/stdout hooks 接入：--semantic-command、--planner-command、--judge-command 和 --video-command。
• 無論哪個評審運行，它只對計劃編寫的斷言進行評分。為實際重複出現的失敗編寫斷言，包括發明的螢幕文字、烘烤在畫格中的信箱模式、偏離正確文化的服裝，以及與場景矛盾的臉部表情。

階段性工作流程

inktofilm produce 是可恢復的：已存在於輸出目錄中的肖像、靜態影像和鏡頭嘗試將被重用，因此相同的命令可以在審查後再次運行，並且只為缺失的工作付費。

1. 自行編寫 script.md 和 plan.json，然後執行 inktofilm produce script.md --plan plan.json --stills-only -o <project>。這會為每個角色渲染一張肖像，為每個鏡頭渲染一張靜態影像，然後停止。打開每個影像。一張不是該角色的肖像、一個構圖錯誤的靜態影像、一張年齡錯誤的臉、一個多餘的人或道具上的文字，在這裡修復成本很低，但在剪輯中修復成本很高：刪除該檔案，強化其提示詞，然後再次運行相同的命令。
2. 當您將在工作迴圈中進行評判時使用 --no-judge 拍攝，或者當運行無人值守時使用 --judge-claude。--no-judge 會執行媒體檢查，選擇每個鏡頭的最新嘗試，為選定的剪輯編寫 suite.json，並組裝一個簡單剪輯的 final.mp4。
3. 對於每個鏡頭，inktofilm frames shots/<shot>-attempt-1.mp4 會取樣評審將看到的畫格。檢視它們，編寫已審查的結果檔案，並使用 inktofilm run suite.json --semantic-results reviewed.json -o review 重播它。
4. 僅重新生成失敗的內容：--reshoot <shot_id> 會為該鏡頭進行一次新的嘗試，編號接續磁碟上的現有編號，而其他所有內容都將被重用。當失敗是提示詞的錯時，先編輯提示詞。根據舊的拍攝來評判新的拍攝，而不是假設它更好；當較早的拍攝勝出時，--select <shot_id>=<attempt> 會使其再次成為該鏡頭的剪輯，因此清單、suite.json 和 final.mp4 都遵循審查者的選擇。
5. 當電影需要的不僅僅是簡單剪輯時，請自行使用 FFmpeg 組裝最終剪輯：重疊、聲音橋接、對話和本機排版的標題卡。

撰寫能通過生成的提示詞

• 每個影片提示詞中的演員聖經僅涵蓋鏡頭列表中出現的角色，因此請列出它們。一個描述整個演員陣容的單角色鏡頭傾向於讓其他角色出現在背景中。
• 參考肖像會按照鏡頭 characters 的順序傳遞給靜態影像編輯器。在靜態提示詞中按該順序引用它們，例如「來自第一張參考影像的女性」，並仍然重新說明她的頭髮、皮膚和服裝；參考能固定身份，文字能固定畫框。
• 將靜態影像描述為一張照片：構圖、每個人的位置、他們在鏡頭開啟的瞬間在做什麼、光線、鏡頭。在可能帶有文字的物件上說「無文字」，例如槳板、標誌或螢幕，並以「填滿整個畫框，邊緣到邊緣，無黑條，無信箱模式」結束每個靜態提示詞：否則廣角定場鏡頭會以內嵌在影像中的電影黑條形式返回，然後影片會繼承這些黑條。
• 肖像會比書面描述更顯老、更整潔。給出兩次年齡（「25 歲，看起來像二十五歲而不是更年長」），按長度和行為描述頭髮（「頭頂五公分長，梳向一側，不向後梳，不是平頭」），並命名電影其餘部分使用的光線和調色盤，否則孤立的鏡頭會以與相鄰鏡頭不同的色溫返回。
• 當靜態影像被拒絕時，將其移動到旁邊的 rejected/ 資料夾中，而不是刪除它。重新運行只會渲染缺失的內容，如果新的拍攝失去了正確的構圖，較早的拍攝仍然可用。
• 當鏡頭有靜態影像時，以「完全從提供的畫格開始」開始一個影片提示詞，並說明誰保持相同的臉、頭髮和服裝。指出不得增加的必需道具數量。
• MiniMax H3 Max 會生成原生音效和唇形同步語音。對於有口語台詞，在提示詞中引用確切文字，指出說話者，並要求自然的嘴唇動作和無字幕；將相同的文字放在計劃的 dialogue 欄位中，以便評審可以檢查。可接受的持續時間為每個鏡頭 5 到 15 秒，解析度為 480P 或 768P；兩行對話需要六秒而不是五秒。畫格無法確認說了什麼，因此轉錄原生音訊（本機的 whisper.cpp 就足夠了）並與劇本進行比較；模型也會在人群場景中即興發出喃喃的台詞，因此請閱讀整個轉錄稿，而不僅僅是您編寫的台詞。
• 光線「捕捉」或「反射在」角色眼睛中會被字面渲染為發光的虹膜。說明眼睛保持其自然顏色，並禁止在其中出現有色光。
• 兩個手持道具傾向於在幾幀內合併到一隻手中，無論靜態影像顯示什麼。當道具很重要時，給它一個不是手的位置（嘴巴、口袋、桌子），或者計劃讓它成為可選的，並根據舞台調度而不是哪隻手拿著什麼來評判拍攝。
• 以朝向下一鏡頭主題的視線方向結束一個鏡頭（在切換到她轉身之前瞥向前排），這樣銜接讀起來是因果關係，而不是兩次生成。
• 在 FFmpeg 組裝中，concat 會發出微秒級時間基準，後續的 xfade 會拒絕該基準；在混合溶解和硬剪輯時，在 concat 之前和之後將每個影片鏈固定為 settb=1/<fps>。將每個剪輯修剪到其計劃長度，以便標題卡保持其完整的運行時間，並從檔案而不是假設中讀取剪輯持續時間。
• 以攝影師而非舞台經理的身份撰寫影片提示詞。在任何區塊調度之前，以媒介和物理開場：「寫實風格的真人 <類型> 電影，非動畫，非遊戲過場動畫」、鏡頭、光線來源、空氣中在做什麼（霧氣、霜塵、雨），以及「物理上可信的布料、頭髮和重量」。一個主要是區塊調度和禁止性文字（「保持坐姿」、「沒有人離開他們的位置」、「與第一幀相同的臉」）的提示詞會返回一張抽搐的照片：模型只動畫化它被告知要動畫化的內容，並凍結其餘部分，而靜止狀態讀起來很假。在一個子句中命名必須保持穩定的內容（一把劍，兩張臉），而不是在五個子句中。
• 為每個動作設定一個時鐘：「在前半秒內」、「在中點」、「在最後一秒」。不定時的動作要麼從不出現，要麼花在醞釀上，而沒有定時節拍的鏡頭會返回為人們保持姿勢的緩慢推進。
• 對於包含打鬥場面的電影，切勿在 visual_style 中寫入「慢動作」或「優雅、從容」：該風格會在每個鏡頭中重複，因此每個交鋒都以漂浮方式出現，打鬥沒有節奏。在風格中說「實時速度」，並在打鬥提示詞內建立節奏：計算交鋒次數（「在前兩秒內三次砍擊和三次格擋」），命名停頓（「劍刃鎖住，一個保持的節拍」），然後是釋放（「她打破鎖定，下一輪攻勢更快」），並讓速度變化只存在於一次衝擊中。對比讀起來才是節奏；均勻的優雅讀起來是緩慢的。
• 向下退出讀起來是墜落。一個「從屋簷踏出，落入霧中」的人物，無論提示詞多麼輕盈，都會被觀眾視為跳樓的人。在屋頂上結束一個屋頂場景（敬酒、入鞘的劍、一個凝視），或者在一個獨立的鏡頭中展示下降，並有一個可見的承受重量的著陸。
• 能在觀眾心中生存的對話是戲劇對話，而不是格言。兩個對稱的警句（「霜是冷的，酒不是」）聽起來像是寫出來的；一個帶有轉折的樸實交流聽起來像是說出來的。當使用者提到他們喜歡的場景時，借鑒該場景的對話邏輯（一個陳述的規則，一個聲稱的漏洞，一個簡短的命令，一個厚臉皮的拒絕），然後以您自己的角色自己的語域說出來，然後保持每句台詞足夠短，以便在您給定的秒數內說完。
• 選擇文字轉影片用於寬廣、風景、動作和大規模鏡頭。模型掌控動作，剪輯讀起來像拍攝的。保留影像轉影片用於那些臉部或精確構圖必須匹配靜態影像的鏡頭，並且在那裡也要前置動作。一個精緻的靜態影像對動作來說是個負擔：照片越整潔，剪輯看起來就越像一張照片甦醒過來。當使用者偏好令人信服的動作而不是完全相同的臉時，在計劃中這樣說：將 still_prompt 和 reference_prompt 留空，並在每個角色的 description 中攜帶身份，而製作提示詞會在每個列出該角色的鏡頭中逐字重複該描述。
• 根據來源而不是檔案大小來評判編碼。將原始提供者剪輯的位元率與組裝後電影的位元率進行比較：在相同編碼器設定下，最終數字低得多意味著剪輯是靜態的，而不是編碼是有損的。使用 -preset slow 以 CRF 16 或更低進行組裝，保持提供者的畫格大小（不向任一方向重新縮放 768P 剪輯），並在使用者詢問後期製作是否損失了品質時在交付說明中這樣說。
• 在將對話鏡頭修剪到其計劃長度之前，從轉錄稿中讀取單詞時間戳（whisper-cli -ml 1），並保持剪輯足夠長，以便最後一個單詞在輸出的音訊淡出開始之前結束；一個生存到剪輯末尾的台詞仍然可能因溶解而失去其最後一個音節。重新轉錄組裝後電影的對話視窗，而不僅僅是原始剪輯。
• 一個沒有語音的剪輯的轉錄稿不是語音的證據。whisper 會在穩定的背景環境音上發明簡短的台詞和字幕信用；在為「即興」台詞重新拍攝之前，用時間戳和響度包絡（語音在背景環境音之上顯示為峰值）來確認它。
• 從參考肖像編輯的靜態影像會繼承肖像的臉，但會發明天氣。在每個靜態提示詞中固定天空、降水和季節（「晴朗的夜晚，屋頂上的霜，沒有雪」），否則一張單獨的臉部匹配特寫會在電影其餘部分都未出現的下雪天返回。