remotion-rules

name	remotion-rules
description	Rules and patterns for writing Remotion compositions in this project. Trigger whenever the user asks to create, modify, or debug a Remotion composition, `<Player>`, `<Sequence>`, captions, video playback, or rendering pipeline.

Hard rules (enforced, violations = broken renders)

1. No CSS transitions/animations. Every frame is captured after React commit; transitions freeze. Use interpolate(frame, [inFrame, outFrame], [fromValue, toValue]) or spring().

2. <Video> vs <OffthreadVideo>:

   import { useRemotionEnvironment } from "remotion";
   const env = useRemotionEnvironment();
   return env.type === "player"
     ? <Video src={src} />            // @remotion/media, WebCodecs, fast preview
     : <OffthreadVideo src={src} />;  // render path, reliable
   

3. inputProps memoization:

   // WRONG — recreates object every render, Player remounts
   <Player inputProps={{ spec: buildSpec() }} ... />
   
   // RIGHT
   const inputProps = useMemo(() => ({ spec }), [spec]);
   <Player inputProps={inputProps} ... />
   

4. Google Fonts for Polish:

   import { loadFont } from "@remotion/google-fonts/Montserrat";
   loadFont("normal", { weights: ["900"], subsets: ["latin", "latin-ext"] });
   

5. Render API route shape:

   export const runtime = "nodejs";
   let bundlePromise: Promise<string> | null = null;
   const getBundle = () => (bundlePromise ??= bundle({ entryPoint: "..." }));
   

Composition rules

• ONE composition <Composition id="MusicVideo">, calculateMetadata derives duration from inputProps.spec.durationSec * fps
• Flat <Sequence> children, never nested beyond 2 levels
• Master <Audio src={audioUrl} /> at the bottom of <AbsoluteFill>, never inside a <Sequence> unless you want it trimmed

Karaoke captions

Use @remotion/captions:

import { createTikTokStyleCaptions } from "@remotion/captions";
const { pages } = createTikTokStyleCaptions({
  captions,
  combineTokensWithinMilliseconds: 1200,
});

Each page = one <Sequence>, render per-token highlighting via useCurrentFrame() + interpolate().

When to ask user

• "Should this effect fire on every beat, every downbeat, or only at section boundaries?"
• "Fade duration: fixed ms or proportional to section length?"
• "New font preset — do you want me to verify Polish diacritic coverage first?"