模板
模板是一種可重複使用的設計。它只讀取鏡頭屬性和已解析的代碼。在選擇時間長短或緩動曲線之前,請先閱讀 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);
// ...
},
});
要求:
- 匯出使用
defineTemplate建立的template(客戶模板)。 - 每個 schema 欄位都必須有
.default(),以確保新鏡頭和 Studio 啟動時為有效狀態。可加上.describe()供 Studio 表單使用。 - 透過
color(tokens, nameOrHex)處理顏色,透過font(tokens, role)處理字型,透過motion(tokens, fps)處理時間長短和緩動曲線,透過safeArea(tokens, video)處理位置,並透過px(sizeAt1080, video)處理尺寸。 - 僅從
useCurrentFrame()搭配interpolate/spring進行動畫。不可使用 CSS 過渡動畫、setTimeout、Date.now()或Math.random()(請使用 remotion 中的random(seed))。每次渲染結果必須完全相同。 - 除非模板是全螢幕畫面,否則請保持背景透明;下方第三條和疊加圖層應帶有 Alpha 通道渲染。每個元素必須在最後一個影格消失。
- 明確失敗:當文字無法容納或缺少代碼時,請擲出內含修復提示的
Error。請使用引擎中的assertFits/wrapLines;它們會使用已載入的字型進行測量,並在溢位時拋錯。 - 用於命名代碼(顏色、標誌、字型、音效)的屬性需在
check中以checkRefs驗證,以便mg check在渲染前捕捉拼寫錯誤。 durationSeconds和check在 Node 環境(mg check)中執行,且執行於字型載入之前:請勿在此處測量文字。- 圖片和標誌:使用
<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,作為實際範例。
驗證
- 在測試專案中執行
pnpm mg new-shot <client>/<project> <shot> --template <client>/<name>,並建立第二個使用最長實際文字的鏡頭。 - 執行
pnpm mg check <client>/<project>。 - 執行
pnpm mg still <client>/<project> <shot>並檢視影格。接著執行pnpm mg render。 - 遵循
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。