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  * Redistribution and use in source and binary forms, with or without
00005  * modification, are permitted provided that the following conditions
00006  * are met:
00007  *
00008  * - Redistributions of source code must retain the above copyright
00009  * notice, this list of conditions and the following disclaimer.
00010  *
00011  * - Redistributions in binary form must reproduce the above copyright
00012  * notice, this list of conditions and the following disclaimer in the
00013  * documentation and/or other materials provided with the distribution.
00014  *
00015  * - Neither the name of the Xiph.org Foundation nor the names of its
00016  * contributors may be used to endorse or promote products derived from
00017  * this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00020  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00021  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00022  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
00023  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00024  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00025  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00026  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00027  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00028  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  */
00031 
00032 #ifndef FLAC__FORMAT_H
00033 #define FLAC__FORMAT_H
00034 
00035 #include "export.h"
00036 #include "ordinals.h"
00037 
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif
00041 
00086 /*
00087     Most of the values described in this file are defined by the FLAC
00088     format specification.  There is nothing to tune here.
00089 */
00090 
00092 #define FLAC__MIN_BLOCK_SIZE (16u)
00093 
00095 #define FLAC__MAX_BLOCK_SIZE (65535u)
00096 
00098 #define FLAC__MAX_CHANNELS (8u)
00099 
00101 #define FLAC__MIN_BITS_PER_SAMPLE (4u)
00102 
00104 #define FLAC__MAX_BITS_PER_SAMPLE (32u)
00105 
00114 #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
00115 
00120 #define FLAC__MAX_SAMPLE_RATE (655350u)
00121 
00123 #define FLAC__MAX_LPC_ORDER (32u)
00124 
00128 #define FLAC__MIN_QLP_COEFF_PRECISION (5u)
00129 
00133 #define FLAC__MAX_QLP_COEFF_PRECISION (15u)
00134 
00136 #define FLAC__MAX_FIXED_ORDER (4u)
00137 
00139 #define FLAC__MAX_RICE_PARTITION_ORDER (15u)
00140 
00142 #define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u)
00143 
00150 extern FLAC_API const char *FLAC__VERSION_STRING;
00151 
00156 extern FLAC_API const char *FLAC__VENDOR_STRING;
00157 
00159 extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */
00160 
00164 extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */
00165 
00167 extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
00168 
00170 #define FLAC__STREAM_SYNC_LENGTH (4u)
00171 
00172 
00173 /*****************************************************************************
00174  *
00175  * Subframe structures
00176  *
00177  *****************************************************************************/
00178 
00179 /*****************************************************************************/
00180 
00182 typedef enum {
00183     FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
00186 } FLAC__EntropyCodingMethodType;
00187 
00193 extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[];
00194 
00195 
00198 typedef struct {
00199 
00200     unsigned *parameters;
00203     unsigned *raw_bits;
00206     unsigned capacity_by_order;
00211 } FLAC__EntropyCodingMethod_PartitionedRiceContents;
00212 
00215 typedef struct {
00216 
00217     unsigned order;
00220     const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents;
00223 } FLAC__EntropyCodingMethod_PartitionedRice;
00224 
00225 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; 
00226 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; 
00227 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; 
00229 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER;
00234 typedef struct {
00235     FLAC__EntropyCodingMethodType type;
00236     union {
00237         FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
00238     } data;
00239 } FLAC__EntropyCodingMethod;
00240 
00241 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; 
00243 /*****************************************************************************/
00244 
00246 typedef enum {
00247     FLAC__SUBFRAME_TYPE_CONSTANT = 0, 
00248     FLAC__SUBFRAME_TYPE_VERBATIM = 1, 
00249     FLAC__SUBFRAME_TYPE_FIXED = 2, 
00250     FLAC__SUBFRAME_TYPE_LPC = 3 
00251 } FLAC__SubframeType;
00252 
00258 extern FLAC_API const char * const FLAC__SubframeTypeString[];
00259 
00260 
00263 typedef struct {
00264     FLAC__int32 value; 
00265 } FLAC__Subframe_Constant;
00266 
00267 
00270 typedef struct {
00271     const FLAC__int32 *data; 
00272 } FLAC__Subframe_Verbatim;
00273 
00274 
00277 typedef struct {
00278     FLAC__EntropyCodingMethod entropy_coding_method;
00281     unsigned order;
00284     FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
00287     const FLAC__int32 *residual;
00289 } FLAC__Subframe_Fixed;
00290 
00291 
00294 typedef struct {
00295     FLAC__EntropyCodingMethod entropy_coding_method;
00298     unsigned order;
00301     unsigned qlp_coeff_precision;
00304     int quantization_level;
00307     FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
00310     FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
00313     const FLAC__int32 *residual;
00315 } FLAC__Subframe_LPC;
00316 
00317 extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; 
00318 extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; 
00323 typedef struct {
00324     FLAC__SubframeType type;
00325     union {
00326         FLAC__Subframe_Constant constant;
00327         FLAC__Subframe_Fixed fixed;
00328         FLAC__Subframe_LPC lpc;
00329         FLAC__Subframe_Verbatim verbatim;
00330     } data;
00331     unsigned wasted_bits;
00332 } FLAC__Subframe;
00333 
00334 extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; 
00335 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; 
00336 extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; 
00338 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /* = 0x00 */
00339 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /* = 0x02 */
00340 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /* = 0x10 */
00341 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /* = 0x40 */
00342 
00343 /*****************************************************************************/
00344 
00345 
00346 /*****************************************************************************
00347  *
00348  * Frame structures
00349  *
00350  *****************************************************************************/
00351 
00353 typedef enum {
00354     FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, 
00355     FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, 
00356     FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, 
00357     FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 
00358 } FLAC__ChannelAssignment;
00359 
00365 extern FLAC_API const char * const FLAC__ChannelAssignmentString[];
00366 
00368 typedef enum {
00369     FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, 
00370     FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER 
00371 } FLAC__FrameNumberType;
00372 
00378 extern FLAC_API const char * const FLAC__FrameNumberTypeString[];
00379 
00380 
00383 typedef struct {
00384     unsigned blocksize;
00387     unsigned sample_rate;
00390     unsigned channels;
00393     FLAC__ChannelAssignment channel_assignment;
00396     unsigned bits_per_sample;
00399     FLAC__FrameNumberType number_type;
00402     union {
00403         FLAC__uint32 frame_number;
00404         FLAC__uint64 sample_number;
00405     } number;
00409     FLAC__uint8 crc;
00414 } FLAC__FrameHeader;
00415 
00416 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; 
00417 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; 
00418 extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; 
00419 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; 
00420 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; 
00421 extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; 
00422 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; 
00423 extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; 
00424 extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; 
00429 typedef struct {
00430     FLAC__uint16 crc;
00435 } FLAC__FrameFooter;
00436 
00437 extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; 
00442 typedef struct {
00443     FLAC__FrameHeader header;
00444     FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
00445     FLAC__FrameFooter footer;
00446 } FLAC__Frame;
00447 
00448 /*****************************************************************************/
00449 
00450 
00451 /*****************************************************************************
00452  *
00453  * Meta-data structures
00454  *
00455  *****************************************************************************/
00456 
00458 typedef enum {
00459 
00460     FLAC__METADATA_TYPE_STREAMINFO = 0,
00463     FLAC__METADATA_TYPE_PADDING = 1,
00466     FLAC__METADATA_TYPE_APPLICATION = 2,
00469     FLAC__METADATA_TYPE_SEEKTABLE = 3,
00472     FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
00475     FLAC__METADATA_TYPE_CUESHEET = 5,
00478     FLAC__METADATA_TYPE_UNDEFINED = 6
00481 } FLAC__MetadataType;
00482 
00488 extern FLAC_API const char * const FLAC__MetadataTypeString[];
00489 
00490 
00493 typedef struct {
00494     unsigned min_blocksize, max_blocksize;
00495     unsigned min_framesize, max_framesize;
00496     unsigned sample_rate;
00497     unsigned channels;
00498     unsigned bits_per_sample;
00499     FLAC__uint64 total_samples;
00500     FLAC__byte md5sum[16];
00501 } FLAC__StreamMetadata_StreamInfo;
00502 
00503 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; 
00504 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; 
00505 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; 
00506 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; 
00507 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; 
00508 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; 
00509 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; 
00510 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; 
00511 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; 
00514 #define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)
00515 
00518 typedef struct {
00519     int dummy;
00524 } FLAC__StreamMetadata_Padding;
00525 
00526 
00529 typedef struct {
00530     FLAC__byte id[4];
00531     FLAC__byte *data;
00532 } FLAC__StreamMetadata_Application;
00533 
00534 extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; 
00538 typedef struct {
00539     FLAC__uint64 sample_number;
00542     FLAC__uint64 stream_offset;
00546     unsigned frame_samples;
00548 } FLAC__StreamMetadata_SeekPoint;
00549 
00550 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; 
00551 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; 
00552 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; 
00555 #define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u)
00556 
00561 extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;
00562 
00563 
00576 typedef struct {
00577     unsigned num_points;
00578     FLAC__StreamMetadata_SeekPoint *points;
00579 } FLAC__StreamMetadata_SeekTable;
00580 
00581 
00584 typedef struct {
00585     FLAC__uint32 length;
00586     FLAC__byte *entry;
00587 } FLAC__StreamMetadata_VorbisComment_Entry;
00588 
00589 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; 
00594 typedef struct {
00595     FLAC__StreamMetadata_VorbisComment_Entry vendor_string;
00596     FLAC__uint32 num_comments;
00597     FLAC__StreamMetadata_VorbisComment_Entry *comments;
00598 } FLAC__StreamMetadata_VorbisComment;
00599 
00600 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; 
00607 typedef struct {
00608     FLAC__uint64 offset;
00613     FLAC__byte number;
00615 } FLAC__StreamMetadata_CueSheet_Index;
00616 
00617 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; 
00618 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; 
00619 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; 
00626 typedef struct {
00627     FLAC__uint64 offset;
00630     FLAC__byte number;
00633     char isrc[13];
00636     unsigned type:1;
00639     unsigned pre_emphasis:1;
00642     FLAC__byte num_indices;
00645     FLAC__StreamMetadata_CueSheet_Index *indices;
00648 } FLAC__StreamMetadata_CueSheet_Track;
00649 
00650 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; 
00651 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; 
00652 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; 
00653 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; 
00654 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; 
00655 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; 
00656 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; 
00663 typedef struct {
00664     char media_catalog_number[129];
00670     FLAC__uint64 lead_in;
00673     FLAC__bool is_cd;
00676     unsigned num_tracks;
00679     FLAC__StreamMetadata_CueSheet_Track *tracks;
00682 } FLAC__StreamMetadata_CueSheet;
00683 
00684 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; 
00685 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; 
00686 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; 
00687 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; 
00688 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; 
00695 typedef struct {
00696     FLAC__byte *data;
00697 } FLAC__StreamMetadata_Unknown;
00698 
00699 
00702 typedef struct {
00703     FLAC__MetadataType type;
00708     FLAC__bool is_last;
00711     unsigned length;
00714     union {
00715         FLAC__StreamMetadata_StreamInfo stream_info;
00716         FLAC__StreamMetadata_Padding padding;
00717         FLAC__StreamMetadata_Application application;
00718         FLAC__StreamMetadata_SeekTable seek_table;
00719         FLAC__StreamMetadata_VorbisComment vorbis_comment;
00720         FLAC__StreamMetadata_CueSheet cue_sheet;
00721         FLAC__StreamMetadata_Unknown unknown;
00722     } data;
00725 } FLAC__StreamMetadata;
00726 
00727 extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; 
00728 extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; 
00729 extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; 
00732 #define FLAC__STREAM_METADATA_HEADER_LENGTH (4u)
00733 
00734 /*****************************************************************************/
00735 
00736 
00737 /*****************************************************************************
00738  *
00739  * Utility functions
00740  *
00741  *****************************************************************************/
00742 
00743 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
00752 FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
00753 
00754 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
00765 FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
00766 
00767 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
00780 FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
00781 
00782 /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
00801 FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation);
00802 
00803 /* \} */
00804 
00805 #ifdef __cplusplus
00806 }
00807 #endif
00808 
00809 #endif

Generated on Fri Oct 3 00:07:10 2003 for FLAC by doxygen1.3