Skip to content

Link format.h documentation to RFC 9639 #947

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Sinkleberg wants to merge 1 commit into
base: master
Choose a base branch
from
+30 −30
Open

Link format.h documentation to RFC 9639 #947

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions include/FLAC/format.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ extern "C" {
* structures used by the rest of the interfaces.
*
* First, you should be familiar with the
* <A HREF="https://xiph.org/flac/format.html">FLAC format</A>. Many of the values here
* <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html">FLAC format</A>. Many of the values here
* follow directly from the specification. As a user of libFLAC, the
* interesting parts really are the structures that describe the frame
* header and metadata blocks.
Expand Down Expand Up @@ -225,7 +225,7 @@ typedef struct {
*/
} FLAC__EntropyCodingMethod_PartitionedRiceContents;

/** Header for a Rice partitioned residual. (c.f. <A HREF="https://xiph.org/flac/format.html#partitioned_rice">format specification</A>)
/** Header for a Rice partitioned residual. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-coded-residual">format specification</A>)
*/
typedef struct {

Expand All @@ -247,7 +247,7 @@ extern FLAC_API const uint32_t FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCA
extern FLAC_API const uint32_t FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_ESCAPE_PARAMETER;
/**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE2_PARAMETER_LEN)-1 */

/** Header for the entropy coding method. (c.f. <A HREF="https://xiph.org/flac/format.html#residual">format specification</A>)
/** Header for the entropy coding method. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-coded-residual">format specification</A>)
*/
typedef struct {
FLAC__EntropyCodingMethodType type;
Expand Down Expand Up @@ -276,7 +276,7 @@ typedef enum {
extern FLAC_API const char * const FLAC__SubframeTypeString[];


/** CONSTANT subframe. (c.f. <A HREF="https://xiph.org/flac/format.html#subframe_constant">format specification</A>)
/** CONSTANT subframe. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-constant-subframe">format specification</A>)
*/
typedef struct {
FLAC__int64 value; /**< The constant signal value. */
Expand All @@ -289,7 +289,7 @@ typedef enum {
} FLAC__VerbatimSubframeDataType;


/** VERBATIM subframe. (c.f. <A HREF="https://xiph.org/flac/format.html#subframe_verbatim">format specification</A>)
/** VERBATIM subframe. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-verbatim-subframe">format specification</A>)
*/
typedef struct {
union {
Expand All @@ -300,7 +300,7 @@ typedef struct {
} FLAC__Subframe_Verbatim;


/** FIXED subframe. (c.f. <A HREF="https://xiph.org/flac/format.html#subframe_fixed">format specification</A>)
/** FIXED subframe. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-fixed-predictor-subframe">format specification</A>)
*/
typedef struct {
FLAC__EntropyCodingMethod entropy_coding_method;
Expand All @@ -317,7 +317,7 @@ typedef struct {
} FLAC__Subframe_Fixed;


/** LPC subframe. (c.f. <A HREF="https://xiph.org/flac/format.html#subframe_lpc">format specification</A>)
/** LPC subframe. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-linear-predictor-subframe">format specification</A>)
*/
typedef struct {
FLAC__EntropyCodingMethod entropy_coding_method;
Expand Down Expand Up @@ -346,7 +346,7 @@ extern FLAC_API const uint32_t FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /**<
extern FLAC_API const uint32_t FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /**< == 5 (bits) */


/** FLAC subframe structure. (c.f. <A HREF="https://xiph.org/flac/format.html#subframe">format specification</A>)
/** FLAC subframe structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-subframes">format specification</A>)
*/
typedef struct {
FLAC__SubframeType type;
Expand Down Expand Up @@ -413,7 +413,7 @@ typedef enum {
extern FLAC_API const char * const FLAC__FrameNumberTypeString[];


/** FLAC frame header structure. (c.f. <A HREF="https://xiph.org/flac/format.html#frame_header">format specification</A>)
/** FLAC frame header structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-frame-header">format specification</A>)
*/
typedef struct {
uint32_t blocksize;
Expand Down Expand Up @@ -462,7 +462,7 @@ extern FLAC_API const uint32_t FLAC__FRAME_HEADER_ZERO_PAD_LEN; /**< == 1 (bit)
extern FLAC_API const uint32_t FLAC__FRAME_HEADER_CRC_LEN; /**< == 8 (bits) */


/** FLAC frame footer structure. (c.f. <A HREF="https://xiph.org/flac/format.html#frame_footer">format specification</A>)
/** FLAC frame footer structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-frame-footer">format specification</A>)
*/
typedef struct {
FLAC__uint16 crc;
Expand All @@ -475,7 +475,7 @@ typedef struct {
extern FLAC_API const uint32_t FLAC__FRAME_FOOTER_CRC_LEN; /**< == 16 (bits) */


/** FLAC frame structure. (c.f. <A HREF="https://xiph.org/flac/format.html#frame">format specification</A>)
/** FLAC frame structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-frame-structure">format specification</A>)
*/
typedef struct {
FLAC__FrameHeader header;
Expand All @@ -496,25 +496,25 @@ typedef struct {
typedef enum {

FLAC__METADATA_TYPE_STREAMINFO = 0,
/**< <A HREF="https://xiph.org/flac/format.html#metadata_block_streaminfo">STREAMINFO</A> block */
/**< <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-streaminfo">STREAMINFO</A> block */

FLAC__METADATA_TYPE_PADDING = 1,
/**< <A HREF="https://xiph.org/flac/format.html#metadata_block_padding">PADDING</A> block */
/**< <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-padding">PADDING</A> block */

FLAC__METADATA_TYPE_APPLICATION = 2,
/**< <A HREF="https://xiph.org/flac/format.html#metadata_block_application">APPLICATION</A> block */
/**< <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-application">APPLICATION</A> block */

FLAC__METADATA_TYPE_SEEKTABLE = 3,
/**< <A HREF="https://xiph.org/flac/format.html#metadata_block_seektable">SEEKTABLE</A> block */
/**< <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-seek-table">SEEKTABLE</A> block */

FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
/**< <A HREF="https://xiph.org/flac/format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block (a.k.a. FLAC tags) */
/**< <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-vorbis-comment">VORBISCOMMENT</A> block (a.k.a. FLAC tags) */

FLAC__METADATA_TYPE_CUESHEET = 5,
/**< <A HREF="https://xiph.org/flac/format.html#metadata_block_cuesheet">CUESHEET</A> block */
/**< <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-cuesheet">CUESHEET</A> block */

FLAC__METADATA_TYPE_PICTURE = 6,
/**< <A HREF="https://xiph.org/flac/format.html#metadata_block_picture">PICTURE</A> block */
/**< <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-picture">PICTURE</A> block */

FLAC__METADATA_TYPE_UNDEFINED = 7,
/**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */
Expand All @@ -531,7 +531,7 @@ typedef enum {
extern FLAC_API const char * const FLAC__MetadataTypeString[];


/** FLAC STREAMINFO structure. (c.f. <A HREF="https://xiph.org/flac/format.html#metadata_block_streaminfo">format specification</A>)
/** FLAC STREAMINFO structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-streaminfo">format specification</A>)
*/
typedef struct {
uint32_t min_blocksize, max_blocksize;
Expand All @@ -556,7 +556,7 @@ extern FLAC_API const uint32_t FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /**<
/** The total stream length of the STREAMINFO block in bytes. */
#define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)

/** FLAC PADDING structure. (c.f. <A HREF="https://xiph.org/flac/format.html#metadata_block_padding">format specification</A>)
/** FLAC PADDING structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-padding">format specification</A>)
*/
typedef struct {
int dummy;
Expand All @@ -567,7 +567,7 @@ typedef struct {
} FLAC__StreamMetadata_Padding;


/** FLAC APPLICATION structure. (c.f. <A HREF="https://xiph.org/flac/format.html#metadata_block_application">format specification</A>)
/** FLAC APPLICATION structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-application">format specification</A>)
*/
typedef struct {
FLAC__byte id[4];
Expand All @@ -576,7 +576,7 @@ typedef struct {

extern FLAC_API const uint32_t FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /**< == 32 (bits) */

/** SeekPoint structure used in SEEKTABLE blocks. (c.f. <A HREF="https://xiph.org/flac/format.html#seekpoint">format specification</A>)
/** SeekPoint structure used in SEEKTABLE blocks. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-seek-point">format specification</A>)
*/
typedef struct {
FLAC__uint64 sample_number;
Expand Down Expand Up @@ -604,7 +604,7 @@ extern FLAC_API const uint32_t FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN
extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;


/** FLAC SEEKTABLE structure. (c.f. <A HREF="https://xiph.org/flac/format.html#metadata_block_seektable">format specification</A>)
/** FLAC SEEKTABLE structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-seek-table">format specification</A>)
*
* \note From the format specification:
* - The seek points must be sorted by ascending sample number.
Expand All @@ -622,7 +622,7 @@ typedef struct {
} FLAC__StreamMetadata_SeekTable;


/** Vorbis comment entry structure used in VORBIS_COMMENT blocks. (c.f. <A HREF="https://xiph.org/flac/format.html#metadata_block_vorbis_comment">format specification</A>)
/** Vorbis comment entry structure used in VORBIS_COMMENT blocks. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-vorbis-comment">format specification</A>)
*
* For convenience, the APIs maintain a trailing NUL character at the end of
* \a entry which is not counted toward \a length, i.e.
Expand All @@ -636,7 +636,7 @@ typedef struct {
extern FLAC_API const uint32_t FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /**< == 32 (bits) */


/** FLAC VORBIS_COMMENT structure. (c.f. <A HREF="https://xiph.org/flac/format.html#metadata_block_vorbis_comment">format specification</A>)
/** FLAC VORBIS_COMMENT structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-vorbis-comment">format specification</A>)
*/
typedef struct {
FLAC__StreamMetadata_VorbisComment_Entry vendor_string;
Expand All @@ -648,7 +648,7 @@ extern FLAC_API const uint32_t FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS


/** FLAC CUESHEET track index structure. (See the
* <A HREF="https://xiph.org/flac/format.html#cuesheet_track_index">format specification</A> for
* <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-cuesheet-track-index-point">format specification</A> for
* the full description of each field.)
*/
typedef struct {
Expand All @@ -667,7 +667,7 @@ extern FLAC_API const uint32_t FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN


/** FLAC CUESHEET track structure. (See the
* <A HREF="https://xiph.org/flac/format.html#cuesheet_track">format specification</A> for
* <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-cuesheet-track">format specification</A> for
* the full description of each field.)
*/
typedef struct {
Expand Down Expand Up @@ -704,7 +704,7 @@ extern FLAC_API const uint32_t FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_


/** FLAC CUESHEET structure. (See the
* <A HREF="https://xiph.org/flac/format.html#metadata_block_cuesheet">format specification</A>
* <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-cuesheet">format specification</A>
* for the full description of each field.)
*/
typedef struct {
Expand Down Expand Up @@ -770,7 +770,7 @@ typedef enum {
extern FLAC_API const char * const FLAC__StreamMetadata_Picture_TypeString[];

/** FLAC PICTURE structure. (See the
* <A HREF="https://xiph.org/flac/format.html#metadata_block_picture">format specification</A>
* <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-picture">format specification</A>
* for the full description of each field.)
*/
typedef struct {
Expand Down Expand Up @@ -836,7 +836,7 @@ typedef struct {
} FLAC__StreamMetadata_Unknown;


/** FLAC metadata block structure. (c.f. <A HREF="https://xiph.org/flac/format.html#metadata_block">format specification</A>)
/** FLAC metadata block structure. (c.f. <A HREF="https://www.rfc-editor.org/rfc/rfc9639.html#name-metadata-block-header">format specification</A>)
*/
typedef struct FLAC__StreamMetadata {
FLAC__MetadataType type;
Expand Down