carocut-builder-remotion-ref

name	carocut-builder-remotion-ref
description	Remotion API 参考索引。包含 50+ 条 Remotion API 规则的目录索引、关键规则速查表、常用模式代码示例。加载此 skill 获取索引，然后按需 read 具体规则文件。是 carocut-builder-compositor 的伴侣参考。

Remotion Reference

Comprehensive Remotion API reference with best practices. This skill supplements carocut-builder-compositor with detailed API documentation.

Relationship to other skills:

• carocut-builder-compositor: Implementation patterns, visual standards, project structure
• carocut-reviewer: Debugging, preview, render commands
• This skill: Remotion API reference, component documentation

---

Critical Rules (MANDATORY)

Rule	Implementation	Why
Frame calculation	Always Math.round(sec * fps)	Float frames cause jitter/crashes
interpolate safety	Math.max(duration, 1) for inputRange	Equal values crash Remotion
extrapolate clamp	Always add extrapolateLeft/Right: 'clamp'	Prevents values outside range
CSS animations	FORBIDDEN	Frame-inaccurate, breaks render
Native HTML media	FORBIDDEN - use <Img>, <Audio>, <Video>	Remotion needs asset tracking
setTimeout/setInterval	FORBIDDEN	Not frame-synchronized
useEffect side effects	FORBIDDEN	Breaks deterministic rendering

---

Quick Reference

Core Hooks

Hook	Returns	Usage
useCurrentFrame()	number	Current frame (0-indexed)
useVideoConfig()	{ fps, width, height, durationInFrames }	Video configuration

Animation Functions

Function	Signature	Purpose
interpolate	interpolate(frame, inputRange, outputRange, options)	Linear interpolation
spring	spring({ frame, fps, config })	Physics-based animation
Easing	Easing.out(Easing.cubic)	Easing curves

Components

Component	Props	Purpose
<Sequence>	from, durationInFrames, premountFor, name	Time-based children
<Series>	children	Sequential playback
<AbsoluteFill>	style	Full-frame container
<Img>	src	Image (use with staticFile)
<Audio>	src, volume, startFrom	Audio playback
<Video>	src, startFrom, endAt	Video playback
<OffthreadVideo>	src	Memory-efficient video

Utility Functions

Function	Usage
staticFile("path")	Reference public/ assets
delayRender()	Pause render until ready
continueRender(handle)	Resume after delayRender
getInputProps()	Get CLI input props

---

References Directory

Detailed documentation organized by category. Load specific files when needed.

Core Concepts

Topic	File	When to Use
Compositions	references/compositions.md	Defining compositions, registerRoot
Sequencing	references/sequencing.md	Sequence, Series, TransitionSeries
Timing	references/timing.md	Easing functions, spring config
Animations	references/animations.md	interpolate patterns, motion
Parameters	references/parameters.md	Zod schemas, input props
Calculate Metadata	references/calculate-metadata.md	Dynamic duration/dimensions

Media Components

Topic	File	When to Use
Images	references/images.md	Img component, sizing
Videos	references/videos.md	Video component, playback
Audio	references/audio.md	Sound, volume curves, trimming
GIFs	references/gifs.md	Animated GIF playback
Transparent Videos	references/transparent-videos.md	Alpha channel, WebM

Assets and Resources

Topic	File	When to Use
Assets	references/assets.md	staticFile, importing
Fonts	references/fonts.md	Google Fonts, local fonts, @font-face
Trimming	references/trimming.md	Cut audio/video start/end

Text and Typography

Topic	File	When to Use
Text Animations	references/text-animations.md	Typewriter, word-by-word
Measuring Text	references/measuring-text.md	Text dimensions, overflow
Measuring DOM Nodes	references/measuring-dom-nodes.md	Element size calculation

Captions and Subtitles

Topic	File	When to Use
Subtitles	references/subtitles.md	Caption display basics
Display Captions	references/display-captions.md	Styled caption rendering
Import SRT Captions	references/import-srt-captions.md	Parse SRT files
Transcribe Captions	references/transcribe-captions.md	Audio-to-text

Visual Effects

Topic	File	When to Use
Transitions	references/transitions.md	Scene transitions, TransitionSeries
Light Leaks	references/light-leaks.md	Overlay light effects
Lottie	references/lottie.md	After Effects animations

Data Visualization

Topic	File	When to Use
Charts	references/charts.md	Recharts integration
Maps	references/maps.md	Mapbox, geographic data

Advanced Features

