Communitygithub.com

motionsnip-studio

以程式碼構建動態圖形,並在 MotionSnip Studio 本地播放器中進行審查。使用者觀看渲染結果、修改文字、更換音樂、在畫面上圈選問題,然後回傳一個提示。

motionsnip-studio 是什麼?

MotionSnip Studio 是一個 AI 代理技能,專為需要反覆迭代程式碼生成的動態圖形、解說影片或產品宣傳影片的開發人員設計。它建立一個緊密的反饋循環:代理建構並渲染影片,產生一個 `reel.json` 描述檔,然後啟動一個本地播放器伺服器。使用者觀看渲染結果,直接在畫面上點擊、圈選問題、調整音樂,最後點擊「傳送給 Claude」將結構化的反饋發送回代理。代理接著解析反饋檔案,應用精確的修改(如調整文字、顏色、尺寸或音訊設定),重新渲染影片,並自動增版次編號,讓播放器自動重新載入以顯示更新。此技能支援 Remotion 及任何能輸出 mp4、webm 或 mov 檔案的渲染器。它採用「先自我審查、再交給使用者」的策略,包括自動產生聯絡表單以檢查排版和時機問題,並將可編輯的屬性(如音樂和文字)分離出來,以實現更快速的迭代,而無需每次都完全重新渲染。核心元件是 `reel.json` 檔案,它作為代理與使用者播放器之間的合約,定義場景、元素、道具、品牌資產和反饋紀錄。該技能也支援輸出不同長寬比(如 9:16 用於 Reels),並可選配即時渲染器和匯出掛鉤。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jishanpathan7/motionsnip-studio/tree/HEAD

在你喜歡的 AI 中提問

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

說明文件

MotionSnip Studio

你負責建構影片。使用者則在本地播放器中進行審查。流程如下:

  1. 建構並渲染影片。
  2. 在 reel.json 中描述它。
  3. 開啟播放器。
  4. 使用者進行審查,然後點擊 傳送給 Claude。你會收到一行:Apply the MotionSnip Studio feedback in <絕對路徑>。
  5. 套用反饋,重新渲染,並增加 version。播放器會自動重新載入,協助使用者確認你的修改。

在本文件中,<技能目錄> 指的是存放此 SKILL.md 的資料夾,通常是 ~/.claude/skills/motionsnip-studio。

1. 設定專案

每個影片使用一個獨立資料夾:

<專案>/
  reel.json        你撰寫這個
  video.mp4        渲染結果(任何名稱;reel.json 的 "src" 指向它)
  assets/          音樂、圖片、標誌(使用者上傳的檔案也會放在這裡)
  public/          可選;Remotion 的 staticFile() 素材
  exports/         由播放器的「匯出」功能產生;請勿編輯
  .motionsnip/     播放器狀態與歷史紀錄;請勿編輯

如果使用者還沒有渲染器,Remotion 是不錯的預設選擇(npx create-video@latest)。任何能輸出 mp4、webm 或 mov 的工具都可以。

2. 建構以便於編輯

  • 將文案、顏色、字型和時間設定集中在一個資料物件中(Remotion 的 defaultProps 或一個 content.ts),而不是分散在各個元件中。這樣,反饋編輯就只需修改一行。
  • 為每個畫面中的元素指定一個穩定的 ID,並在 reel.json 中使用相同的 ID。
  • 將音樂作為獨立檔案提供。僅在影片中渲染音效。 將音軌放入 assets/,並將 audio.music 指向它,同時將 audio.videoAudio 設為 "effects"。播放器會在影片旁播放音樂,讓使用者無需重新渲染即可切換音軌、調整起始點和設定音量。他們的「匯出」功能會在後端使用 ffmpeg 將其混合。
  • 僅在使用者要求時才將音樂燒錄到影片中。此時將 videoAudio 設為 "mix"。

3. 先渲染查看,再展示

渲染後,使用聯絡表單檢查自己的作品:

ffmpeg -v error -y -i video.mp4 -vf "fps=1,scale=480:-1,tile=4x3" -frames:v 1 /tmp/sheet.png

打開圖片並查看。在開啟播放器之前,修正截斷的文字、空白幀、錯誤的顏色和時機間隙。查看單一幀:

ffmpeg -v error -y -ss 12.4 -i video.mp4 -frames:v 1 /tmp/frame.png

