remotion-best-practices

Overview

What is the remotion-best-practices skill?

remotion-best-practices スキルは、React ベースの動画制作フレームワークである Remotion で動画を構築するためのガイドとルールをまとめたものです。アニメーション、オーディオ、字幕、FFmpeg の利用、アセット、3D シーンなどに関するドメイン固有のパターンを、rules/ 以下のフォーカスされたルールファイルとして整理しています。

ゼロから断片的なサンプルを寄せ集めるのではなく、Remotion のコードをどう構造化すれば安定してレンダリングでき、複雑なプロジェクトにもスケールし、長期的に保守しやすくなるかについて、意見のあるガイダンスを提供します。

Who is this skill for?

次のような場合は、このスキルのインストールを検討してください。

• Remotion と React を使ってマーケティング動画、プロダクト動画、SNS 用動画を作っている
• データ駆動・テンプレートベースなど、プログラムで動画を生成したい
• ポッドキャストやオーディオグラム、音楽ビジュアライザーなど、音声中心のコンテンツを扱っている
• 字幕・キャプション・SRT ワークフローの明確なパターンが欲しい
• Remotion のコンポジションに 3D や Three.js のコンテンツを組み込みたい

フロントエンドエンジニア、コードを書くモーションデザイナー、Remotion プロジェクトの書き方を標準化したいチームなどに特に役立ちます。

What problems does it solve?

Remotion best-practices スキルは、実際の Remotion プロジェクトで頻出する次のような実務的な課題の解決に役立ちます。

• すべてのアニメーションをフレーム駆動にして、安定かつ決定的にレンダリングできるようにする
• public/ フォルダと staticFile() を使って、画像・動画・音声・フォントを正しくインポート・参照する
• タイミング・トランジション・パラメータが一貫した、きれいな動画コンポジションを組み立てる
• 音声（レイヤー、トリム、ディレイ、音量、再生速度、ループ、効果音）の扱い方を整理する
• オーディオビジュアライゼーション（スペクトラムバー、波形、低音に反応するエフェクトなど）を生成する
• SRT 取込や文字起こしを含む、キャプション・字幕のワークフローを構築する
• トリミング、フレーム抽出、無音検出などの用途で FFmpeg を活用する
• @remotion/three を通じて Three.js と React Three Fiber を利用し、3D を統合する
• レンダリング前に、コンポジションのメタデータ（duration、dimensions、props）を動的に算出する
• レンダリング前に Mediabunny でメディア互換性を検証する

簡単なデモを超える Remotion プロジェクトを作るのであれば、これらのルールは本番環境で検証されたパターンとして大いに役立ちます。

When is this skill a good fit?

remotion-best-practices スキルがフィットするのは、次のようなケースです。

• プロジェクトですでに Remotion を使っている、もしくは動画生成用途で Remotion を評価している
• アニメーション、アセット、音声、字幕、3D に関する一貫したガイドラインが欲しい
• 抽象的なドキュメントではなく、コードレベルの具体的な例を確認したい

このスキルは、Remotion の公式ドキュメントの代替でも、React を一から学ぶための完全なチュートリアルでもありません。基本的な React に慣れており、Remotion のドキュメントを少なくとも一通り眺めていることを前提にしています。

How to Use

1. Installation and setup

Install the skill into your agent environment

スキルマネージャーを使って、upstream リポジトリから Remotion best-practices スキルを追加します。

npx skills add https://github.com/remotion-dev/skills --skill remotion

これで remotion-best-practices のナレッジがエージェントから利用可能になり、Remotion プロジェクトを支援する際にルールファイルを参照できるようになります。

Review the core documentation files

インストールが完了したら、まず次のファイルを確認してください。

• SKILL.md – スキル全体の概要、利用シーン、主要ルールファイルへのリンク
• rules/animations.md – useCurrentFrame() と useVideoConfig() によるアニメーション制御
• rules/assets.md – 画像・動画・音声・フォントを正しくインポートする方法
• rules/audio.md – 音声の扱い方、トリミング、ディレイ、レイヤリング
• rules/audio-visualization.md – 音声データ、波形、スペクトラムビジュアライゼーション
• rules/3d.md – @remotion/three を使った Three.js と React Three Fiber による 3D シーン

これらのルールが、多くの Remotion ベースの動画編集ワークフローの土台になります。

2. Core concepts and best practices

Drive all animations by frame

Remotion のアニメーションにおける中核原則については、rules/animations.md を参照してください。

• 現在のフレームを読むために useCurrentFrame() を使う
• fps を取得するために useVideoConfig() を使う
• アニメーションのタイミングは秒単位で設計し、フレームに変換する（seconds * fps）
• interpolate() などのヘルパーを使って、フレームから位置・不透明度・その他のプロパティにマッピングする
• CSS transitions、CSS animations、Tailwind の animation クラスは使用しない（Remotion では安定してレンダリングされないため）

フレームベースのアプローチを徹底することで、再生速度や環境に依存せず、一貫した出力が得られます。

Manage assets via public/ and staticFile()

rules/assets.md ではメディアの扱い方を定義しています。

