remotion-dev/remotion · error · Error

Unknown MP3 header

Error message

Unknown MP3 header 

What it means

Thrown by `parseMp3` when the first three bytes of an MP3 data chunk do not match any recognized signature: not `0x54 0x41 0x47` (ID3v1 `TAG`), not `0x49 0x44 0x33` (ID3v2/v3), and not `0xFF` (MPEG frame sync). The parser treats this as an unrecognized/corrupt MP3 header.

Source

Thrown at packages/media-parser/src/containers/mp3/parse-mp3.ts:48

	if (bytes[0] === 0x54 && bytes[1] === 0x41 && bytes[2] === 0x47) {
		parseID3V1(iterator);
		return null;
	}

	// ID3 v2 or v3
	if (bytes[0] === 0x49 && bytes[1] === 0x44 && bytes[2] === 0x33) {
		parseId3({state});
		return null;
	}

	if (bytes[0] === 0xff) {
		await parseMpegHeader({
			state,
		});
		return null;
	}

	throw new Error('Unknown MP3 header ' + JSON.stringify(bytes));
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Verify the file is genuinely an MP3 file using `ffprobe -i file.mp3` or checking the magic bytes.
2. Re-download or re-encode the file if it may be corrupt.
3. If the file is a different format, use the appropriate parser or convert it to MP3.
4. Inspect the first few bytes with a hex editor to confirm they start with `FF FB`, `FF F3`, `FF FA`, or `49 44 33` (ID3).

Example fix

# check the file is valid MP3
ffprobe -i input.mp3

# if not, convert to MP3
ffmpeg -i input.wav -codec:a libmp3lame output.mp3

// Verify file starts with valid MP3 magic bytes
async function isLikelyMp3(file: File): Promise<boolean> {
  const header = new Uint8Array(await file.slice(0, 3).arrayBuffer());
  // ID3v2
  if (header[0] === 0x49 && header[1] === 0x44 && header[2] === 0x33) return true;
  // ID3v1 (TAG)
  if (header[0] === 0x54 && header[1] === 0x41 && header[2] === 0x47) return true;
  // MPEG frame sync
  if (header[0] === 0xff) return true;
  return false;
}

try {
  await parseMedia({src, fields: {durationInSeconds: true}});
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown MP3 header')) {
    console.error('The file does not contain valid MP3 data.');
  }
  throw e;
}

When it happens

Trigger: The MP3 parser encounters a data region starting with bytes that match none of the known MP3 signatures. This happens when the file is not actually MP3, is corrupt, or has garbage data between valid frames.

Common situations: Passing a non-MP3 file (e.g., WAV, FLAC, OGG) that was misidentified as MP3. Corrupt or partially-downloaded MP3 files. Files with extraneous padding or junk bytes. The parser was pointed at an MP3 stream mid-way through non-audio data.

Related errors

• Reserved sampling frequency
• Invalid sampling frequency for MPEG version:
• Expected 1
• Expected MPEG Version 1 or 2
• Expected Layer I, II or III

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