remotion-best-practices

Overview

What is the remotion-best-practices skill?

The remotion-best-practices skill is a curated set of guides and rules for building videos with Remotion, the React-based video creation framework. It collects domain-specific patterns for animations, audio, captions, FFmpeg usage, assets, 3D scenes, and more into focused rule files under rules/.

Instead of piecing together examples from scratch, this skill gives you opinionated guidance on how to structure Remotion code so it renders reliably, scales to complex projects, and stays maintainable over time.

Who is this skill for?

Install this skill if you:

• Build marketing, product, or social videos using Remotion and React
• Need to generate videos programmatically (for example, data-driven or template-based content)
• Work with audio-heavy content such as podcasts, audiograms, or music visualizers
• Want clear patterns for captions, subtitles, and SRT workflows
• Are adding 3D or Three.js content to your Remotion compositions

It is useful for frontend engineers, motion designers who code, and teams standardizing how they write Remotion projects.

What problems does it solve?

The Remotion best-practices skill helps you solve practical issues that come up in real Remotion projects, such as:

• Driving all animations by frames so renders are stable and deterministic
• Importing and referencing images, videos, audio, and fonts correctly via the public/ folder and staticFile()
• Creating clean video compositions with consistent timing, transitions, and parameters
• Handling audio (layering, trimming, delaying, volume, speed, loops, SFX)
• Generating audio visualizations (spectrum bars, waveforms, bass-reactive effects)
• Working with captions and subtitles, including SRT import and transcription
• Using FFmpeg for tasks like trimming, extracting frames, or detecting silence
• Integrating 3D using Three.js and React Three Fiber via @remotion/three
• Dynamically calculating composition metadata (duration, dimensions, props) before rendering
• Validating media compatibility with Mediabunny before rendering

If you are building anything beyond a trivial Remotion demo, these rules give you patterns that are battle-tested for real production scenarios.

When is this skill a good fit?

Use the remotion-best-practices skill when:

• Your project already uses Remotion or you are evaluating Remotion for video generation
• You want consistent guidelines on animations, assets, audio, captions, and 3D
• You need code-level examples and not just high-level docs

It is not a replacement for the main Remotion documentation or a full tutorial on learning React. It assumes you are comfortable with basic React and have at least skimmed the Remotion docs.

How to Use

1. Installation and setup

Install the skill into your agent environment

Use the skill manager to add the Remotion best-practices skill from the upstream repository:

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

This makes the remotion-best-practices knowledge available to your agent so it can reference the rule files when assisting with your Remotion project.

Review the core documentation files

Once installed, open these files first:

• SKILL.md – Top-level description, when to use, and links to key rule files
• rules/animations.md – How to drive animations with useCurrentFrame() and useVideoConfig()
• rules/assets.md – How to import images, videos, audio, and fonts correctly
• rules/audio.md – Working with audio, trimming, delays, and layering
• rules/audio-visualization.md – Audio data, waveforms, and spectrum visualizations
• rules/3d.md – 3D scenes using Three.js and React Three Fiber via @remotion/three

These rules give you the foundation for most Remotion video-editing workflows.

2. Core concepts and best practices

Drive all animations by frame

Refer to rules/animations.md for the central Remotion animation principle:

• Use useCurrentFrame() to read the current frame
• Use useVideoConfig() to get fps
• Calculate animation timings in seconds, then convert to frames (seconds * fps)
• Use helpers like interpolate() to map frames to positions, opacity, or other properties
• Avoid CSS transitions, CSS animations, and Tailwind animation classes; they do not render reliably in Remotion

This frame-driven approach ensures consistent output regardless of playback speed or environment.

Manage assets via public/ and staticFile()

The rules/assets.md file defines how to handle media:

• Place all static media (images, fonts, audio, video) in the public/ folder
• Use staticFile("my-file.ext") to reference assets inside public/
• Pair staticFile() with Remotion components like <Img>, <Video>, <Audio>
• Use remote URLs directly when the file is hosted on the web

This pattern prevents broken paths, takes care of URL encoding, and works across different deployment setups.

Build robust audio and sound design

The rules/audio.md file covers audio-specific workflows:

• Import audio with <Audio> from @remotion/media
• Trim audio segments with trimBefore and trimAfter (frame-based)
• Delay audio or sync it with visuals using <Sequence> wrappers
• Layer multiple <Audio> components for music, voiceover, and SFX

For audio-driven visuals, combine this with rules/audio-visualization.md to:

• Install @remotion/media-utils
• Use useWindowedAudioData() to read audio samples for a time window
• Use visualizeAudio() to produce frequency data for spectrum bars

This makes it straightforward to create audiograms, beat-reactive titles, and music visualizations.

Handle captions and subtitles

The top-level SKILL.md points you to caption-related rules:

• rules/subtitles.md – Subtitle usage patterns
• rules/display-captions.md – Rendering captions on screen
• rules/import-srt-captions.md – Importing SRT caption files
• rules/transcribe-captions.md – Transcription-oriented workflows

Use these when you need:

• Burned-in subtitles for social content
• Language-specific caption tracks
• Automated or semi-automated caption workflows

Use FFmpeg for advanced video operations

The rules/ffmpeg.md guide shows when to use FFmpeg alongside Remotion for operations like:

• Trimming or concatenating source videos
• Detecting silence in audio
• Extracting frames or creating GIFs

Remotion focuses on rendering; FFmpeg handles heavy lifting on raw media files. Combining both is often the most efficient approach for production video pipelines.

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

If you want 3D scenes in your Remotion videos, read rules/3d.md:

• Install the @remotion/three package with the recommended npx remotion add @remotion/three command (or the equivalent for your package manager)
• Wrap 3D content in <ThreeCanvas> and pass width and height from useVideoConfig()
• Set up basic lighting (for example, ambientLight and directionalLight)
• Drive all 3D animations using useCurrentFrame() instead of useFrame() from @react-three/fiber

This ensures your 3D content renders correctly frame by frame without flickering or desync.

3. Dynamic compositions and metadata

Calculate duration and dimensions dynamically

The rules/calculate-metadata.md file shows how to use calculateMetadata on a <Composition> to:

• Adjust durationInFrames based on external data (for example, the length of an input video)
• Match composition dimensions to an input video or other dynamic values
• Transform props before rendering starts

Paired with helpers like rules/get-video-duration.md and rules/get-video-dimensions.md, this allows you to:

• Auto-size your composition to uploaded content
• Ensure intros/outros precisely match media length

This is especially helpful for user-generated or template-based video systems.

4. Media validation and compatibility

Check if a video can be decoded

The rules/can-decode.md guide introduces Mediabunny for compatibility checks:

• Install Mediabunny with npx remotion add mediabunny
• Use the provided canDecode() helper to check if a URL-source video can be decoded by the browser
• Use the canDecodeBlob() variant for uploaded Blob sources

This is useful when building upload flows where you need to verify media before starting an expensive render.

5. Additional focused rules

Beyond the core topics, rules/ contains specialized guides that you can pull in as needed:

• rules/compositions.md – Structure and manage your Remotion compositions
• rules/timing.md, rules/sequencing.md, rules/transitions.md, rules/text-animations.md – Fine-grained control over motion and timing
• rules/fonts.md, rules/measuring-text.md, rules/measuring-dom-nodes.md – Typography and layout precision
• rules/gifs.md, rules/images.md, rules/videos.md, rules/transparent-videos.md, rules/trimming.md, rules/extract-frames.md – Working with different media formats and operations
• rules/maps.md, rules/charts.md, rules/lottie.md, rules/light-leaks.md – Domain-specific visual patterns
• rules/voiceover.md, rules/sfx.md – Voice and sound effects workflows
• rules/tailwind.md – Using Tailwind in a Remotion-compatible way (excluding forbidden animation classes)

You can reference these selectively depending on the features your project requires.

6. Workflow tips for using this skill

With an AI agent

If you are using an AI assistant that has this skill installed:

• Ask it to open a specific rule file (for example, rules/audio.md) when you need deeper examples
• Let it generate code snippets that comply with the rules (no CSS transitions, all animations via useCurrentFrame(), proper staticFile() usage, etc.)
• Use the skill as a checklist when reviewing or refactoring your Remotion code

In a team setting

For teams, standardize on this skill by:

• Sharing links to relevant rules/*.md files in your documentation
• Adopting patterns from the skill into your internal coding guidelines
• Using it as a reference when onboarding developers onto Remotion projects

FAQ

Is this skill the same as the Remotion framework?

No. Remotion is the underlying framework for creating videos with React. The remotion-best-practices skill is a collection of best-practices and rule files that sit on top of Remotion to guide how you structure code, handle media, and avoid common pitfalls.

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

Yes. The Remotion ecosystem is React-based, and the examples in the rule files assume you understand components, props, and hooks. The skill focuses on Remotion-specific concerns, not on teaching React from scratch.

How do I install the Remotion best-practices skill?

Install it into your agent or skills environment with:

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

Then open SKILL.md and the rules/ folder to explore the available topics.

Can I use this skill without a Remotion project yet?

You can read the content and examples without an existing project, but it is most useful once you have a Remotion workspace. Many rules reference packages like @remotion/media, @remotion/media-utils, @remotion/three, or Mediabunny that you will want to install directly into your project.

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

Yes. The rules/3d.md file is dedicated to 3D in Remotion using Three.js and React Three Fiber through @remotion/three. It explains how to install the package, wrap content in <ThreeCanvas>, and drive animations using useCurrentFrame().

Where do I find guidance on audio visualizations and audiograms?

Use rules/audio-visualization.md. It shows how to install @remotion/media-utils, fetch audio data with useWindowedAudioData(), and transform it via visualizeAudio() to build spectral bars and waveforms for audiograms.

What if I need to work with captions and subtitles?

Start from SKILL.md, which points to:

• rules/subtitles.md for general subtitle patterns
• rules/display-captions.md for on-screen rendering
• rules/import-srt-captions.md for SRT file import
• rules/transcribe-captions.md for transcription workflows

These guides cover most captioning needs in Remotion-based videos.

When should I use FFmpeg instead of pure Remotion code?

Use FFmpeg when you need operations on raw media files such as precise trimming, concatenation, silence detection, or frame extraction. Remotion excels at composing and rendering scenes in React. rules/ffmpeg.md explains how and when to integrate FFmpeg alongside your Remotion pipeline.

Can this skill help me avoid performance and rendering issues?

Yes. Many of the rules exist specifically to avoid common pitfalls, such as:

• Flickering 3D scenes when useFrame() is used instead of useCurrentFrame()
• Animations that don’t render because they rely on CSS transitions
• Broken asset paths and incorrectly encoded URLs
• Media that fails during rendering because it can’t be decoded

Following the patterns in rules/animations.md, rules/assets.md, rules/3d.md, and rules/can-decode.md will help you build more reliable Remotion projects.

How do I explore all available rule files?

After installation, open the rules/ directory in your environment. Key files include:

• 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

Use the Files tab or your editor to browse the rest for more specialized topics like charts, maps, GIFs, and Tailwind.