• 静的なメディア（画像・フォント・音声・動画）はすべて public/ フォルダに配置する
• public/ 内のアセットは staticFile("my-file.ext") で参照する
• staticFile() は <Img>、<Video>、<Audio> など Remotion のコンポーネントと組み合わせて使う
• ファイルが Web 上にホストされている場合は、リモート URL をそのまま利用する

このパターンに従うことでパス切れを防ぎ、URL エンコードの問題を回避し、異なるデプロイ環境でも安定して動作させることができます。

Build robust audio and sound design

rules/audio.md では、音声に特化したワークフローを扱っています。

• @remotion/media の <Audio> で音声をインポートする
• trimBefore と trimAfter（フレームベース）で音声区間をトリミングする
• <Sequence> でラップして、音声を遅延させたり映像と同期させたりする
• 複数の <Audio> コンポーネントで音楽・ボイスオーバー・効果音をレイヤーする

音声を軸にしたビジュアルを作る場合は、rules/audio-visualization.md と組み合わせて次を行います。

• @remotion/media-utils をインストールする
• useWindowedAudioData() で指定時間窓の音声サンプルを取得する
• visualizeAudio() を用いてスペクトラムバー向けの周波数データを生成する

これにより、オーディオグラム、音に反応するタイトル、音楽ビジュアライゼーションなどを手早く実装できます。

Handle captions and subtitles

トップレベルの SKILL.md から、字幕関連のルールへたどれます。

• rules/subtitles.md – 字幕利用の基本パターン
• rules/display-captions.md – 画面上へのキャプション描画
• rules/import-srt-captions.md – SRT 字幕ファイルのインポート
• rules/transcribe-captions.md – 文字起こし中心のワークフロー

これらは次のようなニーズに対応します。

• SNS 向けの焼き込み字幕（burned-in subtitles）
• 言語別の字幕トラック
• 自動〜半自動の字幕制作ワークフロー

Use FFmpeg for advanced video operations

rules/ffmpeg.md では、Remotion と並行して FFmpeg を使うべきケースを解説しています。

• 元動画のトリミングや連結
• 音声の無音区間検出
• フレーム抽出や GIF 作成

Remotion はレンダリングとコンポジションに特化し、FFmpeg は生のメディアファイルの重い処理を担当します。両者を組み合わせることで、本番環境の動画パイプラインを効率的に構築できます。

Bring in 3D with Three.js and React Three Fiber

Remotion の動画に 3D シーンを組み込みたい場合は、rules/3d.md を確認してください。

• 推奨コマンド npx remotion add @remotion/three（もしくは使用中のパッケージマネージャーに合わせたコマンド）で @remotion/three をインストールする
• 3D コンテンツを <ThreeCanvas> でラップし、useVideoConfig() から取得した width と height を渡す
• ambientLight や directionalLight などで基本的なライティングを設定する
• @react-three/fiber の useFrame() ではなく、useCurrentFrame() を使って 3D アニメーションを駆動する

これにより、3D コンテンツがフレーム単位で正しくレンダリングされ、ちらつきや同期ずれを防げます。

3. Dynamic compositions and metadata

Calculate duration and dimensions dynamically

rules/calculate-metadata.md では、<Composition> 上で calculateMetadata を使う方法を紹介しています。

• 外部データ（入力動画の長さなど）にもとづいて durationInFrames を調整する
• 入力動画やその他の動的な値にコンポジションの dimensions を合わせる
• レンダリング開始前に props を変換する

rules/get-video-duration.md や rules/get-video-dimensions.md などのヘルパーと組み合わせることで、次のようなことが可能になります。

• アップロードされたコンテンツに合わせてコンポジションのサイズを自動調整する
• イントロ・アウトロの長さをメディアの長さと正確に合わせる

ユーザー生成コンテンツやテンプレートベースの動画システムで特に有用です。

4. Media validation and compatibility

Check if a video can be decoded

rules/can-decode.md では、互換性チェックのための Mediabunny を紹介しています。

• npx remotion add mediabunny で Mediabunny をインストールする
• ブラウザが URL ベースの動画をデコードできるかどうか、canDecode() ヘルパーでチェックする
• アップロードされた Blob ソース向けには canDecodeBlob() を使う

高負荷なレンダリング処理を始める前に、アップロードフローの中でメディアを検証したい場合に便利です。

5. Additional focused rules

コアトピック以外にも、rules/ には必要に応じて参照できる専門的なガイドが含まれています。

• rules/compositions.md – Remotion コンポジションの構造化と管理
• rules/timing.md, rules/sequencing.md, rules/transitions.md, rules/text-animations.md – モーションとタイミングの細かな制御
• rules/fonts.md, rules/measuring-text.md, rules/measuring-dom-nodes.md – タイポグラフィとレイアウト精度
• rules/gifs.md, rules/images.md, rules/videos.md, rules/transparent-videos.md, rules/trimming.md, rules/extract-frames.md – 各種メディアフォーマットと処理
• rules/maps.md, rules/charts.md, rules/lottie.md, rules/light-leaks.md – ドメイン別のビジュアルパターン
• rules/voiceover.md, rules/sfx.md – ボイスオーバーと効果音のワークフロー
• rules/tailwind.md – 禁止されている animation クラスを除き、Remotion と両立する Tailwind の使い方

