change min bps from 1 to 4
[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 #define FLAC__MIN_BITS_PER_SAMPLE (4u)
30 /*NOTE: only up to 24 because of the current predictor coefficient quantization and the fact we use int32s for all work */
31 #define FLAC__MAX_BITS_PER_SAMPLE (24u)
32 /* the following is ((2 ** 20) - 1) div 10 */
33 #define FLAC__MAX_SAMPLE_RATE (1048570u)
34 #define FLAC__MAX_LPC_ORDER (32u)
35 #define FLAC__MIN_QLP_COEFF_PRECISION (5u)
36 /* changing this also means changing all of fixed.c and more, so DON'T! */
37 #define FLAC__MAX_FIXED_ORDER (4u)
38 #define FLAC__MAX_RICE_PARTITION_ORDER (15u)
39
40 /* VERSION should come from configure */
41 #ifdef VERSION
42 #define FLAC__VERSION_STRING VERSION
43 #else
44 #define FLAC__VERSION_STRING "0.9"
45 #endif
46
47 extern const byte     FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */;
48 extern const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */;
49 extern const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */;
50
51
52 /*****************************************************************************
53  *
54  * NOTE: Within the bitstream, all fixed-width numbers are big-endian coded.
55  *       All numbers are unsigned unless otherwise noted.
56  *
57  *****************************************************************************/
58
59
60 /*****************************************************************************
61  *
62  * Subframe structures
63  *
64  *****************************************************************************/
65
66 /*****************************************************************************/
67
68 typedef enum {
69         FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
70 } FLAC__EntropyCodingMethodType;
71 extern const char *FLAC__EntropyCodingMethodTypeString[];
72
73 /*****************************************************************************
74  *
75  *  4: partition order => (2 ** order) subdivisions
76  */
77 typedef struct {
78         unsigned order;
79         unsigned parameters[1 << FLAC__MAX_RICE_PARTITION_ORDER];
80 } FLAC__EntropyCodingMethod_PartitionedRice;
81
82 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /* = 4 bits */
83 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /* = 4 bits */
84
85 /*****************************************************************************
86  *
87  *  2: entropy coding method:
88  *     00: partitioned rice coding
89  *     01-11: reserved
90  *  ?: entropy coding method data
91  */
92 typedef struct {
93         FLAC__EntropyCodingMethodType type;
94         union {
95                 FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
96         } data;
97 } FLAC__EntropyCodingMethod;
98
99 extern const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /* = 2 bits */
100
101 /*****************************************************************************/
102
103 typedef enum {
104         FLAC__SUBFRAME_TYPE_CONSTANT = 0,
105         FLAC__SUBFRAME_TYPE_VERBATIM = 1,
106         FLAC__SUBFRAME_TYPE_FIXED = 2,
107         FLAC__SUBFRAME_TYPE_LPC = 3
108 } FLAC__SubframeType;
109 extern const char *FLAC__SubframeTypeString[];
110
111 /*****************************************************************************
112  *
113  * n: constant value for signal; n = frame's bits-per-sample
114  */
115 typedef struct {
116         int32 value;
117 } FLAC__Subframe_Constant;
118
119 /*****************************************************************************
120  *
121  * n*i: unencoded signal; n = frame's bits-per-sample, i = frame's blocksize
122  */
123 typedef struct {
124         const int32 *data;
125 } FLAC__Subframe_Verbatim;
126
127 /*****************************************************************************
128  *
129  *  n: unencoded warm-up samples (n = fixed-predictor order * bits per sample)
130  *  ?: entropy coding method info
131  *  ?: encoded residual ((blocksize minus fixed-predictor order) samples)
132  *  The order is stored in the main subframe header
133  */
134 typedef struct {
135         FLAC__EntropyCodingMethod entropy_coding_method;
136         unsigned order;
137         int32 warmup[FLAC__MAX_FIXED_ORDER];
138         const int32 *residual;
139 } FLAC__Subframe_Fixed;
140
141 /*****************************************************************************
142  *
143  *  n: unencoded warm-up samples (n = lpc order * bits per sample)
144  *  4: (qlp coeff precision in bits)-1 (1111 = invalid, use to check for erroneous sync)
145  *  5: qlp shift needed in bits (signed)
146  *  n: unencoded predictor coefficients (n = lpc order * qlp coeff precision)
147  *  ?: entropy coding method info
148  *  ?: encoded residual ((blocksize minus lpc order) samples)
149  *  The order is stored in the main subframe header
150  */
151 typedef struct {
152         FLAC__EntropyCodingMethod entropy_coding_method;
153         unsigned order;
154         unsigned qlp_coeff_precision;
155         int quantization_level;
156         int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
157         int32 warmup[FLAC__MAX_LPC_ORDER];
158         const int32 *residual;
159 } FLAC__Subframe_LPC;
160
161 extern const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /* = 4 bits */
162 extern const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /* = 5 bits */
163
164 /*****************************************************************************
165  *
166  *  1: zero pad, to prevent sync-fooling string of 1s (use to check for erroneous sync)
167  *  6: subframe type
168  *       000000: constant value
169  *       000001: verbatim
170  *       00001x: reserved
171  *       0001xx: reserved
172  *       001xxx: fixed predictor, xxx=order <= 4, else reserved
173  *       01xxxx: reserved
174  *       1xxxxx: lpc, xxxxx=order-1
175  *  1: 'wasted bits' flag
176  *       0: no wasted bits in source subblock
177  *       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.
178  *             ?: unary coded (n-1)
179  *  ?: subframe-specific data (c.f. FLAC__Subframe_*)
180  */
181 typedef struct {
182         FLAC__SubframeType type;
183         union {
184                 FLAC__Subframe_Constant constant;
185                 FLAC__Subframe_Fixed fixed;
186                 FLAC__Subframe_LPC lpc;
187                 FLAC__Subframe_Verbatim verbatim;
188         } data;
189         unsigned wasted_bits;
190 } FLAC__Subframe;
191
192 extern const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; /* = 1 bit */
193 extern const unsigned FLAC__SUBFRAME_TYPE_LEN; /* = 6 bits */
194 extern const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /* = 1 bit */
195
196 extern const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /* = 0x00 */
197 extern const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /* = 0x02 */
198 extern const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /* = 0x10 */
199 extern const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /* = 0x40 */
200
201 /*****************************************************************************/
202
203
204 /*****************************************************************************
205  *
206  * Frame structures
207  *
208  *****************************************************************************/
209
210 typedef enum {
211         FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0,
212         FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1,
213         FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2,
214         FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3
215 } FLAC__ChannelAssignment;
216 extern const char *FLAC__ChannelAssignmentString[];
217
218 /*****************************************************************************
219  *
220  * 14: sync code '11111111111110'
221  *  2: reserved
222  *        00: currently required value
223  *        01-11: reserved
224  *  4: blocksize in samples
225  *        0000: get from stream header => implies constant blocksize throughout stream
226  *        0001: 192 samples (AES/EBU) => implies constant blocksize throughout stream
227  *        0010-0101: 576 * (2^(n-2)) samples, i.e. 576/1152/2304/4608 => implies constant blocksize throughout stream
228  *        0110: get 8 bit (blocksize-1) from end of header => possibly variable blocksize throughout stream unless it's the last frame
229  *        0111: get 16 bit (blocksize-1) from end of header => possibly variable blocksize throughout stream unless it's the last frame
230  *        1000-1111: 256 * (2^(n-8)) samples, i.e. 256/512/1024/2048/4096/8192/16384/32768 => implies constant blocksize throughout stream
231  *  4: sample rate:
232  *        0000: get from stream header
233  *        0001-0011: reserved
234  *        0100: 8kHz
235  *        0101: 16kHz
236  *        0110: 22.05kHz
237  *        0111: 24kHz
238  *        1000: 32kHz
239  *        1001: 44.1kHz
240  *        1010: 48kHz
241  *        1011: 96kHz
242  *        1100: get 8 bit sample rate (in kHz) from end of header
243  *        1101: get 16 bit sample rate (in Hz) from end of header
244  *        1110: get 16 bit sample rate (in tens of Hz) from end of header
245  *        1111: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
246  *  4: channel assignment
247  *     0000-0111: (number of independent channels)-1.  when == 0001, channel 0 is the left channel and channel 1 is the right
248  *     1000: left/side stereo : channel 0 is the left             channel, channel 1 is the side(difference) channel
249  *     1001: right/side stereo: channel 0 is the side(difference) channel, channel 1 is the right            channel
250  *     1010: mid/side stereo  : channel 0 is the mid(average)     channel, channel 1 is the side(difference) channel
251  *     1011-1111: reserved
252  *  3: sample size in bits
253  *        000: get from stream header
254  *        001: 8 bits per sample
255  *        010: 12 bits per sample
256  *        011: reserved
257  *        100: 16 bits per sample
258  *        101: 20 bits per sample
259  *        110: 24 bits per sample
260  *        111: reserved
261  *  1: zero pad, to prevent sync-fooling string of 1s (use to check for erroneous sync)
262  *  ?: if(variable blocksize)
263  *        8-56: 'UTF-8' coded sample number (decoded number is 0-36 bits) (use to check for erroneous sync)
264  *     else
265  *        8-48: 'UTF-8' coded frame number (decoded number is 0-31 bits) (use to check for erroneous sync)
266  *  ?: if(blocksize bits == 11x)
267  *        8/16 bit (blocksize-1)
268  *  ?: if(sample rate bits == 11xx)
269  *        8/16 bit sample rate
270  *  8: CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0) of everything before the crc, including the sync code
271  */
272 typedef struct {
273         unsigned blocksize; /* in samples */
274         unsigned sample_rate; /* in Hz */
275         unsigned channels;
276         FLAC__ChannelAssignment channel_assignment;
277         unsigned bits_per_sample;
278         union {
279                 uint32 frame_number;
280                 uint64 sample_number;
281         } number;
282         uint8 crc;
283 } FLAC__FrameHeader;
284
285 extern const unsigned FLAC__FRAME_HEADER_SYNC; /* = 0x3ffe */
286 extern const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /* = 14 bits */
287 extern const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /* = 2 bits */
288 extern const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /* = 4 bits */
289 extern const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /* = 4 bits */
290 extern const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /* = 4 bits */
291 extern const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /* = 3 bits */
292 extern const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /* = 1 bit */
293 extern const unsigned FLAC__FRAME_HEADER_CRC_LEN; /* = 8 bits */
294
295 /*****************************************************************************
296  *
297  * 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
298  */
299 typedef struct {
300         uint16 crc;
301 } FLAC__FrameFooter;
302
303 extern const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /* = 16 bits */
304
305 typedef struct {
306         FLAC__FrameHeader header;
307         FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
308         FLAC__FrameFooter footer;
309 } FLAC__Frame;
310
311 /*****************************************************************************/
312
313
314 /*****************************************************************************
315  *
316  * Meta-data structures
317  *
318  *****************************************************************************/
319
320 typedef enum {
321         FLAC__METADATA_TYPE_STREAMINFO = 0,
322         FLAC__METADATA_TYPE_PADDING = 1,
323         FLAC__METADATA_TYPE_APPLICATION = 2
324 } FLAC__MetaDataType;
325 extern const char *FLAC__MetaDataTypeString[];
326
327 /*****************************************************************************
328  *
329  * 16: minimum blocksize (in samples) of all blocks in the stream
330  * 16: maximum blocksize (in samples) of all blocks in the stream
331  * 24: minimum framesize (in bytes) of all frames in the stream; 0 => unknown
332  * 24: maximum framesize (in bytes) of all frames in the stream; 0 => unknown
333  * 20: sample rate in Hz, 0 is invalid
334  *  3: (number of channels)-1
335  *  5: (bits per sample)-1
336  * 36: total samples, 0 => unknown
337  *128: MD5 digest of the original unencoded audio data
338  *---- -----------------
339  * 34  bytes total
340  */
341 typedef struct {
342         unsigned min_blocksize, max_blocksize;
343         unsigned min_framesize, max_framesize;
344         unsigned sample_rate;
345         unsigned channels;
346         unsigned bits_per_sample;
347         uint64 total_samples;
348         byte md5sum[16];
349 } FLAC__StreamMetaData_StreamInfo;
350
351 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /* = 16 bits */
352 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /* = 16 bits */
353 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /* = 24 bits */
354 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /* = 24 bits */
355 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /* = 20 bits */
356 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /* = 3 bits */
357 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /* = 5 bits */
358 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /* = 36 bits */
359 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /* = 128 bits */
360 extern const unsigned FLAC__STREAM_METADATA_STREAMINFO_LENGTH; /* = 34 bytes */
361
362 /*****************************************************************************
363  *
364  *   n: '0' bits
365  *----- -----------------
366  * n/8  bytes total
367  */
368 typedef struct {
369         int dummy; /* conceptually this is an empty struct since we don't store the padding bytes */
370 } FLAC__StreamMetaData_Padding;
371
372 /*****************************************************************************
373  *
374  *    32: Registered application ID
375  *     n: Application data
376  *------- -----------------
377  * 4+n/8  bytes total
378  */
379 typedef struct {
380         byte id[16];
381         byte *data;
382 } FLAC__StreamMetaData_Application;
383
384 extern const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /* = 32 bits */
385
386 /*****************************************************************************
387  *
388  *  1: =1 if this is the last meta-data block, else =0
389  *  7: meta-data type (c.f. FLAC__MetaDataType)
390  * 24: length (in bytes) of the block-specific data to follow
391  *---- -----------------
392  *  4  bytes total
393  */
394 typedef struct {
395         FLAC__MetaDataType type;
396         bool is_last;
397         unsigned length; /* in bytes */
398         union {
399                 FLAC__StreamMetaData_StreamInfo stream_info;
400                 FLAC__StreamMetaData_Padding padding;
401                 FLAC__StreamMetaData_Application application;
402         } data;
403 } FLAC__StreamMetaData;
404
405 extern const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /* = 1 bits */
406 extern const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /* = 7 bits */
407 extern const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /* = 24 bits */
408
409 /*****************************************************************************/
410
411
412 /*****************************************************************************
413  *
414  * Stream structures
415  *
416  *****************************************************************************/
417
418 typedef struct {
419         FLAC__StreamMetaData_StreamInfo stream_info;
420         FLAC__Frame *frames;
421 } FLAC__Stream;
422
423 /*****************************************************************************/
424
425 #endif