Communitygithub.com

reel — AI 影片製作與編輯工具

用於製作或編輯影片、宣傳片、MV/歌詞影片、照片+配樂+配音、素材剪輯成片、推鏡頭特寫、網頁邊講邊高亮。交付必須通過 reel check → reel deliver 並取得完成回執。

reel — AI 影片製作與編輯工具 是什麼?

reel 是一個以 ffmpeg 為核心的分層影片製作工具,專為 AI agent 設計。它能協助 agent 檢視素材、制定目標、編寫 plan,並由程式碼負責取景幾何、渲染與驗收。支援多種比例配置(預設豎屏 1080×1920)。該工具強調嚴格的交付流程,設有程式碼閘門確保影片品質與一致性。用戶需依序完成 brief 登記、聲音試聽、成片檢查、審片記錄,最後透過 `reel deliver` 交付並取得最終回執才能標記為完成。reel 可作為獨立腳本(`bin/reel`)執行,支援本地與遠端 GPU 渲染,也提供網頁跟隨與高亮功能,適合製作各類影片內容,如宣傳片、口播、MV/歌詞影片等。

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

在你喜歡的 AI 中提問

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

說明文件

reel — agent 的影片製作 / 編輯工具

ffmpeg 為核心的分層工具:agent 看素材、定目標、寫 plan;程式碼負責取景幾何、渲染和驗收。比例可配(預設豎屏 1080×1920)。 命令和格式細節在引擎 README 與 docs/engine.zh.md,動手前先讀。

交付閘門(必須走)

規則沒人執行就等於沒有,下面每一步都有程式碼攔著:不走就交不出「成片」。

  1. 開工先寫 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。
  2. 聲音先試聽:沒有固定預設聲音。先出 10–20 秒樣本給人聽,同意後把原話、樣本路徑、樣本 sha256 寫進 brief.voice.approved;換聲音要重新試聽。
  3. 出片後檢查:reel check 成片.mp4 --plan plan.json --brief brief.json [--profile default|social-vertical|項目.json]。exit 1 = 不能交。看 result.gate.blockers(技術不合格)和 pending_review(要人確認);not_covered 列的是沒檢查的項,不能說「已檢查」。
  4. 審片:needs_review 逐項看(reel scrub / 抽幀),每項寫一條帶時間碼的審片記錄;完整看一遍寫 final_watch,聽片寫 final_listen。
  5. 交付:reel deliver 成片.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json。不滿足成片條件報 DELIVERY_NOT_FINAL,只能 --sample,檔名帶「待審樣片」。同版本號不能再交,舊版不刪不覆蓋。
  6. 說「完成」的條件:拿到 status: final 的回執(reel receipt <回執> 可複核)。否則如實說「未完成 / 待審樣片 / 待試聽」。hooks/deliver_gate.py(Stop hook)會攔沒有回執的「已完成」;回執要對應你說的那件作品(點名作品和版本號時按作品名、版本號匹配)。該 hook 預設只管登記過的專案和呼叫過 reel 的回合,REEL_GATE_SCOPE=global 才是全機範圍。
  7. 專案自寫的渲染腳本出的片也一樣走 3–6。
  8. MV:加 --contract mv.json。歌詞檢查讀的是契約聲明的歌詞字層(每句演唱期間字層上有字、開唱前沒有字),不讀成片畫面的像素,所以不能據此說「畫面上的歌詞已核對」。song_level 對合集和 policy: "trim" 逐首比較響度與真峰值,容差與單曲相同。
  9. 參數錯誤也輸出 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

標準工作流程

  1. 備素材到專案目錄 $P(素材、observations.json、plan.json、預覽、成片都放這裡;一個目錄一個 plan,.reel-history/ 記修訂)。
  2. 看素材、定目標:
    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
    
  3. 寫 plan.json(EditPlan v1):camera: [] 真靜止;zoom_to 引用 observation 推到目標;track 跟隨多個時間點的 observation;transition_out 轉場。影片鏡頭不要跨 inspect 給出的切鏡點。
  4. 校驗 + 預覽:reel validate plan.json;reel compile plan.json;reel preview plan.json s2 --out "$P/preview/s2.mp4" --sheet "$P/preview/s2.png",看拼圖確認運鏡。
  5. 出片: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,鏡頭和高亮由瀏覽器逐幀繪製。

  1. 按網頁原文寫口播(要高亮的句子與頁面一字不差),TTS 生成 voice.mp3。
  2. reel words voice.mp3 --out words.json(本機 whisper 逐字時間)。
  3. plan 裡用 kind: "web" 鏡頭、camera: [{"op": "follow"}]、highlight: [{"text": "頁面原文…", "sync": "voice"}],audio.words 指向 words.json。
  4. 報 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)。

相關技能