プロジェクトで必要な機能に応じて、これらをピンポイントで参照してください。

6. Workflow tips for using this skill

With an AI agent

このスキルをインストールした AI アシスタントを使う場合は、次のような活用ができます。

• より詳しい例が必要な時に、特定のルールファイル（例: rules/audio.md）を開いてもらう
• ルールに準拠したコードスニペットの生成を任せる（CSS transitions を使わない、useCurrentFrame() ベースのアニメーション、staticFile() の適切な利用など）
• Remotion コードのレビューやリファクタリング時に、スキルをチェックリスト代わりに用いる

In a team setting

チームで標準化して使う場合は、次のような形で導入するのがおすすめです。

• 社内ドキュメントから、関連する rules/*.md へのリンクを共有する
• スキルにあるパターンを、自社のコーディングガイドラインに取り込む
• Remotion プロジェクトに新しく参加する開発者のオンボーディング時に、リファレンスとして活用する

FAQ

Is this skill the same as the Remotion framework?

違います。Remotion は React で動画を作成するための基盤フレームワークです。remotion-best-practices スキルは、その Remotion の上に載るベストプラクティスとルールファイルの集合で、コード構造やメディアの扱い方、よくある落とし穴の回避方法をガイドします。

Do I need to know React to benefit from this skill?

必要です。Remotion エコシステムは React ベースであり、ルールファイル中のサンプルもコンポーネント・props・hooks を理解していることを前提としています。このスキルの主眼は Remotion 固有の課題 であり、React の基礎を教えることではありません。

How do I install the Remotion best-practices skill?

次のコマンドで、エージェントやスキル実行環境にインストールします。

npx skills add https://github.com/remotion-dev/skills --skill remotion

その後、SKILL.md と rules/ フォルダを開き、利用可能なトピックを確認してください。

Can I use this skill without a Remotion project yet?

既存のプロジェクトがなくても内容やサンプルを読むことはできますが、Remotion のワークスペースを用意してからの方が価値を最大化できます。多くのルールでは @remotion/media、@remotion/media-utils、@remotion/three、Mediabunny などのパッケージをプロジェクトにインストールして使うことを前提としています。

Does this skill cover 3D content with Three.js?

はい。rules/3d.md は、@remotion/three を通じて Three.js と React Three Fiber を用いた Remotion での 3D 表現に特化したファイルです。パッケージのインストール方法、<ThreeCanvas> でのラップ、useCurrentFrame() によるアニメーション駆動などを解説しています。

Where do I find guidance on audio visualizations and audiograms?

rules/audio-visualization.md を参照してください。@remotion/media-utils のインストール方法、useWindowedAudioData() での音声データ取得、visualizeAudio() による変換を通じて、オーディオグラム向けのスペクトラムバーや波形を構築する手順を説明しています。

What if I need to work with captions and subtitles?

まず SKILL.md から次のファイルをたどってください。

• 一般的な字幕パターン: rules/subtitles.md
• 画面への描画: rules/display-captions.md
• SRT ファイルのインポート: rules/import-srt-captions.md
• 文字起こしワークフロー: rules/transcribe-captions.md

これらのガイドで、多くの Remotion ベースの動画における字幕ニーズをカバーできます。

When should I use FFmpeg instead of pure Remotion code?

生のメディアファイルに対して、厳密なトリミング・連結・無音検出・フレーム抽出などを行いたい場合は FFmpeg を使うのが適しています。Remotion は React の中でシーンを構成してレンダリングするのが得意です。rules/ffmpeg.md では、Remotion パイプラインの中で FFmpeg をどのように組み合わせるか、その判断基準と使い方を説明しています。

Can this skill help me avoid performance and rendering issues?

はい。このスキル内の多くのルールは、次のようなよくある問題を避けるために存在します。

• useCurrentFrame() の代わりに useFrame() を使ってしまうことで起こる 3D シーンのちらつき
• CSS transitions に依存しているためにレンダリングされないアニメーション
• アセットパスの破損や URL エンコード不備
• デコードできないメディアが原因でレンダリング中に失敗するケース

rules/animations.md、rules/assets.md、rules/3d.md、rules/can-decode.md に沿って実装することで、より信頼性の高い Remotion プロジェクトを構築しやすくなります。

How do I explore all available rule files?

インストール後、環境内で rules/ ディレクトリを開いてください。代表的なファイルは次の通りです。

• rules/3d.md
• rules/animations.md
• rules/assets.md
• rules/audio-visualization.md
• rules/audio.md
• rules/ffmpeg.md
• rules/compositions.md
• rules/timing.md
• rules/subtitles.md
• rules/voiceover.md

それ以外にも、charts・maps・GIF・Tailwind など、より専門的なトピックを扱うファイルがあるので、Files タブやエディタからブラウズして確認してみてください。