Remotion Pixel Formats: Complete Guide to YUV and Alpha Channel Support

Remotion supports eight FFmpeg-compatible pixel formats including yuv420p (default), alpha-capable yuva420p, and 10-bit options like yuv444p10le, with specific codec restrictions enforced through validation functions.

Remotion's rendering pipeline relies on FFmpeg-compatible pixel formats to encode video output. The remotion-dev/remotion repository defines these formats in packages/renderer/src/pixel-format.ts, providing a type-safe system for configuring color space, alpha transparency, and bit depth.

Supported Pixel Formats in Remotion

The core list of valid pixel formats is exported as validPixelFormats from packages/renderer/src/pixel-format.ts. These YUV-based formats cover standard definition, high fidelity, and transparency use cases:

• yuv420p — The default pixel format (DEFAULT_PIXEL_FORMAT) used when no format is specified. Offers good compression with 4:2:0 chroma subsampling.
• yuva420p — Adds an alpha channel for transparency; only supported by VP8 and VP9 codecs.
• yuv422p — 4:2:2 chroma subsampling for higher color fidelity than 4:2:0.
• yuv444p — Full chroma resolution (4:4:4) with no subsampling.
• yuv420p10le — 10-bit depth, little-endian, with 4:2:0 subsampling.
• yuv422p10le — 10-bit depth with 4:2:2 subsampling.
• yuv444p10le — 10-bit depth with full chroma resolution.
• yuva444p10le — 10-bit depth with alpha channel support.

Codec-Specific Pixel Format Restrictions

Not every codec supports every pixel format. Remotion provides the validPixelFormatsForCodec helper function to filter available formats based on the selected codec (vp8, vp9, h264, h265, etc.).

The logic implemented in packages/renderer/src/pixel-format.ts follows these rules:

• VP8 and VP9 — Support all eight pixel formats including alpha-capable formats (yuva420p, yuva444p10le).
• H.264, H.265, and other codecs — Do not support alpha channels. The yuva420p format is filtered out from the available options.

export const validPixelFormatsForCodec = (codec: Codec) => {
  if (codec === 'vp8' || codec === 'vp9') {
    return validPixelFormats;
  }
  return validPixelFormats.filter((format) => format !== 'yuva420p');
};

Validating Pixel Format and Codec Combinations

Remotion validates pixel format and codec compatibility at the start of each render job using validateSelectedPixelFormatAndCodecCombination. This function throws a descriptive TypeError if an invalid combination is detected, preventing wasted rendering time.

The validation logic checks:

1. Whether the pixel format exists in validPixelFormats
2. Whether alpha formats (yuva420p) are being used with non-VP8/VP9 codecs

export const validateSelectedPixelFormatAndCodecCombination = (
  pixelFormat: PixelFormat | undefined,
  codec: Codec,
) => {
  if (typeof pixelFormat === 'undefined') {
    return pixelFormat;
  }

  if (!validPixelFormats.includes(pixelFormat)) {
    throw new TypeError(`Value ${pixelFormat} is not valid as a pixel format.`);
  }

  if (pixelFormat !== 'yuva420p') {
    return;
  }

  const validFormats = validPixelFormatsForCodec(codec);

  if (!(validFormats as string[]).includes(pixelFormat)) {
    throw new TypeError(
      `Pixel format was set to 'yuva420p' but codec ${codec} does not support it. Valid pixel formats for codec ${codec} are: ${validFormats.join(
        ', ',
      )}.`,
    );
  }
};

Configuring Pixel Formats in Your Remotion Project

Remotion exposes configuration APIs through packages/cli/src/config/pixel-format.ts. Developers can programmatically set and retrieve the pixel format using setPixelFormat and getPixelFormat.

The configuration system validates inputs against RenderInternals.validPixelFormats before accepting them:

import type {PixelFormat} from '@remotion/renderer';
import {RenderInternals} from '@remotion/renderer';

