MOV sound sample descriptions

In a sound track (handler soun), each entry of the stsd atom is a sound description. Its version field, at offset 16, decides the layout: version 0 for plain 8- or 16-bit audio, version 1 (QuickTime 3) for compressed audio, version 2 (QuickTime 7) for high-resolution and multichannel audio. Offsets count from the start of the entry.

Version 0

Offset	Size	Type	Name	Meaning
0	4	uint32	sample description size	Bytes in this entry.
4	4	FourCC	data format	Audio format (table below).
8	6	–	reserved	0.
14	2	uint16	data reference index	1-based index into `dref`.
16	2	int16	version	0, 1 or 2.
18	2	int16	revision level	0.
20	4	uint32	vendor	0.
24	2	int16	number of channels	1 mono, 2 stereo; more are not supported in versions 0 and 1.
26	2	int16	sample size	Bits per uncompressed sample, 8 or 16. Deeper formats write 16 here and use version 1.
28	2	int16	compression ID	0 in version 0. −2 in version 1 means the sample tables are redefined for compressed audio (below).
30	2	int16	packet size	0.
32	4	16.16 fixed	sample rate	Unsigned. The integer part should equal the media time scale. Old files have 22254.5454 or 11127.2727; rates of 65536 and above cannot be stored.

Version 0 is meant for raw or twos audio, one or two channels, 8 or 16 bits, compression ID 0. Such files sometimes give the format as NONE or 0.

Version 1

Version 0’s 36 bytes, then four uint32 fields, then extension atoms.

Offset	Size	Name	Meaning
36	4	samples per packet	Uncompressed frames (one sample from each channel) produced by one compressed frame: the frame’s duration at a time scale equal to the sample rate. Always 1 for uncompressed formats. If 0, the four fields are unused.
40	4	bytes per packet	For uncompressed audio, bytes in one channel’s sample (frame size ÷ channels). Replaces the sample size field, which says 16.
44	4	bytes per frame	Bytes in a frame, compressed or not: bytes per packet × channels.
48	4	bytes per sample	1 for 8-bit audio, 2 in every other case, even for samples wider than 2 bytes.
52	varies	extensions	Atoms (below).

Uncompressed formats other than raw and twos are treated as compressed, so older players can convert them; for these the sample size and bytes per sample fields mean little.

Compression ID −2: redefined sample tables

With compression ID 0, the sample tables of a compressed track pretend to point at 1-byte uncompressed samples inside the compressed frames. With −2 (introduced in QuickTime 4.1 for variable bit rate), each compressed frame is one media sample: stsc and stco point at frames, stsz gives frame sizes and stts their durations. Bytes per packet and bytes per frame are then 0; samples per packet and bytes per sample are set when constant.

Version 2

Keeps the 36-byte start of version 0 with fixed values in the old fields, so older readers skip it safely, then adds new fields. Uncompressed audio uses the format lpcm; compressed audio uses its own code (usually mp4a) with details in extensions.

Offset	Size	Type	Name	Meaning
16	2	int16	version	2.
18	2	int16	revision level	0.
20	4	uint32	vendor	0.
24	2	int16	always3	3.
26	2	int16	always16	16.
28	2	int16	alwaysMinus2	−2 (0xFFFE).
30	2	int16	always0	0.
32	4	uint32	always65536	65536.
36	4	uint32	sizeOfStructOnly	Offset from the start of the entry to the extensions, normally 72.
40	8	float64	audioSampleRate	Sample rate in hertz, so any rate can be stored.
48	4	uint32	numAudioChannels	Number of channels; their assignment is given by a `chan` extension.
52	4	uint32	always7F000000	0x7F000000.
56	4	uint32	constBitsPerChannel	Bits per channel, for uncompressed audio only; otherwise 0.
60	4	uint32	formatSpecificFlags	LPCM flags (below), or codec-specific flags.
64	4	uint32	constBytesPerAudioPacket	Bytes per packet when constant; 0 when variable (as for AAC).
68	4	uint32	constLPCMFramesPerAudioPacket	LPCM frames per packet when constant; 0 when variable.
72	varies	atoms	extensions	Extension atoms.

An LPCM frame is one sample from every channel; an audio packet is a codec’s natural access unit, or one LPCM frame for uncompressed audio. Apple’s field list leaves out audioSampleRate, though its text uses it; the offsets above include it, as QuickTime files and readers such as FFmpeg do.

