Communitygithub.com

jayfirke/motion-studio

以導演的身份規劃影片,並在渲染前,以可播放的 previz 頁面(包含真實語音、音樂和音效、時間軸、每個決策的三個可切換選項、時間錨定的筆記、版本和一個核准按鈕)呈現給擁有者。適用於任何長度超過 10 秒的新影片,以及當擁有者要求「先看看」、「previs」、「故事板」、「animatic」,或在 previz 頁面上留下筆記時。會產出 approved-video-spec.json 供引擎技能使用;本身不負責最終渲染。

motion-studio 是什麼?

Motion Studio 是一個 AI 導演技能,旨在將昂貴的創意決策階段提前到成本最低的預製作環節。它作為一個專屬的 Previs Studio 應用程式(基於 React 和 TypeScript)運作,為使用者提供一個完整的互動預覽頁面。此頁面包含影片播放器、故事板、計畫、引導式審查等功能,讓擁有者可以視覺化、試聽並對故事的每個面向給予意見,從音樂和配音到鏡頭運動和轉場效果。對於每一個決策點,該技能預設會提供三個截然不同的選項,並在每個選項旁附上一句簡短的說明或權衡取捨,鼓勵探索和迭代。 Motion Studio 的運作方式是產生一個結構化的計劃(previs.json),該計劃可在一個中央工作室檢視,或作為每個專案獨立頁面的一部分。它透過一個基於筆記的系統與 Claude Code 無縫整合,系統會追蹤評論、要求、選擇和核准狀態。一旦專案獲得核准,它會產出一個 approved-video-spec.json 檔案,作為一個凍結的規格,交由下游的渲染引擎(如 HyperFrames 或 Remotion)執行最終的影片生成。這種設計確保在投入大量渲染資源之前,所有創意決策都已被核准,從而最小化成本並最大化導演意圖的保真度。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jayfirke/motion-studio/tree/HEAD/.agents/skills/video-director-previs

在你喜歡的 AI 中提問

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

說明文件

video-director-previs

在最便宜的階段做出昂貴的創意決策。此技能負責前製:指導、故事、劇本、分鏡、風格幀、動態腳本、音樂、音效、配音、引擎選擇、品管、審查、版本與核准。引擎(HyperFrames、video-shotcraft、Remotion、motion-reel、bang-motion、Diffusion Studio)只建構擁有者核准的內容。

實例:examples/crumb-previs/(一個虛構的分帳應用程式)。其資料包位於 Previs Studio 的示範影片中(_shared/previs/studio/films/011-crumb/)。

應用程式不會因影片而改變。 Previs Studio 是一個固定的 React + TypeScript 應用程式(原始碼位於 _shared/previs/app/,請參閱其 README)。在該處執行 npm run build 會進行型別檢查、打包,並內嵌到 _shared/previs/studio/index.html 和 _shared/previs/page/index.html(範本);為每個影片頁面在 scripts/inline.mjs 中新增一個目標。執行 npm run smoke 會在真實的 Chrome 瀏覽器中,以桌機、平板、手機和全螢幕模式驅動建置好的頁面(使用 --out 參數截圖)。切勿手動編輯已建置好的 index.html。

擁有者得到的:觀看(具備真正全螢幕的影片風格播放器、懸停預覽、結束卡;註解模式能標示滑鼠所指的最小元件、滾動放大或縮小、拖曳框選多個元件、使用筆和箭頭、在鏡頭行上拖曳以選取時間範圍;音軌軌道帶有波形、節拍、閃避曲線、獨奏/靜音/音量以及可對齊節拍的可拖曳音效)、選擇會在其時間點原地重播並附帶聲音、並排比較、按住以聽取原始音訊、故事板(可在原地播放鏡頭卡片、全部播放、每個鏡頭的選擇、鏡頭列表)、計畫(主導演、故事、導演團隊、視覺、音效、資產、製作、檢查、附有「要求復原」功能的版本、規格匯出)、引導式審查、詢問導演、⌘K 搜尋、復原/重做、淺色和深色主題、每個控制項都有工具提示。影片僅以資料包形式送達。

