How to Configure Output Settings Like Codec and Pixel Format in Remotion

You configure codec and pixel format in Remotion by passing the codec and pixelFormat options to the renderMedia() function, which validates the combination and translates them into FFmpeg arguments.

Remotion is a React-based framework for programmatic video generation. When rendering videos programmatically or via CLI, you must specify how the final video should be encoded. This guide explains how to configure output settings like codec and pixel format in Remotion based on the actual implementation in the remotion-dev/remotion repository.

Understanding Codec and Pixel Format Configuration in Remotion

Remotion abstracts FFmpeg complexity through the @remotion/renderer package. The core configuration happens in renderMedia(), defined in packages/renderer/src/render-media.ts.

Default Values and Supported Options

If you omit output settings, Remotion applies safe defaults defined in the source code:

• Default codec: 'h264' (defined in packages/renderer/src/codec.ts as DEFAULT_CODEC)
• Default pixel format: 'yuv420p' (defined in packages/renderer/src/pixel-format.ts as DEFAULT_PIXEL_FORMAT)

Supported codecs include 'h264', 'h265', 'vp8', 'vp9', 'prores', 'gif', and 'aac'. Supported pixel formats include 'yuv420p', 'yuva420p', 'yuv422p', and 'yuv444p'.

Validation Logic for Codec-Pixel Format Combinations

Not all combinations are valid. For example, H.264 does not support alpha channels, while VP9 requires specific settings for transparency.

The function validateSelectedPixelFormatAndCodecCombination in packages/renderer/src/pixel-format.ts enforces these rules. If you attempt an invalid combination—such as codec: 'h264' with pixelFormat: 'yuva420p'—Remotion throws a TypeError with a clear message explaining the incompatibility.

How to Set Codec and Pixel Format in renderMedia()

Pass the codec and pixelFormat options directly to renderMedia(). Both options are part of the RenderMediaOptions type.

Standard H.264 Output

import {renderMedia} from '@remotion/renderer';

await renderMedia({
  composition: MyComp,
  codec: 'h264',              // Uses libx264 encoder
  outputLocation: 'output.mp4',
});

Transparent WebM with VP9

To render video with an alpha channel, you must use VP8 or VP9 with the yuva420p pixel format:

await renderMedia({
  composition: MyComp,
  codec: 'vp9',               // Maps to libvpx-vp9
  pixelFormat: 'yuva420p',   // Enables alpha channel
  outputLocation: 'transparent.webm',
});

Professional ProRes Editing Format

For high-quality intermediate files compatible with professional video editors:

await renderMedia({
  composition: MyComp,
  codec: 'prores',            // Maps to prores_ks
  pixelFormat: 'yuv422p',    // 4:2:2 chroma subsampling
  outputLocation: 'master.mov',
});

Error Handling for Invalid Combinations

Attempting unsupported combinations results in immediate validation errors:

await renderMedia({
  composition: MyComp,
  codec: 'h264',
  pixelFormat: 'yuva420p',   // ❌ Not supported for H.264
  outputLocation: 'out.mp4',
});
// Throws: TypeError: Pixel format was set to 'yuva420p' but codec h264 does not support it.

How Remotion Translates Settings to FFmpeg

Remotion does not encode video directly; it orchestrates FFmpeg processes. Your configuration options are mapped to FFmpeg command-line arguments through several translation layers.

Encoder Mapping and Hardware Acceleration

The function getCodecName in packages/renderer/src/get-codec-name.ts translates Remotion codec identifiers into FFmpeg encoder names:

• 'h264' → libx264 (or h264_nvenc / h264_qsv for hardware acceleration)
• 'vp9' → libvpx-vp9
• 'prores' → prores_ks

This function also determines whether hardware acceleration is available based on the codec and system capabilities.

FFmpeg Argument Generation

The generateFfmpegArgs function in packages/renderer/src/ffmpeg-args.ts constructs the final command array:

1. Pixel format insertion: Adds -pix_fmt <pixelFormat> to the arguments.
2. Alpha channel handling: When pixelFormat is 'yuva420p' (used for transparent WebM), it automatically injects -auto-alt-ref 0 to prevent FFmpeg from dropping the alpha channel during encoding.

These arguments are then passed to internalStitchFramesToVideo, which spawns the FFmpeg process that produces your final video file.

Common Configuration Patterns

Transparent WebM with VP9 and YUVA420P

For web animations requiring transparency, combine VP9 with the YUVA420P pixel format. According to the source code in ffmpeg-args.ts, Remotion automatically adds the -auto-alt-ref 0 flag required to preserve the alpha channel in WebM containers.

await renderMedia({
  codec: 'vp9',
  pixelFormat: 'yuva420p',
  composition: MyComp,
  outputLocation: 'animation.webm',
});

Professional Editing with ProRes and YUV422P

For delivering to professional video editors or broadcast workflows, use ProRes 422. The yuv422p pixel format provides higher chroma fidelity than the default 420p, and Remotion maps this to the prores_ks FFmpeg encoder.

await renderMedia({
  codec: 'prores',
  pixelFormat: 'yuv422p',
  composition: MyComp,
  outputLocation: 'master.mov',
});

Summary

• Configure output settings in Remotion by passing codec and pixelFormat to renderMedia() in packages/renderer/src/render-media.ts.
• Default values are 'h264' for codec (defined in codec.ts) and 'yuv420p' for pixel format (defined in pixel-format.ts).
• Validation occurs via validateSelectedPixelFormatAndCodecCombination in pixel-format.ts, which prevents unsupported combinations like H.264 with alpha channels.
• FFmpeg translation happens through getCodecName (encoder selection) and generateFfmpegArgs (command-line construction), with special handling for transparent WebM via -auto-alt-ref 0.

Frequently Asked Questions

What is the default codec and pixel format in Remotion?

If you do not specify output settings, Remotion uses h264 as the default codec and yuv420p as the default pixel format. These constants are defined in packages/renderer/src/codec.ts and packages/renderer/src/pixel-format.ts respectively, ensuring broad compatibility with standard MP4 players.

Can I use H.264 with an alpha channel?

No. The H.264 codec does not support alpha transparency. If you need transparent video, you must use the vp8 or vp9 codec combined with the yuva420p pixel format. Remotion's validation logic in pixel-format.ts will throw a TypeError if you attempt to combine h264 with yuva420p.

How do I enable hardware acceleration when configuring codecs?

Hardware acceleration is handled automatically by the getCodecName function in packages/renderer/src/get-codec-name.ts. When you specify a codec like h264 or h265, Remotion detects available hardware encoders such as h264_nvenc (NVIDIA) or h264_qsv (Intel Quick Sync) and uses them when possible. You do not need to manually specify encoder names; simply use the standard codec identifiers.

What happens if I specify an invalid codec and pixel format combination?

Remotion validates your configuration before starting the render process. The function validateSelectedPixelFormatAndCodecCombination in packages/renderer/src/pixel-format.ts checks compatibility. If you provide an unsupported pair—such as prores with yuva420p—the function throws a TypeError with a descriptive message explaining which pixel formats are valid for your chosen codec.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}