FLAC  1.2.1
format.h
Go to the documentation of this file.
1 /* libFLAC - Free Lossless Audio Codec library
2  * Copyright (C) 2000,2001,2002,2003,2004,2005,2006,2007,2008,2009 Josh Coalson
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * - Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * - Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  *
15  * - Neither the name of the Xiph.org Foundation nor the names of its
16  * contributors may be used to endorse or promote products derived from
17  * this software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
23  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31 
32 #ifndef FLAC__FORMAT_H
33 #define FLAC__FORMAT_H
34 
35 #include "export.h"
36 #include "ordinals.h"
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
86 /*
87  Most of the values described in this file are defined by the FLAC
88  format specification. There is nothing to tune here.
89 */
90 
92 #define FLAC__MAX_METADATA_TYPE_CODE (126u)
93 
95 #define FLAC__MIN_BLOCK_SIZE (16u)
96 
98 #define FLAC__MAX_BLOCK_SIZE (65535u)
99 
102 #define FLAC__SUBSET_MAX_BLOCK_SIZE_48000HZ (4608u)
103 
105 #define FLAC__MAX_CHANNELS (8u)
106 
108 #define FLAC__MIN_BITS_PER_SAMPLE (4u)
109 
111 #define FLAC__MAX_BITS_PER_SAMPLE (32u)
112 
121 #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
122 
127 #define FLAC__MAX_SAMPLE_RATE (655350u)
128 
130 #define FLAC__MAX_LPC_ORDER (32u)
131 
134 #define FLAC__SUBSET_MAX_LPC_ORDER_48000HZ (12u)
135 
139 #define FLAC__MIN_QLP_COEFF_PRECISION (5u)
140 
144 #define FLAC__MAX_QLP_COEFF_PRECISION (15u)
145 
147 #define FLAC__MAX_FIXED_ORDER (4u)
148 
150 #define FLAC__MAX_RICE_PARTITION_ORDER (15u)
151 
153 #define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u)
154 
161 extern FLAC_API const char *FLAC__VERSION_STRING;
162 
167 extern FLAC_API const char *FLAC__VENDOR_STRING;
168 
170 extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */
171 
175 extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */
176 
178 extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
179 
181 #define FLAC__STREAM_SYNC_LENGTH (4u)
182 
183 
184 /*****************************************************************************
185  *
186  * Subframe structures
187  *
188  *****************************************************************************/
189 
190 /*****************************************************************************/
191 
193 typedef enum {
202 
208 extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[];
209 
210 
213 typedef struct {
214 
215  unsigned *parameters;
218  unsigned *raw_bits;
223  unsigned capacity_by_order;
229 
232 typedef struct {
233 
234  unsigned order;
241 
242 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN;
243 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN;
245 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN;
254 typedef struct {
256  union {
258  } data;
260 
261 extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN;
263 /*****************************************************************************/
264 
266 typedef enum {
272 
278 extern FLAC_API const char * const FLAC__SubframeTypeString[];
279 
280 
283 typedef struct {
284  FLAC__int32 value;
286 
287 
290 typedef struct {
291  const FLAC__int32 *data;
293 
294 
297 typedef struct {
298  FLAC__EntropyCodingMethod entropy_coding_method;
301  unsigned order;
304  FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
307  const FLAC__int32 *residual;
310 
311 
314 typedef struct {
315  FLAC__EntropyCodingMethod entropy_coding_method;
318  unsigned order;
321  unsigned qlp_coeff_precision;
324  int quantization_level;
327  FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
330  FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
333  const FLAC__int32 *residual;
336 
337 extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN;
338 extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN;
343 typedef struct {
344  FLAC__SubframeType type;
345  union {
346  FLAC__Subframe_Constant constant;
347  FLAC__Subframe_Fixed fixed;
348  FLAC__Subframe_LPC lpc;
349  FLAC__Subframe_Verbatim verbatim;
350  } data;
351  unsigned wasted_bits;
353 
361 extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN;
362 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN;
363 extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN;
365 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK;
366 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK;
367 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK;
368 extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK;
370 /*****************************************************************************/
371 
372 
373 /*****************************************************************************
374  *
375  * Frame structures
376  *
377  *****************************************************************************/
378 
380 typedef enum {
386 
392 extern FLAC_API const char * const FLAC__ChannelAssignmentString[];
393 
395 typedef enum {
399 
405 extern FLAC_API const char * const FLAC__FrameNumberTypeString[];
406 
407 
410 typedef struct {
411  unsigned blocksize;
414  unsigned sample_rate;
417  unsigned channels;
420  FLAC__ChannelAssignment channel_assignment;
423  unsigned bits_per_sample;
426  FLAC__FrameNumberType number_type;
431  union {
432  FLAC__uint32 frame_number;
433  FLAC__uint64 sample_number;
434  } number;
438  FLAC__uint8 crc;
444 
445 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC;
446 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN;
447 extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN;
448 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCKING_STRATEGY_LEN;
449 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN;
450 extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN;
451 extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN;
452 extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN;
453 extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN;
454 extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN;
459 typedef struct {
460  FLAC__uint16 crc;
466 
467 extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN;
472 typedef struct {
473  FLAC__FrameHeader header;
475  FLAC__FrameFooter footer;
476 } FLAC__Frame;
477 
478 /*****************************************************************************/
479 
480 
481 /*****************************************************************************
482  *
483  * Meta-data structures
484  *
485  *****************************************************************************/
486 
488 typedef enum {
489 
515 
521 extern FLAC_API const char * const FLAC__MetadataTypeString[];
522 
523 
526 typedef struct {
527  unsigned min_blocksize, max_blocksize;
528  unsigned min_framesize, max_framesize;
529  unsigned sample_rate;
530  unsigned channels;
531  unsigned bits_per_sample;
532  FLAC__uint64 total_samples;
533  FLAC__byte md5sum[16];
535 
536 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN;
537 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN;
538 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN;
539 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN;
540 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN;
541 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN;
542 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN;
543 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN;
544 extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN;
547 #define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)
548 
551 typedef struct {
552  int dummy;
558 
559 
562 typedef struct {
563  FLAC__byte id[4];
564  FLAC__byte *data;
566 
567 extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN;
571 typedef struct {
572  FLAC__uint64 sample_number;
575  FLAC__uint64 stream_offset;
579  unsigned frame_samples;
582 
583 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN;
584 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN;
585 extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN;
588 #define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u)
589 
594 extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;
595 
596 
609 typedef struct {
610  unsigned num_points;
613 
614 
621 typedef struct {
622  FLAC__uint32 length;
623  FLAC__byte *entry;
625 
626 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN;
631 typedef struct {
633  FLAC__uint32 num_comments;
636 
637 extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN;
644 typedef struct {
645  FLAC__uint64 offset;
650  FLAC__byte number;
653 
654 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN;
655 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN;
656 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN;
663 typedef struct {
664  FLAC__uint64 offset;
667  FLAC__byte number;
670  char isrc[13];
673  unsigned type:1;
676  unsigned pre_emphasis:1;
679  FLAC__byte num_indices;
686 
687 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN;
688 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN;
689 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN;
690 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN;
691 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN;
692 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN;
693 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN;
700 typedef struct {
701  char media_catalog_number[129];
707  FLAC__uint64 lead_in;
710  FLAC__bool is_cd;
713  unsigned num_tracks;
720 
721 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN;
722 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN;
723 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN;
724 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN;
725 extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN;
729 typedef enum {
751  FLAC__STREAM_METADATA_PICTURE_TYPE_UNDEFINED
753 
760 extern FLAC_API const char * const FLAC__StreamMetadata_Picture_TypeString[];
761 
766 typedef struct {
770  char *mime_type;
781  FLAC__byte *description;
788  FLAC__uint32 width;
791  FLAC__uint32 height;
794  FLAC__uint32 depth;
797  FLAC__uint32 colors;
802  FLAC__uint32 data_length;
805  FLAC__byte *data;
809 
810 extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_TYPE_LEN;
811 extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_MIME_TYPE_LENGTH_LEN;
812 extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DESCRIPTION_LENGTH_LEN;
813 extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_WIDTH_LEN;
814 extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_HEIGHT_LEN;
815 extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DEPTH_LEN;
816 extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_COLORS_LEN;
817 extern FLAC_API const unsigned FLAC__STREAM_METADATA_PICTURE_DATA_LENGTH_LEN;
824 typedef struct {
825  FLAC__byte *data;
827 
828 
831 typedef struct {
832  FLAC__MetadataType type;
837  FLAC__bool is_last;
840  unsigned length;
843  union {
848  FLAC__StreamMetadata_VorbisComment vorbis_comment;
852  } data;
856 
857 extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN;
858 extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN;
859 extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN;
862 #define FLAC__STREAM_METADATA_HEADER_LENGTH (4u)
863 
864 /*****************************************************************************/
865 
866 
867 /*****************************************************************************
868  *
869  * Utility functions
870  *
871  *****************************************************************************/
872 
880 FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
881 
892 FLAC_API FLAC__bool FLAC__format_blocksize_is_subset(unsigned blocksize, unsigned sample_rate);
893 
903 FLAC_API FLAC__bool FLAC__format_sample_rate_is_subset(unsigned sample_rate);
904 
917 FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_name_is_legal(const char *name);
918 
933 FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_value_is_legal(const FLAC__byte *value, unsigned length);
934 
950 FLAC_API FLAC__bool FLAC__format_vorbiscomment_entry_is_legal(const FLAC__byte *entry, unsigned length);
951 
962 FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
963 
976 FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
977 
996 FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation);
997 
1014 FLAC_API FLAC__bool FLAC__format_picture_is_legal(const FLAC__StreamMetadata_Picture *picture, const char **violation);
1015 
1016 /* \} */
1017 
1018 #ifdef __cplusplus
1019 }
1020 #endif
1021 
1022 #endif