Topic	File	When to Use
3D	references/3d.md	Three.js, React Three Fiber
Tailwind	references/tailwind.md	Tailwind CSS integration
Can Decode	references/can-decode.md	Check codec support
Extract Frames	references/extract-frames.md	Get frames from video
Get Video Duration	references/get-video-duration.md	Query video length
Get Video Dimensions	references/get-video-dimensions.md	Query video size
Get Audio Duration	references/get-audio-duration.md	Query audio length

---

Common Patterns

interpolate with Safety

// ALWAYS include clamp options
const opacity = interpolate(
  frame,
  [startFrame, endFrame],
  [0, 1],
  { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' }
);

// ALWAYS ensure minimum 1-frame duration
const duration = Math.max(secToFrames(text.length * 0.02), 1);

Staggered Entry Animation

{items.map((item, index) => {
  const delay = 0.5 + index * 0.12;
  const startFrame = Math.round(delay * fps);
  const endFrame = Math.round((delay + 0.3) * fps);

  const opacity = interpolate(
    frame,
    [startFrame, endFrame],
    [0, 1],
    { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' }
  );
  const translateY = interpolate(
    frame,
    [startFrame, endFrame],
    [20, 0],
    { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' }
  );

  return (
    <div key={index} style={{ opacity, transform: `translateY(${translateY}px)` }}>
      {item}
    </div>
  );
})}

Spring Animation

const { fps } = useVideoConfig();
const scale = spring({
  frame,
  fps,
  config: {
    damping: 12,
    stiffness: 100,
    mass: 0.5,
  },
});

BGM with Fade In/Out

const { durationInFrames } = useVideoConfig();
const fadeInFrames = 60;  // 2 seconds at 30fps
const fadeOutFrames = 90; // 3 seconds

<Audio
  src={staticFile('audio/bgm/ambient.mp3')}
  volume={(f) => interpolate(
    f,
    [0, fadeInFrames, durationInFrames - fadeOutFrames, durationInFrames],
    [0, 0.15, 0.15, 0],
    { extrapolateLeft: 'clamp', extrapolateRight: 'clamp' }
  )}
  loop
/>

Voiceover Positioning

// Absolute positioning - NOT nested Sequences
const voStartFrame = computeShotStartFrame('shot_005') + msToFrames(200);

<Sequence from={voStartFrame} durationInFrames={msToFrames(voDuration)} name="Shot-005">
  <Audio src={staticFile('audio/vo/VO_005.wav')} />
</Sequence>

TransitionSeries Usage

import { TransitionSeries, linearTiming } from '@remotion/transitions';
import { fade } from '@remotion/transitions/fade';

<TransitionSeries>
  <TransitionSeries.Sequence durationInFrames={CHAPTER1_DURATION}>
    <Chapter1 />
  </TransitionSeries.Sequence>

  <TransitionSeries.Transition
    presentation={fade()}
    timing={linearTiming({ durationInFrames: 15 })}
  />

  <TransitionSeries.Sequence durationInFrames={CHAPTER2_DURATION}>
    <Chapter2 />
  </TransitionSeries.Sequence>
</TransitionSeries>

---

Frame Calculation Utilities

import { FPS } from './constants';

// Seconds to frames (always integer)
export function secToFrames(sec: number): number {
  return Math.round(sec * FPS);
}

// Milliseconds to frames (always integer)
export function msToFrames(ms: number): number {
  return Math.round((ms / 1000) * FPS);
}

// Safe duration (minimum 1 frame)
export function safeDuration(frames: number): number {
  return Math.max(frames, 1);
}

---

Error Quick Reference

Error Message	Cause	Fix
inputRange must be strictly monotonically increasing	Equal inputRange values	Use Math.max(duration, 1)
Could not find composition	Missing registerRoot	Check Root.tsx exports
staticFile not found	Wrong path	Path relative to public/, case-sensitive
Render timed out	delayRender not continued	Call continueRender()
White screen in Studio	Component crash	Check DevTools Console
WebGL render fails	OpenGL flag	Add renderer flag like--gl angle-egl

---

Render Commands

All render output MUST go to the out/ directory so it appears in the resource panel.

# Test render (first 10 seconds)
npx remotion render MyComposition --frames=0-300 out/test.mp4

# Full render
npx remotion render MyComposition out/output.mp4

# High quality render
npx remotion render MyComposition --crf=15 out/output_hq.mp4

# Low memory render
npx remotion render MyComposition --concurrency=2 --gl=angle out/output.mp4

---

Notes

• This reference supplements carocut-builder-compositor, not replaces it
• For visual standards (fonts, colors, layout), see carocut-builder-compositor
• For debugging workflow, see carocut-reviewer
• Load specific rule files only when implementing that feature