兩個家,同一個應用程式

  • Previs Studio(所有影片): _shared/previs/studio/。新增一部影片 = 新增 films/<id>/previs.json + films/<id>/audio/... 以及在 films.json 中新增一行。本地端:python3 -m http.server --directory _shared/previs/studio(或 .claude/launch.json 中的 previs-studio 條目)。
  • 每個影片的頁面: projects/NNN/previs/page/ 存放一份相同的 index.html(標題為 <產品> Previs),以及一個只有一行資料的 films.json(其 path 為 "")、previs.json 和 audio/。
  • 作為 claude.ai Artifact(僅限 Claude): 使用 capabilities: {"db": {}, "user": {}, "sample": {}, "comments": {}, "downloads": true} 發布頁面。db 儲存筆記和選項,sample 驅動「詢問導演」功能,comments 承載「發送給 Claude Code」指令,downloads 提供規格匯出。沒有這些功能,頁面仍可運作並在瀏覽器中儲存。
  • 資料庫路徑:評論(固定在影片上的變更請求;集合保留舊名稱)films/<id>/notes(kind 為 frame、region、range、sound、shot、revert 或 request;target、targets、box、strokes、quick chips、t/t2、當時的 picks 和 version);選項和音效調整 films/<id>/state/picks(tweaks:<scene>.<sfx> {dt, db}、lane.vo|music|sfx {db}、mix.duck {on});新增選項 films/<id>/state/custom;核准 films/<id>/state/approval;Claude 的狀態 films/<id>/state/claude;活動 films/<id>/activity;筆記(關於整部影片的自由想法:將其作為背景資訊閱讀,切勿視為任務)films/<id>/pad。

函式庫:按需提供超過三個選項

每個決策預設提供三個導演選項;D['libraries'] 能新增更多選項,供審查者(或「詢問」分頁)拉入使用:direction(視覺:token 集合 + fonts_url)、music(CC0 背景音樂,包含 bpm、phase、tags、level)、motion(ease、spring {f,d} 或 bezier)、pacing、camera、transition、sfx(影片中的每個聲音)和 voice(Fish 語音:dir、durs、其他語言的 texts、intro、sample)。全域的 voice 決策選擇旁白者;一個語音將每一行解析為 <dir><scene>-<A|B|C>.mp3;一個帶有 needs 但沒有 dir 的語音會以字幕形式播放,直到被錄製。新增的選項存在於頁面資料庫中、可復原,並會納入已核准的規格中。以 examples/crumb-previs/libraries.py 為模型建立函式庫:

  • 音樂:搜尋 Freesound CC0(freesound.py search ... --min-dur 20)、執行 freesound.py get,然後執行 python3 _shared/previs/music_lib.py <page>/audio/music/lib <oggs>(生成對齊節拍的 24 秒片段,並測量 BPM);為每個背景音樂片段撰寫標籤和選用原因;在 _shared/ASSETS.md 中記錄。
  • 語音:使用 search_voices 挑選公開的 Fish 語音(不得使用真人或角色複製品),將其列在 voices/voices.tsv 中,撰寫 voices/lines-<lang>.txt,執行 voices/make_voices.sh(免費模型),然後使用 whisper-cli 抽查錄音片段,並重新生成任何有漏字的片段。
  • AI 導演(「詢問」分頁,lib/director.ts)也可以設計視覺風格(需經對比度檢查、允許使用 Google 字型)、動態感覺,以及新的台詞措辭(這些需要錄音:它會為 Claude Code 提交一個請求筆記)。

Claude Code 對筆記的處理(每輪都需執行)

