Communitygithub.com

film-academy

向代理展示如何規劃、構建或剪輯「影片學院」,最終產出一個基於 ffmpeg 的剪輯。流程涵蓋影片學院、從此處開始:描述產品、執行兩個指令、手動流程(`make` 的逐步動作)。當新任務涉及此工藝時使用。

film-academy 是什麼?

Film Academy 是一個 AI 代理技能,專為 Claude Code、Cursor 或 Codex 等平台設計,旨在將影片製作轉變為如同程式碼般的建構、量測與修正流程。此技能的核心是將影片規劃為一個 HTML 頁面,由 Chromium 逐幀渲染,再由 ffmpeg 合成。它整合了多項專業功能:音樂會自動對齊小節線並壓縮至 -14 LUFS 的標準響度;一道「門控」機制會根據鏡頭長度、靜態幀比例、卡片字數以及剪輯工藝等量化數值,拒絕任何比前一次剪輯更慢或更無生氣的版本。所有客戶對影片的原始評語都會逐字記錄,並作為每次剪輯通過前的必答條件。這個技能支援從社交短片(6-15 秒)到品牌形象片(30-60 秒)的製作,並能處理網頁應用與原生應用(後者需提供螢幕錄影)。其指令式工作流程包含從新專案初始化、渲染、混音、合併、量測到交付的完整管道,確保每一次產出都是可重複、可量測且受客戶品味驅動的專業成果。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tincurik/film-academy/tree/HEAD

在你喜歡的 AI 中提問

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

說明文件

影片學院

一套將影片建構、量測與修正如程式碼般進行的方法。你以網頁形式撰寫影片,渲染器進行拍攝,混音器將聲音對齊節拍,門控機制拒絕任何比上一次更慢或更無生氣的剪輯,而客戶對影片的所有意見都會被逐字保留,且在剪輯通過前必須得到回應。

所有指令從此技能資料夾執行(python film.py ...)。需要 ffmpeg、Python 3.9+、pip install playwright && playwright install chromium。python film.py check 會告知缺少哪些元件。OCR(tesseract)為選用。

從此處開始:描述產品,執行兩個指令

當客戶描述一個產品並想要一支影片時:

  1. 僅收集你不能虛構的資訊:產品名稱、單一承諾(一句話)、2-4 個真實事實(佐證行)、一個真實數字(如果有)、一個行動呼籲(URL),以及產品是網頁還是原生/手機應用(若是後者則要求提供螢幕錄影,見下方說明)。切勿捏造任何宣稱或數字:影片僅呈現你所得到的內容。一次訊息內詢問完畢;若他們未提供長度,6-15 秒為社交短片,30-60 秒為品牌形象片。
  2. python film.py new "<name>" --promise "<promise>" --points "Label=value|Label=value" [--number "40%" --number-label "..."] [--slam "No setup."] [--action "One tap"] --url <url> [--music track.mp3 --drop-bar N] [--recording rec.mov] 會寫入 films/<slug>/film.json 與頁面。
  3. python film.py make films/<slug>:渲染、音效、門控;每一次 make 都是一個帶編號的建置版本(v1、v2,以此類推),並會與前一個版本進行門控比較。加上 --master 參數則輸出 1920x1080 60fps 的版本。
  4. 查看它(執行 python film.py sheet <film.mp4> films/<slug>/sheet.jpg,然後讀取圖片;你無法播放影片)並告知客戶 MP4 檔案的位置。
  5. 品味是他們的。 第一版是合格且通用的。請客戶觀看並指出問題所在;在當輪就將每一條意見逐字記錄下來(film.py note "<他們的原文>" --source "who, date" --store films/<slug>/film-notes.json),修改 film.json 或 film.html,針對新的建置版本勾選每一條筆記(film.py tick N1 --film <mp4> --where 0:04 --store ...),然後再次執行 make。門控機制會拒絕任何還有未勾選筆記的建置版本,以及比上一次更慢或更靜態的版本。
  6. 明確告知客戶:門控機制能捕捉到無生氣或變差的剪輯,但無法評判品味;此外,工作會消耗他們的 Claude Tokens(首次製作約需數萬個,每次修正輪次約需 10-30k 個;自訂場景會消耗更多),因此建議每輪修正多個問題,並閱讀一張連接觸控表而非多張單獨截圖。

原生或手機應用(非網頁):要求提供一段簡短的螢幕錄影(5-10 秒,單一任務,關閉通知,螢幕上無個人資訊),然後執行 python film.py import-recording rec.mov films/<slug> --start 2 --seconds 6。它會在頁面視窗內以影格方式顯示,取代原本繪製的卡片。

在修改超出 film.json 範圍的頁面之前,請先閱讀 playbook.md(先看結構與剪輯章節,在選擇音樂前先看聲音章節)。音樂:預設使用產生的佔位音軌;切勿在儲存庫中內附音軌,客戶提供的音軌必須擁有允許其發布影片的授權。

手動流程(make 的逐步動作)

