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  *---- -----------------
  70  * 18  bytes total
  71  */
  72 typedef struct {
  73         unsigned min_blocksize, max_blocksize;
  74         unsigned min_framesize, max_framesize;
  75         unsigned sample_rate;
  76         unsigned channels;
  77         unsigned bits_per_sample;
  78         uint64 total_samples;
  79 } FLAC__StreamMetaData_Encoding;
  80
  81 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MIN_BLOCK_SIZE_LEN; /* = 16 bits */
  82 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MAX_BLOCK_SIZE_LEN; /* = 16 bits */
  83 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MIN_FRAME_SIZE_LEN; /* = 24 bits */
  84 extern const unsigned FLAC__STREAM_METADATA_ENCODING_MAX_FRAME_SIZE_LEN; /* = 24 bits */
  85 extern const unsigned FLAC__STREAM_METADATA_ENCODING_SAMPLE_RATE_LEN; /* = 20 bits */
  86 extern const unsigned FLAC__STREAM_METADATA_ENCODING_CHANNELS_LEN; /* = 3 bits */
  87 extern const unsigned FLAC__STREAM_METADATA_ENCODING_BITS_PER_SAMPLE_LEN; /* = 5 bits */
  88 extern const unsigned FLAC__STREAM_METADATA_ENCODING_TOTAL_SAMPLES_LEN; /* = 36 bits */
  89 extern const unsigned FLAC__STREAM_METADATA_ENCODING_LENGTH; /* = 18 bytes */
  90
  91 /*****************************************************************************
  92  *
  93  *  1: =1 if this is the last meta-data block, else =0
  94  *  7: meta-data type (c.f. FLAC__MetaDataType)
  95  * 24: length (in bytes) of the block-specific data to follow
  96  *---- -----------------
  97  *  4  bytes total
  98  */
  99 typedef struct {
 100         FLAC__MetaDataType type;
 101         bool is_last;
 102         unsigned length; /* in bytes */
 103         union {
 104                 FLAC__StreamMetaData_Encoding encoding;
 105         } data;
 106 } FLAC__StreamMetaData;
 107
 108 extern const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /* = 1 bits */
 109 extern const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /* = 7 bits */
 110 extern const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /* = 24 bits */
 111
 112 /*****************************************************************************/
 113
 114 typedef enum {
 115         FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
 116 } FLAC__EntropyCodingMethodType;
 117
 118 /*****************************************************************************
 119  *
 120  *  4: partition order => (2 ** order) subdivisions
 121  */
 122 typedef struct {
 123         unsigned order;
 124         unsigned parameters[1 << FLAC__MAX_RICE_PARTITION_ORDER];
 125 } FLAC__EntropyCodingMethod_PartitionedRice;
 126
 127 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /* = 4 bits */
 128 extern const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /* = 4 bits */
 129
 130 /*****************************************************************************
 131  *
 132  *  2: entropy coding method:
 133  *     00: partitioned rice coding
 134  *     01-11: reserved
 135  *  ?: entropy coding method data
 136  */
 137 typedef struct {
 138         FLAC__EntropyCodingMethodType type;
 139         union {
 140                 FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
 141         } data;
 142 } FLAC__EntropyCodingMethod;
 143
 144 extern const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /* = 2 bits */
 145
 146 /*****************************************************************************/
 147
 148 typedef enum {
 149         FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0,
 150         FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1,
 151         FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2,
 152         FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3
 153 } FLAC__ChannelAssignment;
 154
 155 /*****************************************************************************
 156  *
 157  *  9: sync code '111111110'
 158  *  3: blocksize in samples
 159  *        000: get from stream header => implies constant blocksize throughout stream
 160  *        001: 192 samples (AES/EBU) => implies constant blocksize throughout stream
 161  *        010-101: 576 * (2^(2-n)) samples, i.e. 576/1152/2304/4608 => implies constant blocksize throughout stream
 162  *        110: get 8 bit (blocksize-1) from end of header => variable blocksize throughout stream unless it's the last frame
 163  *        111: get 16 bit (blocksize-1) from end of header => variable blocksize throughout stream unless it's the last frame
 164  *  4: sample rate:
 165  *        0000: get from stream header
 166  *        0001-0011: reserved
 167  *        0100: 8kHz
 168  *        0101: 16kHz
 169  *        0110: 22.05kHz
 170  *        0111: 24kHz
 171  *        1000: 32kHz
 172  *        1001: 44.1kHz
 173  *        1010: 48kHz
 174  *        1011: 96kHz
 175  *        1100: get 8 bit sample rate (in kHz) from end of header
 176  *        1101: get 16 bit sample rate (in Hz) from end of header
 177  *        1110: get 16 bit sample rate (in tens of Hz) from end of header
 178  *        1111: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
 179  *  4: channel assignment
 180  *     0000-0111: (number of independent channels)-1.  when == 0001, channel 0 is the left channel and channel 1 is the right
 181  *     1000: left/side stereo : channel 0 is the left             channel, channel 1 is the side(difference) channel
 182  *     1001: right/side stereo: channel 0 is the side(difference) channel, channel 1 is the right            channel
 183  *     1010: mid/side stereo  : channel 0 is the mid(average)     channel, channel 1 is the side(difference) channel
 184  *     1011-1111: reserved
 185  *  3: sample size in bits
 186  *        000: get from stream header
 187  *        001: 8 bits per sample
 188  *        010: 12 bits per sample
 189  *        011: reserved
 190  *        100: 16 bits per sample
 191  *        101: 20 bits per sample
 192  *        110: 24 bits per sample
 193  *        111: reserved
 194  *  1: zero pad, to prevent sync-fooling string of 1s (use to check for erroneous sync)
 195  *  ?: if(variable blocksize)
 196  *        8-56: 'UTF-8' coded sample number (decoded number is 0-36 bits) (use to check for erroneous sync)
 197  *     else
 198  *        8-48: 'UTF-8' coded frame number (decoded number is 0-31 bits) (use to check for erroneous sync)
 199  *  ?: if(blocksize bits == 11x)
 200  *        8/16 bit (blocksize-1)
 201  *  ?: if(sample rate bits == 11xx)
 202  *        8/16 bit sample rate
 203  *  8: CRC-8 (polynomial = x^8 + x^2 + x + 1) of everything before the crc, including the sync code
 204  */
 205 typedef struct {
 206         unsigned blocksize; /* in samples */
 207         unsigned sample_rate; /* in Hz */
 208         unsigned channels;
 209         FLAC__ChannelAssignment channel_assignment;
 210         unsigned bits_per_sample;
 211         union {
 212                 uint32 frame_number;
 213                 uint64 sample_number;
 214         } number;
 215 } FLAC__FrameHeader;
 216
 217 extern const unsigned FLAC__FRAME_HEADER_SYNC; /* = 0x1fe */
 218 extern const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /* = 9 bits */
 219 extern const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /* = 3 bits */
 220 extern const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /* = 4 bits */
 221 extern const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /* = 4 bits */
 222 extern const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /* = 3 bits */
 223 extern const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /* = 1 bit */
 224 extern const unsigned FLAC__FRAME_HEADER_CRC8_LEN; /* = 8 bits */
 225
 226 /*****************************************************************************/
 227
 228 typedef enum {
 229         FLAC__SUBFRAME_TYPE_CONSTANT = 0,
 230         FLAC__SUBFRAME_TYPE_VERBATIM = 1,
 231         FLAC__SUBFRAME_TYPE_FIXED = 2,
 232         FLAC__SUBFRAME_TYPE_LPC = 3
 233 } FLAC__SubframeType;
 234
 235 /*****************************************************************************
 236  *
 237  * n: constant value for signal; n = frame's bits-per-sample
 238  */
 239 typedef struct {
 240         int32 value;
 241 } FLAC__SubframeHeader_Constant;
 242
 243 /*****************************************************************************
 244  *
 245  * n*i: unencoded signal; n = frame's bits-per-sample, i = frame's blocksize
 246  */
 247 /* There is no (trivial) for structure FLAC__SubframeHeader_Verbatim */
 248
 249 /*****************************************************************************
 250  *
 251  *  n: unencoded warm-up samples (n = fixed-predictor order * bits per sample)
 252  *  ?: entropy coding method info
 253  *  ?: encoded residual ((blocksize minus fixed-predictor order) samples)
 254  *  The order is stored in the main subframe header
 255  */
 256 typedef struct {
 257         FLAC__EntropyCodingMethod entropy_coding_method;
 258         unsigned order;
 259         int32 warmup[FLAC__MAX_FIXED_ORDER];
 260 } FLAC__SubframeHeader_Fixed;
 261
 262 /*****************************************************************************
 263  *
 264  *  n: unencoded warm-up samples (n = lpc order * bits per sample)
 265  *  4: (qlp coeff precision in bits)-1 (1111 = invalid, use to check for erroneous sync)
 266  *  5: qlp shift needed in bits (signed)
 267  *  n: unencoded predictor coefficients (n = lpc order * qlp coeff precision)
 268  *  ?: entropy coding method info
 269  *  ?: encoded residual ((blocksize minus lpc order) samples)
 270  *  The order is stored in the main subframe header
 271  */
 272 typedef struct {
 273         FLAC__EntropyCodingMethod entropy_coding_method;
 274         unsigned order;
 275         unsigned qlp_coeff_precision;
 276         int quantization_level;
 277         int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
 278         int32 warmup[FLAC__MAX_LPC_ORDER];
 279 } FLAC__SubframeHeader_LPC;
 280
 281 extern const unsigned FLAC__SUBFRAME_HEADER_LPC_QLP_COEFF_PRECISION_LEN; /* = 4 bits */
 282 extern const unsigned FLAC__SUBFRAME_HEADER_LPC_QLP_SHIFT_LEN; /* = 5 bits */
 283
 284 /*****************************************************************************
 285  *
 286  *  8: subframe type
 287  *       xxxxxxx1: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
 288  *       00000000: constant value
 289  *       00000010: verbatim
 290  *       000001x0: reserved
 291  *       00001xx0: reserved
 292  *       0001xxx0: fixed predictor, xxx=order <= 4, else reserved
 293  *       001xxxx0: reserved
 294  *       01xxxxx0: lpc, xxxxx=order-1
 295  *       1xxxxxxx: invalid, to prevent sync-fooling string of 1s (use to check for erroneous sync)
 296  *  ?: subframe-specific header (c.f. FLAC__SubframeHeader_*)
 297  */
 298 typedef struct {
 299         FLAC__SubframeType type;
 300         union {
 301                 FLAC__SubframeHeader_Constant constant;
 302                 FLAC__SubframeHeader_Fixed fixed;
 303                 FLAC__SubframeHeader_LPC lpc;
 304         } data; /* data will be undefined for FLAC__SUBFRAME_TYPE_VERBATIM */
 305 } FLAC__SubframeHeader;
 306
 307 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_CONSTANT; /* = 0x00 */
 308 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_VERBATIM; /* = 0x02 */
 309 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_FIXED; /* = 0x10 */
 310 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_LPC; /* = 0x40 */
 311 extern const unsigned FLAC__SUBFRAME_HEADER_TYPE_LEN; /* = 8 bits */
 312
 313 /*****************************************************************************/
 314
 315 #endif