템플릿
템플릿은 재사용 가능한 디자인입니다. shot props와 해결된 토큰만을 읽습니다. 타이밍이나 이징을 선택하기 전에 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에 작성하지 마세요.
애니메이션 코드를 작성하기 전에 스키마(사용자가 에이전트 없이 변경할 수 있는 props)를 제안하고 사용자와 확인하세요.
계약
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을 내보냅니다(클라이언트 템플릿).- 모든 스키마 필드는
.default()를 가져 새 shot과 Studio가 유효하게 시작됩니다. Studio 양식을 위해.describe()를 추가하세요. - 색상은
color(tokens, nameOrHex), 폰트는font(tokens, role), 지속 시간과 이징은motion(tokens, fps), 위치는safeArea(tokens, video), 크기는px(sizeAt1080, video)를 통해 처리하세요. useCurrentFrame()에서interpolate/spring으로만 애니메이션합니다. CSS 전환,setTimeout,Date.now()또는Math.random()은 사용하지 마세요(random(seed)를 remotion에서 사용). 모든 렌더링이 동일해야 합니다.- 템플릿이 전체 프레임이 아닌 한 배경을 투명하게 유지하세요. 로우어 서드와 오버레이는 알파로 렌더링됩니다. 모든 요소는 마지막 프레임에서 사라져야 합니다.
- 실패 시 크게 알리기: 텍스트가 맞지 않거나 토큰이 누락된 경우 수정 힌트와 함께
Error를 던지세요. 엔진의assertFits/wrapLines를 사용하세요. 이 함수들은 로드된 폰트로 측정하고 넘칠 경우 예외를 던집니다. - 토큰(색상, 로고, 폰트, 사운드)을 명명하는 props는
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>을 실행하고, 가장 긴 현실적인 텍스트로 두 번째 shot도 추가합니다. 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.