1a49893c80fc11c4ba0a0be9e4fafba3e52f259b
[flac.git] / include / FLAC / format.h
1 /* libFLAC - Free Lossless Audio Coder library
2  * Copyright (C) 2000  Josh Coalson
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17  * Boston, MA  02111-1307, USA.
18  */
19
20 #ifndef FLAC__FORMAT_H
21 #define FLAC__FORMAT_H
22
23 #include "ordinals.h"
24
25 /* changing the following values to be higher will break the framing and hence the stream format, so DON'T! */
26 #define FLAC__MIN_BLOCK_SIZE (16u)
27 #define FLAC__MAX_BLOCK_SIZE (65535u)
28 #define FLAC__MAX_CHANNELS (8u)
29 /*NOTE: only up to 24 because of the current predictor coefficient quantization and the fact we use int32s for all work */
30 #define FLAC__MAX_BITS_PER_SAMPLE (24u)
31 /* the following is ((2 ** 20) - 1) div 10 */
32 #define FLAC__MAX_SAMPLE_RATE (1048570u)
33 #define FLAC__MAX_LPC_ORDER (32u)
34 #define FLAC__MIN_QLP_COEFF_PRECISION (5u)
35 /* changing this also means changing all of fixed.c and more, so DON'T! */
36 #define FLAC__MAX_FIXED_ORDER (4u)
37 #define FLAC__MAX_RICE_PARTITION_ORDER (15u)
38
39 #define FLAC__VERSION_STRING "0.4"
40 extern const unsigned FLAC__MAJOR_VERSION;
41 extern const unsigned FLAC__MINOR_VERSION;
42
43 extern const byte     FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */;
44 extern const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */;
45 extern const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */;
46
47
48 /*****************************************************************************
49  *
50  * NOTE: Within the bitstream, all fixed-width numbers are big-endian coded.
51  *       All numbers are unsigned unless otherwise noted.
52  *
53  *****************************************************************************/
54
55 typedef enum {
56         FLAC__METADATA_TYPE_ENCODING = 0
57 } FLAC__MetaDataType;
58
59 /*****************************************************************************
60  *
61  * 16: minimum blocksize (in samples) of all blocks in the stream
62  * 16: maximum blocksize (in samples) of all blocks in the stream
63  * 24: minimum framesize (in bytes) of all frames in the stream; 0 => unknown
64  * 24: maximum framesize (in bytes) of all frames in the stream; 0 => unknown
65  * 20: sample rate in Hz, 0 is invalid
66  *  3: (number of channels)-1
67  *  5: (bits per sample)-1
68  * 36: total samples, 0 => unknown
69  *128: MD5 digest of the original unencoded audio data
70  *---- -----------------
71  * 34  bytes total
72  */
73 typedef struct {
74         unsigned min_blocksize, max_blocksize;
75         unsigned min_framesize, max_framesize;
76         unsigned sample_rate;
77         unsigned channels;
78         unsigned bits_per_sample;
79         uint64 total_samples;
80         byte md5sum[16];
81 } FLAC__StreamMetaData_Encoding;
82
83 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MIN_BLOCK_SIZE_LEN; /* = 16 bits */
84 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MAX_BLOCK_SIZE_LEN; /* = 16 bits */
85 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MIN_FRAME_SIZE_LEN; /* = 24 bits */
86 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MAX_FRAME_SIZE_LEN; /* = 24 bits */
87 extern const unsigned FLAC__STREAM_METADATA_ENCODING_SAMPLE_RATE_LEN; /* = 20 bits */
88 extern const unsigned FLAC__STREAM_METADATA_ENCODING_CHANNELS_LEN; /* = 3 bits */
89 extern const unsigned FLAC__STREAM_METADATA_ENCODING_BITS_PER_SAMPLE_LEN; /* = 5 bits */
90 extern const unsigned FLAC__STREAM_METADATA_ENCODING_TOTAL_SAMPLES_LEN; /* = 36 bits */
91 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MD5SUM_LEN; /* = 128 bits */
92 extern const unsigned FLAC__STREAM_METADATA_ENCODING_LENGTH; /* = 34 bytes */
93
94 /*****************************************************************************
95  *
96  *  1: =1 if this is the last meta-data block, else =0
97  *  7: meta-data type (c.f. FLAC__MetaDataType)
98  * 24: length (in bytes) of the block-specific data to follow
99  *---- -----------------
100  *  4  bytes total
101  */
102 typedef struct {
103         FLAC__MetaDataType type;
104         bool is_last;
105         unsigned length; /* in bytes */
106         union {
107                 FLAC__StreamMetaData_Encoding encoding;
108         } data;
109 } FLAC__StreamMetaData;
110
111 extern const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /* = 1 bits */
112 extern const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /* = 7 bits */
113 extern const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /* = 24 bits */
114
115 /*****************************************************************************/
116
117 typedef enum {
118         FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
119 } FLAC__EntropyCodingMethodType;
120
121 /*****************************************************************************
122  *
123  *  4: partition order => (2 ** order) subdivisions
124  */
125 typedef struct {
126         unsigned order;
127         unsigned parameters[1 << FLAC__MAX_RICE_PARTITION_ORDER];
128 } FLAC__EntropyCodingMethod_PartitionedRice;
129
130 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /* = 4 bits */
131 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /* = 4 bits */
132
133 /*****************************************************************************
134  *
135  *  2: entropy coding method:
136  *     00: partitioned rice coding
137  *     01-11: reserved
138  *  ?: entropy coding method data
139  */
140 typedef struct {
141         FLAC__EntropyCodingMethodType type;
142         union {
143                 FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
144         } data;
145 } FLAC__EntropyCodingMethod;
146
147 extern const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /* = 2 bits */
148
149 /*****************************************************************************/
150
151 typedef enum {
152         FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0,
153         FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1,
154         FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2,
155         FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3
156 } FLAC__ChannelAssignment;
157
158 /*****************************************************************************
159  *
160  *  9: sync code '111111110'
161  *  3: blocksize in samples
162  *        000: get from stream header => implies constant blocksize throughout stream
163  *        001: 192 samples (AES/EBU) => implies constant blocksize throughout stream
164  *        010-101: 576 * (2^(2-n)) samples, i.e. 576/1152/2304/4608 => implies constant blocksize throughout stream
165  *        110: get 8 bit (blocksize-1) from end of header => variable blocksize throughout stream unless it's the last frame
166  *        111: get 16 bit (blocksize-1) from end of header => variable blocksize throughout stream unless it's the last frame
167  *  4: sample rate:
168  *        0000: get from stream header
169  *        0001-0011: reserved
170  *        0100: 8kHz
171  *        0101: 16kHz
172  *        0110: 22.05kHz
173  *        0111: 24kHz
174  *        1000: 32kHz
175  *        1001: 44.1kHz
176  *        1010: 48kHz
177  *        1011: 96kHz
178  *        1100: get 8 bit sample rate (in kHz) from end of header
179  *        1101: get 16 bit sample rate (in Hz) from end of header
180  *        1110: get 16 bit sample rate (in tens of Hz) from end of header
181  *        1111: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
182  *  4: channel assignment
183  *     0000-0111: (number of independent channels)-1.  when == 0001, channel 0 is the left channel and channel 1 is the right
184  *     1000: left/side stereo : channel 0 is the left             channel, channel 1 is the side(difference) channel
185  *     1001: right/side stereo: channel 0 is the side(difference) channel, channel 1 is the right            channel
186  *     1010: mid/side stereo  : channel 0 is the mid(average)     channel, channel 1 is the side(difference) channel
187  *     1011-1111: reserved
188  *  3: sample size in bits
189  *        000: get from stream header
190  *        001: 8 bits per sample
191  *        010: 12 bits per sample
192  *        011: reserved
193  *        100: 16 bits per sample
194  *        101: 20 bits per sample
195  *        110: 24 bits per sample
196  *        111: reserved
197  *  1: zero pad, to prevent sync-fooling string of 1s (use to check for erroneous sync)
198  *  ?: if(variable blocksize)
199  *        8-56: 'UTF-8' coded sample number (decoded number is 0-36 bits) (use to check for erroneous sync)
200  *     else
201  *        8-48: 'UTF-8' coded frame number (decoded number is 0-31 bits) (use to check for erroneous sync)
202  *  ?: if(blocksize bits == 11x)
203  *        8/16 bit (blocksize-1)
204  *  ?: if(sample rate bits == 11xx)
205  *        8/16 bit sample rate
206  *  8: CRC-8 (polynomial = x^8 + x^2 + x + 1) of everything before the crc, including the sync code
207  */
208 typedef struct {
209         unsigned blocksize; /* in samples */
210         unsigned sample_rate; /* in Hz */
211         unsigned channels;
212         FLAC__ChannelAssignment channel_assignment;
213         unsigned bits_per_sample;
214         union {
215                 uint32 frame_number;
216                 uint64 sample_number;
217         } number;
218 } FLAC__FrameHeader;
219
220 extern const unsigned FLAC__FRAME_HEADER_SYNC; /* = 0x1fe */
221 extern const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /* = 9 bits */
222 extern const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /* = 3 bits */
223 extern const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /* = 4 bits */
224 extern const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /* = 4 bits */
225 extern const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /* = 3 bits */
226 extern const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /* = 1 bit */
227 extern const unsigned FLAC__FRAME_HEADER_CRC8_LEN; /* = 8 bits */
228
229 /*****************************************************************************/
230
231 typedef enum {
232         FLAC__SUBFRAME_TYPE_CONSTANT = 0,
233         FLAC__SUBFRAME_TYPE_VERBATIM = 1,
234         FLAC__SUBFRAME_TYPE_FIXED = 2,
235         FLAC__SUBFRAME_TYPE_LPC = 3
236 } FLAC__SubframeType;
237
238 /*****************************************************************************
239  *
240  * n: constant value for signal; n = frame's bits-per-sample
241  */
242 typedef struct {
243         int32 value;
244 } FLAC__SubframeHeader_Constant;
245
246 /*****************************************************************************
247  *
248  * n*i: unencoded signal; n = frame's bits-per-sample, i = frame's blocksize
249  */
250 /* There is no (trivial) for structure FLAC__SubframeHeader_Verbatim */
251
252 /*****************************************************************************
253  *
254  *  n: unencoded warm-up samples (n = fixed-predictor order * bits per sample)
255  *  ?: entropy coding method info
256  *  ?: encoded residual ((blocksize minus fixed-predictor order) samples)
257  *  The order is stored in the main subframe header
258  */
259 typedef struct {
260         FLAC__EntropyCodingMethod entropy_coding_method;
261         unsigned order;
262         int32 warmup[FLAC__MAX_FIXED_ORDER];
263 } FLAC__SubframeHeader_Fixed;
264
265 /*****************************************************************************
266  *
267  *  n: unencoded warm-up samples (n = lpc order * bits per sample)
268  *  4: (qlp coeff precision in bits)-1 (1111 = invalid, use to check for erroneous sync)
269  *  5: qlp shift needed in bits (signed)
270  *  n: unencoded predictor coefficients (n = lpc order * qlp coeff precision)
271  *  ?: entropy coding method info
272  *  ?: encoded residual ((blocksize minus lpc order) samples)
273  *  The order is stored in the main subframe header
274  */
275 typedef struct {
276         FLAC__EntropyCodingMethod entropy_coding_method;
277         unsigned order;
278         unsigned qlp_coeff_precision;
279         int quantization_level;
280         int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
281         int32 warmup[FLAC__MAX_LPC_ORDER];
282 } FLAC__SubframeHeader_LPC;
283
284 extern const unsigned FLAC__SUBFRAME_HEADER_LPC_QLP_COEFF_PRECISION_LEN; /* = 4 bits */
285 extern const unsigned FLAC__SUBFRAME_HEADER_LPC_QLP_SHIFT_LEN; /* = 5 bits */
286
287 /*****************************************************************************
288  *
289  *  8: subframe type
290  *       xxxxxxx1: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
291  *       00000000: constant value
292  *       00000010: verbatim
293  *       000001x0: reserved
294  *       00001xx0: reserved
295  *       0001xxx0: fixed predictor, xxx=order <= 4, else reserved
296  *       001xxxx0: reserved
297  *       01xxxxx0: lpc, xxxxx=order-1
298  *       1xxxxxxx: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
299  *  ?: subframe-specific header (c.f. FLAC__SubframeHeader_*)
300  */
301 typedef struct {
302         FLAC__SubframeType type;
303         union {
304                 FLAC__SubframeHeader_Constant constant;
305                 FLAC__SubframeHeader_Fixed fixed;
306                 FLAC__SubframeHeader_LPC lpc;
307         } data; /* data will be undefined for FLAC__SUBFRAME_TYPE_VERBATIM */
308 } FLAC__SubframeHeader;
309
310 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_CONSTANT; /* = 0x00 */
311 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_VERBATIM; /* = 0x02 */
312 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_FIXED; /* = 0x10 */
313 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_LPC; /* = 0x40 */
314 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_LEN; /* = 8 bits */
315
316 /*****************************************************************************/
317
318 #endif