自我審查。 然後像一個吹毛求疵的審查者一樣再看一次,並記錄你仍然看到的問題。檢查:

  • 安全區域。 所有重要元素是否都位於從每個邊緣向內 10% 的範圍內(標題安全區)?
  • 尺寸。 內文文字高度至少約為畫面高度的 3%,以便在手機上閱讀。
  • 對比度。 文字和關鍵形狀必須與背景明顯區分。
  • 錯字與溢出。 每個單字拼寫正確,沒有被裁剪或超出其範圍。
  • 剪接與時機。 剪接點沒有閃爍幀,沒有空白幀,沒有在可讀取前就消失的內容。

修正你能修正的問題。對於任何遺留的問題,或任何屬於品味問題的部分,將發現新增到 reel.json 中的 review(第 4 節)。播放器會在該幀上將每個發現繪製為一個標記為 C1、C2… 的藍色虛線圓圈,使用者可以將其新增為自己的註釋或將其關閉。僅撰寫你實際在幀截圖中看到的內容:提供時間,以及位置或元素,以便圓圈能準確標記。當沒有什麼可說的時,讓 review 保持空白;不要為了填空而新增內容。

4. 撰寫 reel.json

reel.json 是你和播放器之間的合約。請撰寫純 JSON(不含註解)。

{
  "id": "acme-launch",              // 穩定;使用者儲存的編輯內容以此為鍵
  "title": "Acme launch",
  "version": 1,                     // 每次渲染時增加;播放器在它改變時會重新載入
  "path": "/abs/path/to/project",   // 你的工作目錄;會顯示在提示中
  "src": "video.mp4",
  "w": 1920, "h": 1080, "fps": 30, "duration": 32.0,
  "reference": "可選:影片的參考範本",
  "brand": {
    "colors": [{ "id": "accent", "name": "強調色", "v": "#5B5BF7" }],
    "fonts":  [{ "id": "head", "name": "標題", "v": "Inter" }],
    "logo": "assets/logo.svg"       // 或 null
  },
  "audio": {
    "music": "assets/track.mp3",    // 在影片旁播放,或為 null
    "videoAudio": "effects",        // "effects" = 影片僅包含音效;"mix" = 音樂已燒錄
    "bpm": 120, "drop": 4.0,        // 可選的節拍網格;drop = 重拍落地的秒數
    "musicVol": 1, "sfxVol": 1,     // 0..1
    "musicOffset": 0,               // 秒;正值表示音樂延遲開始,負值表示跳過音軌開頭
    "musicFade": 0,                 // 結尾淡出的秒數
    "note": "自由文字"
  },
  "assets": [{ "id": "assets/track.mp3", "name": "track.mp3", "type": "audio", "from": "User" }],
  "scenes": [
    { "id": "S1", "name": "鉤子", "t": [0, 4.5], "els": [
      { "id": "headline", "label": "標題", "t": [0.3, 4.3],
        "box": [20, 38, 60, 24],    // x, y, w, h 佔畫面的百分比;若是旁白、音訊或全螢幕素材則為 null
        "src": "src/Hook.tsx:12",   // 繪製該元素的檔案(或檔案:行號)
        "props": {
          "text":   { "type": "text",   "label": "文字",   "v": "Meet Acme" },
          "color":  { "type": "color",  "label": "顏色",  "v": "brand.accent" },
          "motion": { "type": "motion", "label": "動畫", "v": "文字逐一模糊淡入" }
        } }
    ] }
  ],
  "notes": [],
  "review": [                       // 可選:你自己的自我審查發現(第 3 節)
    { "id": "v1-1", "t": 1.5, "elId": "headline", "kind": "safe area",
      "title": "標題超出右邊界",
      "detail": "在第 1.5 秒,最後一個單字距離邊緣僅 2%,超出了標題安全區。",
      "fix": "將框寬度縮小至 56% 或將字體調小一級。" }
  ],
  "outputs": [                      // 可選:由此產生的其他形狀或長度(第 9 節)
    { "id": "vertical", "label": "9:16", "kind": "reframe", "src": "out/vertical.mp4", "w": 1080, "h": 1920, "platform": "reels" }
  ],
  "live": "live.js",                // 可選的即時渲染器(第 7 節)
  "export": { "cwd": "/abs/build/folder", "props": {}, "cmd": "npx remotion render ... \"$OUT\" --props=\"$PROPS\"" }  // 可選(第 8 節)
}

