poke/alac/ALACMagicCookieDescription.txt

__________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________
Apple Lossless Format "Magic Cookie" Description
__________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________

Many encoded formats for audio require additional, codec specific configuration information in order to operate successfully.
This codec specific information is often called a 'magic cookie'. The Apple Lossless codec's 'magic cookie' contains the 
ALACSpecificConfig and optional ALACChannelLayoutInfo (both described below).

The 'magic cookie' must accompany the bitstream when stored in any file container (M4A/MP4, CAF) so that it may be provided to the 
decoder when decoding the bitstream. From the caller's perspective, the 'magic cookie' is opaque and should be stored in the file 
and presented to the decoder exactly as it is vended from the encoder (and consequently stored in the file). 

The ALAC 'magic cookie' as stored in a file has all fields described in big-endian order (regardless of file format).

The layout of the 'magic cookie' is as follows:


---------------- ALAC Specific Info (24 bytes) (mandatory) ---------------------------
(ALACSpecificConfig)		Decoder Info
	
---------------- Channel Layout Info (24 bytes) (optional) ----------------------------
(ALAC Channel Layout Info)	Channel Layout Info


If the channel layout is absent from the cookie, then the following assumptions are made:
1 channel - mono
2 channels - stereo in left, right order
> 2 channels - no specific channel designation or role.


__________________________________________________________________________________________________________________________________
* ALAC Specific Info (24 bytes) (mandatory)
__________________________________________________________________________________________________________________________________

The Apple Lossless codec stores specific information about the encoded stream in the ALACSpecificConfig. This
info is vended by the encoder and is used to setup the decoder for a given encoded bitstream. 

When read from and written to a file, the fields of this struct must be in big-endian order. 
When vended by the encoder (and received by the decoder) the struct values will be in big-endian order.

/*
    struct	ALACSpecificConfig (defined in ALACAudioTypes.h)
    abstract   	This struct is used to describe codec provided information about the encoded Apple Lossless bitstream. 
		It must accompany the encoded stream in the containing audio file and be provided to the decoder.

    field      	frameLength 		uint32_t	indicating the frames per packet when no explicit frames per packet setting is 
							present in the packet header. The encoder frames per packet can be explicitly set 
							but for maximum compatibility, the default encoder setting of 4096 should be used.

    field      	compatibleVersion 	uint8_t 	indicating compatible version, 
							value must be set to 0

    field      	bitDepth 		uint8_t 	describes the bit depth of the source PCM data (maximum value = 32)

    field      	pb 			uint8_t 	currently unused tuning parameter. 
						 	value should be set to 40

    field      	mb 			uint8_t 	currently unused tuning parameter. 
						 	value should be set to 10

    field      	kb			uint8_t 	currently unused tuning parameter. 
						 	value should be set to 14

    field      	numChannels 		uint8_t 	describes the channel count (1 = mono, 2 = stereo, etc...)
							when channel layout info is not provided in the 'magic cookie', a channel count > 2
							describes a set of discreet channels with no specific ordering

    field      	maxRun			uint16_t 	currently unused. 
   						  	value should be set to 255

    field      	maxFrameBytes 		uint32_t 	the maximum size of an Apple Lossless packet within the encoded stream. 
						  	value of 0 indicates unknown

    field      	avgBitRate 		uint32_t 	the average bit rate in bits per second of the Apple Lossless stream. 
						  	value of 0 indicates unknown

    field      	sampleRate 		uint32_t 	sample rate of the encoded stream
 */

typedef struct ALACSpecificConfig
{
	uint32_t	frameLength;
	uint8_t		compatibleVersion;
	uint8_t		bitDepth;
	uint8_t		pb;
	uint8_t		mb;
	uint8_t		kb;
	uint8_t		numChannels;
	uint16_t	maxRun;
	uint32_t	maxFrameBytes;
	uint32_t	avgBitRate;
	uint32_t	sampleRate;

} ALACSpecificConfig;
		

__________________________________________________________________________________________________________________________________
Channel Layout Info (24 bytes) (optional)
__________________________________________________________________________________________________________________________________

The Apple Lossless codec can support a specific set of channel layouts. When channel information is vended 
by the encoder (in the 'magic cookie'), it is formatted in the the ALACChannelLayoutInfo.

When read from and written to a file, the fields of this struct must be in big-endian order. 
When vended by the encoder (and received by the decoder) the struct values will be in big-endian order.

/*
    struct	ALACChannelLayoutInfo (defined in ALACAudioTypes.h)
    abstract	This struct is used to specify particular channel orderings or configurations.
		It is an optional portion of the 'magic cookie', being required to describe specific channel layouts (see below)
		of more than 2 channels. 

    field      	channelLayoutInfoSize 	uint32_t 	indicates the size of the channel layout data
							value should be set to 24

    field      	channelLayoutInfoID 	uint32_t 	identifier indicating that channel layout info is present 
							value = 'chan'

    field      	versionFlags 		uint32_t 	version flags
						 	value should be set to 0

    field	channelLayoutTag	uint32_t	channel layout type
							from defined list in ALACAudioTypes.h (see below)

    field      	reserved1 		uint32_t 	currently unused field
						 	value should be set to 0

    field      	reserved2 		uint32_t	currently unused field 
						 	value should be set to 0
*/

