REMOTION MOTION DESIGN — Implementation Skill
1. Review before coding
- Read
CLAUDE.md,MASTER_PROMPT.md, and the architecture docs. - Check the actual Remotion/React/TypeScript versions and package manager.
- Find the existing entry point and composition registry.
- Follow the repository's conventions; do not swap dependencies without need.
- Use the output of
beyond-video, the script, storyboard, and Style Bible as the production spec. - Verify the APIs you use against the Remotion source of the installed version
(e.g.
packages/core/srcin a reference clone) before relying on memory.
2. Composition profile
Defaults:
- width: 1080
- height: 1920
- fps: 60
- aspect: 9:16
- duration: positive integer in frames
Every composition needs a unique ID and explicit metadata. Do not store different FPS values in several layers without a reason.
<Composition> accepts id, fps, width, height, durationInFrames,
defaultProps, and optionally calculateMetadata (dynamic duration/metadata from
props) and schema. durationInFrames must be positive.
3. Timeline engineering
- Keep durations and start frames in centralized data/config.
- Use one frame-interval convention;
[start, end)is recommended. - Scene
durationInFramesmust be positive. - Make sure the composition's total duration holds every scene plus the tail/closing.
- Validate overlaps and gaps; overlap only when it is intended for a transition/compositing.
- Do not rely on floating point for the final frame boundary.
4. Deterministic animation — time/frame APIs (Remotion 4.x)
Time sources:
useCurrentFrame()— the current frame, 0-indexed. Only usable inside a composition component; outside a composition it throws.useVideoConfig()— returns{width, height, fps, durationInFrames, id, defaultProps, defaultVideoImageFormat, ...}; throws outside a composition.
Interpolation and spring:
interpolate(input, inputRange, outputRange, options?)— overloads for number, string, boolean, and array output. Options:easing,extrapolateLeft/extrapolateRight('extend' | 'identity' | 'clamp' | 'wrap'),output,outputType,posterize. Clamp extrapolation when motion must not run past the range.spring({frame, fps, config?, from=0, to=1, durationInFrames?, durationRestThreshold?, delay=0, reverse=false}).SpringConfig:damping(default 10),mass(1),stiffness(100),overshootClamping(false).damping <= 0makes the animation never settle (infinite-loop error).measureSpring({fps, config?, threshold=0.005})— number of frames until the spring settles;threshold=0yieldsInfinity.
Rules:
- Motion must be a function of frame and props.
- Seed particle/noise/random values.
- Avoid
setInterval,setTimeout,requestAnimationFrame,Date.now(), and self-running CSS keyframes as the main source of video motion. - Do not fetch network data while the composition renders.
- Do not include audio/video from unstable URLs or URLs that require login.
delayRender(label?, options?)holds the render untilcontinueRender(handle)is called (e.g. async assets); its timeout is set with the CLI--timeout.
5. Sequence, Series, and local vs global frames
This is the rule most often gotten wrong — a real bug once happened because a
component computed the global frame inside a Series.Sequence:
- Inside a
<Sequence>,useCurrentFrame()returns the frame RELATIVE to the start of the Sequence:(frame - (cumulatedFrom + relativeFrom)) * playbackRate. Components inside a Sequence do NOT see the global frame. <Sequence>props:from?,name?,durationInFrames?(must be positive; required when usingloop),layout('absolute-fill'|'none'),premountFor,loop, and crop props (only withlayout="absolute-fill").<Series.Sequence>may ONLY be used inside<Series>; aSeries.Sequenceoutside<Series>throws "This component must be inside a<Series />component."- Two valid routing patterns — pick one and stay consistent:
- Global frame router (used in the video project): one router component
uses the global
useCurrentFrame()and picks the beat by its[start, end)range; beat components compute from the global frame. - Series: each
Series.Sequenceholds one beat; beat components compute from the local frame (0 at the start of the Sequence).
- Global frame router (used in the video project): one router component
uses the global
- Do not mix both patterns in one composition without an explicit reason.
6. Scene/component structure
- One scene has one narrative/visual responsibility.
- Scene props are defined in TypeScript.
- Reusable components solve a clear visual task.
- Avoid a single file holding the whole video.
- Separate content config, renderer, style tokens, and asset references.
- Add designed fallbacks for optional assets; never hide a missing critical asset.
7. Media components and assets
<Img src>— an image that fails to load withoutonErrorcancels the render (cancelRender). Always provideonErrorfor critical assets, or make sure the asset exists before rendering.staticFile(path)— maps a file inpublic/; use it for every local asset (images, audio, video).<Audio>— seesound-designfor mapping a cue sheet to props (trimBefore/After— older aliasstartFrom/endAt—volume,playbackRate). A cue's position on the timeline is set by<Sequence from>; the trim props only cut which part of the file plays.<Audio>has nomutedprop; mute is a CLI flag (--muted).<Video>/<OffthreadVideo>and<Still>follow the same frame rules; media duration must be scheduled from frames, not from file metadata.
8. 2D motion
Use SVG/shapes/CSS/rasters as needed. Mind anchors, transform origins, anti-aliasing, layering, clipping, and the safe area. Every transform must be frame-driven.
9. Pixel and stickman support
Pixel art:
- lock the logical canvas and pixel scale;
- use nearest-neighbor when scaling sprites;
- snap positions to the grid when needed;
- lock the palette and sprite dimensions;
- avoid blur and subpixel shimmer.
Stickman:
- keep proportions and pivots consistent;
- use a pose/rig library when the project's scale justifies it;
- animate silhouette and gesture so they read;
- sync expressions/poses with story beats.
For walk cycles, follow-through, and idle motion, see character-animation.
10. 3D motion
- Add 3D only when it brings creative value.
- Check the versions of
three,@react-three/fiber,@remotion/three, and their docs. - For Remotion ThreeCanvas integration, follow the frame-driven approach of the installed API version; do not assume real-time R3F patterns are automatically deterministic.
- Drive camera, transforms, materials, lighting, and particles from the frame.
- Consider renderer/headless compatibility, texture size, geometry, and compute cost.
- Separate the 3D layer from 2D typography/overlays when it helps readability and maintainability.
- For directing 3D scenes in detail, see
3d-scene-director.
11. Typography and transitions
- Prioritize hierarchy and readability.
- Never cover important copy with a transition.
- Every transition connects two beats; do not add effects without a function.
- Keep motion curves and intensity consistent through the Style Bible.
- Match text duration to reading needs.
12. Closing implementation
Implement the closing logo + CTA according to the beyond-video worksheet. The logo must come from an official asset or an approved placeholder. Copy, timing, motif, and compositing must feel made for the video at hand.
13. QA before handoff
Check composition ID, metadata, frame ranges, imports, types, static assets, fonts, style consistency, safe area, closing, and asset licenses. Run the available lint/typecheck/tests. Do not render MP4. Do not commit/push.
Output format
- Composition registry: ID, 1080×1920, 60 FPS, durationInFrames, scene list + frame ranges.
- APIs used: API name + relevant signature + where it was verified (installed Remotion version).
- Frame routing pattern: global or Series — one choice, consistent across the composition.
- Asset register: file,
staticFile, fallback/onErrorper critical asset. - QA checklist + typecheck/lint results.
Mini example
Global frame router (video project pattern):
const frame = useCurrentFrame();
const beat = BEATS.find((b) => frame >= b.start && frame < b.end);
return (
<AbsoluteFill>
{beat?.id === 'S01-B01' && <Hook />}
{beat?.id === 'S01-B02' && <Problem />}
</AbsoluteFill>
);
Spring with a measured duration:
const settle = measureSpring({fps, config: {damping: 12}});
const progress = spring({frame, fps, config: {damping: 12}});
Failure modes
- A component inside
Series.Sequencecomputes the global frame → wrong beat, scenes show at the wrong time. Fix: compute from the local frame, or switch to a global frame router. Series.Sequenceused without<Series>→ throws at render. Wrap it in<Series>, or use<Sequence>directly (notSeries.Sequence).springwithdamping <= 0→ the animation never settles. Keepdamping > 0.- Missing image without
onError→ the render is cancelled. AddonErroror make sure the asset exists before rendering. useCurrentFrame()/useVideoConfig()outside a composition → throws. Call them only inside composition components.