規則:

  • 屬性類型: text、longtext、number、color(brand.<id> 連結到色板)、media(一個素材 ID)、list(行;cols: [{ k, type, options? }])、choice(options: [...])、motion(對動作的純文字描述;使用者只能對此發表評論)。
  • 場景涵蓋 0..duration,且無間隙。時間以秒為單位。
  • 在不同版本之間保持場景和元素 ID 穩定。儲存的編輯內容通過 ID 匹配。
  • box 必須與元素在螢幕上的實際位置匹配,以畫面百分比為單位。如有疑問,請從幀截圖測量。使用者點擊這些框來選取元素。
  • src 應指向繪製該元素的程式碼,以便你之後能找到它。
  • 每個屬性值必須與實際渲染的內容相等。當新的 reel.json 值與要求相符時,播放器會將編輯標記為已完成。
  • path 可以省略;伺服器會填入專案資料夾。
  • review 發現: id(在此版本中唯一,例如 v2-1)、t(秒)、title(一行)、可選的 detail、fix 和 kind(safe area、size、contrast、typo、overflow、cut、timing 或你自訂的詞彙)。使用 elId(元素 ID,在其框上標記圓圈)、box: [x, y, w, h] 或 x、y(佔畫面的百分比)來定位。為每個版本撰寫一份新的清單;不要重複任何使用者已關閉的內容。
  • outputs:請參閱第 9 節。
  • 未知欄位將被忽略。缺少的可選欄位將使用預設值。

5. 開啟播放器

在背景啟動伺服器,然後將伺服器列印的 URL 提供給使用者:

node <技能目錄>/player/server.mjs <專案> &
# MotionSnip Studio:http://localhost:4321  (專案:/abs/path)

選項:--port 4321(連接埠忙碌時會自動上移)、--no-open(不開啟瀏覽器)、--ffmpeg /path/to/ffmpeg(用於匯出)。需要 Node 18 或更新版本,無需安裝步驟。如果該專案的伺服器已在執行中,請勿啟動另一個;播放器會自行獲取新版本。

用一兩行告訴使用者要做什麼:觀看影片,點擊任何內容進行修正,右鍵點擊圈選問題,然後按 傳送給 Claude。

純影片。 如果使用者想要審查或編輯一個沒有 reel.json 的影片檔案(例如螢幕錄影、手機剪輯),直接傳遞該檔案:node <技能目錄>/player/server.mjs path/to/clip.mp4 &。請不要為它撰寫 reel.json。播放器會讓使用者進行修剪、剪裁、新增文字、標誌或模糊效果,以及設定顏色,其匯出功能會自行套用這些編輯。然後,他們的反饋檔案只會包含固定在幀上的註釋;遵循這些註釋,如果註釋要求新的剪切,則以相同的檔案名稱匯出,以便播放器將其視為下一個版本。

6. 套用反饋檔案

使用者會貼上 Apply the MotionSnip Studio feedback in <專案>/.motionsnip/feedback-vN.md。讀取該檔案。它包含以下部分:

  • 精確修改。 類似 [00:01.2 · S1 · 標題] 文字 (src/Hook.tsx:12):"Meet Acme" -> "Say hi to Acme" 的行。在程式碼和 reel.json 中進行完全相同的修改。不要改寫。對 brand.<id> 的顏色編輯會修改色板條目,因此所有與之連結的內容都會改變。
  • 尺寸和位置編輯。 [x, y, w, h] -> [x, y, w, h] (scale 1.12),以畫面百分比為單位。使用畫面尺寸將其轉換為像素(x% * w / 100),在程式碼中移動或調整元素大小,並更新其 box。
  • 音效設定。 新音軌(已儲存在 assets/ 中)、開始偏移、淡出、音量。更新 reel.json 中的 audio。如果影片僅包含音效,通常不需要為此重新渲染。如果音樂已燒錄(videoAudio: "mix"),請使用新設定重新渲染。
  • 對 {標籤} 版本的評論。 與上述相同類型的評論,但針對的是剪輯版本(9:16、1:1 或倒數計時)而非主版本。時間和位置基於該版本自身的畫面和時鐘;倒數計時的部分會說明它從主版本的哪些部分剪輯而來。盡可能在主版本中修正根本原因(將重要內容放在裁切版本能見到的區域)。如果你自己製作了該版本(它存在於你的 outputs 中),也請重新渲染它,並增加其自身的 version。
  • MotionSnip Studio 製作的剪輯版本。 播放器根據其裁切鍵或範圍自行從主版本渲染的版本。請不要動它們的檔案;審查者會在你的下一個版本之後重新渲染它們。
  • 對畫面的評論。 固定在特定時間和位置(x 23.9% y 81.8%)的自由評論,通常針對某個命名元素。在決定如何處理之前,請擷取該幀並查看。註釋是請求,而非精確值;請運用判斷力,並保持場景其餘部分完整。
  • 來自 vN-1 的未完成事項。 你上一輪修改過,但使用者表示尚未正確的內容,並附帶他們的理由。優先修正這些。
  • 來自你的自我審查。 結尾為 (來自你的自我審查,v1-2;審查者同意) 的評論是你自己發現且被使用者接受的項目。將其視為任何其他註釋來處理。
  • 來自你的自我審查,已關閉。 使用者看過且滿意的發現。保持這些內容不變,不要在下一次 review 中再次標記它們。
  • 場景。 每個場景的狀態。除非編輯或註釋提及,否則請不要動已核准的場景。