擁有者從頁面發送筆記(「發送給 Claude Code」:一個會喚醒等待中工作階段的即時評論,或是一則複製的訊息)。然後: 0. 變更之前先拉取。 claude.ai 上的 Claude 可以自行回覆「發送給 Claude Code」的討論串、編輯資料檔案,並發布新版本。在建構之前,請讀取已發布的 previs.json,將其與您的本地建構進行比較,並將任何變更移植到 build_previs.py 中,以便下一次建構能保留這些變更。

  1. 設定 films/<id>/state/claude {state:"reading"|"working"|"publishing"|"idle", at, message, version, open},讓頁面顯示您正在執行的操作。
  2. 對於每一則未處理的筆記:讀取時將其 update 為 claude: {state:"seen"},變更時更新為 {state:"working"},然後設定為 status:"done"、claude:{state:"done", at, msg},並在 replies 中附加 {by:"claude", text, at}(如果 if_version 相符則固定)。當您需要詢問擁有者時,使用 state:"question"(問題寫在 msg 中);當您建議維持原樣時,使用 "wontfix"。kind:"request" 的筆記是來自「詢問」分頁的任務(錄製新台詞、尋找聲音);prefer 指向擁有者偏好的選項;intent:"question" 表示需要一個答案,而非變更。 每個 at 都是真實時間:從 date -u +%Y-%m-%dT%H:%M:%SZ 取得,切勿猜測。
  3. 在 films/<id>/activity 中新增行({at, by:"claude", kind:"seen"|"applied"|"published"|"question", text, version}):記錄您讀取了什麼、變更了什麼、發布了什麼。
  4. 如果擁有者使用了「發送給 Claude Code」,請在頁面評論串中回覆,然後將其標記為已解決。

規則

  • 一位導演,沒有委員會。 按照下面的專家檢查清單,親自依序完成。除非擁有者要求(成本規則),否則不使用工作流程或子代理。
  • 積極推斷;僅詢問真正的障礙(產品真相、缺少的資產、授權問題)。在擁有者看到東西之前,絕不發送冗長的問卷。
  • 預設為每個決策提供三個選項。 引導、音樂、動態感覺、節奏,以及每個場景:轉場、鏡頭、語音台詞、每個音效事件。選項必須有實質差異。標記導演的選擇,並為每個選項提供一句簡潔的理由或權衡。「無」是一個有效的音效選項。
  • 產品真相。 每個場景都標記為 real_ui、conceptual_ui、conceptual_visual 或 external_footage;任何非真實的內容都會在播放器中顯示標籤。
  • 基本規則仍然適用(AGENTS.md、OWNER.md):禁止的陳腔濫調、載片、兩個文字層級、錄製的擬音、預設語音、授權。頁面僅播放 CC0 或自製音訊;Mixkit(僅供渲染)僅能以名稱出現。
  • 縮小規模。 一個 6 秒的片段可以是一張引導卡片、3 個音樂選項和一個 6 秒的動態腳本。一個 40 秒的產品影片則需要完整的設定。
  • 鎖定。 一旦擁有者核准,故事、文案、順序、時間點和選項即被鎖定。後續的筆記僅能更改其目標;列出您保留了哪些內容。

專家檢查清單(導演需逐一簡要涵蓋)

故事(2 秒內建立鉤子,每個節奏一個狀態)· 劇本和語音台詞(每秒字數 ≤ 3.4)· 編輯節奏(變化鏡頭長度、間歇、不要每個剪輯都對在節拍上)· 美術指導(3 種方向,以 token 集合表示:bg、on-bg、card、on-card、muted、line、paper、on-paper、accent、on-accent、frame、display、ui、mono)· 字體排印學 · 參考資料(借用 / 避免 / 使用位置;文法,絕非內容)· 鏡頭(每個移動都有理由)· 動作(目的、緩動、UI 上 overshoot ≤ 4%、字體上無)· 轉場(簡單的剪輯是有效的)· 資產(現有 / 新生成 / 產出 / 佔位,附帶授權)· 音樂(測量 BPM 和相位、能量曲線、Drop 位置)· 音效(資產、時間、觸發器、增益、原因)· 混音(語音為主導,閃避 8 dB,衝擊聲最大)· 引擎(選擇原因、備用方案、替代方案、回退方案)· 品管。

檔案(每個影片一個資料夾)

projects/NNN-name/previs/
  build_previs.py          # 撰寫 page/previs.json;複製 examples/crumb-previs/build_previs.py 並編輯(scenes = HTML 風格幀 + 動畫補間)
  vo-lines.txt             # 每行 3 種措辭,供 fish_tts.py 使用
  page/index.html          # 由 _shared/previs/app 建置(npm run build;在 scripts/inline.mjs 中將此頁面新增為目標)
  page/films.json          # [{"id": "NNN-name", "name": "Product", "path": ""}]
  page/previs.json         # 整個計劃
  page/audio/{music,vo,sfx}/
  changes.jsonl            # 僅附加的變更日誌,每行一個操作
  approved-video-spec.json # 核准後由 _shared/previs/freeze_spec.py 寫入

