reel — agent 的影片製作 / 編輯工具
ffmpeg 為核心的分層工具:agent 看素材、定目標、寫 plan;程式碼負責取景幾何、渲染和驗收。比例可配(預設豎屏 1080×1920)。
命令和格式細節在引擎 README 與 docs/engine.zh.md,動手前先讀。
交付閘門(必須走)
規則沒人執行就等於沒有,下面每一步都有程式碼攔著:不走就交不出「成片」。
- 開工先寫 brief(
$P/brief.json)並登記:reel register brief.json。寫清交付語言、成片還是樣片、交付目錄、不許改什麼;寫不出就問用戶。登記後,Bash 裡用 cp/mv/ffmpeg 直接寫進交付目錄,或用reel … --out PATH/--out=PATH(--png、--sheet、--report、--check-png同理)指向交付目錄,會被hooks/guard_delivery.py拒絕。這個 guard 只解析命令文字,盡力而為:萬用字元、花括號、命令替換、腳本內部及遠端寫入可能攔不住,別拿它當許可,交付只走reel deliver。 - 聲音先試聽:沒有固定預設聲音。先出 10–20 秒樣本給人聽,同意後把原話、樣本路徑、樣本 sha256 寫進
brief.voice.approved;換聲音要重新試聽。 - 出片後檢查:
reel check 成片.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|項目.json]。exit 1 = 不能交。看result.gate.blockers(技術不合格)和pending_review(要人確認);not_covered列的是沒檢查的項,不能說「已檢查」。 - 審片:
needs_review逐項看(reel scrub/ 抽幀),每項寫一條帶時間碼的審片記錄;完整看一遍寫final_watch,聽片寫final_listen。 - 交付:
reel deliver 成片.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json。不滿足成片條件報DELIVERY_NOT_FINAL,只能--sample,檔名帶「待審樣片」。同版本號不能再交,舊版不刪不覆蓋。 - 說「完成」的條件:拿到
status: final的回執(reel receipt <回執>可複核)。否則如實說「未完成 / 待審樣片 / 待試聽」。hooks/deliver_gate.py(Stop hook)會攔沒有回執的「已完成」;回執要對應你說的那件作品(點名作品和版本號時按作品名、版本號匹配)。該 hook 預設只管登記過的專案和呼叫過 reel 的回合,REEL_GATE_SCOPE=global才是全機範圍。 - 專案自寫的渲染腳本出的片也一樣走 3–6。
- MV:加
--contract mv.json。歌詞檢查讀的是契約聲明的歌詞字層(每句演唱期間字層上有字、開唱前沒有字),不讀成片畫面的像素,所以不能據此說「畫面上的歌詞已核對」。song_level對合集和policy: "trim"逐首比較響度與真峰值,容差與單曲相同。 - 參數錯誤也輸出 JSON(
ARG_INVALID,退出碼 2),--help輸出幫助文字。reel voice check核對中文(預設--lang zh)另需pypinyin(裝進同一個 venv),缺了報BACKEND_UNAVAILABLE;reel words只需whisper-cli和模型。
brief.json 的例子(MV 另加 "kind": "mv"):
{"version": "reel.brief.v1", "name": "招生宣傳", "language": "zh-CN", "deliverable": "final",
"delivery_root": "~/Deliveries/<項目>", "must_not_change": ["片尾署名"],
"voice": {"mode": "tts", "voice_id": "zh-CN-XiaoxiaoNeural",
"approved": {"voice_id": "zh-CN-XiaoxiaoNeural", "by": "user", "quote": "這個聲音可以",
"sample": "voice_sample.mp3", "sample_sha256": "<shasum -a 256 的結果>"}},
"profile": "default"}
- brief 裡只有
name、must_not_change和鍵名為text/title/caption/label的欄位會進文字掃描;language、delivery_root、voice.*不掃。 - 沒有配音寫
"voice": {"mode": "none"};真人錄音寫"recorded"。靜音版用專案 profile:{"extends": "default", "audio": "silent"}。 - profile:
default(通用閾值)、social-vertical(豎屏社交平台:1080×1920 30fps、-16 LUFS);專案差異寫專案 profile(extends),有意的長停留登記進allow並寫理由。文字掃描的詞表在 profile 的text段:banned和extra_banned(不分大小寫子字串,命中 fail,專案自己的禁用詞加在extra_banned)、banned_words(區分大小寫的大寫整詞TODO/TBD/FIXME,命中 fail)、review(placeholder、lorem ipsum,整詞,命中 needs_review,要寫text_scan審片記錄)。
每個 Bash 呼叫區塊的開頭
agent 的每次 Bash 呼叫是全新 shell,函數不會保留,所以 reel 是 PATH 上的腳本(bin/reel),不是函數。它按 REEL_PYTHON → ~/.local/share/reel/venv/bin/python → python3 的順序選直譯器。環境有問題先跑 reel doctor(列出必要及可選依賴和修復辦法,必要項缺失退出 1):
command -v reel >/dev/null || export PATH="$HOME/.claude/plugins/reel/bin:$PATH"
P="$HOME/work/<專案>"; mkdir -p "$P/preview" && cd "$P" # 成果落專案目錄,不落 /tmp
標準工作流程
- 備素材到專案目錄
$P(素材、observations.json、plan.json、預覽、成片都放這裡;一個目錄一個 plan,.reel-history/記修訂)。 - 看素材、定目標:
reel inspect 素材/a.jpg 素材/b.mp4 reel frame 素材/a.jpg --out "$P/preview/a_grid.png" # 讀帶 0–1 網格的圖,讀出目標框 reel observe --obs observations.json --src 素材 --asset a.jpg --bbox x0,y0,x1,y1 --label "目標" reel locate --obs observations.json --src 素材 --asset b.mp4 --t 2 --query "red cup" --check-png "$P/preview/chk.png" # OWLv2,需要 torch - 寫 plan.json(EditPlan v1):
camera: []真靜止;zoom_to引用 observation 推到目標;track跟隨多個時間點的 observation;transition_out轉場。影片鏡頭不要跨inspect給出的切鏡點。 - 校驗 + 預覽:
reel validate plan.json;reel compile plan.json;reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png",看拼圖確認運鏡。 - 出片:
reel render plan.json --out "$P/成片.mp4" --sheet "$P/preview/final.png" --where mac。成片音訊固定為 AAC 48 kHz,checks含取樣率。checks全過只說明渲染沒壞,接著走交付閘門 3–6。
時間線與卡點
- 看:
reel timeline plan.json --format text;reel timeline plan.json --png tl.png [--beats beats.json];reel scrub plan.json --cuts --render 成片.mp4 --out 目錄。 - 改:
reel edit plan.json --op '{"op":"trim","id":"s3","duration":2.4}'(每步校驗後寫入);reel undo plan.json --to r2;reel history plan.json。 - 卡點:
reel beats 音樂.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat(--dry-run先看報告)。
網頁:邊講邊跟隨邊高亮
素材是網頁時不做 OCR:文字位置直接讀 DOM,鏡頭和高亮由瀏覽器逐幀繪製。
- 按網頁原文寫口播(要高亮的句子與頁面一字不差),TTS 生成
voice.mp3。 reel words voice.mp3 --out words.json(本機 whisper 逐字時間)。- plan 裡用
kind: "web"鏡頭、camera: [{"op": "follow"}]、highlight: [{"text": "頁面原文…", "sync": "voice"}],audio.words指向words.json。 - 報
TEXT_NOT_FOUND= 頁面沒有這段原文;TEXT_NOT_IN_VOICE= 配音對不上。
遠端 GPU(可選)
- 設
REEL_REMOTE=user@gpu-host(可空格分隔多個)後,reel render --where 5090/--where auto會把渲染派到遠端 NVIDIA 主機(NVENC + libass),成果拉回本機再驗收一次。不設則只用本機。 - 視訊記憶體預設 ≤80%,超過報
NEED_USER_APPROVAL,先告訴用戶,同意後才加--allow-over-80;GPU 利用率 ≥50% 報GPU_BUSY,不搶。遠端 flock 保證同一時間只一個 reel GPU 任務。 reel remote probe查狀態;reel remote setup-vision在遠端建獨立 venv(torch + OWLv2)。