然後:

  1. 進行修改。保持 ID 穩定。
  2. 重新渲染到相同的 src 檔案(或新檔案並更新 src)。
  3. 檢查聯絡表單和你觸及的幀。
  4. 更新 reel.json 中每個變更的值,並將 version 設為 N+1(檔案中會顯示下一個號碼)。在所有渲染完成後,最後再增加版次。
  5. 用一行告訴使用者變更了什麼,例如「v4 已準備好 · 套用了 5 項修改,尾註需要您過目」。

絕對不要編輯 .motionsnip/、exports/ 或播放器在 outputs/ 中的剪輯版本(列在 .motionsnip/outputs.json 中);它們屬於播放器。

7. 可選:即時渲染器

如果影片可以在瀏覽器中執行(canvas、DOM、Remotion Player bundle),你可以提供 live.js 並設定 "live": "live.js"。播放器會將其作為經典 script 載入,並呼叫:

window.MotionSnipLive = (container) => ({
  seek(timeSeconds) {}, play() {}, pause() {}, setRate(rate) {},
  // boxes[id] = [x, y, w, h, nx, ny, nw, nh]:原始值,然後是編輯後的值,佔畫面的百分比
  setBoxes(boxes) {},
});

然後播放器會隱藏影片並驅動你的渲染器,因此移動或調整大小的元素會真實顯示。

8. 可選:匯出掛鉤

在 reel.json 中新增 export,讓使用者能從播放器渲染最終版本:

"export": {
  "cwd": "/abs/path/to/remotion/project",
  "props": { "musicSrc": null },
  "cmd": "npx remotion render src/index.ts Main \"$RAW\" --props=\"$PROPS\""
}

伺服器在 cwd 中使用 sh -c 執行 cmd,並設定:

  • PROPS:一個 JSON 檔案的路徑,其內容是 export.props 與使用者編輯的合併。編輯內容的格式為 { "edits": { "<elId>": { "<prop>": value } }, "boxes": { "<elId>": [x, y, w, h] }, "colors": { "<id>": "#hex" }, "fonts": { "<id>": "Name" } } (框的數值為畫面百分比)。請讓你的 composition 讀取這些內容,以便渲染包含它們。
  • OUT:最終檔案在 exports/ 中的路徑。如果你的渲染已包含所有內容,請直接寫入此處。
  • RAW:一個暫存路徑。請改為寫入此處,伺服器會將使用者選擇的音樂和音量混合到其中,以產生 OUT。
  • PROJECT:專案資料夾。

進度來自命令列印的最後一個 n/m 配對(Remotion 會像這樣列印幀數)。

如果沒有匯出掛鉤,匯出功能仍然可以運作:它會複製影片並使用 ffmpeg 將音樂混合進去。

9. 可選:其他形狀和長度(輸出)

播放器會自行製作剪輯版本:+ 剪輯 使用 ffmpeg 從主版本渲染 9:16、1:1(或從直式主版本渲染 16:9)或 6 秒的倒數計時器到 outputs/<id>.mp4。重新構圖會遵循審查者在主版本上拖動的裁切鍵(或根據你的元素框進行初步猜測,因此請保持 box 準確),或將整個畫面置於模糊填充之上。每個輸出都有自己的分頁、針對 Reels、TikTok 和 Shorts 的安全區域指引,以及自己的註釋。你無需為這些做任何事。

當一個用程式碼建構的影片在重新構圖後看起來更好時...(省略的舊內容應按照此模式翻譯)

相關技能