Communitygithub.com

/reel:Claude Code 影片製作

指導 AI 代理如何規劃、建構或剪輯「短影片」,並產出完成的影片剪輯。流程依循 /reel:Claude Code 的影片製作程序,工作順序為:先有導演方向,再進行剪輯,最後通過強制性的交付關卡。當新任務需要此技能時使用。

reel:Claude Code 影片製作 是什麼?

這是一個專為 Claude Code 設計的影片製作技能,稱為「/reel」。它提供了一套結構化的工作流程,從腳本撰寫、視覺素材分析、語音配音,到最終剪輯與交付。此技能的核心特色在於強制性的「交付關卡」(Delivery Gate),確保任何對外發布的影片都必須遵循嚴格的步驟:先註冊簡報(brief)、通過語音審核、通過技術檢查,並完成人工審查與簽核。它支援多種平台,包括 Claude Code、Coxwave 等基於終端機的 AI 代理。此工具以 ffmpeg 為基礎,提供可設定的輸出尺寸(預設為 1080x1920 的垂直影片),並支援子像素推近、動態追蹤、轉場特效、字幕嵌入、背景音樂、調色等功能。所有命令都會回傳 JSON 格式的結果,並在失敗時回傳錯誤碼。它還整合了遠端 GPU 渲染、節拍偵測、網頁敘事等進階功能,讓 AI 代理能夠高效地完成從素材管理到最終交付的整個影片製作流程。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shuaige121/reel/tree/HEAD/skills/reel

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 重新思考內容;不要只重新剪輯。

交付關卡(強制性)

每個步驟都由程式碼強制執行:跳過任何一步就無法交付最終剪輯。

  1. 先撰寫簡報($P/brief.json,範本如下)並註冊:reel register brief.json。交付語言、最終版或樣本、交付資料夾以及哪些內容不能更改:如果你無法填寫這些內容,請詢問使用者。註冊後,Bash 掛鉤會拒絕將 cp/mv/ffmpeg 寫入到交付資料夾。
  2. 試聽語音。 沒有預設語音。選擇一個符合簡報要求的語音,渲染一個 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 語音僅用於內部草稿,絕不能用於最終交付的影片。
  3. 檢查渲染結果: 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);永遠不要說那些項目已被檢查。
  4. 審查。 查看每個 needs_review 項目(reel scrub,影格擷取)並為每個項目撰寫一個帶有時間碼觀察結果的審查記錄。觀看整段剪輯並簽署 final_watch(每個鏡頭至少一個影格);從頭到尾聆聽並簽署 final_listen(代理簽名需要附帶時間碼的觀察結果;如果使用者已聆聽,請記錄他們的原話作為 quote)。當你兩個都簽署完成後,將其作為最終版交付:收據上會顯示 approved_by: agent,而你的回覆應是「最終剪輯,已由 Claude 審查,但您尚未看過」。使用者的反饋將成為下一個版本。reviews.json 的格式在 docs/ENGINE.md 中。
  5. 交付: 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,刪除,然後重新註冊。
  6. 說「完成」 需要一張包含 status: final 的收據(reel receipt <receipt.json> 會重新驗證)。否則,請說明真實狀態:「尚未完成」、「樣本待審查」、「語音未試聽」。停止掛鉤會阻止沒有匹配收據的完成聲明。
  7. 由專案自己的渲染腳本(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 中。

  1. 素材放入 $P(資產、observations.json、plan.json、預覽、渲染和檢查報告都存放在那裡;每個資料夾一個計畫)。
  2. 腳本和語音。 撰寫旁白腳本,選擇一個符合簡報要求的語音並通過試聽(關卡步驟 2)。產出 voice.mp3(或 .wav),並且如果你想要字幕,產生 voice.vtt。對於發表的作品,優先使用真實錄音或其授權涵蓋該用途的語音;對於純音樂作品,請將 audio.voice 指向音樂軌道(它是時間軸錨點)。
  3. 查看並選定目標: reel inspect(列出每個檔案)→ reel frame(讀取帶有 0-1 網格的影像,並讀出主體的邊界框)→ reel observe 以註冊它,或 reel locate --query ... --check-png ...(OWLv2;在使用偵測前先查看檢查圖像)。
  4. 撰寫 plan.json(EditPlan v1):camera: [] 保持畫格靜止;zoom_to 搭配 observation_id 會推進到已註冊的主體上;當主體在影片中移動時使用 track;transition_out 用於轉場。不要讓影片鏡頭跨越 inspect 報告的場景切換點。audio.voice 是必需的,且相對於 src_dir 解析。
  5. 驗證和預覽: reel validate → reel compile → reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png,然後讀取聯絡表(contact sheet)來判斷鏡頭運動。
  6. 渲染: 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、簡報、審查、收據和設定檔。

相關技能