let currentPixelFormat: PixelFormat = RenderInternals.DEFAULT_PIXEL_FORMAT;

export const setPixelFormat = (format: PixelFormat) => {
  if (!RenderInternals.validPixelFormats.includes(format)) {
    throw new TypeError(`Value ${format} is not valid as a pixel format.`);
  }

  currentPixelFormat = format;
};

export const getPixelFormat = () => currentPixelFormat;

Practical Implementation Examples

Set a high-fidelity 10-bit format before rendering:

import {setPixelFormat, getPixelFormat} from '@remotion/cli';
import {validateSelectedPixelFormatAndCodecCombination} from '@remotion/renderer';

// Configure for 10-bit color depth
setPixelFormat('yuv444p10le');
console.log('Active pixel format:', getPixelFormat());

// Validate against your chosen codec
const codec = 'h265';
validateSelectedPixelFormatAndCodecCombination(getPixelFormat(), codec);
// Validation passes → render can proceed

Enable alpha transparency for web video:

// Alpha only works with VP8 or VP9
setPixelFormat('yuva420p');
validateSelectedPixelFormatAndCodecCombination('yuva420p', 'vp9');
// Successfully configured for transparent video output

Handle validation errors gracefully:

setPixelFormat('yuva420p');

try {
  // This will throw because H.264 doesn't support alpha
  validateSelectedPixelFormatAndCodecCombination('yuva420p', 'h264');
} catch (error) {
  console.error('Invalid configuration:', error.message);
  // Output: Pixel format was set to 'yuva420p' but codec h264 does not support it...
}

Summary

• Remotion supports eight FFmpeg-compatible pixel formats defined in packages/renderer/src/pixel-format.ts, ranging from standard yuv420p to 10-bit formats like yuv444p10le.
• yuv420p is the default format, while yuva420p and yuva444p10le provide alpha channels for transparency.
• VP8 and VP9 codecs support all formats including alpha; H.264 and H.265 exclude alpha formats.
• Use setPixelFormat and getPixelFormat from @remotion/cli to configure formats programmatically.
• Always validate combinations using validateSelectedPixelFormatAndCodecCombination to catch incompatible settings before rendering begins.

Frequently Asked Questions

What is the default pixel format in Remotion?

The default pixel format is yuv420p, defined as DEFAULT_PIXEL_FORMAT in packages/renderer/src/pixel-format.ts. This format uses 4:2:0 chroma subsampling and provides excellent compatibility across all supported codecs including H.264, H.265, VP8, and VP9. If you do not explicitly call setPixelFormat(), Remotion automatically uses this default for all renders.

Can I use alpha transparency with H.264 in Remotion?

No, alpha transparency is not supported with H.264 in Remotion. The alpha-capable formats yuva420p and yuva444p10le are only compatible with VP8 and VP9 codecs. If you attempt to use yuva420p with H.264, the validateSelectedPixelFormatAndCodecCombination function throws a TypeError explaining that the codec does not support the selected format. For transparent video in Remotion, use VP9 with yuva420p or yuva444p10le.

How do I enable 10-bit color depth in Remotion?

To enable 10-bit color depth, call setPixelFormat() with one of the 10-bit options before starting your render: yuv420p10le, yuv422p10le, yuv444p10le, or yuva444p10le (alpha + 10-bit). These formats are defined in packages/renderer/src/pixel-format.ts and are supported by all Remotion codecs including H.265, which benefits significantly from 10-bit depth for high-dynamic-range content. Remember that 10-bit formats increase file size and processing requirements compared to 8-bit formats like yuv420p.

What happens if I select an incompatible pixel format and codec?

Remotion throws a descriptive TypeError during the validation phase before rendering begins. The validateSelectedPixelFormatAndCodecCombination function checks your selected format against the codec's capabilities using validPixelFormatsForCodec. If you select an incompatible combination—such as yuva420p with H.264—the error message explicitly lists the valid pixel formats for your chosen codec, allowing you to correct the configuration immediately without wasting render time.

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