Code film
此處的 film 是指一個能在收到請求時繪製任意時間點的網頁(window.renderAt(t))。一個小型 harness 會在無頭 Chromium 中,於 GPU 上請求每個影格,並由 ffmpeg 將影格與音軌合併。過程中不會進行任何影片拍攝或產生,因此畫面完全符合程式碼的呈現,且在任何解析度下皆一致。
此資料夾中的工具組已在 "Dial-A-Dev 98"(Builder Wars 週主題 "Shipped in 1998",2026 年 11 月)中驗證:44 秒、1920x1080、11 個鏡頭、1,326 個影格,約 45 秒內完成渲染。該影片的完整原始碼位於 examples/dial-a-dev-98/ 中。其模式遵循 github.com/Vincentwei1021/mg-styles-15 (MIT),該專案也是動態設計風格的良好入門教材。
開始一部影片
bash ~/.claude/skills/code-film/new-film.sh ~/Work/<film-folder> # 複製工具組,安裝兩個本地套件
cd ~/Work/<film-folder>
# 音效需要 ElevenLabs 金鑰:使用者自行將 ELEVENLABS_API_KEY=... 儲存在 ./.env 中(切勿在對話中要求提供)
node harness/render.mjs film --stills 0,1,2 # 輸出 PNG 靜態圖 -> film/out/stills/
bash tools/build.sh v1 # 提示清單、混音、渲染、X 編碼 -> film/out/<filmName>_v1.mp4
將影片保留在其專屬資料夾中,且位於任何產品儲存庫之外。在安裝任何全域性套件之前,請先詢問。
工作順序
- 簡報。 產品、受眾、發布位置、長度、畫面比例 (16:9、9:16、1:1)。若為 Builder Wars,請呼叫
get_video_guide並遵循其規則(其規則優先於此檔案)。 - 腳本構想。 一個核心想法、在前半秒內設定鉤子、逐步升級、在約 60-75% 的時長處安排一個英雄時刻,以及一個精心構圖的結尾畫面。選擇一種風格,並將其標誌性特徵寫成可測試的陳述句。
- 先製作提示表 (
film/cues.json)。將旁白腳本寫成逐行文字,並附上預估時長。鏡頭與台詞和口說單字綁定,而非與固定的秒數綁定,因此新的旁白錄製會重新調整整部影片的時間。 - 先做靜態圖,再做動態。 建立最難的兩到三個畫面的外觀,並以全尺寸檢視。在畫面尚未達到足以成為海報的水準之前,不要對其進行動畫製作。
- 鏡頭。 每個鏡頭一個模組(合約如下)。使用靜態圖和小型連環圖來檢查每個鏡頭。
- 旁白。 試聽(庫存聲音和三種設計的聲音),錄製每句台詞並取得單字時間點,然後讓提示表移動剪接點:
node tools/vo.mjs --voice <id>,接著使用--reuse --tempo 1.12來緊湊朗讀節奏。 - 音效與音樂。 將它們列在
audio/sfx.json和audio/music.json中,並使用node tools/sfx.mjs --music產生。每個鏡頭宣告其自身的音效提示,因此音效打點能與畫面緊密結合。 - 建置 (
tools/build.sh),然後自行檢視連環圖並修正所見問題。 - 評審。 提供一個獨立的代理程式
rubric.md、影片檔案和簡報。此代理程式未參與影片製作;它會評分並回傳排序後的修正項目。套用修正、重新建置,然後才展示給使用者。若時間允許,進行兩輪。 - 完成並交接。
tools/finish.sh會編碼為 X 格式,並製作海報和連環圖。執行目標平台的自身檢查器。由使用者發布;切勿代為發布。
頁面合約
window.FILM = { width, height, fps, duration, shots, lines, sfx },window.renderAt = async (t) => {...}, 然後window.__ready = true。- 每個影格都是
t的純函數:僅使用種子亂數,沒有時鐘、沒有 CSS 過渡效果、沒有從一個影格帶到下一個影格的狀態。 harness 可能以任意順序和在多個瀏覽器上同時請求影格。 - 一個鏡頭是
{ name, samples(lt), render(lt, post, renderer), overlay(g, lt), look(lt), sfx: [...] }:render將線性 HDR 繪製到post.scene中;overlay在 1920x1080 的 canvas 上繪製 2D 疊加層(若有繪製則回傳 true);samples是該時間點的動態模糊採樣數(平靜時為 3,快速移動時為 12-20);look回傳後製設定(泛光、閃爍、錄音帶效果量、故障效果);sfx列出{ t, s, g, a, len }:本地時間、音效名稱、增益、a: 'peak'表示將音效的最大聲時刻對齊提示點,以及可選的剪輯長度。
film/js/film.js將鏡頭名稱對應到工廠函數,並繪製所有覆蓋在每個鏡頭之上的元素。- 用於外觀開發的查詢開關:
?clean(無錄音帶效果處理)、?nocc(無字幕)、?mb=1、?rs=0.5。 render也會接收處理序號碼和總數 (render(lt, post, renderer, i, K)),並且一個鏡頭可以設定shutter: 0。 在沒有動態模糊的情況下,K 次處理可用於其他用途:移動鏡頭以獲得景深、移動主光源以獲得柔和陰影,以及移動像素網格以獲得抗鋸齒效果(如 storybook 中的rig.js)。look()可能回傳paper: true以獲得乾淨的完成效果(色彩真實的色調曲線、顆粒感、暗角),以取代錄音帶效果處理。film.js可能匯出loadFonts(任何必須在第一個影格之前完成的非同步操作)、buildCaptions和caption。
此機器(檢查日期 2026-11-11)
- Chromium 155 位於
/usr/bin/chromium,RTX 4070 Ti SUPER。硬體 WebGL2 需要--use-gl=angle --use-angle=gl-egl(harness 會傳遞這些參數,並在回退到軟體渲染時發出警告)。WebGPU 會回退到軟體渲染:請使用 WebGL2。 - ffmpeg 9,附帶 libx264 和 NVENC;ImageMagick 用於連環圖;無 Blender,虛擬環境外無 numpy。
- 完整 1080p 渲染:使用三個工作者時,每個影格約需 0.03 秒。
ElevenLabs 注意事項(檢查日期 2026-11-11)
- 金鑰存放在影片資料夾的
.env中。金鑰可能缺少user_read權限,因此可能無法讀取方案和剩餘點數;請如實說明,而非猜測。 - 使用的方案最多只允許
mp3_44100_128(更高格式需要 Creator 方案)。語音模型eleven_v4可以運作,並接受音訊標籤如[excited];這些標籤會出現在對齊結果中,並由vo.mjs移除。 - 庫存聲音朗讀速度較慢,不適合強力推銷。一個設計的聲音(
eleven.mjs design,然後voice-save.mjs,會佔用一個聲音槽位)加上--tempo 1.12可以達到電視購物的節奏。speed設定對時間點的改變微乎其微。 - 音效的音量變化很大,其中一個甚至回傳了無聲檔案:
mix.mjs會對每個檔案進行峰值正規化,跳過接近無聲的檔案並發出提示。對於回傳三次無聲檔案的音效,請使用更直接的提示詞重新產生("One loud hand clap" 可行,而描述打板聲的提示詞回傳了三次無聲)。 - 說書人的聲音朗讀速度慢:庫存聲音 George 測得每秒 2.25 個單字。
--tempo 1.25將其提升至每秒 2.7 個單字,這是一般的說話速度。根據錄製好的台詞決定長度,而非根據字數。 - 產生的音樂會在聲明長度之前結束。
mix.mjs會找到音量實際結束的位置,並將其與影片的結尾對齊。 - 角色聲音(例如兒童電視節目吉祥物)會以其描述所賦予的節奏朗讀:同一段文字,描述為 "speaks slowly to toddlers" 時耗時 31 秒,而描述為 "lively, brisk pace" 時耗時 24 秒。請將節奏放入描述中,設計兩到三個描述(每個預覽三次),使用
tools/audition-stats.mjs進行測量(長度、中位數音高、音高範圍),並預期還需要加上--tempo 1.3。描述一種類型;切勿提及真實角色或人物的名稱。 - 使用者從試聽中挑選的聲音,在影片中聽起來可能音調更高,儘管測得的音高和亮度相同:模型朗讀單句台詞的速度比朗讀較長的試聽段落快約 1.3 倍,再加上
--tempo會使聲音聽起來更高、更單薄。vo.mjs --reuse --tempo 1.38 --pitch -2可在相同速度下降低音調(時間點不變,因此只需在舊的主音軌上重新混音並執行finish.sh;無需渲染)。為使用者製作 0、-1、-2、-3 半音的比較片段,然後重新檢查旁白音軌的音量(mix.vo)。 voice-save.mjs <generated id> "<name>" "<description>"可將預覽儲存到帳戶(佔用一個聲音槽位)。在錄製新的旁白之前,請先保留上一位旁白者的錄音(cp -r audio/vo audio/vo_<name>)。- 免費方案未獲得商業發布授權。如果方案未知,請告知使用者。
曾發生的問題,以便不再重蹈覆轍
畫面與程式碼:
- 根據文字在句子中的位置來估計單字被說出的時間,誤差可達一秒(例如 "98" 會讀作 "ninety-eight")。請使用錄製好的單字時間點(
mark(line, word))。 - three.js 將擠出文字的大小設定得比名義尺寸大。請將單字符合目標寬度;永遠不要相信數字。
- 被方向光照亮的平面鏡子會變得均勻白色。為圓盤和鍍鉻表面提供點光源或多樣的環境,使高光成為一個亮點。
- 重疊的傾斜圓盤會相交。請在深度上層層排列它們,並限制傾斜角度。
- 模糊的地板反射會將背景閃光變成點狀網格:請在鏡面處理中關閉閃光效果。
- 偽粗體點陣字型(將文字繪製兩次,相距一個像素)會填滿 W 和 M 的內部空間。
ui98.js僅在與相鄰筆畫保持開放的間隙處加粗筆畫。 - 上半部顏色與背景色相近的標誌會消失。為擠出文字添加深色邊框(
makeLetters中的outline),並使其側面保持接近黑色。 - 錄音帶噪點編碼成本高昂。請以無失真格式渲染(
--lossless),然後使用位元率上限進行一次編碼。
第一輪評審在我認為已完成的影片中發現的問題(評分約 6/10)。請在評審之前檢查這些項目:
- 產品名稱必須在約 2 秒內出現在畫面上,且第 0 影格即是縮圖。從第一個影格開始,一個固定的下方三分之一處顯示產品名稱,可以同時解決這兩個問題。
- 疊加文字和字幕覆蓋了最佳的笑點。在放置任何疊加文字後,請檢查其下方的畫面。
- 在攝影機推近後,文字跑出了標題安全區域。請檢查每次推近的最後一個影格,而非第一個。
- 每次剪接都使用相同的白色閃爍和故障效果,看起來像是一個模板;同樣地,四個鏡頭共用一個背景,以及五個相同的星形爆裂效果也是如此。請多樣化;將大型閃爍保留給一兩次重點打擊。
- 在 1080p 下看起來沒問題的字幕,在手機上會變得太小:字母高度約 40 像素,並擁有自己的區域。
- 一個從未兌現的前提。影片說 "unless someone picks up the phone",那麼就必須有人接電話。
- 落在口說單字下的音效打點會聽不見。請將打點移到單字之後,並提高音量。
兩輪評審在 paper storybook 影片中發現的問題(約 6/10,然後約 7/10)。下次請優先檢查這些項目:
- 真實產品畫面以全螢幕顯示時,看起來像是螢幕錄影,破壞了世界觀。請將它們保留在場景內部(場景中的筆電),以兩個大型裁切搭配大字體呈現,並使用 16 個影格或更長的、符合世界觀的轉場效果來切換。裁切掉任何邊框,使螢幕側邊無接縫,並將遊戲內貨幣標示為假設。
- 跨鏡頭的數字必須一致。"Pretend millionaire" 之後緊接著一個顯示 $9,100 的看板,破壞了英雄台詞。
- 英雄畫面靜止了 1.4 秒。請在每個停頓期間保持某種動態(金幣傾瀉、燈光閃爍、台詞結束時的第二波效果),並從第一個影格開始就以寬景框取。
- 旁白間隙超過一秒,且僅有微弱的背景音樂時,聽起來像是死寂。請縮短間隙,或在其中加入一個笑料和音效。
- 具有乾淨邊緣的平面形狀,即使加上顆粒感,看起來仍像是向量圖形。稍微不規則的切割線和沿著邊緣的較淺紙張核心(storybook 中
paper.js的piece()函數)解決了這個問題。招牌應該是切割字母(cutSign),而不是印刷字體。 - 任何浮動的物體都需要可見的支撐(支架、彈簧、標籤)。光束必須是不透明的紙張。
- 關鍵動作在手機上顯得太小:拋硬幣、皇冠換頭、按鈕。請放大動作,並將攝影機推近進行拍攝。
- 彈出物件互相穿透,也穿透了正在翻動的書頁。真實的摺疊幾何形狀使得面向讀者的摺疊部分在書頁開始關閉的瞬間就會向後躺平。請保持這些摺疊部分直立,讓每個彈出物件在書頁幾乎完全打開之前保持低位(
book.js中的rise),並隱藏在關閉的書本內平躺的零件。 - 頁面不能在句子結束前開始翻動:鏡頭的
lead時間不能長於其前方的gap時間。 - 重複畫面中已呈現的笑點的字幕會破壞效果。台詞行的
cc可能只保留其開頭的幾個單字;當其餘部分被說出時,字幕就會消失。 - 以第一個影格結束:書本關閉,封面朝上,地址顯示在一條帶子上。同時也能乾淨地循環播放。
使用者觀看該影片後所做的更改(剪輯 v4):
- 針對其他角色的笑話("Sam hates Kim",一片暴風雲)聽起來很刻薄。他要求將笑話指向主角:Sam 流下一滴眼淚,然後幻想自己成為第一名("Dream, Sam, dream.")。請將笑話目標對準主角。
- 從產品抄來的標語("Highest monthly income wins")讓他問贏得什麼;結果什麼也沒有。在錄製之前,請檢查腳本中的每個宣稱是否與產品的實際功能相符。
- 思想泡泡比畫面還高:請將攝影機隨著它升高,同時將它所反映的真實物體保持在畫面中(夢想看板下的真實看板),並在書頁翻轉前幾個影格讓它消失,這樣就沒有高大的物體會隨著書頁移動。
工作分割:
- 在第一個工作階段中先建立外觀和引擎(兩到三個使用者認可的畫面),並將鏡頭合約和每個鏡頭的簡報寫入檔案(
SHOTS.md、BRIEFS.md)。然後將鏡頭分派給全新的代理程式,每個代理程式負責一或兩個鏡頭,使用model: "opus"並以這些檔案作為簡報。請勿為此使用 forks:fork 總是使用工作階段自身的模型和努力值,無法分配給較便宜的模型(在 styles 影片中,forks 佔了 55% 的使用量)。每個代理程式只擁有自己的鏡頭檔案;先撰寫共享角色;逐一載入鏡頭模組,這樣在編輯過程中損壞的檔案只會影響其自身的鏡頭。以相同的方式將評審修正分派出去,交給全新的代理程式,並提供鏡頭檔案和修正清單,而不是恢復建置者的工作;將引擎檔案保留給主要工作階段。 - 每輪評審都交給一個全新的代理程式,並告知第二個評審不要閱讀第一個評審的筆記。
流程:
pkill -f <pattern>會比對到執行它的 shell。請將 pattern 寫成[p]attern。- 頁面錯誤會讓 harness 處於等待狀態。它在 45 秒後會放棄並印出頁面錯誤;請勿在除錯時將其輸出透過
tail管線傳送,否則錯誤訊息只會在結尾才出現
…
[已截斷以利翻譯]