Communitygithub.com

yazzang-homelab/motion-studio

讓 Claude 審視自己產出的影格:使用 critique.mjs 取得證據、嚴格的 7 軸評分、在 docs/review_log.md 中記錄帶有時間戳記的 P0/P1/P2 問題、修復最嚴重的 3 個問題、重新檢查、通過閘門。用於「評論它」、「審查影格」、「它好嗎?」等指令。

motion-studio 是什麼?

這是一個專為 AI 代理(如 Claude Code 或 Cursor)設計的「批判性評論循環」技能,旨在協助動畫或影片專案的反覆迭代與品質把關。其核心功能是讓 AI 代理能夠「觀看」自己產出的影格,並透過一個嚴格、自動化的 7 軸評分系統來評估品質。此技能支援使用者發起「評論它」或「審查影格」等請求。它會先產生證據(如連續圖、電話圖、靜態圖等),然後從確定性、字體、死區、彈跳/跳動、同步、音訊和靜音等 7 個維度進行評分,並將帶有優先級(P0/P1/P2)和時間戳記的問題記錄到 `docs/review_log.md` 檔案中。在每一輪評論中,AI 代理會自動修復評分最差的 3 個問題,然後重新檢查受影響的片段,並重複此循環,直到連續 3 輪的所有軸向評分都達到 8 分以上且沒有 P0 等級的錯誤,最後才會通過閘門並執行最終渲染。根據其 SKILL.md 文件,此技能適用於任何使用 `studio.json` 作為專案設定檔案的影片專案,並強調以高努力值(high)運行,因為誠實地評斷影格需要刻意關注。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/yazzang-homelab/motion-studio/tree/HEAD/skills/critique-loop

在你喜歡的 AI 中提問

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

說明文件

評論循環(課程步驟 11)

Opus 可以讀取圖片,因此它能查看自己渲染的內容。這個習慣區分了成功的影片和被貼上「有點普通」標籤的影片。迭代是方法,而非失敗:一個廣為流傳的 45 秒短片,背後是大約 6.75 小時內進行的 163 次模型呼叫。此技能以 high 努力值運行,因為誠實評斷影格需要刻意關注。

critique.mjs evidence -> 查看每個 PNG -> 7 軸評分 -> 帶時間戳記的 P0/P1/P2 -> 將一輪結果附加到
docs/review_log.md -> 修復最差的 3 個 -> 重新檢查受影響的秒數 -> 下一輪
直到:>= 3 輪 且 最後一輪每個軸 >= 8 (僅在 gate.naAllowed 列表允許時為 na) 且 無 P0 -> npm run gate -> npm run render:final

在影片專案根目錄(包含 studio.json 的資料夾)中作業。參數(格式和更改內容,皆為選填;格式預設為 studio.json 的 primaryFormat),僅顯示一次:

此技能的檔案位於 ${CLAUDE_SKILL_DIR};以下的相對連結指向該處。

僅審查,不重新渲染: 當使用者要求您審查已存在的證據(如連續圖、靜止影像、影片)而不修改程式碼時,請跳過步驟 1、5 和 6。檢視現有檔案,進行評分,並附加該輪結果(步驟 4)。

0. 在第一輪之前

  • docs/shotlist.md 已獲批准,npm run lint 乾淨無誤,影片可透過 npm run preview 播放。
  • 要評斷音軌,需要有音訊:請先執行 npm run score(或使用提供的音軌執行 npm run beats -- <track>)和 npm run sfx,以便產生提示、節拍網格和同步指標。
  • 音軌是根據混合渲染的結果來評分,且評論者無法進行渲染或混音。在每一輪提示、音樂或畫面時間有變化的回合(通常在第一輪和最後一輪)之前,請先建構它:node tools/render.mjs --format <fmt> --draft --sub 1 --scale 0.5,然後 npm run sfx,再 node tools/mix.mjs --format <fmt>。接著,在評分或向評論者簡報之前,先產生步驟 1 的兩個證據通過。

1. 產生證據

兩個通過,彼此永不覆寫。在此類 PC 上衡量:即時通過大約需要 115 秒(12 秒示範)和約 145 秒(20 秒影片,主要時間花在三次確定性通過加上 15 到 25 秒的瀏覽器啟動),--video 通過約需 85 秒(20 秒影片),一次 motion-critic 運行需要 5 到 12 分鐘。在背景啟動每個通過並輪詢其日誌,切勿在前台等待超過約 2 分鐘:

node tools/critique.mjs --format 9x16                              # 即時影片 -> out/review/9x16/
node tools/critique.mjs --format 9x16 --video out/9x16/final.mp4   # 混合渲染 -> out/review/9x16/video/

