What causes "Reserved sampling frequency" in remotion-dev/remotion?

Verify the file is a valid MP3 using `ffprobe -i file.mp3`.

remotion-dev/remotion · error · Error

Reserved sampling frequency

Error message

Reserved sampling frequency

What it means

Thrown by `getSamplingFrequency` when the 2-bit sampling frequency index read from the MPEG frame header is `0b11`, which the MPEG specification marks as 'reserved' (invalid). The sampling frequency table in `parse-packet-header.ts:17-22` maps `0b11` to `'reserved'` for both MPEG1 and MPEG2.

Source

Thrown at packages/media-parser/src/containers/mp3/parse-packet-header.ts:27

function getSamplingFrequency({
	bits,
	mpegVersion,
}: {
	bits: number;
	mpegVersion: MpegVersion;
}): number {
	const samplingTable: Record<number, Record<string, number | 'reserved'>> = {
		0b00: {MPEG1: 44100, MPEG2: 22050},
		0b01: {MPEG1: 48000, MPEG2: 24000},
		0b10: {MPEG1: 32000, MPEG2: 16000},
		0b11: {MPEG1: 'reserved', MPEG2: 'reserved'},
	};

	const key = `MPEG${mpegVersion}`;
	const value = samplingTable[bits][key];
	if (value === 'reserved') {
		throw new Error('Reserved sampling frequency');
	}

	if (!value) {
		throw new Error(
			'Invalid sampling frequency for MPEG version: ' +
				JSON.stringify({bits, version: mpegVersion}),
		);
	}

	return value;
}

function getBitrateKB({
	bits,
	mpegVersion,
	level,
}: {
	bits: number;

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Verify the file is a valid MP3 using `ffprobe -i file.mp3`.
Re-download or re-encode the file if corruption is suspected.
If the file is not MP3, use the correct parser or convert it.
Use try-catch around `parseMedia` to handle corrupt files gracefully.

Example fix

# validate the MP3 file
ffprobe -i input.mp3 2>&1 | grep -i 'stream'

# re-encode if corrupt
ffmpeg -i input.mp3 -codec:a libmp3lame output.mp3

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate MP3 frame header integrity
async function hasValidFrameHeaders(file: File): Promise<boolean> {
  try {
    const buf = await file.slice(0, 4).arrayBuffer();
    const bytes = new Uint8Array(buf);
    // Skip ID3 if present; otherwise check sync word
    if (bytes[0] !== 0xff) {
      // might have ID3 - that's fine, deeper validation needed
      return true;
    }
    return true; // deeper validation requires parsing bit fields
  } catch {
    return false;
  }
}

Try / catch

try {
  await parseMedia({src, fields: {durationInSeconds: true}});
} catch (e) {
  if (e instanceof Error && e.message === 'Reserved sampling frequency') {
    console.error('The MP3 frame header contains a reserved (invalid) sampling frequency.');
  }
  throw e;
}

Prevention

Validate MP3 files with ffprobe -v error before parsing.
Re-encode files from a known-good source if frame headers are corrupt.
Check for partial downloads or storage corruption.
Use try-catch around parseMedia for untrusted audio files.

When it happens

Trigger: While parsing an MPEG audio frame header in `innerParseMp3PacketHeader`, the 2-bit `samplingFrequencyIndex` (read at line 227) is `0b11`, triggering the reserved-value check at line 26-28.

Common situations: Corrupt MP3 frame headers where the sampling frequency bits are damaged. Files that are not actually MPEG audio but were misidentified. Random data being interpreted as an MPEG frame. Partially-downloaded or truncated files.

Related errors

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