typedef struct ALACChannelLayoutInfo
{
	uint32_t	channelLayoutInfoSize;
	uint32_t	channelLayoutInfoID;
	uint32_t	versionFlags;
	uint32_t	channelLayoutTag;	
	uint32_t	reserved1;	
	uint32_t	reserved2;	
} ALACChannelLayoutInfo;


* Channel Layout Tags

These constants will be used to describe the bitstream's channel layout. (defined in ALACAudioTypes.h)

enum
{
   kALACChannelLayoutTag_Mono         	= (100<<16) | 1,    	// C
   kALACChannelLayoutTag_Stereo       	= (101<<16) | 2,	// L R
   kALACChannelLayoutTag_MPEG_3_0_B   	= (113<<16) | 3,	// C L R
   kALACChannelLayoutTag_MPEG_4_0_B   	= (116<<16) | 4,	// C L R Cs
   kALACChannelLayoutTag_MPEG_5_0_D	= (120<<16) | 5,    	// C L R Ls Rs
   kALACChannelLayoutTag_MPEG_5_1_D   	= (124<<16) | 6,	// C L R Ls Rs LFE
   kALACChannelLayoutTag_AAC_6_1      	= (142<<16) | 7,	// C L R Ls Rs Cs LFE
   kALACChannelLayoutTag_MPEG_7_1_B	= (127<<16) | 8    	// C Lc Rc L R Ls Rs LFE    (doc: IS-13818-7 MPEG2-AAC)
};


__________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________
* Storing Apple Lossless Magic Cookie in Audio Files
__________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________

The Apple Lossless Magic Cookie is treated as opaque by file parsing code.  The 'magic cookie' vended by the encoder 
is placed without modification into the audio file and the read from that file and passed (unmodified) to the decoder.

__________________________________________________________________________________________________________________________________
* CAF File

In a CAF file (Core Audio File), the 'magic cookie' is stored in CAF's Magic Cookie chunk ('kuki').

__________________________________________________________________________________________________________________________________
* MP4/M4A File

In an MP4/M4A file, the 'magic cookie' is encapsulated in the AudioSample entry of a Sound Description box ('stsd').  
An ISO style full box header to describe the ALACSpecificConfig portion is appended to the AudioSampleEntry, followed by the 
'magic cookie' as it is vended by the encoder. 

(All fields are stored in big-endian order: see ISO/IEC 14496-12 for a full description of the SoundDescription and AudioSampleEntry boxes, etc.)

---------------- SoundDescriptionBox (FullBox) ----------------------------

		SampleEntrySize		 	// = sizeof(SoundDescriptionBox)(16) + sizeof (AudioSampleEntry)(AudioSampleEntry.SampleEntrySize)
		SampleEntryType			// = 'stsd'
		VersionFlags 			// = 0
		EntryCount			// = 1

---------------- Audio Sample Entry (REQUIRED) -----------------------------

		SampleEntrySize 		// sizeof(AudioSampleEntry)(36) + sizeof(full ISO box header)(12) + sizeof(Apple Lossless Magic Cookie)
		SampleEntryType			// = 'alac', specifies that the AudioSampleEntry describes an Apple Lossless bitstream
		mReserved[6]			// = 0
		dref index			// = 1
		reserved[2]			// = 0
		channel count			// = number of channels as a uint_16 value
		sample size			// = source pcm bitdepth (example = 16bit source pcm)
		predefined			// = 0
		reserved			// = 0
		sample rate			// sample rate as a uint_32 value

     Appended to AudioSampleEntry:

		ALAC Specific Info Size		// uint_32 value, = 36 (12 + sizeof(ALACSpecificConfig))
		ALAC Specific Info ID		// uint_32 value, = 'alac', format ID which matches the Audio Sample Entry SampleEntryType field
		Version Flags			// uint_32 value, = 0		

		Apple Lossless Magic Cookie	// 'magic cookie' vended from ALAC encoder (24 or 48 Bytes)

__________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________
* Compatibility
__________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________

Previous versions of the Apple Lossless encoder vended a different 'magic cookie'. To ensure compatibility, the Apple Lossless decoder 
must be prepared to parse a 'magic cookie' in the format described below. Note that the 'magic cookie' defined above is 
encapsulated in the following method and can be extracted as a contiguous set of bytes.


---------------- Format Atom (12 bytes) --------------------------------
(uint_32)		Format Atom Size		// = 12
(uint_32)		Channel Layout Info ID		// = 'frma'	
(uint_32)		Format Type			// = 'alac'	
	
---------------- ALAC Specific Info (36 bytes) (required) --------------
(uint_32)		ALAC Specific Info Size		// = 36 (12 + sizeof(ALACSpecificConfig))
(uint_32)		ALAC Specific Info ID		// = 'alac', format ID which matches the Audio Sample Entry SampleEntryType field
(uint_32)		Version Flags			// = 0		

	[ Apple Lossless Magic Cookie (see above) ]

---------------- Terminator Atom (8 bytes) -----------------------------
(uint_32)		Channel Layout Info Size	// = 8	
(uint_32)		Channel Layout Info ID		// = 0