remotion-dev/remotion · warning · Error

@remotion/media-parser cannot handle the private data for VP

Error message

@remotion/media-parser cannot handle the private data for VP9. Do you have an example file you could send so we can implement it? https://remotion.dev/report

What it means

Thrown by `getMatroskaVideoCodecString` (make-track.ts:93) specifically for a `V_VP9` track that carries CodecPrivate data. The parser assumes VP9 needs no private data (codec string is hard-coded to `vp09.00.10.08`) and refuses to silently drop or misinterpret private data it cannot parse, asking instead for a real-world sample.

Source

Thrown at packages/media-parser/src/containers/webm/make-track.ts:93

	throw new Error(`Unknown codec: ${codec.value}`);
};

const getMatroskaVideoCodecString = ({
	track,
	codecSegment: codec,
}: {
	track: TrackEntry;
	codecSegment: CodecIdSegment;
}): string | null => {
	if (codec.value === 'V_VP8') {
		return 'vp8';
	}

	if (codec.value === 'V_VP9') {
		const priv = getPrivateData(track);
		if (priv) {
			throw new Error(
				'@remotion/media-parser cannot handle the private data for VP9. Do you have an example file you could send so we can implement it? https://remotion.dev/report',
			);
		}

		return 'vp09.00.10.08';
	}

	if (codec.value === 'V_MPEG4/ISO/AVC') {
		const priv = getPrivateData(track);
		if (priv) {
			return `avc1.${priv[1].toString(16).padStart(2, '0')}${priv[2].toString(16).padStart(2, '0')}${priv[3].toString(16).padStart(2, '0')}`;
		}

		return NO_CODEC_PRIVATE_SHOULD_BE_DERIVED_FROM_SPS;
	}

	if (codec.value === 'V_MPEGH/ISO/HEVC') {
		const priv = getPrivateData(track);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Report the file to Remotion at https://remotion.dev/report so VP9-with-private-data handling can be implemented.
2. Re-mux to strip the extradata: `ffmpeg -i in.webm -c:v copy -bitexact out.webm` (or re-encode to plain VP9).
3. Transcode to AV1 or H.264 if you need guaranteed parseability today: `ffmpeg -i in.webm -c:v libx264 out.mkv`.
4. Catch the error and treat the asset as unsupported until upstream adds handling.

try {
  await parseMedia({ src, fields: { tracks: true } });
} catch (err) {
  if (err instanceof Error && err.message.includes('cannot handle the private data for VP9')) {
    // Known limitation — strip extradata or transcode, then retry.
    console.warn('VP9 with CodecPrivate is unsupported; remux without extradata.');
    return null;
  }
  throw err;
}

When it happens

Trigger: Parsing a VP9 WebM/MKV track whose TrackEntry contains a non-empty `CodecPrivate` element. The VP9 spec generally does not require CodecPrivate, so its presence is unusual and unhandled.

Common situations: Experimental or non-standard VP9 muxers; files passed through tools that attach extradata; rare edge cases. The error message is deliberately a feature request rather than a hard failure of design.

Related errors

• Unknown audio format
• Unsupported AVCC version ${confVersion}
• Expected av1 private data to be version 1
• Expected av1 private data to be version 1, got ${version}
• Expected vorbis private data version 2

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/e728f358ecc81a3d. Report an issue: GitHub.