Projects
Wiki     Source Code     Timeline     View Tickets     New Ticket     Search

source: trunk/ALACMagicCookieDescription.txt @ 4

Revision 4, 11.6 KB checked in by ealdrich@…, 21 months ago (diff)

Fix transposed values

Line 
1__________________________________________________________________________________________________________________________________
2__________________________________________________________________________________________________________________________________
3Apple Lossless Format "Magic Cookie" Description
4__________________________________________________________________________________________________________________________________
5__________________________________________________________________________________________________________________________________
6
7Many encoded formats for audio require additional, codec specific configuration information in order to operate successfully.
8This codec specific information is often called a 'magic cookie'. The Apple Lossless codec's 'magic cookie' contains the
9ALACSpecificConfig and optional ALACChannelLayoutInfo (both described below).
10
11The 'magic cookie' must accompany the bitstream when stored in any file container (M4A/MP4, CAF) so that it may be provided to the
12decoder when decoding the bitstream. From the caller's perspective, the 'magic cookie' is opaque and should be stored in the file
13and presented to the decoder exactly as it is vended from the encoder (and consequently stored in the file).
14
15The ALAC 'magic cookie' as stored in a file has all fields described in big-endian order (regardless of file format).
16
17The layout of the 'magic cookie' is as follows:
18
19
20---------------- ALAC Specific Info (24 bytes) (mandatory) ---------------------------
21(ALACSpecificConfig)            Decoder Info
22       
23---------------- Channel Layout Info (24 bytes) (optional) ----------------------------
24(ALAC Channel Layout Info)      Channel Layout Info
25
26
27If the channel layout is absent from the cookie, then the following assumptions are made:
281 channel - mono
292 channels - stereo in left, right order
30> 2 channels - no specific channel designation or role.
31
32
33__________________________________________________________________________________________________________________________________
34* ALAC Specific Info (24 bytes) (mandatory)
35__________________________________________________________________________________________________________________________________
36
37The Apple Lossless codec stores specific information about the encoded stream in the ALACSpecificConfig. This
38info is vended by the encoder and is used to setup the decoder for a given encoded bitstream.
39
40When read from and written to a file, the fields of this struct must be in big-endian order.
41When vended by the encoder (and received by the decoder) the struct values will be in big-endian order.
42
43/*
44    struct      ALACSpecificConfig (defined in ALACAudioTypes.h)
45    abstract    This struct is used to describe codec provided information about the encoded Apple Lossless bitstream.
46                It must accompany the encoded stream in the containing audio file and be provided to the decoder.
47
48    field       frameLength             uint32_t        indicating the frames per packet when no explicit frames per packet setting is
49                                                        present in the packet header. The encoder frames per packet can be explicitly set
50                                                        but for maximum compatibility, the default encoder setting of 4096 should be used.
51
52    field       compatibleVersion       uint8_t         indicating compatible version,
53                                                        value must be set to 0
54
55    field       bitDepth                uint8_t         describes the bit depth of the source PCM data (maximum value = 32)
56
57    field       pb                      uint8_t         currently unused tuning parameter.
58                                                        value should be set to 40
59
60    field       mb                      uint8_t         currently unused tuning parameter.
61                                                        value should be set to 10
62
63    field       kb                      uint8_t         currently unused tuning parameter.
64                                                        value should be set to 14
65
66    field       numChannels             uint8_t         describes the channel count (1 = mono, 2 = stereo, etc...)
67                                                        when channel layout info is not provided in the 'magic cookie', a channel count > 2
68                                                        describes a set of discreet channels with no specific ordering
69
70    field       maxRun                  uint16_t        currently unused.
71                                                        value should be set to 255
72
73    field       maxFrameBytes           uint32_t        the maximum size of an Apple Lossless packet within the encoded stream.
74                                                        value of 0 indicates unknown
75
76    field       avgBitRate              uint32_t        the average bit rate in bits per second of the Apple Lossless stream.
77                                                        value of 0 indicates unknown
78
79    field       sampleRate              uint32_t        sample rate of the encoded stream
80 */
81
82typedef struct ALACSpecificConfig
83{
84        uint32_t        frameLength;
85        uint8_t         compatibleVersion;
86        uint8_t         bitDepth;
87        uint8_t         pb;
88        uint8_t         mb;
89        uint8_t         kb;
90        uint8_t         numChannels;
91        uint16_t        maxRun;
92        uint32_t        maxFrameBytes;
93        uint32_t        avgBitRate;
94        uint32_t        sampleRate;
95
96} ALACSpecificConfig;
97               
98
99__________________________________________________________________________________________________________________________________
100Channel Layout Info (24 bytes) (optional)
101__________________________________________________________________________________________________________________________________
102
103The Apple Lossless codec can support a specific set of channel layouts. When channel information is vended
104by the encoder (in the 'magic cookie'), it is formatted in the the ALACChannelLayoutInfo.
105
106When read from and written to a file, the fields of this struct must be in big-endian order.
107When vended by the encoder (and received by the decoder) the struct values will be in big-endian order.
108
109/*
110    struct      ALACChannelLayoutInfo (defined in ALACAudioTypes.h)
111    abstract    This struct is used to specify particular channel orderings or configurations.
112                It is an optional portion of the 'magic cookie', being required to describe specific channel layouts (see below)
113                of more than 2 channels.
114
115    field       channelLayoutInfoSize   uint32_t        indicates the size of the channel layout data
116                                                        value should be set to 24
117
118    field       channelLayoutInfoID     uint32_t        identifier indicating that channel layout info is present
119                                                        value = 'chan'
120
121    field       versionFlags            uint32_t        version flags
122                                                        value should be set to 0
123
124    field       channelLayoutTag        uint32_t        channel layout type
125                                                        from defined list in ALACAudioTypes.h (see below)
126
127    field       reserved1               uint32_t        currently unused field
128                                                        value should be set to 0
129
130    field       reserved2               uint32_t        currently unused field
131                                                        value should be set to 0
132*/
133
134typedef struct ALACChannelLayoutInfo
135{
136        uint32_t        channelLayoutInfoSize;
137        uint32_t        channelLayoutInfoID;
138        uint32_t        versionFlags;
139        uint32_t        channelLayoutTag;       
140        uint32_t        reserved1;     
141        uint32_t        reserved2;     
142} ALACChannelLayoutInfo;
143
144
145* Channel Layout Tags
146
147These constants will be used to describe the bitstream's channel layout. (defined in ALACAudioTypes.h)
148
149enum
150{
151   kALACChannelLayoutTag_Mono           = (100<<16) | 1,        // C
152   kALACChannelLayoutTag_Stereo         = (101<<16) | 2,        // L R
153   kALACChannelLayoutTag_MPEG_3_0_B     = (113<<16) | 3,        // C L R
154   kALACChannelLayoutTag_MPEG_4_0_B     = (116<<16) | 4,        // C L R Cs
155   kALACChannelLayoutTag_MPEG_5_0_D     = (120<<16) | 5,        // C L R Ls Rs
156   kALACChannelLayoutTag_MPEG_5_1_D     = (124<<16) | 6,        // C L R Ls Rs LFE
157   kALACChannelLayoutTag_AAC_6_1        = (142<<16) | 7,        // C L R Ls Rs Cs LFE
158   kALACChannelLayoutTag_MPEG_7_1_B     = (127<<16) | 8         // C Lc Rc L R Ls Rs LFE    (doc: IS-13818-7 MPEG2-AAC)
159};
160
161
162__________________________________________________________________________________________________________________________________
163__________________________________________________________________________________________________________________________________
164* Storing Apple Lossless Magic Cookie in Audio Files
165__________________________________________________________________________________________________________________________________
166__________________________________________________________________________________________________________________________________
167
168The Apple Lossless Magic Cookie is treated as opaque by file parsing code.  The 'magic cookie' vended by the encoder
169is placed without modification into the audio file and the read from that file and passed (unmodified) to the decoder.
170
171__________________________________________________________________________________________________________________________________
172* CAF File
173
174In a CAF file (Core Audio File), the 'magic cookie' is stored in CAF's Magic Cookie chunk ('kuki').
175
176__________________________________________________________________________________________________________________________________
177* MP4/M4A File
178
179In an MP4/M4A file, the 'magic cookie' is encapsulated in the AudioSample entry of a Sound Description box ('stsd'). 
180An ISO style full box header to describe the ALACSpecificConfig portion is appended to the AudioSampleEntry, followed by the
181'magic cookie' as it is vended by the encoder.
182
183(All fields are stored in big-endian order: see ISO/IEC 14496-12 for a full description of the SoundDescription and AudioSampleEntry boxes, etc.)
184
185---------------- SoundDescriptionBox (FullBox) ----------------------------
186
187                SampleEntrySize                 // = sizeof(SoundDescriptionBox)(16) + sizeof (AudioSampleEntry)(AudioSampleEntry.SampleEntrySize)
188                SampleEntryType                 // = 'stsd'
189                VersionFlags                    // = 0
190                EntryCount                      // = 1
191
192---------------- Audio Sample Entry (REQUIRED) -----------------------------
193
194                SampleEntrySize                 // sizeof(AudioSampleEntry)(36) + sizeof(full ISO box header)(12) + sizeof(Apple Lossless Magic Cookie)
195                SampleEntryType                 // = 'alac', specifies that the AudioSampleEntry describes an Apple Lossless bitstream
196                mReserved[6]                    // = 0
197                dref index                      // = 1
198                reserved[2]                     // = 0
199                channel count                   // = number of channels as a uint_16 value
200                sample size                     // = source pcm bitdepth (example = 16bit source pcm)
201                predefined                      // = 0
202                reserved                        // = 0
203                sample rate                     // sample rate as a uint_32 value
204
205     Appended to AudioSampleEntry:
206
207                ALAC Specific Info Size         // uint_32 value, = 36 (12 + sizeof(ALACSpecificConfig))
208                ALAC Specific Info ID           // uint_32 value, = 'alac', format ID which matches the Audio Sample Entry SampleEntryType field
209                Version Flags                   // uint_32 value, = 0           
210
211                Apple Lossless Magic Cookie     // 'magic cookie' vended from ALAC encoder (24 or 48 Bytes)
212
213__________________________________________________________________________________________________________________________________
214__________________________________________________________________________________________________________________________________
215* Compatibility
216__________________________________________________________________________________________________________________________________
217__________________________________________________________________________________________________________________________________
218
219Previous versions of the Apple Lossless encoder vended a different 'magic cookie'. To ensure compatibility, the Apple Lossless decoder
220must be prepared to parse a 'magic cookie' in the format described below. Note that the 'magic cookie' defined above is
221encapsulated in the following method and can be extracted as a contiguous set of bytes.
222
223
224---------------- Format Atom (12 bytes) --------------------------------
225(uint_32)               Format Atom Size                // = 12
226(uint_32)               Channel Layout Info ID          // = 'frma'     
227(uint_32)               Format Type                     // = 'alac'     
228       
229---------------- ALAC Specific Info (36 bytes) (required) --------------
230(uint_32)               ALAC Specific Info Size         // = 36 (12 + sizeof(ALACSpecificConfig))
231(uint_32)               ALAC Specific Info ID           // = 'alac', format ID which matches the Audio Sample Entry SampleEntryType field
232(uint_32)               Version Flags                   // = 0         
233
234        [ Apple Lossless Magic Cookie (see above) ]
235
236---------------- Terminator Atom (8 bytes) -----------------------------
237(uint_32)               Channel Layout Info Size        // = 8 
238(uint_32)               Channel Layout Info ID          // = 0 
239
240
241
Note: See TracBrowser for help on using the repository browser.