| 1 | /* libFLAC - Free Lossless Audio Codec library |
| 2 | * Copyright (C) 2000-2009 Josh Coalson |
| 3 | * Copyright (C) 2011-2016 Xiph.Org Foundation |
| 4 | * |
| 5 | * Redistribution and use in source and binary forms, with or without |
| 6 | * modification, are permitted provided that the following conditions |
| 7 | * are met: |
| 8 | * |
| 9 | * - Redistributions of source code must retain the above copyright |
| 10 | * notice, this list of conditions and the following disclaimer. |
| 11 | * |
| 12 | * - Redistributions in binary form must reproduce the above copyright |
| 13 | * notice, this list of conditions and the following disclaimer in the |
| 14 | * documentation and/or other materials provided with the distribution. |
| 15 | * |
| 16 | * - Neither the name of the Xiph.org Foundation nor the names of its |
| 17 | * contributors may be used to endorse or promote products derived from |
| 18 | * this software without specific prior written permission. |
| 19 | * |
| 20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 21 | * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 22 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 23 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR |
| 24 | * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| 25 | * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 26 | * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
| 27 | * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
| 28 | * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
| 29 | * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| 30 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 31 | */ |
| 32 | |
| 33 | #ifndef FLAC__FORMAT_H |
| 34 | #define FLAC__FORMAT_H |
| 35 | |
| 36 | #include "export.h" |
| 37 | #include "ordinals.h" |
| 38 | |
| 39 | #ifdef __cplusplus |
| 40 | extern "C" { |
| 41 | #endif |
| 42 | |
| 43 | /** \file include/FLAC/format.h |
| 44 | * |
| 45 | * \brief |
| 46 | * This module contains structure definitions for the representation |
| 47 | * of FLAC format components in memory. These are the basic |
| 48 | * structures used by the rest of the interfaces. |
| 49 | * |
| 50 | * See the detailed documentation in the |
| 51 | * \link flac_format format \endlink module. |
| 52 | */ |
| 53 | |
| 54 | /** \defgroup flac_format FLAC/format.h: format components |
| 55 | * \ingroup flac |
| 56 | * |
| 57 | * \brief |
| 58 | * This module contains structure definitions for the representation |
| 59 | * of FLAC format components in memory. These are the basic |
| 60 | * structures used by the rest of the interfaces. |
| 61 | * |
| 62 | * First, you should be familiar with the |
| 63 | * <A HREF="../format.html">FLAC format</A>. Many of the values here |
| 64 | * follow directly from the specification. As a user of libFLAC, the |
| 65 | * interesting parts really are the structures that describe the frame |
| 66 | * header and metadata blocks. |
| 67 | * |
| 68 | * The format structures here are very primitive, designed to store |
| 69 | * information in an efficient way. Reading information from the |
| 70 | * structures is easy but creating or modifying them directly is |
| 71 | * more complex. For the most part, as a user of a library, editing |
| 72 | * is not necessary; however, for metadata blocks it is, so there are |
| 73 | * convenience functions provided in the \link flac_metadata metadata |
| 74 | * module \endlink to simplify the manipulation of metadata blocks. |
| 75 | * |
| 76 | * \note |
| 77 | * It's not the best convention, but symbols ending in _LEN are in bits |
| 78 | * and _LENGTH are in bytes. _LENGTH symbols are \#defines instead of |
| 79 | * global variables because they are usually used when declaring byte |
| 80 | * arrays and some compilers require compile-time knowledge of array |
| 81 | * sizes when declared on the stack. |
| 82 | * |
| 83 | * \{ |
| 84 | */ |
| 85 | |
| 86 | |
| 87 | /* |
| 88 | Most of the values described in this file are defined by the FLAC |
| 89 | format specification. There is nothing to tune here. |
| 90 | */ |
| 91 | |
| 92 | /** The largest legal metadata type code. */ |
| 93 | #define FLAC__MAX_METADATA_TYPE_CODE (126u) |
| 94 | |
| 95 | /** The minimum block size, in samples, permitted by the format. */ |
| 96 | #define FLAC__MIN_BLOCK_SIZE (16u) |
| 97 | |
| 98 | /** The maximum block size, in samples, permitted by the format. */ |
| 99 | #define FLAC__MAX_BLOCK_SIZE (65535u) |
| 100 | |
| 101 | /** The maximum block size, in samples, permitted by the FLAC subset for |
| 102 | * sample rates up to 48kHz. */ |
| 103 | #define FLAC__SUBSET_MAX_BLOCK_SIZE_48000HZ (4608u) |
| 104 | |
| 105 | /** The maximum number of channels permitted by the format. */ |
| 106 | #define FLAC__MAX_CHANNELS (8u) |
| 107 | |
| 108 | /** The minimum sample resolution permitted by the format. */ |
| 109 | #define FLAC__MIN_BITS_PER_SAMPLE (4u) |
| 110 | |
| 111 | /** The maximum sample resolution permitted by the format. */ |
| 112 | #define FLAC__MAX_BITS_PER_SAMPLE (32u) |
| 113 | |
| 114 | /** The maximum sample resolution permitted by libFLAC. |
| 115 | * |
| 116 | * \warning |
| 117 | * FLAC__MAX_BITS_PER_SAMPLE is the limit of the FLAC format. However, |
| 118 | * the reference encoder/decoder is currently limited to 24 bits because |
| 119 | * of prevalent 32-bit math, so make sure and use this value when |
| 120 | * appropriate. |
| 121 | */ |
| 122 | #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u) |
| 123 | |
| 124 | /** The maximum sample rate permitted by the format. The value is |
| 125 | * ((2 ^ 16) - 1) * 10; see <A HREF="../format.html">FLAC format</A> |
| 126 | * as to why. |
| 127 | */ |
| 128 | #define FLAC__MAX_SAMPLE_RATE (655350u) |
| 129 | |
| 130 | /** The maximum LPC order permitted by the format. */ |
| 131 | #define FLAC__MAX_LPC_ORDER (32u) |
| 132 | |
| 133 | /** The maximum LPC order permitted by the FLAC subset for sample rates |
| 134 | * up to 48kHz. */ |
| 135 | #define FLAC__SUBSET_MAX_LPC_ORDER_48000HZ (12u) |
| 136 | |
| 137 | /** The minimum quantized linear predictor coefficient precision |
| 138 | * permitted by the format. |
| 139 | */ |
| 140 | #define FLAC__MIN_QLP_COEFF_PRECISION (5u) |
| 141 | |
| 142 | /** The maximum quantized linear predictor coefficient precision |
| 143 | * permitted by the format. |
| 144 | */ |
| 145 | #define FLAC__MAX_QLP_COEFF_PRECISION (15u) |
| 146 | |
| 147 | /** The maximum order of the fixed predictors permitted by the format. */ |
| 148 | #define FLAC__MAX_FIXED_ORDER (4u) |
| 149 | |
| 150 | /** The maximum Rice partition order permitted by the format. */ |
| 151 | #define FLAC__MAX_RICE_PARTITION_ORDER (15u) |
| 152 | |
| 153 | /** The maximum Rice partition order permitted by the FLAC Subset. */ |
| 154 | #define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u) |
| 155 | |
| 156 | /** The version string of the release, stamped onto the libraries and binaries. |
| 157 | * |
| 158 | * \note |
| 159 | * This does not correspond to the shared library version number, which |
| 160 | * is used to determine binary compatibility. |
| 161 | */ |
| 162 | extern FLAC_API const char *FLAC__VERSION_STRING; |
| 163 | |
| 164 | /** The vendor string inserted by the encoder into the VORBIS_COMMENT block. |
| 165 | * This is a NUL-terminated ASCII string; when inserted into the |
| 166 | * VORBIS_COMMENT the trailing null is stripped. |
| 167 | */ |
| 168 | extern FLAC_API const char *FLAC__VENDOR_STRING; |
| 169 | |
| 170 | /** The byte string representation of the beginning of a FLAC stream. */ |
| 171 | extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */ |
| 172 | |
| 173 | /** The 32-bit integer big-endian representation of the beginning of |
| 174 | * a FLAC stream. |
| 175 | */ |
| 176 | extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */ |
| 177 | |
| 178 | /** The length of the FLAC signature in bits. */ |
| 179 | extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */ |
| 180 | |
| 181 | /** The length of the FLAC signature in bytes. */ |
| 182 | #define FLAC__STREAM_SYNC_LENGTH (4u) |
| 183 | |
| 184 | |
| 185 | /***************************************************************************** |
| 186 | * |
| 187 | * Subframe structures |
| 188 | * |
| 189 | *****************************************************************************/ |
| 190 | |
| 191 | /*****************************************************************************/ |
| 192 | |
| 193 | /** An enumeration of the available entropy coding methods. */ |
| 194 | typedef enum { |
| 195 | FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0, |
| 196 | /**< Residual is coded by partitioning into contexts, each with it's own |
| 197 | * 4-bit Rice parameter. */ |
| 198 | |
| 199 | FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2 = 1 |
| 200 | /**< Residual is coded by partitioning into contexts, each with it's own |
| 201 | * 5-bit Rice parameter. */ |
| 202 | } FLAC__EntropyCodingMethodType; |
| 203 | |
| 204 | /** Maps a FLAC__EntropyCodingMethodType to a C string. |
| 205 | * |
| 206 | * Using a FLAC__EntropyCodingMethodType as the index to this array will |
| 207 | * give the string equivalent. The contents should not be modified. |
| 208 | */ |
| 209 | extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[]; |
| 210 | |
| 211 | |
| 212 | /** Contents of a Rice partitioned residual |
| 213 | */ |
| 214 | typedef struct { |
| 215 | |
| 216 | unsigned *parameters; |
| 217 | /**< The Rice parameters for each context. */ |
| 218 | |
| 219 | unsigned *raw_bits; |
| 220 | /**< Widths for escape-coded partitions. Will be non-zero for escaped |
| 221 | * partitions and zero for unescaped partitions. |
| 222 | */ |
| 223 | |
| 224 | unsigned capacity_by_order; |
| 225 | /**< The capacity of the \a parameters and \a raw_bits arrays |
| 226 | * specified as an order, i.e. the number of array elements |
| 227 | * allocated is 2 ^ \a capacity_by_order. |
| 228 | */ |
| 229 | } FLAC__EntropyCodingMethod_PartitionedRiceContents; |
| 230 | |
| 231 | /** Header for a Rice partitioned residual. (c.f. <A HREF="../format.html#partitioned_rice">format specification</A>) |
| 232 | */ |
| 233 | typedef struct { |
| 234 | |
| 235 | unsigned order; |
| 236 | /**< The partition order, i.e. # of contexts = 2 ^ \a order. */ |
| 237 | |
| 238 | const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents; |
| 239 | /**< The context's Rice parameters and/or raw bits. */ |
| 240 | |
| 241 | } FLAC__EntropyCodingMethod_PartitionedRice; |
| 242 | |
| 243 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /**< == 4 (bits) */ |
| 244 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /**< == 4 (bits) */ |
| 245 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN; /**< == 5 (bits) */ |
| 246 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; /**< == 5 (bits) */ |
| 247 | |
| 248 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER; |
| 249 | /**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN)-1 */ |
| 250 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_ESCAPE_PARAMETER; |
| 251 | /**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN)-1 */ |
| 252 | |
| 253 | /** Header for the entropy coding method. (c.f. <A HREF="../format.html#residual">format specification</A>) |
| 254 | */ |
| 255 | typedef struct { |
| 256 | FLAC__EntropyCodingMethodType type; |
| 257 | union { |
| 258 | FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice; |
| 259 | } data; |
| 260 | } FLAC__EntropyCodingMethod; |
| 261 | |
| 262 | extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /**< == 2 (bits) */ |
| 263 | |
| 264 | /*****************************************************************************/ |
| 265 | |
| 266 | /** An enumeration of the available subframe types. */ |
| 267 | typedef enum { |
| 268 | FLAC__SUBFRAME_TYPE_CONSTANT = 0, /**< constant signal */ |
| 269 | FLAC__SUBFRAME_TYPE_VERBATIM = 1, /**< uncompressed signal */ |
| 270 | FLAC__SUBFRAME_TYPE_FIXED = 2, /**< fixed polynomial prediction */ |
| 271 | FLAC__SUBFRAME_TYPE_LPC = 3 /**< linear prediction */ |
| 272 | } FLAC__SubframeType; |
| 273 | |
| 274 | /** Maps a FLAC__SubframeType to a C string. |
| 275 | * |
| 276 | * Using a FLAC__SubframeType as the index to this array will |
| 277 | * give the string equivalent. The contents should not be modified. |
| 278 | */ |
| 279 | extern FLAC_API const char * const FLAC__SubframeTypeString[]; |
| 280 | |
| 281 | |
| 282 | /** CONSTANT subframe. (c.f. <A HREF="../format.html#subframe_constant">format specification</A>) |
| 283 | */ |
| 284 | typedef struct { |
| 285 | FLAC__int32 value; /**< The constant signal value. */ |
| 286 | } FLAC__Subframe_Constant; |
| 287 | |
| 288 | |
| 289 | /** VERBATIM subframe. (c.f. <A HREF="../format.html#subframe_verbatim">format specification</A>) |
| 290 | */ |
| 291 | typedef struct { |
| 292 | const FLAC__int32 *data; /**< A pointer to verbatim signal. */ |
| 293 | } FLAC__Subframe_Verbatim; |
| 294 | |
| 295 | |
| 296 | /** FIXED subframe. (c.f. <A HREF="../format.html#subframe_fixed">format specification</A>) |
| 297 | */ |
| 298 | typedef struct { |
| 299 | FLAC__EntropyCodingMethod entropy_coding_method; |
| 300 | /**< The residual coding method. */ |
| 301 | |
| 302 | unsigned order; |
| 303 | /**< The polynomial order. */ |
| 304 | |
| 305 | FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER]; |
| 306 | /**< Warmup samples to prime the predictor, length == order. */ |
| 307 | |
| 308 | const FLAC__int32 *residual; |
| 309 | /**< The residual signal, length == (blocksize minus order) samples. */ |
| 310 | } FLAC__Subframe_Fixed; |
| 311 | |
| 312 | |
| 313 | /** LPC subframe. (c.f. <A HREF="../format.html#subframe_lpc">format specification</A>) |
| 314 | */ |
| 315 | typedef struct { |
| 316 | FLAC__EntropyCodingMethod entropy_coding_method; |
| 317 | /**< The residual coding method. */ |
| 318 | |
| 319 | unsigned order; |
| 320 | /**< The FIR order. */ |
| 321 | |
| 322 | unsigned qlp_coeff_precision; |
| 323 | /**< Quantized FIR filter coefficient precision in bits. */ |
| 324 | |
| 325 | int quantization_level; |
| 326 | /**< The qlp coeff shift needed. */ |
| 327 | |
| 328 | FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER]; |
| 329 | /**< FIR filter coefficients. */ |
| 330 | |
| 331 | FLAC__int32 warmup[FLAC__MAX_LPC_ORDER]; |
| 332 | /**< Warmup samples to prime the predictor, length == order. */ |
| 333 | |
| 334 | const FLAC__int32 *residual; |
| 335 | /**< The residual signal, length == (blocksize minus order) samples. */ |
| 336 | } FLAC__Subframe_LPC; |
| 337 | |
| 338 | extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /**< == 4 (bits) */ |
| 339 | extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /**< == 5 (bits) */ |
| 340 | |
| 341 | |
| 342 | /** FLAC subframe structure. (c.f. <A HREF="../format.html#subframe">format specification</A>) |
| 343 | */ |
| 344 | typedef struct { |
| 345 | FLAC__SubframeType type; |
| 346 | union { |
| 347 | FLAC__Subframe_Constant constant; |
| 348 | FLAC__Subframe_Fixed fixed; |
| 349 | FLAC__Subframe_LPC lpc; |
| 350 | FLAC__Subframe_Verbatim verbatim; |
| 351 | } data; |
| 352 | unsigned wasted_bits; |
| 353 | } FLAC__Subframe; |
| 354 | |
| 355 | /** == 1 (bit) |
| 356 | * |
| 357 | * This used to be a zero-padding bit (hence the name |
| 358 | * FLAC__SUBFRAME_ZERO_PAD_LEN) but is now a reserved bit. It still has a |
| 359 | * mandatory value of \c 0 but in the future may take on the value \c 0 or \c 1 |
| 360 | * to mean something else. |
| 361 | */ |
| 362 | extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; |
| 363 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; /**< == 6 (bits) */ |
| 364 | extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /**< == 1 (bit) */ |
| 365 | |
| 366 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /**< = 0x00 */ |
| 367 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /**< = 0x02 */ |
| 368 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /**< = 0x10 */ |
| 369 | extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /**< = 0x40 */ |
| 370 | |
| 371 | /*****************************************************************************/ |
| 372 | |
| 373 | |
| 374 | /***************************************************************************** |
| 375 | * |
| 376 | * Frame structures |
| 377 | * |
| 378 | *****************************************************************************/ |
| 379 | |
| 380 | /** An enumeration of the available channel assignments. */ |
| 381 | typedef enum { |
| 382 | FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, /**< independent channels */ |
| 383 | FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, /**< left+side stereo */ |
| 384 | FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, /**< right+side stereo */ |
| 385 | FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 /**< mid+side stereo */ |
| 386 | } FLAC__ChannelAssignment; |
| 387 | |
| 388 | /** Maps a FLAC__ChannelAssignment to a C string. |
| 389 | * |
| 390 | * Using a FLAC__ChannelAssignment as the index to this array will |
| 391 | * give the string equivalent. The contents should not be modified. |
| 392 | */ |
| 393 | extern FLAC_API const char * const FLAC__ChannelAssignmentString[]; |
| 394 | |
| 395 | /** An enumeration of the possible frame numbering methods. */ |
| 396 | typedef enum { |
| 397 | FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, /**< number contains the frame number */ |
| 398 | FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER /**< number contains the sample number of first sample in frame */ |
| 399 | } FLAC__FrameNumberType; |
| 400 | |
| 401 | /** Maps a FLAC__FrameNumberType to a C string. |
| 402 | * |
| 403 | * Using a FLAC__FrameNumberType as the index to this array will |
| 404 | * give the string equivalent. The contents should not be modified. |
| 405 | */ |
| 406 | extern FLAC_API const char * const FLAC__FrameNumberTypeString[]; |
| 407 | |
| 408 | |
| 409 | /** FLAC frame header structure. (c.f. <A HREF="../format.html#frame_header">format specification</A>) |
| 410 | */ |
| 411 | typedef struct { |
| 412 | unsigned blocksize; |
| 413 | /**< The number of samples per subframe. */ |
| 414 | |
| 415 | unsigned sample_rate; |
| 416 | /**< The sample rate in Hz. */ |
| 417 | |
| 418 | unsigned channels; |
| 419 | /**< The number of channels (== number of subframes). */ |
| 420 | |
| 421 | FLAC__ChannelAssignment channel_assignment; |
| 422 | /**< The channel assignment for the frame. */ |
| 423 | |
| 424 | unsigned bits_per_sample; |
| 425 | /**< The sample resolution. */ |
| 426 | |
| 427 | FLAC__FrameNumberType number_type; |
| 428 | /**< The numbering scheme used for the frame. As a convenience, the |
| 429 | * decoder will always convert a frame number to a sample number because |
| 430 | * the rules are complex. */ |
| 431 | |
| 432 | union { |
| 433 | FLAC__uint32 frame_number; |
| 434 | FLAC__uint64 sample_number; |
| 435 | } number; |
| 436 | /**< The frame number or sample number of first sample in frame; |
| 437 | * use the \a number_type value to determine which to use. */ |
| 438 | |
| 439 | FLAC__uint8 crc; |
| 440 | /**< CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0) |
| 441 | * of the raw frame header bytes, meaning everything before the CRC byte |
| 442 | * including the sync code. |
| 443 | */ |
| 444 | } FLAC__FrameHeader; |
| 445 | |
| 446 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; /**< == 0x3ffe; the frame header sync code */ |
| 447 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /**< == 14 (bits) */ |
| 448 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /**< == 1 (bits) */ |
| 449 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN; /**< == 1 (bits) */ |
| 450 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /**< == 4 (bits) */ |
| 451 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /**< == 4 (bits) */ |
| 452 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /**< == 4 (bits) */ |
| 453 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /**< == 3 (bits) */ |
| 454 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /**< == 1 (bit) */ |
| 455 | extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; /**< == 8 (bits) */ |
| 456 | |
| 457 | |
| 458 | /** FLAC frame footer structure. (c.f. <A HREF="../format.html#frame_footer">format specification</A>) |
| 459 | */ |
| 460 | typedef struct { |
| 461 | FLAC__uint16 crc; |
| 462 | /**< CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with |
| 463 | * 0) of the bytes before the crc, back to and including the frame header |
| 464 | * sync code. |
| 465 | */ |
| 466 | } FLAC__FrameFooter; |
| 467 | |
| 468 | extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /**< == 16 (bits) */ |
| 469 | |
| 470 | |
| 471 | /** FLAC frame structure. (c.f. <A HREF="../format.html#frame">format specification</A>) |
| 472 | */ |
| 473 | typedef struct { |
| 474 | FLAC__FrameHeader header; |
| 475 | FLAC__Subframe subframes[FLAC__MAX_CHANNELS]; |
| 476 | FLAC__FrameFooter footer; |
| 477 | } FLAC__Frame; |
| 478 | |
| 479 | /*****************************************************************************/ |
| 480 | |
| 481 | |
| 482 | /***************************************************************************** |
| 483 | * |
| 484 | * Meta-data structures |
| 485 | * |
| 486 | *****************************************************************************/ |
| 487 | |
| 488 | /** An enumeration of the available metadata block types. */ |
| 489 | typedef enum { |
| 490 | |
| 491 | FLAC__METADATA_TYPE_STREAMINFO = 0, |
| 492 | /**< <A HREF="../format.html#metadata_block_streaminfo">STREAMINFO</A> block */ |
| 493 | |
| 494 | FLAC__METADATA_TYPE_PADDING = 1, |
| 495 | /**< <A HREF="../format.html#metadata_block_padding">PADDING</A> block */ |
| 496 | |
| 497 | FLAC__METADATA_TYPE_APPLICATION = 2, |
| 498 | /**< <A HREF="../format.html#metadata_block_application">APPLICATION</A> block */ |
| 499 | |
| 500 | FLAC__METADATA_TYPE_SEEKTABLE = 3, |
| 501 | /**< <A HREF="../format.html#metadata_block_seektable">SEEKTABLE</A> block */ |
| 502 | |
| 503 | FLAC__METADATA_TYPE_VORBIS_COMMENT = 4, |
| 504 | /**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block (a.k.a. FLAC tags) */ |
| 505 | |
| 506 | FLAC__METADATA_TYPE_CUESHEET = 5, |
| 507 | /**< <A HREF="../format.html#metadata_block_cuesheet">CUESHEET</A> block */ |
| 508 | |
| 509 | FLAC__METADATA_TYPE_PICTURE = 6, |
| 510 | /**< <A HREF="../format.html#metadata_block_picture">PICTURE</A> block */ |
| 511 | |
| 512 | FLAC__METADATA_TYPE_UNDEFINED = 7, |
| 513 | /**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */ |
| 514 | |
| 515 | FLAC__MAX_METADATA_TYPE = FLAC__MAX_METADATA_TYPE_CODE, |
| 516 | /**< No type will ever be greater than this. There is not enough room in the protocol block. */ |
| 517 | } FLAC__MetadataType; |
| 518 | |
| 519 | /** Maps a FLAC__MetadataType to a C string. |
| 520 | * |
| 521 | * Using a FLAC__MetadataType as the index to this array will |
| 522 | * give the string equivalent. The contents should not be modified. |
| 523 | */ |
| 524 | extern FLAC_API const char * const FLAC__MetadataTypeString[]; |
| 525 | |
| 526 | |
| 527 | /** FLAC STREAMINFO structure. (c.f. <A HREF="../format.html#metadata_block_streaminfo">format specification</A>) |
| 528 | */ |
| 529 | typedef struct { |
| 530 | unsigned min_blocksize, max_blocksize; |
| 531 | unsigned min_framesize, max_framesize; |
| 532 | unsigned sample_rate; |
| 533 | unsigned channels; |
| 534 | unsigned bits_per_sample; |
| 535 | FLAC__uint64 total_samples; |
| 536 | FLAC__byte md5sum[16]; |
| 537 | } FLAC__StreamMetadata_StreamInfo; |
| 538 | |
| 539 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /**< == 16 (bits) */ |
| 540 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /**< == 16 (bits) */ |
| 541 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /**< == 24 (bits) */ |
| 542 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /**< == 24 (bits) */ |
| 543 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /**< == 20 (bits) */ |
| 544 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /**< == 3 (bits) */ |
| 545 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /**< == 5 (bits) */ |
| 546 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /**< == 36 (bits) */ |
| 547 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /**< == 128 (bits) */ |
| 548 | |
| 549 | /** The total stream length of the STREAMINFO block in bytes. */ |
| 550 | #define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u) |
| 551 | |
| 552 | /** FLAC PADDING structure. (c.f. <A HREF="../format.html#metadata_block_padding">format specification</A>) |
| 553 | */ |
| 554 | typedef struct { |
| 555 | int dummy; |
| 556 | /**< Conceptually this is an empty struct since we don't store the |
| 557 | * padding bytes. Empty structs are not allowed by some C compilers, |
| 558 | * hence the dummy. |
| 559 | */ |
| 560 | } FLAC__StreamMetadata_Padding; |
| 561 | |
| 562 | |
| 563 | /** FLAC APPLICATION structure. (c.f. <A HREF="../format.html#metadata_block_application">format specification</A>) |
| 564 | */ |
| 565 | typedef struct { |
| 566 | FLAC__byte id[4]; |
| 567 | FLAC__byte *data; |
| 568 | } FLAC__StreamMetadata_Application; |
| 569 | |
| 570 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /**< == 32 (bits) */ |
| 571 | |
| 572 | /** SeekPoint structure used in SEEKTABLE blocks. (c.f. <A HREF="../format.html#seekpoint">format specification</A>) |
| 573 | */ |
| 574 | typedef struct { |
| 575 | FLAC__uint64 sample_number; |
| 576 | /**< The sample number of the target frame. */ |
| 577 | |
| 578 | FLAC__uint64 stream_offset; |
| 579 | /**< The offset, in bytes, of the target frame with respect to |
| 580 | * beginning of the first frame. */ |
| 581 | |
| 582 | unsigned frame_samples; |
| 583 | /**< The number of samples in the target frame. */ |
| 584 | } FLAC__StreamMetadata_SeekPoint; |
| 585 | |
| 586 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; /**< == 64 (bits) */ |
| 587 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; /**< == 64 (bits) */ |
| 588 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; /**< == 16 (bits) */ |
| 589 | |
| 590 | /** The total stream length of a seek point in bytes. */ |
| 591 | #define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u) |
| 592 | |
| 593 | /** The value used in the \a sample_number field of |
| 594 | * FLAC__StreamMetadataSeekPoint used to indicate a placeholder |
| 595 | * point (== 0xffffffffffffffff). |
| 596 | */ |
| 597 | extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER; |
| 598 | |
| 599 | |
| 600 | /** FLAC SEEKTABLE structure. (c.f. <A HREF="../format.html#metadata_block_seektable">format specification</A>) |
| 601 | * |
| 602 | * \note From the format specification: |
| 603 | * - The seek points must be sorted by ascending sample number. |
| 604 | * - Each seek point's sample number must be the first sample of the |
| 605 | * target frame. |
| 606 | * - Each seek point's sample number must be unique within the table. |
| 607 | * - Existence of a SEEKTABLE block implies a correct setting of |
| 608 | * total_samples in the stream_info block. |
| 609 | * - Behavior is undefined when more than one SEEKTABLE block is |
| 610 | * present in a stream. |
| 611 | */ |
| 612 | typedef struct { |
| 613 | unsigned num_points; |
| 614 | FLAC__StreamMetadata_SeekPoint *points; |
| 615 | } FLAC__StreamMetadata_SeekTable; |
| 616 | |
| 617 | |
| 618 | /** Vorbis comment entry structure used in VORBIS_COMMENT blocks. (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>) |
| 619 | * |
| 620 | * For convenience, the APIs maintain a trailing NUL character at the end of |
| 621 | * \a entry which is not counted toward \a length, i.e. |
| 622 | * \code strlen(entry) == length \endcode |
| 623 | */ |
| 624 | typedef struct { |
| 625 | FLAC__uint32 length; |
| 626 | FLAC__byte *entry; |
| 627 | } FLAC__StreamMetadata_VorbisComment_Entry; |
| 628 | |
| 629 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /**< == 32 (bits) */ |
| 630 | |
| 631 | |
| 632 | /** FLAC VORBIS_COMMENT structure. (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>) |
| 633 | */ |
| 634 | typedef struct { |
| 635 | FLAC__StreamMetadata_VorbisComment_Entry vendor_string; |
| 636 | FLAC__uint32 num_comments; |
| 637 | FLAC__StreamMetadata_VorbisComment_Entry *comments; |
| 638 | } FLAC__StreamMetadata_VorbisComment; |
| 639 | |
| 640 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */ |
| 641 | |
| 642 | |
| 643 | /** FLAC CUESHEET track index structure. (See the |
| 644 | * <A HREF="../format.html#cuesheet_track_index">format specification</A> for |
| 645 | * the full description of each field.) |
| 646 | */ |
| 647 | typedef struct { |
| 648 | FLAC__uint64 offset; |
| 649 | /**< Offset in samples, relative to the track offset, of the index |
| 650 | * point. |
| 651 | */ |
| 652 | |
| 653 | FLAC__byte number; |
| 654 | /**< The index point number. */ |
| 655 | } FLAC__StreamMetadata_CueSheet_Index; |
| 656 | |
| 657 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */ |
| 658 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; /**< == 8 (bits) */ |
| 659 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == 3*8 (bits) */ |
| 660 | |
| 661 | |
| 662 | /** FLAC CUESHEET track structure. (See the |
| 663 | * <A HREF="../format.html#cuesheet_track">format specification</A> for |
| 664 | * the full description of each field.) |
| 665 | */ |
| 666 | typedef struct { |
| 667 | FLAC__uint64 offset; |
| 668 | /**< Track offset in samples, relative to the beginning of the FLAC audio stream. */ |
| 669 | |
| 670 | FLAC__byte number; |
| 671 | /**< The track number. */ |
| 672 | |
| 673 | char isrc[13]; |
| 674 | /**< Track ISRC. This is a 12-digit alphanumeric code plus a trailing \c NUL byte */ |
| 675 | |
| 676 | unsigned type:1; |
| 677 | /**< The track type: 0 for audio, 1 for non-audio. */ |
| 678 | |
| 679 | unsigned pre_emphasis:1; |
| 680 | /**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */ |
| 681 | |
| 682 | FLAC__byte num_indices; |
| 683 | /**< The number of track index points. */ |
| 684 | |
| 685 | FLAC__StreamMetadata_CueSheet_Index *indices; |
| 686 | /**< NULL if num_indices == 0, else pointer to array of index points. */ |
| 687 | |
| 688 | } FLAC__StreamMetadata_CueSheet_Track; |
| 689 | |
| 690 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */ |
| 691 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; /**< == 8 (bits) */ |
| 692 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; /**< == 12*8 (bits) */ |
| 693 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; /**< == 1 (bit) */ |
| 694 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; /**< == 1 (bit) */ |
| 695 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+13*8 (bits) */ |
| 696 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */ |
| 697 | |
| 698 | |
| 699 | /** FLAC CUESHEET structure. (See the |
| 700 | * <A HREF="../format.html#metadata_block_cuesheet">format specification</A> |
| 701 | * for the full description of each field.) |
| 702 | */ |
| 703 | typedef struct { |
| 704 | char media_catalog_number[129]; |
| 705 | /**< Media catalog number, in ASCII printable characters 0x20-0x7e. In |
| 706 | * general, the media catalog number may be 0 to 128 bytes long; any |
| 707 | * unused characters should be right-padded with NUL characters. |
| 708 | */ |
| 709 | |
| 710 | FLAC__uint64 lead_in; |
| 711 | /**< The number of lead-in samples. */ |
| 712 | |
| 713 | FLAC__bool is_cd; |
| 714 | /**< \c true if CUESHEET corresponds to a Compact Disc, else \c false. */ |
| 715 | |
| 716 | unsigned num_tracks; |
| 717 | /**< The number of tracks. */ |
| 718 | |
| 719 | FLAC__StreamMetadata_CueSheet_Track *tracks; |
| 720 | /**< NULL if num_tracks == 0, else pointer to array of tracks. */ |
| 721 | |
| 722 | } FLAC__StreamMetadata_CueSheet; |
| 723 | |
| 724 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */ |
| 725 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; /**< == 64 (bits) */ |
| 726 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; /**< == 1 (bit) */ |
| 727 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< == 7+258*8 (bits) */ |
| 728 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */ |
| 729 | |
| 730 | |
| 731 | /** An enumeration of the PICTURE types (see FLAC__StreamMetadataPicture and id3 v2.4 APIC tag). */ |
| 732 | typedef enum { |
| 733 | FLAC__STREAM_METADATA_PICTURE_TYPE_OTHER = 0, /**< Other */ |
| 734 | FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON_STANDARD = 1, /**< 32x32 pixels 'file icon' (PNG only) */ |
| 735 | FLAC__STREAM_METADATA_PICTURE_TYPE_FILE_ICON = 2, /**< Other file icon */ |
| 736 | FLAC__STREAM_METADATA_PICTURE_TYPE_FRONT_COVER = 3, /**< Cover (front) */ |
| 737 | FLAC__STREAM_METADATA_PICTURE_TYPE_BACK_COVER = 4, /**< Cover (back) */ |
| 738 | FLAC__STREAM_METADATA_PICTURE_TYPE_LEAFLET_PAGE = 5, /**< Leaflet page */ |
| 739 | FLAC__STREAM_METADATA_PICTURE_TYPE_MEDIA = 6, /**< Media (e.g. label side of CD) */ |
| 740 | FLAC__STREAM_METADATA_PICTURE_TYPE_LEAD_ARTIST = 7, /**< Lead artist/lead performer/soloist */ |
| 741 | FLAC__STREAM_METADATA_PICTURE_TYPE_ARTIST = 8, /**< Artist/performer */ |
| 742 | FLAC__STREAM_METADATA_PICTURE_TYPE_CONDUCTOR = 9, /**< Conductor */ |
| 743 | FLAC__STREAM_METADATA_PICTURE_TYPE_BAND = 10, /**< Band/Orchestra */ |
| 744 | FLAC__STREAM_METADATA_PICTURE_TYPE_COMPOSER = 11, /**< Composer */ |
| 745 | FLAC__STREAM_METADATA_PICTURE_TYPE_LYRICIST = 12, /**< Lyricist/text writer */ |
| 746 | FLAC__STREAM_METADATA_PICTURE_TYPE_RECORDING_LOCATION = 13, /**< Recording Location */ |
| 747 | FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_RECORDING = 14, /**< During recording */ |
| 748 | FLAC__STREAM_METADATA_PICTURE_TYPE_DURING_PERFORMANCE = 15, /**< During performance */ |
| 749 | FLAC__STREAM_METADATA_PICTURE_TYPE_VIDEO_SCREEN_CAPTURE = 16, /**< Movie/video screen capture */ |
| 750 | FLAC__STREAM_METADATA_PICTURE_TYPE_FISH = 17, /**< A bright coloured fish */ |
| 751 | FLAC__STREAM_METADATA_PICTURE_TYPE_ILLUSTRATION = 18, /**< Illustration */ |
| 752 | FLAC__STREAM_METADATA_PICTURE_TYPE_BAND_LOGOTYPE = 19, /**< Band/artist logotype */ |
| 753 | FLAC__STREAM_METADATA_PICTURE_TYPE_PUBLISHER_LOGOTYPE = 20, /**< Publisher/Studio logotype */ |
| 754 | FLAC__STREAM_METADATA_PICTURE_TYPE_UNDEFINED |
| 755 | } FLAC__StreamMetadata_Picture_Type; |
| 756 | |
| 757 | /** Maps a FLAC__StreamMetadata_Picture_Type to a C string. |
| 758 | * |
| 759 | * Using a FLAC__StreamMetadata_Picture_Type as the index to this array |
| 760 | * will give the string equivalent. The contents should not be |
| 761 | * modified. |
| 762 | */ |
| 763 | extern FLAC_API const char * const FLAC__StreamMetadata_Picture_TypeString[]; |
| 764 | |
| 765 | /** FLAC PICTURE structure. (See the |
| 766 | * <A HREF="../format.html#metadata_block_picture">format specification</A> |
| 767 | * for the full description of each field.) |
| 768 | */ |
| 769 | typedef struct { |
| 770 | FLAC__StreamMetadata_Picture_Type type; |
| 771 | /**< The kind of picture stored. */ |
| 772 | |
| 773 | char *mime_type; |
| 774 | /**< Picture data's MIME type, in ASCII printable characters |
| 775 | * 0x20-0x7e, NUL terminated. For best compatibility with players, |
| 776 | * use picture data of MIME type \c image/jpeg or \c image/png. A |
| 777 | * MIME type of '-->' is also allowed, in which case the picture |
| 778 | * data should be a complete URL. In file storage, the MIME type is |
| 779 | * stored as a 32-bit length followed by the ASCII string with no NUL |
| 780 | * terminator, but is converted to a plain C string in this structure |
| 781 | * for convenience. |
| 782 | */ |
| 783 | |
| 784 | FLAC__byte *description; |
| 785 | /**< Picture's description in UTF-8, NUL terminated. In file storage, |
| 786 | * the description is stored as a 32-bit length followed by the UTF-8 |
| 787 | * string with no NUL terminator, but is converted to a plain C string |
| 788 | * in this structure for convenience. |
| 789 | */ |
| 790 | |
| 791 | FLAC__uint32 width; |
| 792 | /**< Picture's width in pixels. */ |
| 793 | |
| 794 | FLAC__uint32 height; |
| 795 | /**< Picture's height in pixels. */ |
| 796 | |
| 797 | FLAC__uint32 depth; |
| 798 | /**< Picture's color depth in bits-per-pixel. */ |
| 799 | |
| 800 | FLAC__uint32 colors; |
| 801 | /**< For indexed palettes (like GIF), picture's number of colors (the |
| 802 | * number of palette entries), or \c 0 for non-indexed (i.e. 2^depth). |
| 803 | */ |
| 804 | |
| 805 | FLAC__uint32 data_length; |
| 806 | /**< Length of binary picture data in bytes. */ |
| 807 | |
| 808 | FLAC__byte *data; |
| 809 | /**< Binary picture data. */ |
| 810 | |
| 811 | } FLAC__StreamMetadata_Picture; |
| 812 | |
| 813 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_TYPE_LEN; /**< == 32 (bits) */ |
| 814 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_MIME_TYPE_LENGTH_LEN; /**< == 32 (bits) */ |
| 815 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DESCRIPTION_LENGTH_LEN; /**< == 32 (bits) */ |
| 816 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_WIDTH_LEN; /**< == 32 (bits) */ |
| 817 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_HEIGHT_LEN; /**< == 32 (bits) */ |
| 818 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DEPTH_LEN; /**< == 32 (bits) */ |
| 819 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_COLORS_LEN; /**< == 32 (bits) */ |
| 820 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DATA_LENGTH_LEN; /**< == 32 (bits) */ |
| 821 | |
| 822 | |
| 823 | /** Structure that is used when a metadata block of unknown type is loaded. |
| 824 | * The contents are opaque. The structure is used only internally to |
| 825 | * correctly handle unknown metadata. |
| 826 | */ |
| 827 | typedef struct { |
| 828 | FLAC__byte *data; |
| 829 | } FLAC__StreamMetadata_Unknown; |
| 830 | |
| 831 | |
| 832 | /** FLAC metadata block structure. (c.f. <A HREF="../format.html#metadata_block">format specification</A>) |
| 833 | */ |
| 834 | typedef struct { |
| 835 | FLAC__MetadataType type; |
| 836 | /**< The type of the metadata block; used determine which member of the |
| 837 | * \a data union to dereference. If type >= FLAC__METADATA_TYPE_UNDEFINED |
| 838 | * then \a data.unknown must be used. */ |
| 839 | |
| 840 | FLAC__bool is_last; |
| 841 | /**< \c true if this metadata block is the last, else \a false */ |
| 842 | |
| 843 | unsigned length; |
| 844 | /**< Length, in bytes, of the block data as it appears in the stream. */ |
| 845 | |
| 846 | union { |
| 847 | FLAC__StreamMetadata_StreamInfo stream_info; |
| 848 | FLAC__StreamMetadata_Padding padding; |
| 849 | FLAC__StreamMetadata_Application application; |
| 850 | FLAC__StreamMetadata_SeekTable seek_table; |
| 851 | FLAC__StreamMetadata_VorbisComment vorbis_comment; |
| 852 | FLAC__StreamMetadata_CueSheet cue_sheet; |
| 853 | FLAC__StreamMetadata_Picture picture; |
| 854 | FLAC__StreamMetadata_Unknown unknown; |
| 855 | } data; |
| 856 | /**< Polymorphic block data; use the \a type value to determine which |
| 857 | * to use. */ |
| 858 | } FLAC__StreamMetadata; |
| 859 | |
| 860 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /**< == 1 (bit) */ |
| 861 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /**< == 7 (bits) */ |
| 862 | extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bits) */ |
| 863 | |
| 864 | /** The total stream length of a metadata block header in bytes. */ |
| 865 | #define FLAC__STREAM_METADATA_HEADER_LENGTH (4u) |
| 866 | |
| 867 | /*****************************************************************************/ |
| 868 | |
| 869 | |
| 870 | /***************************************************************************** |
| 871 | * |
| 872 | * Utility functions |
| 873 | * |
| 874 | *****************************************************************************/ |
| 875 | |
| 876 | /** Tests that a sample rate is valid for FLAC. |
| 877 | * |
| 878 | * \param sample_rate The sample rate to test for compliance. |
| 879 | * \retval FLAC__bool |
| 880 | * \c true if the given sample rate conforms to the specification, else |
| 881 | * \c false. |
| 882 | */ |
| 883 | FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate); |
| 884 | |
| 885 | /** Tests that a blocksize at the given sample rate is valid for the FLAC |
| 886 | * subset. |
| 887 | * |
| 888 | * \param blocksize The blocksize to test for compliance. |
| 889 | * \param sample_rate The sample rate is needed, since the valid subset |
| 890 | * blocksize depends on the sample rate. |
| 891 | * \retval FLAC__bool |
| 892 | * \c true if the given blocksize conforms to the specification for the |
| 893 | * subset at the given sample rate, else \c false. |
| 894 | */ |
| 895 | FLAC_API FLAC__bool FLAC__format_blocksize_is_subset(unsigned blocksize, unsigned sample_rate); |
| 896 | |
| 897 | /** Tests that a sample rate is valid for the FLAC subset. The subset rules |
| 898 | * for valid sample rates are slightly more complex since the rate has to |
| 899 | * be expressible completely in the frame header. |
| 900 | * |
| 901 | * \param sample_rate The sample rate to test for compliance. |
| 902 | * \retval FLAC__bool |
| 903 | * \c true if the given sample rate conforms to the specification for the |
| 904 | * subset, else \c false. |
| 905 | */ |
| 906 | FLAC_API FLAC__bool FLAC__format_sample_rate_is_subset(unsigned sample_rate); |
| 907 | |
| 908 | /** Check a Vorbis comment entry name to see if it conforms to the Vorbis |
| 909 | * comment specification. |
| 910 | * |
| 911 | * Vorbis comment names must be composed only of characters from |
| 912 | * [0x20-0x3C,0x3E-0x7D]. |
| 913 | * |
| 914 | * \param name A NUL-terminated string to be checked. |
| 915 | * \assert |
| 916 | * \code name != NULL \endcode |
| 917 | * \retval FLAC__bool |
| 918 | * \c false if entry name is illegal, else \c true. |
| 919 | */ |
| 920 | FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_name_is_legal(const char *name); |
| 921 | |
| 922 | /** Check a Vorbis comment entry value to see if it conforms to the Vorbis |
| 923 | * comment specification. |
| 924 | * |
| 925 | * Vorbis comment values must be valid UTF-8 sequences. |
| 926 | * |
| 927 | * \param value A string to be checked. |
| 928 | * \param length A the length of \a value in bytes. May be |
| 929 | * \c (unsigned)(-1) to indicate that \a value is a plain |
| 930 | * UTF-8 NUL-terminated string. |
| 931 | * \assert |
| 932 | * \code value != NULL \endcode |
| 933 | * \retval FLAC__bool |
| 934 | * \c false if entry name is illegal, else \c true. |
| 935 | */ |
| 936 | FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__byte *value, unsigned length); |
| 937 | |
| 938 | /** Check a Vorbis comment entry to see if it conforms to the Vorbis |
| 939 | * comment specification. |
| 940 | * |
| 941 | * Vorbis comment entries must be of the form 'name=value', and 'name' and |
| 942 | * 'value' must be legal according to |
| 943 | * FLAC__format_vorbiscomment_entry_name_is_legal() and |
| 944 | * FLAC__format_vorbiscomment_entry_value_is_legal() respectively. |
| 945 | * |
| 946 | * \param entry An entry to be checked. |
| 947 | * \param length The length of \a entry in bytes. |
| 948 | * \assert |
| 949 | * \code value != NULL \endcode |
| 950 | * \retval FLAC__bool |
| 951 | * \c false if entry name is illegal, else \c true. |
| 952 | */ |
| 953 | FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_is_legal(const FLAC__byte *entry, unsigned length); |
| 954 | |
| 955 | /** Check a seek table to see if it conforms to the FLAC specification. |
| 956 | * See the format specification for limits on the contents of the |
| 957 | * seek table. |
| 958 | * |
| 959 | * \param seek_table A pointer to a seek table to be checked. |
| 960 | * \assert |
| 961 | * \code seek_table != NULL \endcode |
| 962 | * \retval FLAC__bool |
| 963 | * \c false if seek table is illegal, else \c true. |
| 964 | */ |
| 965 | FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table); |
| 966 | |
| 967 | /** Sort a seek table's seek points according to the format specification. |
| 968 | * This includes a "unique-ification" step to remove duplicates, i.e. |
| 969 | * seek points with identical \a sample_number values. Duplicate seek |
| 970 | * points are converted into placeholder points and sorted to the end of |
| 971 | * the table. |
| 972 | * |
| 973 | * \param seek_table A pointer to a seek table to be sorted. |
| 974 | * \assert |
| 975 | * \code seek_table != NULL \endcode |
| 976 | * \retval unsigned |
| 977 | * The number of duplicate seek points converted into placeholders. |
| 978 | */ |
| 979 | FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table); |
| 980 | |
| 981 | /** Check a cue sheet to see if it conforms to the FLAC specification. |
| 982 | * See the format specification for limits on the contents of the |
| 983 | * cue sheet. |
| 984 | * |
| 985 | * \param cue_sheet A pointer to an existing cue sheet to be checked. |
| 986 | * \param check_cd_da_subset If \c true, check CUESHEET against more |
| 987 | * stringent requirements for a CD-DA (audio) disc. |
| 988 | * \param violation Address of a pointer to a string. If there is a |
| 989 | * violation, a pointer to a string explanation of the |
| 990 | * violation will be returned here. \a violation may be |
| 991 | * \c NULL if you don't need the returned string. Do not |
| 992 | * free the returned string; it will always point to static |
| 993 | * data. |
| 994 | * \assert |
| 995 | * \code cue_sheet != NULL \endcode |
| 996 | * \retval FLAC__bool |
| 997 | * \c false if cue sheet is illegal, else \c true. |
| 998 | */ |
| 999 | FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation); |
| 1000 | |
| 1001 | /** Check picture data to see if it conforms to the FLAC specification. |
| 1002 | * See the format specification for limits on the contents of the |
| 1003 | * PICTURE block. |
| 1004 | * |
| 1005 | * \param picture A pointer to existing picture data to be checked. |
| 1006 | * \param violation Address of a pointer to a string. If there is a |
| 1007 | * violation, a pointer to a string explanation of the |
| 1008 | * violation will be returned here. \a violation may be |
| 1009 | * \c NULL if you don't need the returned string. Do not |
| 1010 | * free the returned string; it will always point to static |
| 1011 | * data. |
| 1012 | * \assert |
| 1013 | * \code picture != NULL \endcode |
| 1014 | * \retval FLAC__bool |
| 1015 | * \c false if picture data is illegal, else \c true. |
| 1016 | */ |
| 1017 | FLAC_API FLAC__bool FLAC__format_picture_is_legal(const FLAC__StreamMetadata_Picture *picture, const char **violation); |
| 1018 | |
| 1019 | /* \} */ |
| 1020 | |
| 1021 | #ifdef __cplusplus |
| 1022 | } |
| 1023 | #endif |
| 1024 | |
| 1025 | #endif |