{"record":{"id":"f2e6c870cd8781a3","repo":"remotion-dev/remotion","slug":"the-primary-audio-track-must-be-transcoded-to-opus","errorCode":null,"errorMessage":"The primary audio track must be transcoded to Opus, but this browser does not support a compatible Opus encoder.","messagePattern":"The primary audio track must be transcoded to Opus, but this browser does not support a compatible Opus encoder\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/video-matting/src/prepare-audio.ts","lineNumber":318,"sourceCode":"\n\tif (\n\t\t!(await canEncodeAudio('opus', {\n\t\t\tnumberOfChannels: outputNumberOfChannels,\n\t\t\tsampleRate: outputSampleRate,\n\t\t\tquality,\n\t\t}))\n\t) {\n\t\toutputNumberOfChannels = Math.min(originalNumberOfChannels, 2);\n\t\toutputSampleRate = 48_000;\n\n\t\tif (\n\t\t\t!(await canEncodeAudio('opus', {\n\t\t\t\tnumberOfChannels: outputNumberOfChannels,\n\t\t\t\tsampleRate: outputSampleRate,\n\t\t\t\tquality,\n\t\t\t}))\n\t\t) {\n\t\t\tthrow new Error(\n\t\t\t\t'The primary audio track must be transcoded to Opus, but this browser ' +\n\t\t\t\t\t'does not support a compatible Opus encoder.',\n\t\t\t);\n\t\t}\n\t}\n\n\tconst sampleSources = outputs.map((output) => {\n\t\tconst source = new AudioSampleSource({\n\t\t\tcodec: 'opus',\n\t\t\tquality,\n\t\t\ttransform: {\n\t\t\t\tnumberOfChannels:\n\t\t\t\t\toutputNumberOfChannels === originalNumberOfChannels\n\t\t\t\t\t\t? undefined\n\t\t\t\t\t\t: outputNumberOfChannels,\n\t\t\t\tsampleRate:\n\t\t\t\t\toutputSampleRate === originalSampleRate\n\t\t\t\t\t\t? undefined","sourceCodeStart":300,"sourceCodeEnd":336,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/video-matting/src/prepare-audio.ts#L300-L336","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Update to a recent Chromium-based browser that supports the Opus AudioEncoder.","Downmix the audio to stereo/mono and use a standard sample rate (48kHz) before transcoding.","Pre-encode the input audio to Opus externally (ffmpeg) and pass copy/transcode-skip options if available.","Feature-detect with canEncodeAudio('opus', config) up front and degrade gracefully."],"exampleFix":"// before\nconst audio = await prepareAudio({input, quality: 10}); // unsupported combo\n// after\nconst ok = await canEncodeAudio('opus', {numberOfChannels: 2, sampleRate: 48000, quality: 0.8});\nif (!ok) throw new Error('Opus encoding unavailable in this browser');\nconst audio = await prepareAudio({input, quality: 0.8});","handlingStrategy":"fallback","validationCode":"const supported = await canEncodeAudio('opus', {numberOfChannels: 2, sampleRate: 48000, quality: 0.8});\nif (!supported) throw new Error('Opus encoder unavailable; pre-transcode audio');","typeGuard":"null","tryCatchPattern":"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; }","preventionTips":["Check canEncodeAudio('opus', ...) at app startup","Downmix to stereo 48kHz before transcoding","Use up-to-date Chromium browsers","Offer a server-side transcode path for unsupported browsers"],"tags":["codec","opus","webcodecs","browser-compatibility"],"backgroundTag":"unsupported-operation","analyzedSha":"b2f4e34732f3c6c222ea029413e22dc402218cd7","analyzedAt":"2026-09-09T13:27:51.281Z","contentChangedAt":"2026-09-09T13:27:51.281Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}