remotion-dev/remotion · error

Expected stsc box in trak box

Error message

Expected stsc box in trak box

What it means

Thrown by getGroupedSamplesPositionsFromMp4 when the supplied TrakBox has no stsc (sample-to-chunk) box. stsc maps samples to chunks and is mandatory for any sample-addressable MP4 track; its absence means the trak is structurally incomplete and sample positions cannot be computed.

Source

Thrown at packages/media-parser/src/get-sample-positions-from-mp4.ts:26

	getStszBox,
} from './containers/iso-base-media/traversal';
import type {SamplePosition} from './get-sample-positions';

// example video: mehmet.mov

export const getGroupedSamplesPositionsFromMp4 = ({
	trakBox,
	bigEndian,
}: {
	trakBox: TrakBox;
	bigEndian: boolean;
}): SamplePosition[] => {
	const stscBox = getStscBox(trakBox);
	const stszBox = getStszBox(trakBox);
	const stcoBox = getStcoBox(trakBox);

	if (!stscBox) {
		throw new Error('Expected stsc box in trak box');
	}

	if (!stcoBox) {
		throw new Error('Expected stco box in trak box');
	}

	if (!stszBox) {
		throw new Error('Expected stsz box in trak box');
	}

	if (stszBox.countType !== 'fixed') {
		throw new Error('Only supporting fixed count type in stsz box');
	}

	const samples: SamplePosition[] = [];

	let timestamp = 0;

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Re-mux the file with ffmpeg (ffmpeg -i in.mp4 -c copy out.mp4) to regenerate sample tables.
2. Filter to traks that actually carry media samples (skip hint/tmcd traks) before computing positions.
3. Wrap the call in try/catch and treat the trak as unsampleable when stsc is missing.

Example fix

// before
const positions = getGroupedSamplesPositionsFromMp4({trakBox, bigEndian});

// after
let positions = [];
try {
  positions = getGroupedSamplesPositionsFromMp4({trakBox, bigEndian});
} catch (err) {
  console.warn('trak missing stsc, skipping', err);
}

import {getStscBox} from '@remotion/media-parser/containers/iso-base-media/traversal';
if (getStscBox(trakBox)) { getGroupedSamplesPositionsFromMp4({trakBox, bigEndian}); }

const hasStsc = (trak: TrakBox): boolean => getStscBox(trak) !== null;

try { getGroupedSamplesPositionsFromMp4({trakBox, bigEndian}); } catch (e) { if (e.message === 'Expected stsc box in trak box') { /* skip trak */ } else throw e; }

When it happens

Trigger: Calling getGroupedSamplesPositionsFromMp4 on a TrakBox whose stbl lacks stsc. Truncated MP4s, partially written files, or traks produced by a buggy muxer that omits stsc.

Common situations: Processing partially downloaded or repaired MP4 files. Handling fragmented MP4 where the sample tables live in moof and the initial moov stsc is sparse. Reading hint or metadata traks that lack sample tables.

Related errors

• Expected stco box in trak box
• Expected stsz box in trak box
• Expected stsz box in trak box
• Expected stco box in trak box
• Expected stsc box in trak box

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