# Carocut Builder Compositor > Remotion Shot 组件实现。将 storyboard 转化为 React 组件。包含关键的帧计算规则（Math.round 强制）、interpolate 安全规则（最小 1 帧）、1080p 视觉标准、动画编排模式、音视频同步架构、组件复用模式。这是技术密度最高的 skill。 - Skill: `bilibili/carocut-builder-compositor` (Agent Skill) - Install (CLI): `npx skillmds@latest add bilibili/carocut-builder-compositor` - Raw SKILL.md: https://api.skillmd.com/api/skills/bilibili/carocut-builder-compositor/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: bilibili (https://skillmd.com/u/bilibili) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bilibili/carocut-builder-compositor --- # Shot Compositor Implements storyboard as Remotion React components. This is the core implementation phase where planning documents become working code. **For additional Remotion API patterns, see `carocut-builder-remotion-ref` skill.** --- ## Incremental Mode When receiving amendment instructions rather than building from scratch: - **Modify specific shots:** Edit only the targeted shot component files. Do not regenerate unaffected shots. - **Add new shots:** Create new `Shot{NNN}_*.tsx` files. Update the chapter index and main Composition to include them. Adjust `from` offsets for all subsequent shots in the same chapter. - **Update frame timing:** When VO durations change, recalculate affected shot durations and propagate changes through all Duration Sync Points (see below). --- ## Implementation Order Must follow this sequence to avoid dependency issues: ```dot digraph implementation_order { rankdir=TB; "1. Shared Components" [shape=box]; "2. Shot Components" [shape=box]; "3. Audio Layers" [shape=box]; "4. Main Composition" [shape=box]; "1. Shared Components" -> "2. Shot Components"; "2. Shot Components" -> "3. Audio Layers"; "3. Audio Layers" -> "4. Main Composition"; } ``` 1. **Shared Components** - FlatDecorations, Card, DataTable, BarChart, plus motion-graphics from `resources.yaml` `components` section 2. **Shot Components** - Chapter-by-chapter implementation 3. **Audio Layers** - VoiceoverLayer, BackgroundMusicLayer, SfxLayer 4. **Main Composition** - Assembly with TransitionSeries ### Motion-Graphics Components Read `manifests/resources.yaml` → `components` section. Each `type: motion-graphics` entry describes a visual element that needs a React component in `src/components/`. **Implementation rules:** - Read the `description` field for visual intent (what to show, what data to include) - Read the `used_in` field to know which shots will import this component - Cross-reference with `storyboard.yaml` → corresponding shots' `visual_description` for layout and composition context - Use primitives (AnimatedText, AnimatedChart, DynamicBackground, etc.) as building blocks - Component naming: derive from the description, use PascalCase (e.g., "三级上报流程图" → `EscalationFlowDiagram.tsx`) --- ## Primitives 组件库 template-project 预置了 `src/primitives/` 组件库，提供电影级的视觉原子能力。 **所有 shot 实现必须优先使用 primitives 组件，禁止从零实现已有 primitive 覆盖的功能。** ### 导入 ```tsx import { KenBurns, AnimatedText, AnimatedChart, Transition, BreathingSpace, CinematicBackdrop, SplitScreen, DynamicBackground, MaskReveal, VideoClip, ParticleSystem, GlitchEffect, EdgeDissolve, NeonText, FilmGrain, GlowEffect, FlashOverlay, ColorSweep, } from '../primitives'; ``` ### Primitive Selection Heuristics When a shot needs one of these visual jobs, prefer the matching primitive before creating a custom component: | Visual job | Prefer these primitives | |-----------|-------------------------| | 静态图片运镜 | `KenBurns` | | 标题/数字/强调文字 | `AnimatedText`, `NeonText` | | 数据图表 | `AnimatedChart` | | 背景层 | `DynamicBackground`, `BreathingSpace`, `CinematicBackdrop` | | 氛围纹理 | `ParticleSystem`, `FilmGrain`, `GlowEffect` | | 失真/崩解 | `GlitchEffect`, `EdgeDissolve` | | 全屏强调/扫屏 | `FlashOverlay`, `ColorSweep` | | 几何揭示 | `MaskReveal`, `Transition` | | 视频素材 | `VideoClip` | **Rule:** If the shot only needs one of the jobs above, do not invent a new effect component. ### KenBurns - 静态图片运镜 为静态图片添加电影级运镜效果，避免画面呆板。 **关键 Props:** | Prop | Type | 说明 | |------|------|------| | src | string | 图片路径（staticFile） | | effect | string | 运镜预设，共 10 种 + custom | | scaleFrom | number | 起始缩放比例 | | scaleTo | number | 结束缩放比例 | | objectFit | string | 图片填充方式 | **effect 可选值:** `zoom-in`, `zoom-out`, `pan-left`, `pan-right`, `pan-up`, `pan-down`, `zoom-in-top-left`, `zoom-in-top-right`, `zoom-in-bottom-left`, `zoom-in-bottom-right`, `custom` **Storyboard 映射:** `camera_movement` → `effect`（`static` 时不使用 KenBurns） ```tsx ``` ### AnimatedText - 文字动画 6 种动画模式，覆盖标题、正文、数据等文字出场需求。 **模式与关键 Props:** | mode | 关键 Props | 用途 | |------|-----------|------| | typewriter | text, speed | 逐字打字效果 | | fade-up | text, unit("char"\|"word"\|"line") | 从下方淡入 | | fade-down | text, unit | 从上方淡入 | | spring-in | text, unit | 弹性出现 | | highlight | text, highlights, highlightColor | 关键词高亮 | | counter | from, to, suffix, prefix | 数字滚动计数 | ```tsx // 标题弹性出现 // 数字计数 // 关键词高亮 ``` ### AnimatedChart - 数据动画 数据可视化动画组件，替代静态 Recharts 图表。 **关键 Props:** | Prop | Type | 说明 | |------|------|------| | type | "bar" \| "horizontal-bar" \| "progress-ring" | 图表类型 | | data | { label, value, color }[] | 数据数组 | | stagger | number | 各数据项动画间隔（秒） | ```tsx ``` ### Transition - 转场效果 7 种转场效果，用于 shot 之间的视觉过渡。 **关键 Props:** | Prop | Type | 说明 | |------|------|------| | type | string | 转场类型，共 7 种 | | direction | "in" \| "out" | 入场或离场 | | durationSec | number | 转场持续时间（秒） | **type 可选值:** `circle-wipe`, `diagonal-wipe`, `iris`, `curtain`, `blinds`, `zoom-fade`, `dissolve-blur` **Storyboard 映射:** `transition_in.type` → `type`，`transition_in.duration_ms` → `durationSec` ```tsx ``` ### BreathingSpace - 呼吸段 用于章节间的视觉休息，让观众消化信息。 **关键 Props:** | Prop | Type | 说明 | |------|------|------| | variant | string | 呼吸段样式，共 5 种 | | color | string | 前景色 | | backgroundColor | string | 背景色 | | text | string | 可叠加的章节标题文字 | | textStyle | CSSProperties | 文字样式 | **variant 可选值:** `gradient`, `fade-black`, `fade-white`, `particles`, `radial-pulse` **Storyboard 映射:** `breathing=true` 时整个 shot 使用 BreathingSpace ```tsx ``` ### SplitScreen - 分屏 同时展示两个内容区域，用于对比、前后对照等场景。 **关键 Props:** | Prop | Type | 说明 | |------|------|------| | layout | "horizontal" \| "vertical" \| "pip" | 分屏布局方式 | | left / right | ReactNode | 左右内容（horizontal/vertical 布局） | | leftLabel / rightLabel | string | 分屏标签 | ```tsx } right={} leftLabel="2007" rightLabel="2024" /> ``` ### DynamicBackground - 动态背景 为 shot 提供动态背景层，增加视觉丰富度和电影感。 **关键 Props:** | Prop | Type | 说明 | |------|------|------| | variant | string | 背景样式，共 6 种 | | colors | string[] | 渐变颜色数组 | | intensity | number | 效果强度（用于 vignette） | **variant 可选值:** `flowing-gradient`, `mesh-gradient`, `grid`, `dots`, `vignette`, `aurora` **关键:** `vignette` 可叠加在任何内容上方增加电影感暗角效果。 ```tsx // 作为 shot 背景 {/* shot 内容放在 children 中 */}
// 叠加暗角 ``` ### CinematicBackdrop / ParticleSystem / FilmGrain - 氛围层 用于 breathing shot、章节间隙、低信息密度镜头的电影感底层。 - `CinematicBackdrop`：克制、稀疏、中心呼吸光 - `ParticleSystem`：漂浮/上升/径向粒子气氛 - `FilmGrain`：全局颗粒，降低“太干净”的数字感 ```tsx ``` ### GlitchEffect / EdgeDissolve - 失真层 用于故障、回忆破碎、信息污染、虚实边界崩塌等镜头。 ```tsx ``` ### NeonText / GlowEffect - 风格化标题层 当 storyboard 指向 synthetic UI、警报、科技感提示、强风格标题时优先使用。 ```tsx
``` ### FlashOverlay / ColorSweep - 强调层 用于冲击式章节切换、记忆闪回、扫屏强调，不必为这类全屏 2D 效果单独再写 transition 组件。 ```tsx ``` ### MaskReveal - 遮罩揭示 通过遮罩动画揭示内容，适合重点内容的戏剧性呈现。 **关键 Props:** | Prop | Type | 说明 | |------|------|------| | shape | string | 遮罩形状，共 10 种 | | durationSec | number | 揭示动画时长（秒） | **shape 可选值:** `circle`, `ellipse`, `rectangle`, `diamond`, `wipe-left`, `wipe-right`, `wipe-up`, `wipe-down`, `split-horizontal`, `split-vertical` ```tsx ``` ### VideoClip - 视频嵌入 嵌入视频片段，支持裁剪、变速、音量控制和淡入淡出。 **关键 Props:** | Prop | Type | 说明 | |------|------|------| | src | string | 视频文件路径 | | playbackRate | number | 播放速率 | | volume | number | 音量（0-1） | | muted | boolean | 是否静音 | | startFromSec | number | 视频起始秒数 | | endAtSec | number | 视频结束秒数 | | fadeInSec | number | 淡入时长（秒） | | fadeOutSec | number | 淡出时长（秒） | | objectFit | string | 视频填充方式 | | overlay | string | 叠加颜色层 | ```tsx ``` ### Storyboard → 组件映射规则 | storyboard 字段 | 组件/属性 | 说明 | |----------------|----------|------| | camera_movement | KenBurns.effect | static 时不使用 KenBurns，其他值直接映射 | | framing | 构图尺寸和元素比例 | ECU=主体占满画面, LS=主体占画面 1/3 | | pacing | 动画 duration 和 stagger | slow=长时值+慢stagger, fast=短时值+快stagger | | visual_tension | spring.damping 和动画幅度 | 低张力=高damping(柔和), 高张力=低damping(弹跳) | | transition_in.type | Transition.type | 直接映射 | | breathing=true | BreathingSpace / CinematicBackdrop | 低信息密度章节停顿优先使用二者之一 | | audio_visual_relation | Audio Sequence.from 偏移 | lead-visual: 画面提前; lead-audio: 音频提前 | | visual_tension ≥ 0.7 | Glow / distortion / texture layers | 优先考虑 `GlowEffect`、`GlitchEffect`、`EdgeDissolve`、`FilmGrain` | | synthetic / warning / HUD 风格标题 | NeonText | 不要手写发光文字阴影 | ### 电影感强制规则（MANDATORY） 1. **禁止静态图片**：所有 `` 必须包裹在 `` 中（除非图片是 UI 元素如图标） 2. **禁止静态文字**：所有首次出现的文字必须使用 ``（已显示的文字可以保持静态） 3. **禁止静态图表**：数据展示必须使用 ``，禁止静态 Recharts 4. **必须有底层氛围背景**：每个 shot 的底层必须使用 ``、`` 或 `` 之一 5. **暗角规则**：在非纯白背景的 shot 上叠加 ``。高张力 shot (visual_tension ≥ 0.7) 强烈建议使用。纯白背景除外。 6. **呼吸段必须实现**：storyboard 中 breathing=true 的 shot 必须使用 `` 7. **呼吸段音频处理**：breathing shot 期间，BGM 应通过 `interpolate` 淡出到 volume 0.05；下一个 shot 开始时 BGM 淡入恢复。不播放旁白。 8. **质感层优先复用**：颗粒、发光、扫屏、故障、边缘崩解优先使用 `FilmGrain`、`GlowEffect`、`ColorSweep`、`GlitchEffect`、`EdgeDissolve` --- ## Critical Rules ### Frame Calculation (MANDATORY) **All frame values must be integers.** Floating-point values cause animation jitter or crashes. ```typescript // CORRECT - always use Math.round() const startFrame = Math.round(delaySec * fps); const startFrame = secToFrames(delaySec); // from timing.ts // WRONG - produces float const startFrame = delaySec * fps; // 0.3 * 30 = 8.999... ``` ### interpolate Safety (MANDATORY) The `inputRange` array must be strictly monotonically increasing. Equal values crash. **Error message:** ``` inputRange must be strictly monotonically increasing but got [27, 27] ``` **Cause:** Zero-length content producing zero duration: ```typescript // DANGEROUS - empty text causes zero duration const typingDuration = secToFrames(line.text.length * 0.02); // = 0 if text.length = 0 interpolate(frame, [start, start + typingDuration], ...); // [27, 27] CRASH ``` **Solution:** ```typescript // SAFE - guarantee minimum 1-frame duration const typingDuration = Math.max(secToFrames(line.text.length * 0.02), 1); // Alternative: skip interpolation for zero-length content const charsVisible = line.text.length === 0 ? 0 : Math.floor(interpolate(frame, [start, end], [0, line.text.length], { extrapolateLeft: "clamp", extrapolateRight: "clamp", })); ``` **Rule:** Any dynamic calculation that feeds into interpolate must be wrapped in `Math.max(..., 1)`. ### extrapolate Clamp (MANDATORY) Always add clamp to prevent values outside range: ```typescript interpolate(frame, [startFrame, endFrame], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp", }); ``` --- ## 1080p Visual Standards ### Font Size Guidelines Video viewing distance requires larger fonts than desktop UI. | Element | Font Size | Example | |---------|-----------|---------| | Main title | 72-84px | Cover title, chapter headers | | Subtitle | 48-56px | Card titles, section headers | | Body text | 24-28px | Paragraphs, descriptions | | Table content | 20-24px | Data cells | | Annotation | 16-20px | Badges, footnotes | | Code | 18-22px | Monospace blocks | **Audit command:** ```bash grep -rn "fontSize:" src/ --include="*.tsx" | grep -E "fontSize:\s*[0-9]{1,2}[^0-9]" ``` ### Text Color Contrast On light backgrounds, use dark text. Light text on light backgrounds becomes unreadable after video compression. ```typescript // Text color hierarchy export const COLORS = { textDark: "#020617", // Titles, emphasis (near black) textPrimary: "#0F172A", // Body text (dark blue-black) textSecondary: "#334155", // Secondary info (dark gray) // NEVER use lighter colors on white/light backgrounds }; ``` **Rule:** On `flatGray`, `flatBlue`, white backgrounds, use only `textDark` or `textPrimary`. --- ## Background Layer Architecture > **优先使用 ``**：新 shot 应使用 primitives 组件库中的 `DynamicBackground` 替代手动组合背景层。仅在 DynamicBackground 不满足需求时使用下面的手动方式。 ### 推荐方式（使用 DynamicBackground） ```tsx {/* Content */} {children} ``` ### 手动方式 Layer Stack (bottom to top) ```tsx {/* 1. Gradient base */} {/* 2. Texture layer */} {/* 3. Optional: depth */} {/* Content layers */}
{children}
``` ### Available Decorations | Component | Purpose | Opacity Range | |-----------|---------|---------------| | `GradientBackground` | Soft gradient base | 1.0 | | `GridDots` | Grid texture | 0.15-0.3 | | `GaussianBlobs` | Floating color blobs | 0.2-0.4 | | `FloatingCircles` | Animated circles | 0.3-0.5 | | `TechGridBackground` | Technical aesthetic | 0.2-0.3 | | `BezierCurveDecoration` | Flowing curves | 0.4-0.6 | **Principle:** Background opacity should never compete with content readability. --- ## Shot Duration Management ### Shots Without Voiceover Shots without voiceover need explicit duration. Do not use default values. | Shot Type | Minimum Duration | Rationale | |-----------|------------------|-----------| | Image display | 4-5 seconds | Viewer comprehension | | Code (10 lines or less) | 6-8 seconds | Reading time | | Code (more than 10 lines) | 8-12 seconds | Complex content | | QR code / CTA | 6-7 seconds | Action time | | Data table | 5-8 seconds | Analysis time | | Chart animation | 4-6 seconds | Animation + comprehension | ### Voiceover-Based Duration ```typescript function calculateShotDuration(voIds: string[], bufferMs = 700): number { const totalVoMs = voIds.reduce((sum, id) => sum + (VO_DURATIONS[id] || 0), 0); return msToFrames(totalVoMs + bufferMs); } // Example const shotDuration = calculateShotDuration(['VO_005', 'VO_006', 'VO_007']); ``` ### Duration Sync Points When modifying shot durations, update ALL of these: 1. `SHOT_DURATIONS` constant (or equivalent timing config) 2. `` for the shot 3. `` for ALL subsequent shots in same chapter 4. Chapter duration exports (`CHAPTER1_DURATION`, etc.) 5. Root composition `durationInFrames` --- ## Animation Timing ### Staggered Entry Pattern Elements should enter sequentially, not simultaneously: ```typescript {items.map((item, index) => { const delay = 0.5 + index * 0.12; // 0.12s between each const opacity = interpolate( frame, [secToFrames(delay), secToFrames(delay + 0.3)], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" } ); const translateY = interpolate( frame, [secToFrames(delay), secToFrames(delay + 0.3)], [20, 0], { extrapolateLeft: "clamp", extrapolateRight: "clamp" } ); return (
{item}
); })} ``` ### Common Animation Combinations | Effect | Properties | |--------|------------| | Fade in + rise | `opacity: 0->1`, `translateY: 20->0` | | Fade in + scale | `opacity: 0->1`, `scale: 0.95->1` | | Slide from left | `translateX: -30->0` | | Pop in | `scale: 0->1.05->1` (spring) | ### Easing Functions ```typescript import { Easing, spring } from 'remotion'; // Smooth deceleration const progress = interpolate(frame, [0, 30], [0, 1], { easing: Easing.out(Easing.cubic), }); // Spring animation const { fps } = useVideoConfig(); const springProgress = spring({ frame, fps, config: { damping: 12, stiffness: 100 }, }); ``` --- ## Audio Architecture ### Three-Layer Model ``` +-------------------------------------+ | SFX Layer (transitions, accents) | Volume: 0.3-0.5 +-------------------------------------+ | VO Layer (voiceover) | Volume: 1.0 +-------------------------------------+ | BGM Layer (background music) | Volume: 0.1-0.2 +-------------------------------------+ ``` ### Audio Positioning **Use absolute frame calculation, not nesting:** ```typescript // CORRECT - Absolute positioning const voStartFrame = computeShotStartFrame('shot_005') + msToFrames(200); // WRONG - Nested positioning (fragile, breaks on refactor) ``` ### BGM Volume Fading ```typescript const bgmVolume = interpolate( frame, [0, secToFrames(2), totalFrames - secToFrames(3), totalFrames], [0, 0.15, 0.15, 0], { extrapolateLeft: "clamp", extrapolateRight: "clamp" } ); ``` --- ## Static Assets ### staticFile() Usage ```typescript import { staticFile, Img, Audio } from 'remotion'; import { KenBurns } from '../primitives'; // Images - 优先使用 KenBurns 包裹（电影感强制规则） // 仅 UI 图标等小元素可直接使用 Img // Audio - use Remotion's Audio component