即時通過負責確定性、精確像素、loop.png 和提示同步;其音訊列顯示 n/a。影片通過負責響度、真實峰值、音訊長度以及編碼實際包含的內容;它會跳過確定性檢查且不寫入 loop.png。根據影片通過評分音軌,根據兩者評分其他所有項目。若無混音,音軌便無證據:將分數評為 4 或更低,並附加一個指出缺少證據的 P1 問題(此類回合不能作為最後一輪)。

out/review/<fmt>/ 中的檔案(video/ 中的同名檔案)顯示內容檢查重點
metrics.md / metrics.json確定性不匹配、繪製文字的字形覆蓋率(字型,即時通過)、死區、爆音、第 0 幀、循環接縫、角落、邊框、提示同步、音訊和靜音區間(--video 通過),以及每個表單的所有頁面列表首先閱讀;每個標記都會變成一個問題或書面駁回
contact.png每個節拍一張靜止影像,標有 時間 · 節拍 · 鏡頭。每個表單(連續圖、鏡頭圖、手機圖、條狀圖;npm run stills 和 critique.mjs 皆同)都被分割成由完整行組成的頁面:沒有一頁高於 --page-height(預設 1800 px)或寬於 1990 px,第 1 頁為 contact.png,然後是 contact-2.png、contact-3.png ...;metrics.md 會列出所有頁面,請開啟所有頁面。--from S --to S 可審查單一章節死節拍、重複鏡頭、狀態變化時的重疊
phone.png每秒一張 360 像素寬的靜止影像在手機上的可讀性
shots.png每個鏡頭中點一張靜止影像構圖、禁止出現的外觀、層級
strip.png最快速動作周圍的 12 個連續幀(使用 --strip-at S 選擇時間點)滑動、爆音、重新開始、文字重疊
loop.png僅限循環影片(studio.json 中 loop: true,畫布影片,即時模式):如下所述的窗格接縫跳躍、未閉合的迴圈

node tools/critique.mjs 的所有標誌(使用 --help 可查看相同列表):

