remotion-dev/remotion · error · Error

The primary audio track must be transcoded to Opus, but this

Error message

The primary audio track must be transcoded to Opus, but this browser does not support a compatible Opus encoder.

What it means

When the audio must be re-encoded to Opus (required for the output container), prepareAudio verifies with canEncodeAudio('opus', {numberOfChannels, sampleRate, quality}) that this browser ships a compatible Opus encoder. If encoding the track's channel count/sample rate is unsupported, it throws so the failure surfaces before packets are processed.

Source

Thrown at packages/video-matting/src/prepare-audio.ts:318

	if (
		!(await canEncodeAudio('opus', {
			numberOfChannels: outputNumberOfChannels,
			sampleRate: outputSampleRate,
			quality,
		}))
	) {
		outputNumberOfChannels = Math.min(originalNumberOfChannels, 2);
		outputSampleRate = 48_000;

		if (
			!(await canEncodeAudio('opus', {
				numberOfChannels: outputNumberOfChannels,
				sampleRate: outputSampleRate,
				quality,
			}))
		) {
			throw new Error(
				'The primary audio track must be transcoded to Opus, but this browser ' +
					'does not support a compatible Opus encoder.',
			);
		}
	}

	const sampleSources = outputs.map((output) => {
		const source = new AudioSampleSource({
			codec: 'opus',
			quality,
			transform: {
				numberOfChannels:
					outputNumberOfChannels === originalNumberOfChannels
						? undefined
						: outputNumberOfChannels,
				sampleRate:
					outputSampleRate === originalSampleRate
						? undefined

View on GitHub (pinned to b2f4e34732)

Solutions

1. Update to a recent Chromium-based browser that supports the Opus AudioEncoder.
2. Downmix the audio to stereo/mono and use a standard sample rate (48kHz) before transcoding.
3. Pre-encode the input audio to Opus externally (ffmpeg) and pass copy/transcode-skip options if available.
4. Feature-detect with canEncodeAudio('opus', config) up front and degrade gracefully.

Example fix

// before
const audio = await prepareAudio({input, quality: 10}); // unsupported combo
// after
const ok = await canEncodeAudio('opus', {numberOfChannels: 2, sampleRate: 48000, quality: 0.8});
if (!ok) throw new Error('Opus encoding unavailable in this browser');
const audio = await prepareAudio({input, quality: 0.8});

const supported = await canEncodeAudio('opus', {numberOfChannels: 2, sampleRate: 48000, quality: 0.8});
if (!supported) throw new Error('Opus encoder unavailable; pre-transcode audio');

null

try { audio = await prepareAudio({input}); } catch (e) { if (e.message.includes('Opus encoder')) { await warnUser('This browser cannot encode Opus; use Chrome or pre-encode the audio.'); return; } throw e; }

When it happens

Trigger: Calling prepareAudio() in a browser where AudioEncoder has no 'opus' support (or rejects the specific numberOfChannels/sampleRate/quality combination), e.g. very old Chrome builds, non-Chromium embedders, or unusual channel counts (e.g. 6-channel surround) that Opus configs reject.

Common situations: Running in an embedded webview without WebCodecs encoders; attempting to transcode 5.1 audio; enterprise browsers with WebCodecs disabled; quality presets outside the supported range.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• The primary audio track uses ${sourceCodec ?? 'an unknown co
• No supported configs
• Could not find video codec
• The audio track cannot be decoded in this browser. Try conve
• The primary video track cannot be decoded.

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/f2e6c870cd8781a3. Report an issue: GitHub.