循環

  1. 簡報,一次完成。 類型(宣傳片、解說片、社交短片),影片的單一承諾(一句話),長度,播放平台,以及允許展示的內容(僅限客戶有權發布的素材;不得使用你無法說明使用權限的資料)。若客戶未提供長度,品牌形象片為 30-60 秒,社交短片為 15 秒。不要詢問影片應該如何製作;那是你的工作。
  2. 先看參考,再做畫面。 取得 2 個以上同領域的影片(觀看它們,僅下載你為私人研究可保留的內容)並執行 python film.py measure ref1.mp4 ref2.mp4。它們的平均鏡頭長度、靜態幀比例與每卡字數將是你的衡量基準。閱讀 playbook.md:在編寫前先看結構與剪輯章節,在混音前先看聲音章節。切勿複製參考影片;取其數據與技法。
  3. 將影片編寫為一個 HTML 頁面(從 academy/template.html 開始,film.py new 會將其複製到專案中;它也定義了 window.timeline() 和 window.cards(),以便門控機制知道真正的剪輯點與卡片文字)。契約:window.seek(t) 作為時間 t 的純函數來繪製頁面狀態(無計時器,無自動播放的 CSS 動畫),window.duration() 回傳秒數,window.cues() 回傳 [{t, sfx, db}] 表示應在特定影格出現的聲音,window.ready 是一個關於字體與圖片的 Promise,window.MISSING 列出載入失敗的素材(任何條目都會導致渲染失敗)。將場景起始點對齊音樂的小節網格(bar = beats_per_bar * 60 / bpm)。以回報畫面開場(第 0 幀是一張圖片),一個承諾,一個關鍵的後期時刻,品牌標誌早期出現並在結尾卡再次出現。
  4. 在渲染前先查看。 模型無法播放影片:執行 python film.py stills film.html out/stills 0,2.5,5 並讀取 PNG 圖片;渲染後執行 python film.py sheet film.mp4 sheet.jpg 會在一張圖片上產生每秒一格。修正你所看到的內容。
  5. 渲染。 python film.py render film.html out/film.mp4 --fps 30 --size 1280x720 --workers 2(主版本使用 --fps 60 --size 1920x1080)。N 個 Chromium 工作者各自渲染一個片段;任何工作者崩潰或素材缺失都會導致整個渲染失敗,絕不接受較短的影片。頁面的提示點(cues)會被寫入 out/film.cues.json。
  6. 音效。 python film.py mix out/film.mp4 out/final.mp4 --plan plan.json --music track.mp3 --sfx sfx_dir --cues out/film.cues.json。plan 以小節為單位列出音樂段落(track_bar -> film_bar, bars),使每次跳轉都落在強拍上;最後一個和弦在結尾卡下方持續。響度壓縮至 -14 LUFS,真實峰值 -1 dBTP(雙遍 loudnorm),並在處理後進行量測。音樂:自備,且需有允許你發布影片的授權(切勿在儲存庫中內附音軌);音效則以 <name>.wav 形式提供。預設無旁白;平淡的合成語音還不如沒有。
  7. 長片分段處理。 為每個段落建立自己的頁面並分別渲染,以便多人或多個代理可並行工作,然後執行 python film.py join p1.mp4 p2.mp4 p3.mp4 --out film.mp4 --dissolve 0.5(每個段落的 .cues.json 會對應到整部影片的時間軸上),並在整部影片上一次完成混音。
  8. 門控。 python film.py gate --film out/final.mp4 --against previous.mp4 --refs ref1.mp4 ref2.mp4 --timeline times.json --bpm 120。當剪輯比前一次更慢、更靜態,或出現大量短鏡頭/每拍都在剪輯的情況時,它會停止處理(退出碼 5);並對每卡字數與響度提出警告。ffmpeg 的場景評分幾乎無法偵測到平緩的轉場效果,因此請在 times.json 中提供真實的剪輯時間({"final": [2.0, 4.0, ...]},鍵值為檔案主檔名)。修正影片,再次渲染,再次門控。從未超越前一次剪輯的影片不算完成。
  9. 筆記約束每一次剪輯。 每當客戶對影片有任何評論,立即在同一輪中逐字記錄:python film.py note "<他們的確切文字>" --source "who, date" [--means "你的解讀"]。在門控之前,針對確切檔案勾選每條筆記,標註其在何處得到回應:python film.py tick N1 --film out/final.mp4 --where 0:04(時間戳記或 shot 7)。film.py gate 會拒絕(退出碼 6)任何筆記在該檔案的雜湊值下尚未被勾選的情況;重新渲染或更換音樂會產生新檔案,需要重新勾選。python film.py notes --film out/final.mp4 會列出仍未處理的筆記。客戶的文字絕不能被編輯;你的解讀應放入 --means 參數中。
  10. 交付完成的影片。 客戶應看到最終剪輯(全解析度主版本、用於海報的靜態圖片),而非動態腳本、故事板或半成品;若他們要求看草稿,那是他們的決定,而非預設行為。

一直成立的規則

  • 客戶的品味凌駕於任何評分之上:門控機制捕捉的是退步與無生氣的剪輯,並非挑選較好的影片。當客戶指出影片的優缺點時,將其加入 playbook 中以供下次使用。
  • 絕不重建管線中已經被量測工具涵蓋的部分:先量測(film.py measure),再修改。
  • 修正內容應放入此資料夾(playbook、頁面模板、規劃檔)中,而非寫入會在會話結束後遺失的提示詞中。
  • 參考影片、片段或有授權的音軌不得放入儲存庫:僅儲存數字。

檔案

檔案用途
film.py命令列工具:new, make, import-recording, check, render, stills, join, mix, measure, gate, sheet, note, tick, notes
academy/project.py, academy/template.htmlnew/make:影片專案、由設定驅動的頁面
academy/render.py逐幀 Chromium 渲染器(並行切片、ffmpeg)
academy/mix.py小節線音樂剪輯、提示點擊中、雙遍 loudnorm 至 -14 LUFS
academy/join.py段落合併(含溶解效果)、提示點合併
academy/gate.py量測與檢查機制
academy/notes.py逐字筆記、與檔案雜湊值綁定的勾選
playbook.md43 個有來源依據的技巧與門控機制的數值
data/參考數值(18 部已發布影片)與剪輯工藝限制(205 部影片),僅含數字
example/一部 10 秒的原創影片(bash example/build.sh):對一個虛構產品執行 new 然後 make

相關技能