change Coder to Codec everywhere
[flac.git] / include / FLAC / format.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001  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 /* VERSION should come from configure */
40 #ifdef VERSION
41 #define FLAC__VERSION_STRING VERSION
42 #else
43 #define FLAC__VERSION_STRING "0.6"
44 #endif
45
46 extern const byte     FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */;
47 extern const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */;
48 extern const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */;
49
50
51 /*****************************************************************************
52  *
53  * NOTE: Within the bitstream, all fixed-width numbers are big-endian coded.
54  *       All numbers are unsigned unless otherwise noted.
55  *
56  *****************************************************************************/
57
58
59 /*****************************************************************************
60  *
61  * Subframe structures
62  *
63  *****************************************************************************/
64
65 /*****************************************************************************/
66
67 typedef enum {
68         FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
69 } FLAC__EntropyCodingMethodType;
70 extern const char *FLAC__EntropyCodingMethodTypeString[];
71
72 /*****************************************************************************
73  *
74  *  4: partition order => (2 ** order) subdivisions
75  */
76 typedef struct {
77         unsigned order;
78         unsigned parameters[1 << FLAC__MAX_RICE_PARTITION_ORDER];
79 } FLAC__EntropyCodingMethod_PartitionedRice;
80
81 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /* = 4 bits */
82 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /* = 4 bits */
83
84 /*****************************************************************************
85  *
86  *  2: entropy coding method:
87  *     00: partitioned rice coding
88  *     01-11: reserved
89  *  ?: entropy coding method data
90  */
91 typedef struct {
92         FLAC__EntropyCodingMethodType type;
93         union {
94                 FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
95         } data;
96 } FLAC__EntropyCodingMethod;
97
98 extern const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /* = 2 bits */
99
100 /*****************************************************************************/
101
102 typedef enum {
103         FLAC__SUBFRAME_TYPE_CONSTANT = 0,
104         FLAC__SUBFRAME_TYPE_VERBATIM = 1,
105         FLAC__SUBFRAME_TYPE_FIXED = 2,
106         FLAC__SUBFRAME_TYPE_LPC = 3
107 } FLAC__SubframeType;
108 extern const char *FLAC__SubframeTypeString[];
109
110 /*****************************************************************************
111  *
112  * n: constant value for signal; n = frame's bits-per-sample
113  */
114 typedef struct {
115         int32 value;
116 } FLAC__Subframe_Constant;
117
118 /*****************************************************************************
119  *
120  * n*i: unencoded signal; n = frame's bits-per-sample, i = frame's blocksize
121  */
122 typedef struct {
123         const int32 *data;
124 } FLAC__Subframe_Verbatim;
125
126 /*****************************************************************************
127  *
128  *  n: unencoded warm-up samples (n = fixed-predictor order * bits per sample)
129  *  ?: entropy coding method info
130  *  ?: encoded residual ((blocksize minus fixed-predictor order) samples)
131  *  The order is stored in the main subframe header
132  */
133 typedef struct {
134         FLAC__EntropyCodingMethod entropy_coding_method;
135         unsigned order;
136         int32 warmup[FLAC__MAX_FIXED_ORDER];
137         const int32 *residual;
138 } FLAC__Subframe_Fixed;
139
140 /*****************************************************************************
141  *
142  *  n: unencoded warm-up samples (n = lpc order * bits per sample)
143  *  4: (qlp coeff precision in bits)-1 (1111 = invalid, use to check for erroneous sync)
144  *  5: qlp shift needed in bits (signed)
145  *  n: unencoded predictor coefficients (n = lpc order * qlp coeff precision)
146  *  ?: entropy coding method info
147  *  ?: encoded residual ((blocksize minus lpc order) samples)
148  *  The order is stored in the main subframe header
149  */
150 typedef struct {
151         FLAC__EntropyCodingMethod entropy_coding_method;
152         unsigned order;
153         unsigned qlp_coeff_precision;
154         int quantization_level;
155         int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
156         int32 warmup[FLAC__MAX_LPC_ORDER];
157         const int32 *residual;
158 } FLAC__Subframe_LPC;
159
160 extern const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /* = 4 bits */
161 extern const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /* = 5 bits */
162
163 /*****************************************************************************
164  *
165  *  8: subframe type
166  *       xxxxxxx1: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
167  *       00000000: constant value
168  *       00000010: verbatim
169  *       000001x0: reserved
170  *       00001xx0: reserved
171  *       0001xxx0: fixed predictor, xxx=order <= 4, else reserved
172  *       001xxxx0: reserved
173  *       01xxxxx0: lpc, xxxxx=order-1
174  *       1xxxxxxx: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
175  *  ?: subframe-specific data (c.f. FLAC__Subframe_*)
176  */
177 typedef struct {
178         FLAC__SubframeType type;
179         union {
180                 FLAC__Subframe_Constant constant;
181                 FLAC__Subframe_Fixed fixed;
182                 FLAC__Subframe_LPC lpc;
183                 FLAC__Subframe_Verbatim verbatim;
184         } data;
185 } FLAC__Subframe;
186
187 extern const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BITS; /* = 0x00 */
188 extern const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BITS; /* = 0x02 */
189 extern const unsigned FLAC__SUBFRAME_TYPE_FIXED_BITS; /* = 0x10 */
190 extern const unsigned FLAC__SUBFRAME_TYPE_LPC_BITS; /* = 0x40 */
191 extern const unsigned FLAC__SUBFRAME_TYPE_LEN; /* = 8 bits */
192
193 /*****************************************************************************/
194
195
196 /*****************************************************************************
197  *
198  * Frame structures
199  *
200  *****************************************************************************/
201
202 typedef enum {
203         FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0,
204         FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1,
205         FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2,
206         FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3
207 } FLAC__ChannelAssignment;
208 extern const char *FLAC__ChannelAssignmentString[];
209
210 /*****************************************************************************
211  *
212  *  9: sync code '111111110'
213  *  3: blocksize in samples
214  *        000: get from stream header => implies constant blocksize throughout stream
215  *        001: 192 samples (AES/EBU) => implies constant blocksize throughout stream
216  *        010-101: 576 * (2^(2-n)) samples, i.e. 576/1152/2304/4608 => implies constant blocksize throughout stream
217  *        110: get 8 bit (blocksize-1) from end of header => variable blocksize throughout stream unless it's the last frame
218  *        111: get 16 bit (blocksize-1) from end of header => variable blocksize throughout stream unless it's the last frame
219  *  4: sample rate:
220  *        0000: get from stream header
221  *        0001-0011: reserved
222  *        0100: 8kHz
223  *        0101: 16kHz
224  *        0110: 22.05kHz
225  *        0111: 24kHz
226  *        1000: 32kHz
227  *        1001: 44.1kHz
228  *        1010: 48kHz
229  *        1011: 96kHz
230  *        1100: get 8 bit sample rate (in kHz) from end of header
231  *        1101: get 16 bit sample rate (in Hz) from end of header
232  *        1110: get 16 bit sample rate (in tens of Hz) from end of header
233  *        1111: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
234  *  4: channel assignment
235  *     0000-0111: (number of independent channels)-1.  when == 0001, channel 0 is the left channel and channel 1 is the right
236  *     1000: left/side stereo : channel 0 is the left             channel, channel 1 is the side(difference) channel
237  *     1001: right/side stereo: channel 0 is the side(difference) channel, channel 1 is the right            channel
238  *     1010: mid/side stereo  : channel 0 is the mid(average)     channel, channel 1 is the side(difference) channel
239  *     1011-1111: reserved
240  *  3: sample size in bits
241  *        000: get from stream header
242  *        001: 8 bits per sample
243  *        010: 12 bits per sample
244  *        011: reserved
245  *        100: 16 bits per sample
246  *        101: 20 bits per sample
247  *        110: 24 bits per sample
248  *        111: reserved
249  *  1: zero pad, to prevent sync-fooling string of 1s (use to check for erroneous sync)
250  *  ?: if(variable blocksize)
251  *        8-56: 'UTF-8' coded sample number (decoded number is 0-36 bits) (use to check for erroneous sync)
252  *     else
253  *        8-48: 'UTF-8' coded frame number (decoded number is 0-31 bits) (use to check for erroneous sync)
254  *  ?: if(blocksize bits == 11x)
255  *        8/16 bit (blocksize-1)
256  *  ?: if(sample rate bits == 11xx)
257  *        8/16 bit sample rate
258  *  8: CRC-8 (polynomial = x^8 + x^2 + x + 1) of everything before the crc, including the sync code
259  */
260 typedef struct {
261         unsigned blocksize; /* in samples */
262         unsigned sample_rate; /* in Hz */
263         unsigned channels;
264         FLAC__ChannelAssignment channel_assignment;
265         unsigned bits_per_sample;
266         union {
267                 uint32 frame_number;
268                 uint64 sample_number;
269         } number;
270 } FLAC__FrameHeader;
271
272 extern const unsigned FLAC__FRAME_HEADER_SYNC; /* = 0x1fe */
273 extern const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /* = 9 bits */
274 extern const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /* = 3 bits */
275 extern const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /* = 4 bits */
276 extern const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /* = 4 bits */
277 extern const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /* = 3 bits */
278 extern const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /* = 1 bit */
279 extern const unsigned FLAC__FRAME_HEADER_CRC8_LEN; /* = 8 bits */
280
281 typedef struct {
282         FLAC__FrameHeader header;
283         FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
284 } FLAC__Frame;
285
286 /*****************************************************************************/
287
288
289 /*****************************************************************************
290  *
291  * Meta-data structures
292  *
293  *****************************************************************************/
294
295 typedef enum {
296         FLAC__METADATA_TYPE_ENCODING = 0
297 } FLAC__MetaDataType;
298 extern const char *FLAC__MetaDataTypeString[];
299
300 /*****************************************************************************
301  *
302  * 16: minimum blocksize (in samples) of all blocks in the stream
303  * 16: maximum blocksize (in samples) of all blocks in the stream
304  * 24: minimum framesize (in bytes) of all frames in the stream; 0 => unknown
305  * 24: maximum framesize (in bytes) of all frames in the stream; 0 => unknown
306  * 20: sample rate in Hz, 0 is invalid
307  *  3: (number of channels)-1
308  *  5: (bits per sample)-1
309  * 36: total samples, 0 => unknown
310  *128: MD5 digest of the original unencoded audio data
311  *---- -----------------
312  * 34  bytes total
313  */
314 typedef struct {
315         unsigned min_blocksize, max_blocksize;
316         unsigned min_framesize, max_framesize;
317         unsigned sample_rate;
318         unsigned channels;
319         unsigned bits_per_sample;
320         uint64 total_samples;
321         byte md5sum[16];
322 } FLAC__StreamMetaData_Encoding;
323
324 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MIN_BLOCK_SIZE_LEN; /* = 16 bits */
325 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MAX_BLOCK_SIZE_LEN; /* = 16 bits */
326 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MIN_FRAME_SIZE_LEN; /* = 24 bits */
327 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MAX_FRAME_SIZE_LEN; /* = 24 bits */
328 extern const unsigned FLAC__STREAM_METADATA_ENCODING_SAMPLE_RATE_LEN; /* = 20 bits */
329 extern const unsigned FLAC__STREAM_METADATA_ENCODING_CHANNELS_LEN; /* = 3 bits */
330 extern const unsigned FLAC__STREAM_METADATA_ENCODING_BITS_PER_SAMPLE_LEN; /* = 5 bits */
331 extern const unsigned FLAC__STREAM_METADATA_ENCODING_TOTAL_SAMPLES_LEN; /* = 36 bits */
332 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MD5SUM_LEN; /* = 128 bits */
333 extern const unsigned FLAC__STREAM_METADATA_ENCODING_LENGTH; /* = 34 bytes */
334
335 /*****************************************************************************
336  *
337  *  1: =1 if this is the last meta-data block, else =0
338  *  7: meta-data type (c.f. FLAC__MetaDataType)
339  * 24: length (in bytes) of the block-specific data to follow
340  *---- -----------------
341  *  4  bytes total
342  */
343 typedef struct {
344         FLAC__MetaDataType type;
345         bool is_last;
346         unsigned length; /* in bytes */
347         union {
348                 FLAC__StreamMetaData_Encoding encoding;
349         } data;
350 } FLAC__StreamMetaData;
351
352 extern const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /* = 1 bits */
353 extern const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /* = 7 bits */
354 extern const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /* = 24 bits */
355
356 /*****************************************************************************/
357
358
359 /*****************************************************************************
360  *
361  * Stream structures
362  *
363  *****************************************************************************/
364
365 typedef struct {
366         FLAC__StreamMetaData_Encoding metadata;
367         FLAC__Frame *frames;
368 } FLAC__Stream;
369
370 /*****************************************************************************/
371
372 #endif