What causes "Unknown sample format ${boxFormat}" in remotion-dev/remotion?

Identify the unknown track: `ffprobe -show_streams input.mp4` and look for non-video/non-audio stream types.

remotion-dev/remotion · warning · Error

Unknown sample format ${boxFormat}

Error message

Unknown sample format ${boxFormat}

What it means

After the video and audio sample-entry branches, the parser throws if the box format (FourCC) was neither recognized as a known video nor audio tag. This is a coverage gap: the file contains a sample entry for a codec the parser does not know about (e.g. a subtitle, hint, or metadata track, or an exotic codec).

Source

Thrown at packages/media-parser/src/containers/iso-base-media/stsd/samples.ts:366

				size: boxSize,
				type: 'video',
				width,
				height,
				horizontalResolutionPpi: horizontalResolution,
				verticalResolutionPpi: verticalResolution,
				spacialQuality,
				temporalQuality,
				dataSize,
				frameCountPerSample,
				compressorName,
				depth,
				colorTableId,
				descriptors: children,
			},
		};
	}

	throw new Error(`Unknown sample format ${boxFormat}`);
};

export const parseIsoFormatBoxes = async ({
	maxBytes,
	logLevel,
	iterator,
	contentLength,
}: {
	maxBytes: number;
	logLevel: MediaParserLogLevel;
	iterator: BufferIterator;
	contentLength: number;
}): Promise<Sample[]> => {
	const samples: Sample[] = [];
	const initialOffset = iterator.counter.getOffset();

	while (
		iterator.bytesRemaining() > 0 &&

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Identify the unknown track: `ffprobe -show_streams input.mp4` and look for non-video/non-audio stream types.
Strip the unrecognized track: `ffmpeg -i input.mp4 -map 0:v -map 0:a cleaned.mp4` to keep only video and audio.
If the file is valid and you need that codec, request upstream support for that FourCC.
Verify you are passing the correct parser entry point; a non-ISOBMFF file fed to this parser would produce unknown box formats.

Example fix

// before: file with subtitle/hint track throws 'Unknown sample format tx3g'
ffmpeg -i input.mp4 -map 0:v:0 -map 0:a:0 -c copy video_audio_only.mp4
// after: only video+audio tracks remain, parser succeeds

Defensive patterns

Strategy: validation

Validate before calling

// List sample-entry FourCCs with ffprobe and filter out unsupported tracks
// ffprobe -show_entries stream=codec_name,codec_tag_string -of json input.mp4
// Then strip non-video/non-audio tracks:
// ffmpeg -i input.mp4 -map 0:v -map 0:a -c copy cleaned.mp4

Type guard

const SUPPORTED_FOURCC = new Set(['avc1','avc3','hev1','hvc1','mp4a','ac-3','ec-3','opus','Opus','vp09','av01']);
function isSupportedSampleFormat(fourcc: string): boolean {
  return SUPPORTED_FOURCC.has(fourcc);
}

Try / catch

try {
  await parseMedia({src, fields: {dimensions: true}});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unknown sample format')) {
    // strip unsupported tracks with ffmpeg and retry
  } else throw err;
}

Prevention

Strip subtitle/hint/metadata tracks with ffmpeg -map before parsing.
Maintain a whitelist of supported codec FourCCs for your input pipeline.
Validate uploads with ffprobe and reject or normalize files with unknown codecs.

When it happens

Trigger: parseIsoFormatBox reaches the end with a boxFormat not present in videoTags or audioTags — e.g. 'text', 'tx3g', 'sbtl', 'wma ', or a proprietary codec FourCC.

Common situations: MP4 files containing subtitle tracks (tx3g), timed metadata, hint tracks for streaming, or files authored by tools that emit non-standard FourCCs. Also common with screen recordings that embed system audio as an unusual codec.

Related errors

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