Communitygithub.com

motion-template

建立或修改 mg Remotion 模板(一種由屬性和代碼驅動的可重複使用的動態圖形)。當現有模板不適用或需要更改動畫時使用。

motion-template 是什麼?

此技能用於為 Remotion 建立或修改名為「模板」的可重複使用動畫設計,特別適用於 motion-toolkit 生態系統。模板會讀取鏡頭屬性和已解析的代碼,並透過 zod 定義結構化的屬性 schema,以確保透過 .default() 方法擁有有效預設值,並透過 .describe() 提供表單說明。動畫僅基於 useCurrentFrame() 與 interpolate/spring 建構,以保證確定性渲染;代碼、字型、尺寸和定位透過 color()、font()、motion()、safeArea() 和 px() 等專用引擎函數處理,而非原始 CSS。此技能支援兩種部署情境:特定客戶模板位於 clients/<client>/templates/ 目錄,共用模板則位於 motion-toolkit 儲存庫的 templates/ 目錄。模板實作需匯出使用 defineTemplate() 建立的 template,並包含 durationSeconds、check 和 component 函數。它遵循嚴格的規則,例如禁止使用 setTimeout、Date.now() 或 Math.random(),要求文字在無法容納時明確拋錯,並支援多種視覺風格(透過 resolveLook 進行 choreo、reveal 和 typo)。校驗流程包括使用 mg check 驗證、使用 mg still 檢查影格,以及遵循 motion-qa 指南。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ryodeushii/motion-graphics/tree/HEAD/skills/motion-template

在你喜歡的 AI 中提問

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

說明文件

模板

模板是一種可重複使用的設計。它只讀取鏡頭屬性和已解析的代碼。在選擇時間長短或緩動曲線之前,請先閱讀 motion-style。如需 Remotion API 的詳細資訊,請使用已安裝的 Remotion 技能(npx remotion skills add)或參閱 https://www.remotion.dev/docs。

存放位置

  • 特定客戶:以 pnpm mg new-template <client> <name> 開頭。它會在 clients/<client>/templates/<name>/index.tsx(id 為 <client>/<name>)寫入一個符合下方規範的可用起始模板;請替換其設計。
  • 共用模板(所有客戶):放置於 motion-toolkit 儲存庫的 templates/<name>/index.tsx,並在 templates/index.ts 註冊,隨新工具包版本發布。請勿寫入 node_modules。

在撰寫動畫程式碼之前,請先提議 schema(使用者無需透過 agent 即可變更的屬性),並與使用者確認。

規範

import { interpolate, useCurrentFrame } from "remotion";
import { z } from "zod";
import { color, defineTemplate, font, motion, px, safeArea } from "motion-toolkit/engine";

const schema = z.object({
  headline: z.string().min(1).default("Headline"),
  holdSeconds: z.number().positive().default(3),
  accent: z.string().default("accent").describe("Color token name or #hex"),
});

export const template = defineTemplate({
  title: "Title card",
  schema,
  durationSeconds: ({ props, tokens }) => {
    const m = motion(tokens, 1);
    return m.seconds("enter") + props.holdSeconds + m.seconds("exit");
  },
  check: ({ props, tokens }) => {
    color(tokens, props.accent); // 在未知代碼名稱時拋錯;在 `mg check` 時執行
  },
  component: ({ props, tokens, video }) => {
    const frame = useCurrentFrame();
    const m = motion(tokens, video.fps);
    // ...
  },
});

要求:

  1. 匯出使用 defineTemplate 建立的 template(客戶模板)。
  2. 每個 schema 欄位都必須有 .default(),以確保新鏡頭和 Studio 啟動時為有效狀態。可加上 .describe() 供 Studio 表單使用。
  3. 透過 color(tokens, nameOrHex) 處理顏色,透過 font(tokens, role) 處理字型,透過 motion(tokens, fps) 處理時間長短和緩動曲線,透過 safeArea(tokens, video) 處理位置,並透過 px(sizeAt1080, video) 處理尺寸。
  4. 僅從 useCurrentFrame() 搭配 interpolate/spring 進行動畫。不可使用 CSS 過渡動畫、setTimeout、Date.now() 或 Math.random()(請使用 remotion 中的 random(seed))。每次渲染結果必須完全相同。
  5. 除非模板是全螢幕畫面,否則請保持背景透明;下方第三條和疊加圖層應帶有 Alpha 通道渲染。每個元素必須在最後一個影格消失。
  6. 明確失敗:當文字無法容納或缺少代碼時,請擲出內含修復提示的 Error。請使用引擎中的 assertFits/wrapLines;它們會使用已載入的字型進行測量,並在溢位時拋錯。
  7. 用於命名代碼(顏色、標誌、字型、音效)的屬性需在 check 中以 checkRefs 驗證,以便 mg check 在渲染前捕捉拼寫錯誤。
  8. durationSeconds 和 check 在 Node 環境(mg check)中執行,且執行於字型載入之前:請勿在此處測量文字。
  9. 圖片和標誌:使用 <Img src={staticFile(tokens.logos[name])} /> 或 staticFile(props.someAsset)。音效:使用 <Html5Audio src={staticFile(file)} /> 並置於 <Sequence from={frame}> 內,檔案來自 tokens.sounds[name]。CLI 會負責暫存這些檔案。

視覺風格

共用模板,以及與之匹配的客戶模板,可接受 look: lookSchema 屬性,並透過 resolveLook(props.look, tokens) 解析。請使用共用輔助函式來建構它們,以使所有三種風格保持一致(請參閱 motion-style):

  • choreo(tokens, look, fps) 提供 beat(frame, index, exitStart, steps) → 根據入場順序,每個元素對應的 { inP, outP };choreoSeconds(...) 則提供相符的時間長度。
  • reveal(look, beat, video) 是某個元素的風格化入場方式(對於 corporate 風格,請將其包裹在 overflow: hidden 中)。
  • typo(tokens, look, "display" | "title" | "body" | "label", size) 是風格化的文字樣式;onColor(hex) 可在色塊上選出可讀的文字;cornerPlacement(corner, inset) 可定位角落圖形。

請閱讀一個共用模板,例如 node_modules/motion-toolkit/templates/title-card/index.tsx,作為實際範例。

驗證

  1. 在測試專案中執行 pnpm mg new-shot <client>/<project> <shot> --template <client>/<name>,並建立第二個使用最長實際文字的鏡頭。
  2. 執行 pnpm mg check <client>/<project>。
  3. 執行 pnpm mg still <client>/<project> <shot> 並檢視影格。接著執行 pnpm mg render。
  4. 遵循 motion-qa 指南。

從參考剪輯著手

當使用者提供參考影片時,請在開始設計前先提取影格。首先建立 renders/reference/ 目錄;隨附的 ffmpeg 為最小化建置版本,不含濾鏡,因此請使用 -r 指定影格率:

pnpm mg ffmpeg -i reference.mp4 -r 10 renders/reference/f_%03d.png

根據這些影格描述哪些物件在移動、移動順序、每個階段花費的時間(以 10 fps 計算影格數),以及緩動的感覺。與使用者確認此分解結果,然後將其映射到代碼:時間長度對應到 motion.durations,曲線對應到 motion.easings。

Individual skills in this repo

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

相關技能