reel:Claude Code 影片製作 是做什麼的?
一個建立在 ffmpeg 之上的分層工具。你(Claude)檢視素材,決定要展示什麼並撰寫計畫;程式碼負責處理構圖幾何、渲染和檢查。輸出尺寸可設定(預設為垂直 1080x1920)。
命令和檔案格式記錄在 reel 儲存庫的 docs/ENGINE.md 中。在執行第一個命令之前,請先閱讀它:cat "$(reel --root)/docs/ENGINE.md"。reel <command> --help 列出所有選項。每個命令都會輸出一個 JSON 物件({"ok": true, "result": ...} 或 {"ok": false, "error": {"code": ..., ...}}),並在失敗時以 exit 1 結束。
工作順序:先有導演方向,再進行剪輯
對於任何使用者以外的人會看到的影片,請遵循 SOP.md:S0 接收、S1 素材包裝、S2 資產清單、S3-S4 director 代理撰寫 direction/BRIEF.md 和分鏡腳本,然後直接開始剪輯(審核步驟 G1 預設不會阻擋流程),接著是下方的交付關卡。在 S7 階段,由一個獨立的 director 代理根據 BRIEF 審查剪輯成果。作為外掛安裝時,該代理的名稱為 reel:director。
- 提供給導演的是原始素材的路徑,而不是你自己的結論。
- 如果已存在一個已核准的 BRIEF,且目的、觀眾和素材範圍沒有改變,則遵循它。
- 如果使用者說影片很無聊或沒有意義,請回到 S3 重新思考內容;不要只重新剪輯。
交付關卡(強制性)
每個步驟都由程式碼強制執行:跳過任何一步就無法交付最終剪輯。
- 先撰寫簡報(
$P/brief.json,範本如下)並註冊:reel register brief.json。交付語言、最終版或樣本、交付資料夾以及哪些內容不能更改:如果你無法填寫這些內容,請詢問使用者。註冊後,Bash 掛鉤會拒絕將cp/mv/ffmpeg寫入到交付資料夾。 - 試聽語音。 沒有預設語音。選擇一個符合簡報要求的語音,渲染一個 10-20 秒的樣本,然後執行
reel voice check sample.mp3 --script sample.txt --brief brief.json。本地的 Whisper 模型會轉錄樣本並與文字進行比對(--lang預設為en;對於中文旁白請傳遞--lang zh,它會透過無聲調拼音進行比較,因此同音字拼寫不會被計為錯誤);只有當錯誤率低於或等於 10% 時,才會將核准寫入brief.voice.approved(by: claude,並附上轉錄文字作為證明)。如果使用者已收聽,請改為記錄他們的原話。- 語音轉文字(STT)證明文字被正確且清晰地閱讀。但它不能證明語音適合該作品:請在你的回覆中說明你選擇了這個語音,如果使用者不喜歡,在下個版本中更換語音。
- 新的語音需要新的檢查。macOS 的
say語音僅用於內部草稿,絕不能用於最終交付的影片。
- 檢查渲染結果:
reel check final.mp4 --plan plan.json --brief brief.json [--profile vertical-strict|project-profile.json] [--text caption.txt]。- Exit 1 表示它無法交付。請閱讀
result.gate.blockers(技術性失敗:即使是樣本也無法交付)和result.gate.pending_review(需要審查者檢查的項目)。 - 不要只依賴
ok。result.gate.not_covered列出了未被檢查的項目(例如螢幕上的文字,因為沒有 OCR);永遠不要說那些項目已被檢查。
- Exit 1 表示它無法交付。請閱讀
- 審查。 查看每個
needs_review項目(reel scrub,影格擷取)並為每個項目撰寫一個帶有時間碼觀察結果的審查記錄。觀看整段剪輯並簽署final_watch(每個鏡頭至少一個影格);從頭到尾聆聽並簽署final_listen(代理簽名需要附帶時間碼的觀察結果;如果使用者已聆聽,請記錄他們的原話作為quote)。當你兩個都簽署完成後,將其作為最終版交付:收據上會顯示approved_by: agent,而你的回覆應是「最終剪輯,已由 Claude 審查,但您尚未看過」。使用者的反饋將成為下一個版本。reviews.json的格式在docs/ENGINE.md中。 - 交付:
reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json。- 如果最終版本條件未滿足,它會失敗並顯示
DELIVERY_NOT_FINAL並列出原因。此時只能使用--sample:檔案名稱會帶有sample-pending-review,並且你在告知使用者時必須稱其為樣本。 - 一個版本號只能被交付一次;舊版本永遠不會被刪除或覆蓋。只有當使用者明確要求移除舊版本時:
reel register brief.json --remove,刪除,然後重新註冊。
- 如果最終版本條件未滿足,它會失敗並顯示
- 說「完成」 需要一張包含
status: final的收據(reel receipt <receipt.json>會重新驗證)。否則,請說明真實狀態:「尚未完成」、「樣本待審查」、「語音未試聽」。停止掛鉤會阻止沒有匹配收據的完成聲明。 - 由專案自己的渲染腳本(
build_*.py等)製作,或在其他工具中組合並匯出的影片,也需要通過步驟 3-6。
{"version": "reel.brief.v1", "name": "spring-promo", "language": "en", "deliverable": "final",
"delivery_root": "~/Videos/deliveries/spring-promo", "must_not_change": ["end card credit"],
"voice": {"mode": "recorded"}, "profile": "default"}
voice.mode:none(無語音)、recorded(真實錄音)、tts或clone(後兩者還需要有voice_id和由reel voice check寫入的approved區塊,或由人類核准並附上quote、sample和sample_sha256)。delivery_root必須是現有的絕對路徑(或是以~開頭)。它不能是家目錄、桌面、文件、下載、iCloud Drive 根目錄、專案資料夾或其父目錄。- 無聲版本使用專案設定檔:
{"extends": "default", "audio": "silent"}。 - 設定檔:
default(通用起始閾值)和vertical-strict(1080x1920 30 fps,-16 LUFS,嚴格)。將專案差異放在一個帶有extends的專案設定檔中;將預期的長停留鏡頭註冊到allow中並附上原因;將禁用詞(舊產品名稱、填充文字)新增到text.extra_banned中。
每次 Bash 呼叫的開頭
每次 Bash 呼叫都會啟動一個全新的 Shell,因此每個呼叫都以以下內容開頭:
REEL_PROJECT=spring-promo # 此專案的名稱
command -v reel >/dev/null || { echo "reel 不在 PATH 上(啟用外掛,或執行 ./install.sh --link)" >&2; return 1 2>/dev/null || exit 1; }
command -v ffmpeg >/dev/null || { echo "找不到 ffmpeg" >&2; return 1 2>/dev/null || exit 1; }
P="${REEL_PROJECTS_DIR:-$HOME/reel-projects}/$REEL_PROJECT"; mkdir -p "$P/preview" && cd "$P"
所有輸出都位於 $P 中,絕對不能放在暫存資料夾;下面的相對路徑是相對於 $P 的。
進行剪輯
由你做出決定(哪些鏡頭、哪個主體、攝影機運動、節奏);感知、幾何、渲染和檢查則由程式碼完成。完整的命令語法在 docs/ENGINE.md 中。
- 素材放入
$P(資產、observations.json、plan.json、預覽、渲染和檢查報告都存放在那裡;每個資料夾一個計畫)。 - 腳本和語音。 撰寫旁白腳本,選擇一個符合簡報要求的語音並通過試聽(關卡步驟 2)。產出
voice.mp3(或.wav),並且如果你想要字幕,產生voice.vtt。對於發表的作品,優先使用真實錄音或其授權涵蓋該用途的語音;對於純音樂作品,請將audio.voice指向音樂軌道(它是時間軸錨點)。 - 查看並選定目標:
reel inspect(列出每個檔案)→reel frame(讀取帶有 0-1 網格的影像,並讀出主體的邊界框)→reel observe以註冊它,或reel locate --query ... --check-png ...(OWLv2;在使用偵測前先查看檢查圖像)。 - 撰寫
plan.json(EditPlan v1):camera: []保持畫格靜止;zoom_to搭配observation_id會推進到已註冊的主體上;當主體在影片中移動時使用track;transition_out用於轉場。不要讓影片鏡頭跨越inspect報告的場景切換點。audio.voice是必需的,且相對於src_dir解析。 - 驗證和預覽:
reel validate→reel compile→reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png,然後讀取聯絡表(contact sheet)來判斷鏡頭運動。 - 渲染:
reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local(僅在使用者設定了遠端 GPU 並要求使用時,才使用--where remote)。通過渲染檢查僅表示檔案沒有損壞;請繼續進行關卡步驟 3-6。
其他進入點,每個在 docs/ENGINE.md 中都有一個章節:
- 檢查和更改時間軸:
reel timeline(--format text或--png多軌影像)、reel scrub(每個剪輯點周圍的影格)、reel edit/undo/history、reel preview --range(附聲音的低解析度預覽)。 - 配合節拍剪輯:
reel beats music.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat;然後使用reel timeline --png --beats檢查每個剪輯點。需要./install.sh --beats。 - 為網頁敘述加上重點: 一個
kind: "web"的鏡頭;文字位置來自 DOM(無需 OCR),因此重點句子必須與頁面文字完全匹配;reel words voice.mp3提供逐字時間碼。需要./install.sh --web。 - Shotcut 專案:
reel mlt project.mlt --video-only;--dupes找出被使用兩次的來源素材。
可用功能:計畫組合、在主體方框上進行子像素推近(sub-pixel push-ins)、跟隨移動主體、xfade 轉場、燒錄字幕、背景音樂、調色與 LUT、網頁鏡頭、OWLv2 主體搜尋、技術檢查、閘道交付。 未內建功能:緩和轉場(eased transitions)、影格內插、語音複製。
遠端 GPU(選用)
--where remote 部分由程式碼強制執行。
- 僅在使用者已設定
REEL_REMOTE(一個 SSH 目標)並要求使用時才使用它;否則使用--where local渲染。 - VRAM 使用率預設限制在 80%。當一個任務需要更多時,工具會回傳
NEED_USER_APPROVAL:首先告知使用者,並且只有在他們同意時才添加--allow-over-80。GPU 利用率達到 50% 或更高表示有其他人正在使用它;不要佔用它。 - 一次只執行一個 reel GPU 任務(遠端檔案鎖定)。不要更改電源限制。切勿重新啟動或關閉主機。
reel remote probe報告主機資訊;reel remote setup-vision在遠端主機上安裝一個包含 torch 和 OWLv2 權重的獨立 venv。
附屬檔案
SOP.md:導演優先的工作流程、角色、步驟和退出條件。director代理(儲存庫中的agents/director.md):簡報、分鏡腳本和審查。- 儲存庫中的
docs/ENGINE.md:命令、EditPlan、簡報、審查、收據和設定檔。