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