differentiate between format max bps and reference codec max bps
[flac.git] / include / FLAC / format.h
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001,2002  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 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 /* changing the following values to be higher will break the framing and hence the stream format, so DON'T! */
30 #define FLAC__MIN_BLOCK_SIZE (16u)
31 #define FLAC__MAX_BLOCK_SIZE (65535u)
32 #define FLAC__MAX_CHANNELS (8u)
33 #define FLAC__MIN_BITS_PER_SAMPLE (4u)
34 #define FLAC__MAX_BITS_PER_SAMPLE (32u)
35 /*
36  * NOTE: the above value is the limit of the FLAC format.  However, the
37  * reference encoder/decoder is currently limited to 24 bits because of
38  * prevalent 32-bit math, so make sure and use the following value when
39  * appropriate:
40  */
41 #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
42 /* the following is ((2 ** 16) - 1) * 10; see format.html as to why */
43 #define FLAC__MAX_SAMPLE_RATE (655350u)
44 #define FLAC__MAX_LPC_ORDER (32u)
45 #define FLAC__MIN_QLP_COEFF_PRECISION (5u)
46 /* changing FLAC__MAX_FIXED_ORDER also means changing all of fixed.c and more, so DON'T! */
47 #define FLAC__MAX_FIXED_ORDER (4u)
48 #define FLAC__MAX_RICE_PARTITION_ORDER (15u)
49
50 /* VERSION should come from configure */
51 #ifdef VERSION
52 #define FLAC__VERSION_STRING VERSION
53 #endif
54
55 extern const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */;
56 extern const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */;
57 extern const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */;
58
59
60 /*****************************************************************************
61  *
62  * NOTE: Within the bitstream, all fixed-width numbers are big-endian coded.
63  *       All numbers are unsigned unless otherwise noted.
64  *
65  *****************************************************************************/
66
67
68 /*****************************************************************************
69  *
70  * Subframe structures
71  *
72  *****************************************************************************/
73
74 /*****************************************************************************/
75
76 typedef enum {
77         FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
78 } FLAC__EntropyCodingMethodType;
79 extern const char *FLAC__EntropyCodingMethodTypeString[];
80
81 /*****************************************************************************
82  *
83  *  4: partition order => (2 ** order) subdivisions
84  */
85 typedef struct {
86         unsigned order;
87         unsigned parameters[1 << FLAC__MAX_RICE_PARTITION_ORDER];
88         unsigned raw_bits[1 << FLAC__MAX_RICE_PARTITION_ORDER];
89 } FLAC__EntropyCodingMethod_PartitionedRice;
90
91 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /* = 4 bits */
92 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /* = 4 bits */
93 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; /* = 5 bits */
94
95 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER; /* = (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN)-1 */
96
97 /*****************************************************************************
98  *
99  *  2: entropy coding method:
100  *     00: partitioned rice coding
101  *     01-11: reserved
102  *  ?: entropy coding method data
103  */
104 typedef struct {
105         FLAC__EntropyCodingMethodType type;
106         union {
107                 FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
108         } data;
109 } FLAC__EntropyCodingMethod;
110
111 extern const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /* = 2 bits */
112
113 /*****************************************************************************/
114
115 typedef enum {
116         FLAC__SUBFRAME_TYPE_CONSTANT = 0,
117         FLAC__SUBFRAME_TYPE_VERBATIM = 1,
118         FLAC__SUBFRAME_TYPE_FIXED = 2,
119         FLAC__SUBFRAME_TYPE_LPC = 3
120 } FLAC__SubframeType;
121 extern const char *FLAC__SubframeTypeString[];
122
123 /*****************************************************************************
124  *
125  * n: constant value for signal; n = frame's bits-per-sample
126  */
127 typedef struct {
128         FLAC__int32 value;
129 } FLAC__Subframe_Constant;
130
131 /*****************************************************************************
132  *
133  * n*i: unencoded signal; n = frame's bits-per-sample, i = frame's blocksize
134  */
135 typedef struct {
136         const FLAC__int32 *data;
137 } FLAC__Subframe_Verbatim;
138
139 /*****************************************************************************
140  *
141  *  n: unencoded warm-up samples (n = fixed-predictor order * bits per sample)
142  *  ?: entropy coding method info
143  *  ?: encoded residual ((blocksize minus fixed-predictor order) samples)
144  *  The order is stored in the main subframe header
145  */
146 typedef struct {
147         FLAC__EntropyCodingMethod entropy_coding_method;
148         unsigned order;
149         FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
150         const FLAC__int32 *residual;
151 } FLAC__Subframe_Fixed;
152
153 /*****************************************************************************
154  *
155  *  n: unencoded warm-up samples (n = lpc order * bits per sample)
156  *  4: (qlp coeff precision in bits)-1 (1111 = invalid, use to check for erroneous sync)
157  *  5: qlp shift needed in bits (signed)
158  *  n: unencoded predictor coefficients (n = lpc order * qlp coeff precision)
159  *  ?: entropy coding method info
160  *  ?: encoded residual ((blocksize minus lpc order) samples)
161  *  The order is stored in the main subframe header
162  */
163 typedef struct {
164         FLAC__EntropyCodingMethod entropy_coding_method;
165         unsigned order;
166         unsigned qlp_coeff_precision;
167         int quantization_level;
168         FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
169         FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
170         const FLAC__int32 *residual;
171 } FLAC__Subframe_LPC;
172
173 extern const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /* = 4 bits */
174 extern const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /* = 5 bits */
175
176 /*****************************************************************************
177  *
178  *  1: zero pad, to prevent sync-fooling string of 1s (use to check for erroneous sync)
179  *  6: subframe type
180  *       000000: constant value
181  *       000001: verbatim
182  *       00001x: reserved
183  *       0001xx: reserved
184  *       001xxx: fixed predictor, xxx=order <= 4, else reserved
185  *       01xxxx: reserved
186  *       1xxxxx: lpc, xxxxx=order-1
187  *  1: 'wasted bits' flag
188  *       0: no wasted bits in source subblock
189  *       1: all samples in source subblock contain n 0 least significant bits.  n-1 follows, unary coded, i.e. n=3, 001 follows, n=7, 0000001 follows.
190  *             ?: unary coded (n-1)
191  *  ?: subframe-specific data (c.f. FLAC__Subframe_*)
192  */
193 typedef struct {
194         FLAC__SubframeType type;
195         union {
196                 FLAC__Subframe_Constant constant;
197                 FLAC__Subframe_Fixed fixed;
198                 FLAC__Subframe_LPC lpc;
199                 FLAC__Subframe_Verbatim verbatim;
200         } data;
201         unsigned wasted_bits;
202 } FLAC__Subframe;
203
204 extern const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; /* = 1 bit */
205 extern const unsigned FLAC__SUBFRAME_TYPE_LEN; /* = 6 bits */
206 extern const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /* = 1 bit */
207
208 extern const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /* = 0x00 */
209 extern const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /* = 0x02 */
210 extern const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /* = 0x10 */
211 extern const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /* = 0x40 */
212
213 /*****************************************************************************/
214
215
216 /*****************************************************************************
217  *
218  * Frame structures
219  *
220  *****************************************************************************/
221
222 typedef enum {
223         FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0,
224         FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1,
225         FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2,
226         FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3
227 } FLAC__ChannelAssignment;
228 extern const char *FLAC__ChannelAssignmentString[];
229
230 typedef enum {
231         FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER,
232         FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER
233 } FLAC__FrameNumberType;
234 extern const char *FLAC__FrameNumberTypeString[];
235
236 /*****************************************************************************
237  *
238  * 14: sync code '11111111111110'
239  *  2: reserved
240  *        00: currently required value
241  *        01-11: reserved
242  *  4: blocksize in samples
243  *        0000: get from stream header => implies constant blocksize throughout stream
244  *        0001: 192 samples (AES/EBU) => implies constant blocksize throughout stream
245  *        0010-0101: 576 * (2^(n-2)) samples, i.e. 576/1152/2304/4608 => implies constant blocksize throughout stream
246  *        0110: get 8 bit (blocksize-1) from end of header => possibly variable blocksize throughout stream unless it's the last frame
247  *        0111: get 16 bit (blocksize-1) from end of header => possibly variable blocksize throughout stream unless it's the last frame
248  *        1000-1111: 256 * (2^(n-8)) samples, i.e. 256/512/1024/2048/4096/8192/16384/32768 => implies constant blocksize throughout stream
249  *  4: sample rate:
250  *        0000: get from stream header
251  *        0001-0011: reserved
252  *        0100: 8kHz
253  *        0101: 16kHz
254  *        0110: 22.05kHz
255  *        0111: 24kHz
256  *        1000: 32kHz
257  *        1001: 44.1kHz
258  *        1010: 48kHz
259  *        1011: 96kHz
260  *        1100: get 8 bit sample rate (in kHz) from end of header
261  *        1101: get 16 bit sample rate (in Hz) from end of header
262  *        1110: get 16 bit sample rate (in tens of Hz) from end of header
263  *        1111: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
264  *  4: channel assignment
265  *     0000-0111: (number of independent channels)-1.  when == 0001, channel 0 is the left channel and channel 1 is the right
266  *     1000: left/side stereo : channel 0 is the left             channel, channel 1 is the side(difference) channel
267  *     1001: right/side stereo: channel 0 is the side(difference) channel, channel 1 is the right            channel
268  *     1010: mid/side stereo  : channel 0 is the mid(average)     channel, channel 1 is the side(difference) channel
269  *     1011-1111: reserved
270  *  3: sample size in bits
271  *        000: get from stream header
272  *        001: 8 bits per sample
273  *        010: 12 bits per sample
274  *        011: reserved
275  *        100: 16 bits per sample
276  *        101: 20 bits per sample
277  *        110: 24 bits per sample
278  *        111: reserved
279  *  1: zero pad, to prevent sync-fooling string of 1s (use to check for erroneous sync)
280  *  ?: if(variable blocksize)
281  *        8-56: 'UTF-8' coded sample number (decoded number is 0-36 bits) (use to check for erroneous sync)
282  *     else
283  *        8-48: 'UTF-8' coded frame number (decoded number is 0-31 bits) (use to check for erroneous sync)
284  *  ?: if(blocksize bits == 11x)
285  *        8/16 bit (blocksize-1)
286  *  ?: if(sample rate bits == 11xx)
287  *        8/16 bit sample rate
288  *  8: CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0) of everything before the crc, including the sync code
289  */
290 typedef struct {
291         unsigned blocksize; /* in samples */
292         unsigned sample_rate; /* in Hz */
293         unsigned channels;
294         FLAC__ChannelAssignment channel_assignment;
295         unsigned bits_per_sample;
296         FLAC__FrameNumberType number_type;
297         union {
298                 FLAC__uint32 frame_number;
299                 FLAC__uint64 sample_number;
300         } number;
301         FLAC__uint8 crc;
302 } FLAC__FrameHeader;
303
304 extern const unsigned FLAC__FRAME_HEADER_SYNC; /* = 0x3ffe */
305 extern const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /* = 14 bits */
306 extern const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /* = 2 bits */
307 extern const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /* = 4 bits */
308 extern const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /* = 4 bits */
309 extern const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /* = 4 bits */
310 extern const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /* = 3 bits */
311 extern const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /* = 1 bit */
312 extern const unsigned FLAC__FRAME_HEADER_CRC_LEN; /* = 8 bits */
313
314 /*****************************************************************************
315  *
316  * 16: CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with 0) of everything before the crc, back to and including the frame header sync code
317  */
318 typedef struct {
319         FLAC__uint16 crc;
320 } FLAC__FrameFooter;
321
322 extern const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /* = 16 bits */
323
324 typedef struct {
325         FLAC__FrameHeader header;
326         FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
327         FLAC__FrameFooter footer;
328 } FLAC__Frame;
329
330 /*****************************************************************************/
331
332
333 /*****************************************************************************
334  *
335  * Meta-data structures
336  *
337  *****************************************************************************/
338
339 typedef enum {
340         FLAC__METADATA_TYPE_STREAMINFO = 0,
341         FLAC__METADATA_TYPE_PADDING = 1,
342         FLAC__METADATA_TYPE_APPLICATION = 2,
343         FLAC__METADATA_TYPE_SEEKTABLE = 3,
344         FLAC__METADATA_TYPE_VORBIS_COMMENT = 4
345 } FLAC__MetaDataType;
346 extern const char *FLAC__MetaDataTypeString[];
347
348 /*****************************************************************************
349  *
350  * 16: minimum blocksize (in samples) of all blocks in the stream
351  * 16: maximum blocksize (in samples) of all blocks in the stream
352  * 24: minimum framesize (in bytes) of all frames in the stream; 0 => unknown
353  * 24: maximum framesize (in bytes) of all frames in the stream; 0 => unknown
354  * 20: sample rate in Hz, 0 is invalid
355  *  3: (number of channels)-1
356  *  5: (bits per sample)-1
357  * 36: total samples, 0 => unknown
358  *128: MD5 digest of the original unencoded audio data
359  *---- -----------------
360  * 34  bytes total
361  */
362 typedef struct {
363         unsigned min_blocksize, max_blocksize;
364         unsigned min_framesize, max_framesize;
365         unsigned sample_rate;
366         unsigned channels;
367         unsigned bits_per_sample;
368         FLAC__uint64 total_samples;
369         FLAC__byte md5sum[16];
370 } FLAC__StreamMetaData_StreamInfo;
371
372 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /* = 16 bits */
373 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /* = 16 bits */
374 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /* = 24 bits */
375 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /* = 24 bits */
376 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /* = 20 bits */
377 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /* = 3 bits */
378 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /* = 5 bits */
379 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /* = 36 bits */
380 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /* = 128 bits */
381 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_LENGTH; /* = 34 bytes */
382
383 /*****************************************************************************
384  *
385  *   n: '0' bits
386  *----- -----------------
387  * n/8  bytes total
388  */
389 typedef struct {
390         int dummy; /* conceptually this is an empty struct since we don't store the padding bytes */
391                    /* empty structs are allowed by C++ but not C, hence the 'dummy' */
392 } FLAC__StreamMetaData_Padding;
393
394 /*****************************************************************************
395  *
396  *    32: Registered application ID
397  *     n: Application data
398  *------- -----------------
399  * 4+n/8  bytes total
400  */
401 typedef struct {
402         FLAC__byte id[4];
403         FLAC__byte *data;
404 } FLAC__StreamMetaData_Application;
405
406 extern const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /* = 32 bits */
407
408 /*****************************************************************************
409  *
410  *  64: sample number of target frame
411  *  64: offset, in bytes, of target frame with respect to beginning of first frame
412  *  16: number of samples in the target frame
413  *----- -----------------
414  *  18  bytes total
415  */
416 typedef struct {
417         FLAC__uint64 sample_number;
418         FLAC__uint64 stream_offset;
419         unsigned frame_samples;
420 } FLAC__StreamMetaData_SeekPoint;
421
422 extern const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; /* = 64 bits */
423 extern const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; /* = 64 bits */
424 extern const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; /* = 16 bits */
425 extern const unsigned FLAC__STREAM_METADATA_SEEKPOINT_LENGTH; /* = 18 bytes */
426
427 extern const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER; /* = 0xffffffffffffffff */
428
429 /*****************************************************************************
430  *
431  *      0: num_points is implied by the metadata block 'length' field (i.e. num_points = length / 18)
432  * n*18*8: seek points (n = num_points, 18 is the size of a seek point in bytes)
433  * ------- -----------------
434  *   n*18  bytes total
435  *
436  * NOTE: the seek points must be sorted by ascending sample number.
437  * NOTE: each seek point's sample number must be the first sample of the target frame.
438  * NOTE: each seek point's sample number must be unique within the table.
439  * NOTE: existence of a SEEKTABLE block implies a correct setting of total_samples in the stream_info block.
440  * NOTE: behavior is undefined when more than one SEEKTABLE block is present in a stream.
441  */
442 typedef struct {
443         unsigned num_points;
444         FLAC__StreamMetaData_SeekPoint *points;
445 } FLAC__StreamMetaData_SeekTable;
446
447 /*****************************************************************************
448  *
449  *     32: Entry length in bytes (WATCHOUT: this is little-endian coded)
450  *      n: Entry (n = 8 * length)
451  *-------- -----------------
452  * 32+n/8  bytes total
453  */
454 typedef struct {
455         FLAC__uint32 length;
456         FLAC__byte *entry;
457 } FLAC__StreamMetaData_VorbisComment_Entry;
458
459 extern const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /* = 32 bits */
460
461 /*****************************************************************************
462  *
463  *          n: Vendor string entry
464  *         32: Number of comment fields (WATCHOUT: this is little-endian coded)
465  *          m: Comment entries
466  *------------ -----------------
467  * (32+m+n)/8  bytes total
468  */
469 typedef struct {
470         FLAC__StreamMetaData_VorbisComment_Entry vendor_string;
471         FLAC__uint32 num_comments;
472         FLAC__StreamMetaData_VorbisComment_Entry *comments;
473 } FLAC__StreamMetaData_VorbisComment;
474
475 extern const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /* = 32 bits */
476
477 /*****************************************************************************
478  *
479  *  1: =1 if this is the last meta-data block, else =0
480  *  7: meta-data type (c.f. FLAC__MetaDataType)
481  * 24: length (in bytes) of the block-specific data to follow
482  *---- -----------------
483  *  4  bytes total
484  */
485 typedef struct {
486         FLAC__MetaDataType type;
487         FLAC__bool is_last;
488         unsigned length; /* in bytes */
489         union {
490                 FLAC__StreamMetaData_StreamInfo stream_info;
491                 FLAC__StreamMetaData_Padding padding;
492                 FLAC__StreamMetaData_Application application;
493                 FLAC__StreamMetaData_SeekTable seek_table;
494                 FLAC__StreamMetaData_VorbisComment vorbis_comment;
495         } data;
496 } FLAC__StreamMetaData;
497
498 extern const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /* = 1 bits */
499 extern const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /* = 7 bits */
500 extern const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /* = 24 bits */
501
502 /*****************************************************************************/
503
504
505 /*****************************************************************************
506  *
507  * Utility functions
508  *
509  *****************************************************************************/
510
511 /*
512  * Since the rules for valid sample rates are slightly complex, they are
513  * encapsulated here:
514  */
515 FLAC__bool FLAC__format_is_valid_sample_rate(unsigned sample_rate);
516
517 #ifdef __cplusplus
518 }
519 #endif
520
521 #endif