remotion-core

Remotion Core

Remotion は React から動画をレンダリングします。コンポジションは、出力がフレームインデックスの純粋関数である React コンポーネントです。同じフレームからは、常に同じピクセルが生成されます。すべてのアニメーションは useCurrentFrame() から導出する必要があり、Date.now()、Math.random()、外部の可変状態を使用してはいけません。

このスキルは、Remotion プロジェクトを構築するための技術的な契約です。以下はビルドガイドであり、各トピックの詳細は references/ にあります（次の一覧を参照）。必要に応じて読んでください。

References

ファイル	読んでわかること…
references/minimal-composition.md	最小限のレンダリング可能なコンポジションの骨組みから始める
references/composition-patterns.md	単独構成とネスト構成を選ぶ、Root.tsx を構成する、Sequence と Series を使う
references/timing-api.md	useCurrentFrame、useVideoConfig、interpolate、spring、measureSpring を使う
references/sequence-and-series.md	<Sequence from> でクリップのタイミングを設定し、<Series> でシーンをつなぎ、ネストしたオフセットを扱う
references/media-elements.md	<OffthreadVideo>、<Audio>、<Img> を配置し、トリミング、音量、startFrom を設定する
references/determinism-rules.md	フレームごとに決定論的なコンポジションを構築する、禁止 API、使用可能なアニメーションプリミティブ
references/calculate-metadata.md	再生時間／fps／サイズを動的に宣言する、レンダリング前にデータを取得する、InputProps のスキーマ
references/static-files.md	staticFile()、getStaticFiles()、public/ ディレクトリを使ってアセットを参照する
references/storyboard-format.md	STORYBOARD.md のプランを作成する
references/review-loop.md	プラン → スケッチ → 構築のレビューパスを実行する
references/production-loop.md	承認済みプランから納品動画を制作する
references/brief-format.md	確定した意図を記すドキュメント BRIEF.md を作成する
references/script-format.md	任意の、確定済みナレーション SCRIPT.md を作成する

アニメーションの詳細（スプリング物理、interpolate の外挿、スタッガー）については、remotion-animation → adapters/ を参照してください。

コンポジションの構築

唯一のルートルール

各コンポジションのエントリーファイル（src/Root.tsx）は、<Composition> を介してコンポジションを登録する RemotionRoot を 1 つエクスポートします。各 <Composition> は 1 つの React コンポーネントを参照します。グローバルな可変状態や、モジュール読み込み時の副作用を使ってはいけません。

// src/Root.tsx
import {Composition} from 'remotion';
import {MyScene} from './MyScene';

export const RemotionRoot: React.FC = () => (
  <>
    <Composition
      id="MyScene"
      component={MyScene}
      durationInFrames={150}
      fps={30}
      width={1920}
      height={1080}
    />
  </>
);

フレーム駆動のレンダリング（絶対遵守）

すべての視覚的な値は useCurrentFrame() から計算します。レンダラーは複数のブラウザーインスタンスを並列で使用する可能性があり、各フレームを個別にキャプチャします。外部の可変状態を読み取るコードでは、スレッドごとに異なるピクセルが生成されます。

import {useCurrentFrame, useVideoConfig, interpolate, spring} from 'remotion';

const MyScene: React.FC = () => {
  const frame = useCurrentFrame();
  const {fps, durationInFrames} = useVideoConfig();

  const opacity = interpolate(frame, [0, 30], [0, 1], {extrapolateRight: 'clamp'});
  const scale = spring({frame, fps, config: {damping: 200}});

  return (
    <AbsoluteFill style={{opacity, transform: `scale(${scale})`}}>
      <h1>Hello Remotion</h1>
    </AbsoluteFill>
  );
};

絶対遵守のルール（自動チェックで見逃す可能性のある不具合を防ぐ）

• Math.random() は使用しない — シード付き疑似乱数には 'remotion' の random(seed) を使う
• Date.now()／performance.now() は使用しない — 時間に基づくすべての値には useCurrentFrame() を使う
• レンダリングパスでは setTimeout／setInterval を使用しない — calculateMetadata の非同期スコープ内でのみ使用する
• 視覚的なプロパティに useState／useEffect を使用しない — すべての視覚状態をフレームインデックスから導出する
• CSS のトランジション／アニメーションは使用しない — Remotion のタイムラインシークとは独立して動作する
• 無限ループは使用しない — repeat(-1) などはレンダラーを停止させる
• フレームから導出した可変状態を保持する useRef は使用しない — シーク時に ref はリセットされる

詳しい理由 → references/determinism-rules.md。

コンポジションのサイズ設定

<Composition> では、必ず width、height、fps、durationInFrames を明示してください。props に基づく場合は、calculateMetadata を使って動的に設定できます。

AbsoluteFill — シーンのルート

<AbsoluteFill> は position: absolute; top: 0; left: 0; width: 100%; height: 100% です。手動で用意した div の代わりに、シーンのルートとして使用してください。コンテンツが画面全体に広がり、正しく合成されることを保証します。

import {AbsoluteFill} from 'remotion';

const MyScene = () => (
  <AbsoluteFill style={{backgroundColor: '#0f0f0f'}}>
    {/* scene content */}
  </AbsoluteFill>
);

シーケンス — クリップのプリミティブ

<Sequence from={startFrame} durationInFrames={duration}> は、子要素のタイムラインをオフセットします。子要素から見ると、親の from フレームがフレーム 0 になります。シーンを構成する際に、あらゆる場所でフレーム計算をハードコーディングせずに済む方法です。

import {Sequence} from 'remotion';

const Timeline = () => (
  <>
    <Sequence from={0} durationInFrames={60}>
      <IntroScene />
    </Sequence>
    <Sequence from={60} durationInFrames={90}>
      <MainScene />
    </Sequence>
    <Sequence from={150} durationInFrames={60}>
      <OutroScene />
    </Sequence>
  </>
);

メディア要素

• <OffthreadVideo> — 動画ファイルに使用します。各フレームをメインスレッド外でレンダリングし、startFrom、endAt、volume に対応しています
• <Audio> — オーディオファイルに使用し、startFrom、endAt、volume に対応しています
• <Img> — 画像に使用します。public/ のアセットには staticFile() を使用してください

public/ ディレクトリ内のアセットへのメディアパスには、すべて staticFile('filename') を使用してください。

既存のコンポジションの編集

• まずファイルを読んでください。無関係なタイミング、ID、props インターフェースは保持してください。
• 既存のコンポジション ID とコンポーネントのシグネチャに合わせてください。
• シーンを追加する場合：重複しない <Sequence from> オフセットを使用してください。
• calculateMetadata はレンダリング前に一度実行されます。レンダリング時に呼び出さないでください。

検証

コマンドの詳細は remotion-cli を使用してください。

• npx remotion studio を実行し、コンソールエラーなしで開くこと
• すべてのコンポジションが表示され、タイムライン上でシークできること
• npx remotion render <entry> <id> out/test.mp4 --concurrency=1 を実行すると、空でないファイルが生成されること
• ffprobe out/test.mp4 で想定どおりの長さと解像度が報告されること
• ユーザーがプレビューを承認してからレンダリングすること