步驟

  1. 閱讀簡報或一句話要求,以及產品來源(真實 UI、token、文案)。撰寫 BRIEF.md,記錄推斷出的決策。
  2. 音訊(廉價、本機):
    • 背景音樂:透過在低頻段起始包絡上進行 85–150 BPM 的梳狀濾波擬合來測量速度和相位(AGENTS-tooling.md,“Previs”);從節拍開始處剪出 24 秒片段,透過 loudnorm 規範化至 −18 LUFS:ffmpeg -ss <phase> -t 24 -i bed.wav -af "loudnorm=I=-18:TP=-2,afade=t=out:st=22.5:d=1.5" page/audio/music/A.mp3。
    • 語音:python3 _shared/tools/fish_tts.py --lines previs/vo-lines.txt --out-dir previs/vo-wav(免費模型),然後將無聲部分修剪成 page/audio/vo/sN-{A,B,C}.mp3。
    • 擬音:從 _guide/prompt-studio/media/foley/ 複製 CC0 預覽,或使用 freesound.py 取得。
  3. 規劃在 build_previs.py 中(參閱範例以了解所有欄位):project、summary、chief、story(節拍 → 場景)、directors、assets、gates、pipeline、changes、directions(3 個)、global.music|motion|pacing|voice(各 3 個)、engine、references、style_rules、audio_notes、qa、versions、film_css(所有顏色透過 token 設定,類別前綴 f-)、fonts_url,以及 scenes[],其中包含 html、anim(補間 {s, t:[a,b], f, to, e} 作用於 x、y、s、sx、sy、r、o、clip、w、blur;{s, set, at, until} 類別切換;{s, count:[from,to], t, p, d} 計數器;e:'m' 跟隨 Motion 選擇)、decisions(轉場類型 cut、push、slide、zoom、iris;鏡頭 {s,x,y,origin};語音 {text, src, dur, at, copy})、sfx(at 可以是列表,用於連續觸發)、key(故事板靜止畫格的時刻)。為每個擁有者可能指向的元素提供一個簡單易懂的 data-name(「收據總計」、「請求按鈕」)。
  4. 本地端檢查:提供頁面資料夾服務,查看每個場景的一張靜止畫格和一個過渡中的畫格,切換所有三種方向一次,確認無控制台錯誤。一次通過,不循環。
  5. 分享頁面(本地端,或作為具有上述功能的 claude.ai Artifact),並將影片新增至 Previs Studio。提供擁有者連結和五行摘要。停止以等待審查。
  6. 審查循環(每輪重新發布一次):
    • 讀取筆記、選項和核准狀態。
    • 對於每則未處理的筆記:僅更改其目標,在 changes.jsonl 中附加一個操作({"v","target","t","change","from","to","reason","preserve":[...]}),然後用一行回覆(上述協定)將筆記標記為完成。revert 類型的筆記要求復原一個已列出的變更。
    • 在 build_previs.py 中增加 versions 並新增該輪的 changes,重新執行,將 previs.json 複製到 Studio 副本中,然後重新發布。播放器會顯示一個「變更內容」橫幅,而「計畫」會列出每個變更,並附帶一個「復原」請求。
  7. 核准:當 state/approval 中的 approved: true(它包含了 picks、tweaks 和 custom)時,儲存它,執行 python3 _shared/previs/freeze_spec.py projects/NNN-name/previs --approval <file>(它會解析新增的選項和語音,並列出 needs_before_build,例如未錄製的台詞),從規格中撰寫 SHOTLIST.md,然後交由規格中命名的引擎技能處理。引擎會嚴格依照規格建構(允許潤飾,不允許更改決策)。

成本

僅限單人工作。一個 20 秒的 previz 大約需要一次工作階段的幾小時(約當於 $30–60 的 API 成本),使用 Fish 免費模型且無需渲染。最終的渲染及其檢查將在核准後進行。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相關技能