Main Page Modules Class Hierarchy Alphabetical List Compound List File List Compound Members File Members

# include/FLAC/format.h

Go to the documentation of this file.

    00001 /* libFLAC - Free Lossless Audio Codec library
    00002  * Copyright (C) 2000,2001,2002,2003  Josh Coalson
    00003  *
    00004  * This library is free software; you can redistribute it and/or
    00005  * modify it under the terms of the GNU Library General Public
    00006  * License as published by the Free Software Foundation; either
    00007  * version 2 of the License, or (at your option) any later version.
    00008  *
    00009  * This library is distributed in the hope that it will be useful,
    00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    00012  * Library General Public License for more details.
    00013  *
    00014  * You should have received a copy of the GNU Library General Public
    00015  * License along with this library; if not, write to the
    00016  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    00017  * Boston, MA  02111-1307, USA.
    00018  */
    00019
    00020 #ifndef FLAC__FORMAT_H
    00021 #define FLAC__FORMAT_H
    00022
    00023 #include "export.h"
    00024 #include "ordinals.h"
    00025
    00026 #ifdef __cplusplus
    00027 extern "C" {
    00028 #endif
    00029
    00074 /*
    00075     Most of the values described in this file are defined by the FLAC
    00076     format specification.  There is nothing to tune here.
    00077 */
    00078
    00080 #define FLAC__MIN_BLOCK_SIZE (16u)
    00081
    00083 #define FLAC__MAX_BLOCK_SIZE (65535u)
    00084
    00086 #define FLAC__MAX_CHANNELS (8u)
    00087
    00089 #define FLAC__MIN_BITS_PER_SAMPLE (4u)
    00090
    00092 #define FLAC__MAX_BITS_PER_SAMPLE (32u)
    00093
    00102 #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
    00103
    00108 #define FLAC__MAX_SAMPLE_RATE (655350u)
    00109
    00111 #define FLAC__MAX_LPC_ORDER (32u)
    00112
    00116 #define FLAC__MIN_QLP_COEFF_PRECISION (5u)
    00117
    00121 #define FLAC__MAX_QLP_COEFF_PRECISION (15u)
    00122
    00124 #define FLAC__MAX_FIXED_ORDER (4u)
    00125
    00127 #define FLAC__MAX_RICE_PARTITION_ORDER (15u)
    00128
    00130 #define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u)
    00131
    00138 extern FLAC_API const char *FLAC__VERSION_STRING;
    00139
    00144 extern FLAC_API const char *FLAC__VENDOR_STRING;
    00145
    00147 extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */
    00148
    00152 extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */
    00153
    00155 extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
    00156
    00158 #define FLAC__STREAM_SYNC_LENGTH (4u)
    00159
    00160
    00161 /*****************************************************************************
    00162  *
    00163  * Subframe structures
    00164  *
    00165  *****************************************************************************/
    00166
    00167 /*****************************************************************************/
    00168
    00170 typedef enum {
    00171     FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
    00174 } FLAC__EntropyCodingMethodType;
    00175
    00181 extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[];
    00182
    00183
    00186 typedef struct {
    00187
    00188     unsigned *parameters;
    00191     unsigned *raw_bits;
    00194     unsigned capacity_by_order;
    00199 } FLAC__EntropyCodingMethod_PartitionedRiceContents;
    00200
    00203 typedef struct {
    00204
    00205     unsigned order;
    00208     const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents;
    00211 } FLAC__EntropyCodingMethod_PartitionedRice;
    00212
    00213 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN;
    00214 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN;
    00215 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN;
    00217 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER;
    00222 typedef struct {
    00223     FLAC__EntropyCodingMethodType type;
    00224     union {
    00225         FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
    00226     } data;
    00227 } FLAC__EntropyCodingMethod;
    00228
    00229 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN;
    00231 /*****************************************************************************/
    00232
    00234 typedef enum {
    00235     FLAC__SUBFRAME_TYPE_CONSTANT = 0,
    00236     FLAC__SUBFRAME_TYPE_VERBATIM = 1,
    00237     FLAC__SUBFRAME_TYPE_FIXED = 2,
    00238     FLAC__SUBFRAME_TYPE_LPC = 3
    00239 } FLAC__SubframeType;
    00240
    00246 extern FLAC_API const char * const FLAC__SubframeTypeString[];
    00247
    00248
    00251 typedef struct {
    00252     FLAC__int32 value;
    00253 } FLAC__Subframe_Constant;
    00254
    00255
    00258 typedef struct {
    00259     const FLAC__int32 *data;
    00260 } FLAC__Subframe_Verbatim;
    00261
    00262
    00265 typedef struct {
    00266     FLAC__EntropyCodingMethod entropy_coding_method;
    00269     unsigned order;
    00272     FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
    00275     const FLAC__int32 *residual;
    00277 } FLAC__Subframe_Fixed;
    00278
    00279
    00282 typedef struct {
    00283     FLAC__EntropyCodingMethod entropy_coding_method;
    00286     unsigned order;
    00289     unsigned qlp_coeff_precision;
    00292     int quantization_level;
    00295     FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
    00298     FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
    00301     const FLAC__int32 *residual;
    00303 } FLAC__Subframe_LPC;
    00304
    00305 extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN;
    00306 extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN;
    00311 typedef struct {
    00312     FLAC__SubframeType type;
    00313     union {
    00314         FLAC__Subframe_Constant constant;
    00315         FLAC__Subframe_Fixed fixed;
    00316         FLAC__Subframe_LPC lpc;
    00317         FLAC__Subframe_Verbatim verbatim;
    00318     } data;
    00319     unsigned wasted_bits;
    00320 } FLAC__Subframe;
    00321
    00322 extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN;
    00323 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN;
    00324 extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN;
    00326 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /* = 0x00 */
    00327 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /* = 0x02 */
    00328 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /* = 0x10 */
    00329 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /* = 0x40 */
    00330
    00331 /*****************************************************************************/
    00332
    00333
    00334 /*****************************************************************************
    00335  *
    00336  * Frame structures
    00337  *
    00338  *****************************************************************************/
    00339
    00341 typedef enum {
    00342     FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0,
    00343     FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1,
    00344     FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2,
    00345     FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3
    00346 } FLAC__ChannelAssignment;
    00347
    00353 extern FLAC_API const char * const FLAC__ChannelAssignmentString[];
    00354
    00356 typedef enum {
    00357     FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER,
    00358     FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER
    00359 } FLAC__FrameNumberType;
    00360
    00366 extern FLAC_API const char * const FLAC__FrameNumberTypeString[];
    00367
    00368
    00371 typedef struct {
    00372     unsigned blocksize;
    00375     unsigned sample_rate;
    00378     unsigned channels;
    00381     FLAC__ChannelAssignment channel_assignment;
    00384     unsigned bits_per_sample;
    00387     FLAC__FrameNumberType number_type;
    00390     union {
    00391         FLAC__uint32 frame_number;
    00392         FLAC__uint64 sample_number;
    00393     } number;
    00397     FLAC__uint8 crc;
    00402 } FLAC__FrameHeader;
    00403
    00404 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC;
    00405 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN;
    00406 extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN;
    00407 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN;
    00408 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN;
    00409 extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN;
    00410 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN;
    00411 extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN;
    00412 extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN;
    00417 typedef struct {
    00418     FLAC__uint16 crc;
    00423 } FLAC__FrameFooter;
    00424
    00425 extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN;
    00430 typedef struct {
    00431     FLAC__FrameHeader header;
    00432     FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
    00433     FLAC__FrameFooter footer;
    00434 } FLAC__Frame;
    00435
    00436 /*****************************************************************************/
    00437
    00438
    00439 /*****************************************************************************
    00440  *
    00441  * Meta-data structures
    00442  *
    00443  *****************************************************************************/
    00444
    00446 typedef enum {
    00447
    00448     FLAC__METADATA_TYPE_STREAMINFO = 0,
    00451     FLAC__METADATA_TYPE_PADDING = 1,
    00454     FLAC__METADATA_TYPE_APPLICATION = 2,
    00457     FLAC__METADATA_TYPE_SEEKTABLE = 3,
    00460     FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
    00463     FLAC__METADATA_TYPE_CUESHEET = 5,
    00466     FLAC__METADATA_TYPE_UNDEFINED = 6
    00469 } FLAC__MetadataType;
    00470
    00476 extern FLAC_API const char * const FLAC__MetadataTypeString[];
    00477
    00478
    00481 typedef struct {
    00482     unsigned min_blocksize, max_blocksize;
    00483     unsigned min_framesize, max_framesize;
    00484     unsigned sample_rate;
    00485     unsigned channels;
    00486     unsigned bits_per_sample;
    00487     FLAC__uint64 total_samples;
    00488     FLAC__byte md5sum[16];
    00489 } FLAC__StreamMetadata_StreamInfo;
    00490
    00491 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN;
    00492 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN;
    00493 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN;
    00494 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN;
    00495 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN;
    00496 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN;
    00497 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN;
    00498 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN;
    00499 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN;
    00502 #define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)
    00503
    00506 typedef struct {
    00507     int dummy;
    00512 } FLAC__StreamMetadata_Padding;
    00513
    00514
    00517 typedef struct {
    00518     FLAC__byte id[4];
    00519     FLAC__byte *data;
    00520 } FLAC__StreamMetadata_Application;
    00521
    00522 extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN;
    00526 typedef struct {
    00527     FLAC__uint64 sample_number;
    00530     FLAC__uint64 stream_offset;
    00534     unsigned frame_samples;
    00536 } FLAC__StreamMetadata_SeekPoint;
    00537
    00538 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN;
    00539 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN;
    00540 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN;
    00543 #define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u)
    00544
    00549 extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;
    00550
    00551
    00564 typedef struct {
    00565     unsigned num_points;
    00566     FLAC__StreamMetadata_SeekPoint *points;
    00567 } FLAC__StreamMetadata_SeekTable;
    00568
    00569
    00572 typedef struct {
    00573     FLAC__uint32 length;
    00574     FLAC__byte *entry;
    00575 } FLAC__StreamMetadata_VorbisComment_Entry;
    00576
    00577 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN;
    00582 typedef struct {
    00583     FLAC__StreamMetadata_VorbisComment_Entry vendor_string;
    00584     FLAC__uint32 num_comments;
    00585     FLAC__StreamMetadata_VorbisComment_Entry *comments;
    00586 } FLAC__StreamMetadata_VorbisComment;
    00587
    00588 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN;
    00595 typedef struct {
    00596     FLAC__uint64 offset;
    00601     FLAC__byte number;
    00603 } FLAC__StreamMetadata_CueSheet_Index;
    00604
    00605 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN;
    00606 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN;
    00607 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN;
    00614 typedef struct {
    00615     FLAC__uint64 offset;
    00618     FLAC__byte number;
    00621     char isrc[13];
    00624     unsigned type:1;
    00627     unsigned pre_emphasis:1;
    00630     FLAC__byte num_indices;
    00633     FLAC__StreamMetadata_CueSheet_Index *indices;
    00636 } FLAC__StreamMetadata_CueSheet_Track;
    00637
    00638 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN;
    00639 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN;
    00640 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN;
    00641 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN;
    00642 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN;
    00643 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN;
    00644 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN;
    00651 typedef struct {
    00652     char media_catalog_number[129];
    00658     FLAC__uint64 lead_in;
    00661     FLAC__bool is_cd;
    00664     unsigned num_tracks;
    00667     FLAC__StreamMetadata_CueSheet_Track *tracks;
    00670 } FLAC__StreamMetadata_CueSheet;
    00671
    00672 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN;
    00673 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN;
    00674 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN;
    00675 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN;
    00676 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN;
    00683 typedef struct {
    00684     FLAC__byte *data;
    00685 } FLAC__StreamMetadata_Unknown;
    00686
    00687
    00690 typedef struct {
    00691     FLAC__MetadataType type;
    00696     FLAC__bool is_last;
    00699     unsigned length;
    00702     union {
    00703         FLAC__StreamMetadata_StreamInfo stream_info;
    00704         FLAC__StreamMetadata_Padding padding;
    00705         FLAC__StreamMetadata_Application application;
    00706         FLAC__StreamMetadata_SeekTable seek_table;
    00707         FLAC__StreamMetadata_VorbisComment vorbis_comment;
    00708         FLAC__StreamMetadata_CueSheet cue_sheet;
    00709         FLAC__StreamMetadata_Unknown unknown;
    00710     } data;
    00713 } FLAC__StreamMetadata;
    00714
    00715 extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN;
    00716 extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN;
    00717 extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN;
    00720 #define FLAC__STREAM_METADATA_HEADER_LENGTH (4u)
    00721
    00722 /*****************************************************************************/
    00723
    00724
    00725 /*****************************************************************************
    00726  *
    00727  * Utility functions
    00728  *
    00729  *****************************************************************************/
    00730
    00731 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
    00740 FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
    00741
    00742 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
    00753 FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
    00754
    00755 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
    00768 FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
    00769
    00770 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
    00789 FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation);
    00790
    00791 /* \} */
    00792
    00793 #ifdef __cplusplus
    00794 }
    00795 #endif
    00796
    00797 #endif