標誌效果
-f, --format <fmt>要審查的格式;預設為 primaryFormat。檔案會寫入 out/review/<fmt>/
--video [path]審查已渲染的 mp4 而非即時影片。僅使用 --video 會使用 out/<fmt>/final.mp4,否則使用 silent.mp4。會增加整合 LUFS、真實峰值和音訊長度;跳過確定性通過;不寫入 loop.png(僅連續性指標)。所有內容都會寫入 out/review/<fmt>/video/,因此即時證據保持不變;報告會提及兩個資料夾
--from <sec>, --to <sec>審查長影片的單一章節:靜止影像、每個表單和每個指標(死區、爆音、確定性樣本、字形覆蓋率、靜音區間、提示)僅涵蓋該範圍,metrics.json 在 range 中記錄。僅對整個影片檢查第 0 幀和循環接縫(報告為已跳過),響度始終是整個檔案,自動條狀圖保持在範圍內。無效範圍(--from 超過結尾、--to 未大於 --from、少於 3 幀)是使用錯誤,退出碼 2
--page-height <px>一個表單圖片的最大高度(預設 1800;圖片檢視器會縮小超過約 2000 px 的內容)。較高的表單會被分割成由完整圖塊行組成的頁面(contact.png、contact-2.png ...);0 = 一個高表單。一頁的寬度也不會超過 1990 px(--cols 會降低以適應)
--strip-at <sec>將 12 幀條狀圖居中於某個時刻,例如問題時間(預設:動作最多的時刻)
--no-determinism當本輪的確定性檢查已通過且僅圖片有變化時,跳過三個雜湊檢查
--skip-determinism-repeat當影片雜湊值、assets/ 下的每個檔案(圖片、字型、音訊、提示資料:名稱、大小和內容)、格式、--from/--to 以及通過的程式碼未改變時,重複使用前一次即時通過成功的確定性結果(資料夾中的 determinism-cache.json);對 film/**、lib/**、studio.json 或 assets/ 的任何編輯都會更改金鑰,因此通過將再次運行。失敗的結果絕不重複使用。指標列顯示 n/a ... reused from the run of <time>。Chrome 升級不屬於金鑰的一部分:升級後,不加此標誌運行一次
--check-hash不啟動瀏覽器:比較即時影片(film/** + lib/** + studio.json 的 sha256 雜湊值)與 out/review/<fmt>/ 中的證據(為 video/ 添加 --video);退出碼 0 = 相同影片,1 = 已更改或無雜湊值,並會列出更改的檔案名稱
--json印出一行 JSON 結果(路徑、每個表單的 pages、range、摘要、發現、nextRound、閘門狀態)而非報告
-h, --help使用說明

若不使用 --json,會印出報告:證據列表、指標表格、機器發現的候選問題、評分標準和一個準備好填寫的審查日誌區塊,內含下一輪的編號(也會儲存為 metrics.md)。該工具從不評分。使用 --json 時,該行會包含 dir(此運行寫入的位置)和 other(另一模式的資料夾、模式和時間,或 null)。

loop.png 窗格,從左到右(皆以相同方式縮小):

窗格顯示解讀方式
last frame第 N-1 幀接縫前的狀態
t=dur unwrapped在 t = duration 時的原始結束狀態僅在運行時期支援 hash(t, { wrap: false }) 時存在,該工具會先測試
seek(0)第 0 幀接縫後的狀態
`last - firstx4`
`end - firstx4`

metrics.json 中的循環判定 loop = { enabled, unwrapped, invariant, hashEqual, endDiff, seamDiff, prevDiff, ratio, continuity, closes, pass }。continuity = 最後一步到第一步最多是最後兩幀之間步驟的 1.5 倍(或低於 critique.staticEps);closes = hash(0) 等於 hash(duration, { wrap: false }),或者它們的平均差異低於 0.1。失敗是影片結束時的 P0 問題。若缺少未包裝窗格(較舊的運行時期,DOM 影片),則僅測量連續性,報告會說明此情況。

每個證據資料夾也包含 film-hash.json(證據所顯示的影片版本;filmHash 在 metrics.json 中重複)和 baseline.json(上次運行的爆音、跳動和死區候選時間)。這對審查有兩個影響:

  • 影片版本: 在您從即時影片渲染任何縮放靜止影像之前,請執行 node tools/critique.mjs --check-hash --format <fmt>。不匹配意味著靜止影像顯示的影片比連續圖更新:停止,報告不匹配(命令會列出更改的檔案)並要求新的證據;切勿混合版本。不要在評論者審查時編輯影片。
  • 差異: 從資料夾中的第二次運行開始,metrics.md 會印出 same as previous run: N of M candidates,並首先列出新的候選項(機器發現列表在每個嚴重性級別內首先放置新發現,並將其他標記為 [same as the previous run])。完整審查新的發現,並僅在影片在其時間附近發生更改時重新驗證舊的發現。

步進(像素藝術,「雙幀」)影片 是故意製造困難步驟。在 studio.json 中設定:critique.stepped: true 會將每個 jump 列為資訊(metrics.json 中的 pops.info,metrics.md 中的「Suppressed by studio.json」部分)而非 P2 發現;單幀的 flicker 仍為 P1。critique.popIgnore: [[t0, t1], ...](秒,0 <= t0 < t1)可在預期的區間內抑制兩種爆音(pops.ignored 會列出它們及其區間)。metrics.md 會說明每個設定抑制了多少候選項及原因。這是影片的語法,而非閾值調整:真正的故障仍會在步進區間外顯示為閃爍或跳動。

指標語義,以便正確分類標誌:

指標失敗條件發現
確定性 (determinism)任何取樣時間的雜湊值在順序、打亂或新頁面上不同(樣本跨越每個鏡頭邊界和提示)P0
字型 (fonts, 即時通過)影片繪製的字元在其字型中沒有字形,或其字型家族未註冊或是通用型(sans-serif):機器會繪製系統字型(每台電腦不同)或是一個豆腐框。頁面會以 window.__TEXT_TRACK__ = true 開啟,因此 text()、kinetic() 和 textWidth() 會記錄它們繪製的內容,而 __studio.coverage() 會進行判斷。每個字型行一個發現,會命名家族和粗細、最多 40 個缺失字元、總數和修復方式。沒有 textUse() 的頁面會給出 preflight: unavailable 的提示,絕非發現;未繪製的幀上的文字不會被看到P0 font-fallback
死區 (dead spans)平均幀差異在 critique.deadSpanSec(2 秒)或更長時間內低於 critique.staticEps(0.35)P1
爆音、flicker (pops)一幀與其相鄰兩幀的差異都超過 critique.popRatio(3)乘以它們彼此差異的程度P1(意圖的閃爍若緊鄰提示,則在書面中駁回)
爆音、jump (pops)差異峰值超過相鄰四個差異平均值的 popRatio 倍:有東西瞬移、彈入或翻轉P2(來自工具);當它影響鏡頭時,您應將其提升為 P1。當 critique.stepped: true 時僅為資訊;不在 critique.popIgnore 區間內
第 0 幀 (frame 0)幾乎為空:與平滑背景(純色填充、漸層或暈影皆算作背景)不同的像素少於 0.5%P0
角落、邊框 (corners, borders)在 30% 或更多的取樣幀中,角落框(critique.cornerPct,8%)內有小型內容;在 25% 或更多的幀中,三邊或更多邊有薄的均勻邊緣線和突然的內部階梯(暈影、漸層或在彩色背景上的卡片不是邊框)P1(來自工具),經肉眼確認後為 P0(禁止出現的外觀)
同步 (sync)少於 80% 的命中提示(四個或更多提示)在節拍的 25 毫秒內,或鏡頭變化未發生在強拍上;上升音、呼嘯聲和呼嘯聲是有意引領節拍的,不計入P2
音訊 (--video)無音訊流、響度超出目標、真實峰值高於目標、音訊長度與影片相差超過一幀無音訊流或真實峰值高於 0 dBTP 為 P0,否則為 P1
靜音 (--video)低於 -50 dB 的 1 秒或更長的靜音區間(每個間隙一個發現,silence 3.2 s at 00:08.1),除非它始於前 0.3 秒內、始於最後 1.0 秒內或位於 critique.allowSilence 區間內。提前結束的音軌在混音後仍會測量到 -14 LUFS,因此響度無法發現它P1 audio-gap(音訊行顯示 WARN)

兩種爆音也需要在 0-255 尺度上的平均步驟高於 1.0,因此接近靜態的場景不會觸發它們。鏡頭邊界上的硬切會被列為切換,而非爆音。畫布影片會以一半或更小的尺寸(pixelScale)掃描,因為 Chrome 的 CPU 畫布會將字形對齊到小尺寸的整像素,從而偽造跳動;DOM 影片則以 10 fps 從螢幕截圖取樣。切勿更改 critique 的閾值來使標誌消失。

2. 仔細查看

使用讀取工具開啟每張圖片。不要僅根據 metrics.md 來評分,也不要根據對程式碼的記憶來評分。順序:metrics.md、contact.png、phone.png、shots.png、strip.png、loop.png(每個及其所有頁面:contact-2.png、contact-3.png ...;metrics.md 的證據列表會命名它們,或列出資料夾),然後是 video/metrics.md 的音訊行。與 docs/shotlist.md(已批准的鏡頭列表)比較。

Individual skills in this repo

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

yazzang-homelab/motion-studio

Plan long-form or overnight films: director's brief (PLAN FIRST or GO, budget, definition of done), ANIMATION_GUIDE + STORYBOARD, chapter subagents, gates, chunked render. Use for 'overnight film', 'music video', '2-minute film'.

yazzang-homelab/motion-studio

Make a launch video, app or product reel, explainer or motion ad from code, end to end: brand assets from a URL, beat-grid shot list, synced sound, critique loop, all formats. Default for new video requests; not footage edits.

yazzang-homelab/motion-studio

Brand-asset stage of a product film (motion-reel runs the whole film): capture real screenshots, logo, colors and fonts from a URL, never redraw UI; brand story beats; voice + mascot. Use to grab or fix a brand's assets.

yazzang-homelab/motion-studio

Turn a reference (a frame, a video or an image library) into docs/style_guide.md and a beat-grid shot list: measure cuts, palette and pace, take grammar not content, wait for OK. Use when the user supplies or names a look.

yazzang-homelab/motion-studio

Build, debug or speed up the seek(t) render engine: render contract, canvas vs page capture, workers/subframes/chunks, determinism fixes, Remotion or HyperFrames handoff. Use for 'render is slow', 'frames differ', 'use Remotion'.

yazzang-homelab/motion-studio

Ship every format from one timeline, then package it: layout() reframing (never crop), render all formats, per-format checks, deliver.mjs, a brand skill, a service offer. Use for 'export 9:16 and 16:9', 'deliver', 'make a skill'.

yazzang-homelab/motion-studio

The viral one-line 'showreel for a résumé' prompt: why it works (anatomy), the credited quote, and seeded variants that avoid look-alike reels; runs it as an engine test. Use for that prompt, its variations, or a showreel.

yazzang-homelab/motion-studio

Score a film to its beat grid: measure a track (beats.mjs) or synthesize one (score.mjs), cue SFX from the film, add voice, mix to -14 LUFS / -1 dBTP at exact length. Use for 'add music', 'sync to the beat', 'SFX', 'loudness'.

yazzang-homelab/motion-studio

Make motion feel physical with closed-form springs from lib/motion.js: presets, springFromFeel, track() for multi-target values, loopTrack loops, indicators, text swaps. Use for 'feels linear', 'add bounce', 'easing to springs'.

yazzang-homelab/motion-studio

Scaffold a motion-studio film project (seek(t) renderer, springs, beat grid, synthesized sound, critique tools), install it, set up the browser, run doctor. Use for 'set up the motion studio', 'new film project', 'init studio'.

yazzang-homelab/motion-studio

Write a six-part XML state spec for a one-shape UI morph film (inputs, direction, structure, build, gotchas, start): states on downbeats, cursor-driven changes, seamless loop, approval gate. Use for 'UI morph', 'state list'.

相關技能