Flag	Name	Meaning
0x1	`kAudioFormatFlagIsFloat`	Floating-point samples.
0x2	`kAudioFormatFlagIsBigEndian`	Big-endian samples.
0x4	`kAudioFormatFlagIsSignedInteger`	Signed integers (clear means unsigned, for integer samples).
0x8	`kAudioFormatFlagIsPacked`	Samples fill their bytes with no padding bits.
0x10	`kAudioFormatFlagIsAlignedHigh`	When not packed, samples sit in the high bits.
0x20	`kAudioFormatFlagIsNonInterleaved`	Channels are stored one after another, not interleaved.
0x40	`kAudioFormatFlagIsNonMixable`	The audio must not be mixed.
bits 7 to 12	`kLinearPCMFormatFlagsSampleFractionMask`	Number of fractional bits in fixed-point samples (shift 7, mask 0x3F << 7).
0x80000000	`kAudioFormatFlagsAreAllClear`	Explicitly no flags set.

For Apple Lossless the same field holds the source bit depth: 1 for 16-bit, 2 for 20-bit, 3 for 24-bit and 4 for 32-bit source data. The meanings of these Core Audio flags are explained in Apple’s Core Audio reference.

Audio formats

Code	Constant	Format
0x00000000	–	Not specified. Should not be used; treat as `raw` or `twos` by sample size.
`NONE`	`kSoundNotCompressed`	The same: treat as `raw` or `twos`.
`raw`	`k8BitOffsetBinaryFormat`	8-bit offset binary, 0 to 255, 128 is silence.
`twos`	`k16BitBigEndianFormat`	Two’s complement big-endian, 8 or 16 bits; 0 is silence.
`sowt`	`k16BitLittleEndianFormat`	16-bit little-endian two’s complement.
`MAC3`	`kMACE3Compression`	MACE 3:1 (obsolete).
`MAC6`	`kMACE6Compression`	MACE 6:1 (obsolete).
`ima4`	`kIMACompression`	IMA ADPCM 4:1.
`fl32`	`kFloat32Format`	32-bit floating point.
`fl64`	`kFloat64Format`	64-bit floating point.
`in24`	`k24BitFormat`	24-bit integer.
`in32`	`k32BitFormat`	32-bit integer.
`ulaw`	`kULawCompression`	µ-law 2:1.
`alaw`	`kALawCompression`	A-law 2:1 (Apple’s table says uLaw, an error).
0x6D730002	`kMicrosoftADPCMFormat`	Microsoft ADPCM, ACM code 2 (`ms` followed by the WAVE format tag).
0x6D730011	`kDVIIntelIMAFormat`	DVI/Intel IMA ADPCM, ACM code 17.
`dvca`	`kDVAudioFormat`	DV audio.
`QDMC`	`kQDesignCompression`	QDesign Music.
`QDM2`	`kQDesign2Compression`	QDesign Music 2.
`Qclp`	`kQUALCOMMCompression`	Qualcomm PureVoice.
0x6D730055	`kMPEGLayer3Format`	MPEG-1 Layer III, constant bit rate only (before QuickTime 4.1).
`.mp3`	`kFullMPEGLay3Format`	MPEG-1 Layer III, constant or variable bit rate (QuickTime 4.1 and later).
`mp4a`	`kMPEG4AudioFormat`	MPEG-4 audio (AAC); needs `esds`.
`ac-3`	`kAC3AudioFormat`	AC-3 and Enhanced AC-3.
`lpcm`	–	Uncompressed audio in a version 2 description, described by the flags and bit depth.

More codes registered for QuickTime, such as agsm, vdva and Opus, are on Data types and codes. PCM, Microsoft ADPCM, µ-law and A-law are the same codecs as found in WAV files.

Extensions

From version 1 on, atoms follow the fixed fields, each with the usual size and type.

Atom	Contents
`wave`	`siDecompressionParam`: a container of atoms with settings for the decoder. Required for `mp4a`, where it normally holds, in order, `frma`, an `mp4a` atom, `esds` and a terminator. Other codecs put their own settings here (for example Microsoft ADPCM’s coefficients).
`frma`	Format: a uint32 copy of the description’s data format.
`esds`	A uint32 version and flags (0), then an MPEG-4 elementary stream descriptor (ISO/IEC 14496-1) holding the AAC decoder configuration.
`chan`	Audio channel layout: version (uint8), flags (3 bytes), then a big-endian Core Audio `AudioChannelLayout`, the same structure as the CAF channel layout chunk. More than two channels needs a version 2 description.
0x00000000	Terminator: an 8-byte atom of type 0 ending the extensions.
`siSlopeAndIntercept`	Deprecated: four float64 values, slope, intercept, minClip and maxClip, passed to the decompressor. Apple does not give its type code.

A sound track that should select a particular subtitle track by default uses a folw track reference; see Track references.