MOV sample tables

The sample table atom, stbl, inside minf, indexes every sample of a track: what it is, when it plays, how big it is and where it lies in the file. Samples are grouped into chunks; a chunk is a run of samples stored together. Sample and chunk numbers start at 1. Every table atom below starts with a one-byte version (0) and three bytes of flags (0) at offset 8.

stbl

A track that references data must have stsd, stsz, stsc and stco (or co64). All the tables describe the same number of samples.

Child	Meaning
`stsd`	Sample descriptions: the codec and its settings.
`stts`	Time-to-sample: decode durations.
`ctts`	Composition offsets, for frames stored out of display order.
`cslg`	Composition shift least greatest: summary of the offsets.
`stss`	Sync samples (key frames). Absent means every sample is a sync sample.
`stps`	Partial sync samples.
`stsc`	Sample-to-chunk.
`stsz`	Sample sizes.
`stco`	32-bit chunk offsets.
`co64`	64-bit chunk offsets, used instead of `stco` only when an offset needs more than 32 bits.
`sdtp`	Sample dependency flags.
`stsh`	Shadow sync. Reserved for future use.
`sgpd`	Sample group description.
`sbgp`	Sample-to-group.
`csgm`	Compact sample-to-group (registered for QuickTime with the MP4 Registration Authority; the compact form defined in ISO/IEC 14496-12).

stsd

Offset	Size	Name	Meaning
12	4	number of entries	Sample descriptions that follow; at least 1.
16	varies	sample description table	The descriptions, each starting with the common header below.

Offset	Size	Name	Meaning
0	4	sample description size	Bytes in this description. Some descriptions end with four zero bytes counted in this size; always step by the size.
4	4	data format	The codec or media format, such as `avc1` or `lpcm`. Codes are listed on Data types and codes.
8	6	reserved	0.
14	2	data reference index	1-based index into `dref`: where these samples are stored.
16	varies	media-specific data	See Video sample descriptions for video. Movie media uses only this common header.

stts

Offset	Size	Name	Meaning
12	4	number of entries	Entries that follow.
16	8 × n	time-to-sample table	Pairs of sample count (uint32: consecutive samples with the same duration) and sample duration (uint32, in the media time scale).

The decode time of sample n+1 is the decode time of sample n plus its duration, starting from 0; the sum of all durations is the media’s length before the edit list. Constant frame rate needs one entry. Entries (4, 3), (2, 1), (3, 2) describe nine samples: four of duration 3, two of 1 and three of 2.

ctts

Offset	Size	Name	Meaning
12	4	entry count	Entries that follow.
16	8 × n	composition offset table	Pairs of sample count (uint32) and composition offset (int32).

Composition (display) time = decode time + offset; offsets may be negative. The atom is present only when frames are stored out of display order. The last displayed frame uses its decode duration as its display duration.

cslg

Offset	Size	Name	Meaning
12	4	compositionOffsetToDisplayOffsetShift	Shift that makes all display offsets non-negative.
16	4	leastDisplayOffset	Smallest composition offset.
20	4	greatestDisplayOffset	Largest composition offset.
24	4	displayStartTime	int32: display time of the first sample shown.
28	4	displayEndTime	int32: display time at the end of the last sample.

Lets a reader know the decode delay needed without scanning ctts. Apple lists the first three fields as unsigned; in ISO/IEC 14496-12 all five are signed, and the least offset is often negative, so read them as int32.

stss and stps

Offset	Size	Name	Meaning
12	4	number of entries	Entries that follow.
16	4 × n	sample numbers	uint32 sample numbers in strictly increasing order.

stss lists the sync samples, key frames that decode on their own. stps has the same layout and lists partial sync samples, which are not full sync samples and so are not listed in stss.

stsc

Offset	Size	Name	Meaning
12	4	number of entries	Entries that follow.
16	12 × n	sample-to-chunk table	first chunk (uint32), samples per chunk (uint32), sample description ID (uint32, 1-based index into `stsd`).

Each entry covers chunks from its first chunk up to the next entry’s first chunk (or the last chunk). Entries (1, 3, 23), (3, 1, 23), (5, 1, 24) mean chunks 1 and 2 hold three samples each, chunks 3 and 4 one each, and chunks from 5 on one each using description 24.

stsz

Offset	Size	Name	Meaning
12	4	sample size	The size of every sample when they are all equal; 0 when sizes vary and the table follows.
16	4	number of entries	The number of samples in the track.
20	4 × n	sample size table	uint32 size of each sample, present only when the sample size is 0.

For uncompressed sound described by a version 0 sound description, the sample size is typically 1 and counts audio frames, not bytes.

stco and co64

Offset	Size	Name	Meaning
12	4	number of entries	One per chunk.
16	4 × n or 8 × n	chunk offset table	uint32 (`stco`) or uint64 (`co64`) offset of each chunk from the start of the file (or of the referenced data), not from `mdat`.

sdtp

After version and flags, one byte per sample, as many as stsz counts:

Bit	Constant	Meaning
0x80	–	Reserved.
0x40	`kQTSampleDependency_EarlierDisplayTimesAllowed`	Later samples may display before this one.
0x20	`kQTSampleDependency_SampleDoesNotDependOnOthers`	An I picture.
0x10	`kQTSampleDependency_SampleDependsOnOthers`	Not an I picture.
0x08	`kQTSampleDependency_NoOtherSampleDependsOnThisSample`	Droppable.
0x04	`kQTSampleDependency_OtherSamplesDependOnThisSample`	Other samples need this one.
0x02	`kQTSampleDependency_ThereIsNoRedundantCodingInThisSample`	No redundant coding.
0x01	`kQTSampleDependency_ThereIsRedundantCodingInThisSample`	Has redundant coding.

The combinations 0x30, 0xC0 and 0x03 are reserved.

sgpd and sbgp

Sample groups, as in ISO/IEC 14496-12. A track has at most one of each per grouping type, and the two are paired by that type. Apple uses them for AAC encoder delay: one pair with grouping type roll, whose single entry is the roll distance, normally −1 (one AAC packet of 1024 samples must be decoded before each packet). When the pair is present, the edit list’s media time and duration exclude the encoder delay; without it, readers assume the classic implicit delay of 2112 samples.

Offset	Size	Name	Meaning (`sgpd`)
8	1	version	1.
9	3	flags	0.
12	4	grouping type	For example `roll`.
16	4	default length	Length of each entry; 2 for `roll`.
20	4	entry count	Entries that follow; 1 for AAC.
24	varies	payload data	For `roll`, an int16 roll distance per entry.

Offset	Size	Name	Meaning (`sbgp`)
8	1	version	0.
9	3	flags	0.
12	4	grouping type	Matches the `sgpd`.
16	4	entry count	Entries that follow.
20	8 × n	table data	sample count (uint32: a run of samples) and group description index (uint32: 1-based entry in `sgpd`, or 0 for no group).

Apple’s page also lists a 4-byte default length after the grouping type in sbgp. That field is not in ISO/IEC 14496-12’s sample-to-group box and readers such as FFmpeg do not expect it, so the layout above follows ISO. (ISO’s version 1 adds a 4-byte grouping type parameter after the grouping type.)

Finding a sample

Convert the movie time to media time with the edit list and the two time scales.
Walk stts to find the sample number at that decode time (with ctts for display time).
To start decoding, step back to the nearest earlier sample in stss.
Use stsc to find the chunk holding the sample and its position in the chunk, and the sample description to use.
Take the chunk’s offset from stco or co64 and add the sizes, from stsz, of the samples before it in that chunk.

.MOV File Format – Sample tables