mirror of
https://codeberg.org/ashley/poke.git
synced 2024-11-17 07:34:38 -05:00
242 lines
12 KiB
Text
242 lines
12 KiB
Text
__________________________________________________________________________________________________________________________________
|
|
__________________________________________________________________________________________________________________________________
|
|
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
|
|
|
|
|
|
|