remotion-bits

# Remotion Bits

Animation components and utilities for building Remotion videos. The library's most powerful feature is **Scene3D** - a camera-based 3D presentation system (like impress.js) that enables cinematic multi-section compositions with flying camera moves, step-aware element animations, and Transform3D position management.

**When building any non-trivial composition, prefer Scene3D as your foundation.** It handles camera movement, timing, element positioning, and responsive layout all in one system. Individual components (AnimatedText, Particles, etc.) work best as content placed inside Scene3D steps.

**Prerequisites:** `remotion` >= 4.0, `react` >= 18, `react-dom` >= 18

```bash
# Via npm
npm install remotion-bits

# Via jsrepo (copies source for customization)
npx jsrepo init https://unpkg.com/remotion-bits/registry.json
npx jsrepo add animated-text particle-system scene-3d
```

## Imports

Everything is exported from `remotion-bits`:

```tsx
import {
  // 3D Scene System (primary workflow)
  Scene3D, Step, Element3D, StepResponsive,
  Transform3D, Vector3,
  useScene3D, useCamera, useActiveStep,
  // Animation Components
  AnimatedText, AnimatedCounter, TypeWriter, CodeBlock,
  StaggeredMotion, GradientTransition, MatrixRain, ScrollingColumns,
  Particles, Spawner, Behavior,
  // Core
  useViewportRect,
  interpolate, Easing,
  interpolateColorKeyframes, interpolateGradientKeyframes,
  random, resolvePoint, createRect,
} from "remotion-bits";
```

## Core Concepts

### 1. AnimatedValue

Most animation properties accept `AnimatedValue`: a static number OR an array of keyframes interpolated over the animation's duration.

```tsx
opacity: 1                // Static
opacity: [0, 1]           // Animate 0→1
opacity: [0, 1, 0.5, 0]  // Multi-keyframe: 0→1→0.5→0 evenly spaced
scale: [0.8, 1]           // Scale from 80% to 100%
y: [30, 0]                // Slide up from 30px offset
```

Keyframes are evenly distributed across the duration. With 4 keyframes over 60 frames: frame 0→20→40→60.

### 2. Responsive Sizing with useViewportRect

**Never hardcode pixel values.** Always use viewport-relative units:

```tsx
const rect = useViewportRect();
// rect.width   - composition width (e.g. 1920)
// rect.height  - composition height (e.g. 1080)
// rect.vw      - 1% of width (19.2)
// rect.vh      - 1% of height (10.8)
// rect.vmin    - min(vw, vh) - USE THIS for most sizing
// rect.vmax    - max(vw, vh)
// rect.cx, cy  - center coordinates
const { vmin } = rect;
```

Use `vmin` for font sizes, element dimensions, spacing, and padding. This ensures compositions render identically at 1920×1080, 1080×1920, 3840×2160, etc.

#### Understanding vmin at Common Resolutions

`vmin` = `min(width, height) / 100`. **Always compute what vmin equals in pixels for your composition size before choosing multipliers.**

| Composition Size | Aspect Ratio | vmin (px) | vmin * 8 | vmin * 10 | vmin * 5 |
|------------------|-------------|-----------|----------|-----------|----------|
| 1920×1080 | 16:9 landscape | **10.8** | 86px | 108px | 54px |
| 1080×1920 | 9:16 portrait | **10.8** | 86px | 108px | 54px |
| 1080×1080 | 1:1 square | **10.8** | 86px | 108px | 54px |
| 3840×2160 | 16:9 4K | **21.6** | 173px | 216px | 108px |
| 1280×720 | 16:9 720p | **7.2** | 58px | 72px | 36px |

#### Font Size Reference (at 1920×1080, vmin = 10.8px)

**Use these proven multipliers from production bits. Err on the side of LARGER, not smaller.**

| Role | Multiplier | Pixels at 1080p | Example |
|------|-----------|-----------------|---------|
| Hero / main title | `vmin * 10–15` | 108–162px | Full-screen headline |
| Section heading | `vmin * 6–8` | 65–86px | Scene3D step titles |
| Subheading | `vmin * 4–5` | 43–54px | Card titles, counters |
| Body / card label | `vmin * 2.5–3` | 27–32px | Feature labels, descriptions |
| Code / small text | `vmin * 1.5–2` | 16–22px | Code blocks, captions |
| Fine print | `vmin * 1–1.2` | 11–13px | Code font in dense blocks |

**Common mistake: using `vmin * 3` for headings.** At 1080p that's only 32px - fine for body text but too small for any heading. For prominent headings, start at `vmin * 8` minimum.

#### Aspect Ratio Awareness

The aspect ratio determines which dimension is the "min" for vmin:

- **Landscape (16:9, 1920×1080):** `vmin` is based on height (1080/100 = 10.8). Horizontal space is abundant; vertical space is limited.
- **Portrait (9:16, 1080×1920):** `vmin` is based on width (1080/100 = 10.8). Vertical space is abundant; horizontal space is limited.
- **Square (1:1, 1080×1080):** `vmin = vmax = vh = vw`. All directions equal.

**Layout implications:**
- In landscape, full-width text can be very long - consider `width: vmin * 70` or `maxWidth` constraints
- In portrait, titles may need to wrap - use fewer words or smaller multipliers for width-constrained text
- Use `vmin` for sizes that should scale uniformly regardless of orientation
- Use `vw`/`vh` when sizing should follow a specific axis (e.g., full-width background: `rect.width`)

#### Element Size Reference

| Element | Multiplier | Description |
|---------|-----------|-------------|
| Card width | `vmin * 50–70` | Floating card, info panel |
| Card height | `vmin * 25–40` | Match content needs |
| Card border-radius | `vmin * 1–2` | Subtle rounding |
| Spacing/gap | `vmin * 1–3` | Between elements |
| Padding | `vmin * 2–4` | Inside containers |
| Particle size | `vmin * 1–3` | Individual particle dot |
| Icon size | `vmin * 8–12` | Decorative icons |

### 3. Transition Props Pattern

Components accept a `transition` prop with this shape:

```tsx
transition={{
  // Timing
  duration: 30,           // Duration in frames
  delay: 10,              // Delay before start
  frames: [0, 60],        // Or explicit frame range (alternative to duration)
  easing: "easeOutCubic", // Easing curve

  // Transform (all accept AnimatedValue)
  x: [30, 0],             // translateX
  y: [30, 0],             // translateY
  z: