remotion-dev/remotion · warning · Error

Expected sampleDescriptionIndex to be 1, but got ${sampleDes

Error message

Expected sampleDescriptionIndex to be 1, but got ${sampleDescriptionIndex}

What it means

The STSC parser only accepts entries whose sampleDescriptionIndex equals 1. The spec permits multiple sample descriptions, but this parser assumes a single description per track and throws when sampleDescriptionIndex != 1. This is a real parser limitation, not necessarily corruption.

Source

Thrown at packages/media-parser/src/containers/iso-base-media/stsd/stsc.ts:37

	offset: number;
	size: number;
}): StscBox => {
	const version = iterator.getUint8();
	if (version !== 0) {
		throw new Error(`Unsupported STSD version ${version}`);
	}

	const flags = iterator.getSlice(3);
	const entryCount = iterator.getUint32();

	const entries: Map<number, number> = new Map();

	for (let i = 0; i < entryCount; i++) {
		const firstChunk = iterator.getUint32();
		const samplesPerChunk = iterator.getUint32();
		const sampleDescriptionIndex = iterator.getUint32();
		if (sampleDescriptionIndex !== 1) {
			throw new Error(
				`Expected sampleDescriptionIndex to be 1, but got ${sampleDescriptionIndex}`,
			);
		}

		entries.set(firstChunk, samplesPerChunk);
	}

	return {
		type: 'stsc-box',
		boxSize: size,
		offset,
		version,
		flags: [...flags],
		entryCount,
		entries,
	};
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Inspect stsc entries: `mp4box -dts input.mp4` or use a hex inspector on the stsc box to see the sampleDescriptionIndex values.
Re-mux with a single sample description: `ffmpeg -i input.mp4 -c copy -movflags +faststart remuxed.mp4`.
If the multi-description layout is intentional (e.g. scalable video), this file is not supported by the current parser — report upstream.
Transcode to collapse to a single description: `ffmpeg -i input.mp4 -c:v libx264 ... out.mp4`.

Example fix

// before: multi-description stsc entries throw
ffmpeg -i input.mp4 -c:v libx264 -c:a aac single_desc.mp4
// after: remuxed with sampleDescriptionIndex=1

Defensive patterns

Strategy: validation

Validate before calling

// Inspect stsc entries with mp4dump before parsing
// mp4dump input.mp4 | grep -A20 stsc → check sample_description_index values
// If any != 1, re-mux with ffmpeg -map 0:v -map 0:a -c copy to collapse descriptions

Type guard

function hasSingleSampleDescription(entries: Array<{sampleDescriptionIndex: number}>): boolean {
  return entries.every((e) => e.sampleDescriptionIndex === 1);
}

Try / catch

try {
  await parseMedia({src, fields: {dimensions: true}});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Expected sampleDescriptionIndex to be 1')) {
    // multi-description file; transcode to single description
  } else throw err;
}

Prevention

Avoid producing files with multiple sample descriptions if you control encoding.
For scalable/multi-layer content, transcode to a single-layer codec before parsing.
Pre-inspect stsc with mp4dump for inputs from untrusted sources.

When it happens

Trigger: An stsc entry has sampleDescriptionIndex other than 1. This happens in MP4 files that legitimately contain multiple sample entries (e.g. layered codecs, scalable streams, or some adaptive content) where chunks reference different descriptions.

Common situations: Files with multiple sample entries in stsd (rare but valid), some encrypted/DRM content with multiple description indices, or files produced by specialized broadcast encoders.

Related errors

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