2
0

ALACMagicCookieDescription.txt 12 KB

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