Commit a70054d7 authored by Josh Coalson's avatar Josh Coalson
Browse files

write up some missing documentation

parent 4b08c0b0
......@@ -588,24 +588,18 @@ typedef struct {
extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */
/** XXX. (c.f. <A HREF="../format.html#XXX">format specification</A>)
/** FLAC CUESHEET track index structure. (See the
* <A HREF="../format.html#cuesheet_track_index">format specification</A> for
* the full description of each field.)
*/
typedef struct {
FLAC__uint64 offset;
/**< The index offset from the beginning of the track, in samples.
* For CD-DA, the offset must be evenly divisible by 588 samples (588
* samples = 44100 samples/sec * 1/75th of a sec). Note that the
* offset is from the beginning of the track, not the beginning of
* the audio data.
/**< Offset in samples, relative to the track offset, of the index
* point.
*/
FLAC__byte number;
/**< The index number. For CD-DA, an index number of 0 corresponds
* to the track pregap. There must be at least one index in every
* track except the lead-out track. The first index in a track must
* be 0 or 1 and subsequently index numbers must increase by 1. Index
* numbers must be unique within a track.
*/
/**< The index point number. */
} FLAC__StreamMetadata_CueSheet_Index;
extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */
......@@ -613,35 +607,32 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN;
extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == @@@@3*8 (bits) */
/** XXX. (c.f. <A HREF="../format.html#XXX">format specification</A>)
/** FLAC CUESHEET track structure. (See the
* <A HREF="../format.html#cuesheet_track">format specification</A> for
* the full description of each field.)
*/
typedef struct {
FLAC__uint64 offset;
/**< The track offset from the beginning of the audio data, in samples.
* This track offset is the offset to the first index point of the
* track. Note that for CD-DA, the track's offset in the TOC is that
* of the track's INDEX 01 even if there is an INDEX 00.
*
* For CD-DA, the offset must be evenly divisible by 588 samples (588
* samples = 44100 samples/sec * 1/75th of a sec).
*/
/**< Track offset in samples, relative to the beginning of the FLAC audio stream. */
FLAC__byte number;
/**< The track number. A track number of 0 is not allowed to avoid
* conflicting with the CD-DA spec, which reserves this for the
* lead-in. For CD-DA the number must be 1-99, or 170 for the lead-out.
* It is not required but encouraged to start with track 1 and increase
* sequentially. A CUESHEET block is required to have a lead-out
* track; it is always the last track in the cuesheet and the number
* must be 170 for CD-DA. Track numbers must be unique within a
* CUESHEET.
*/
/**< The track number. */
char isrc[13];
/**< Track ISRC. This is a 12-digit alphanumeric code plus a trailing '\0' */
unsigned type:1;
/**< The track type: 0 for audio, 1 for non-audio. */
unsigned pre_emphasis:1;
/**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */
char isrc[13]; /*@@@@ 12 ascii characters plus trailing '\0' */
unsigned type:1; /*@@@@q-channel control bit 3: 0=>audio, 1=>data (undefined for CD-DA, defined for CDROM) */
unsigned pre_emphasis:1; /*@@@@q-channel control bit 5: 0=>no pre-em, 1=>pre-em */
FLAC__byte num_indices;
/**< The number of track index points. */
FLAC__StreamMetadata_CueSheet_Index *indices;
/**< NULL if num_indices == 0, else pointer to array of index points. */
} FLAC__StreamMetadata_CueSheet_Track;
extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */
......@@ -653,14 +644,29 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN
extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */
/** FLAC CUESHEET structure. (c.f. <A HREF="../format.html#metadata_block_cuesheet">format specification</A>)
/** FLAC CUESHEET structure. (See the
* <A HREF="../format.html#metadata_block_cuesheet">format specification</A>
* for the full description of each field.)
*/
typedef struct {
char media_catalog_number[129]; /*@@@@ in the stream, the media_catalog_number will be 128 alphanumeric ascii characters; unused digits are padded out to the right with NUL characters. in memory, the 129th character will be guaranteed to be a null character so that the whole string is always a valid C string. CD-DA: 13 ascii digits ('0'-'9') plus 116 trailing '\0' characters */
FLAC__uint64 lead_in; /*@@@@ length of lead-in in samples; required to compute some versions of CD TOC hashes; CD-DA says the lead-in must be digital silence and rippers don't save it by convention, so TRACK 00 is disallowed and instead we store only the length. The lead-in is the number of samples up to the first index point of the first track, \b not INDEX 01 of the first track. This is so applications can correctly compute a CD-DA TOC equivalent even when there is TRACK 01 INDEX 00 data. */
FLAC__bool is_cd; /* \c true if CUESHEET corresponds to a Compact Disc, else \c false */
char media_catalog_number[129];
/**< Media catalog number, in ASCII printable characters 0x20-0x7e. In
* general, the media catalog number may be 0 to 128 bytes long; any
* unused characters should be right-padded with NUL characters.
*/
FLAC__uint64 lead_in;
/**< The number of lead-in samples. */
FLAC__bool is_cd;
/**< \c true if CUESHEET corresponds to a Compact Disc, else \c false */
unsigned num_tracks;
/**< The number of tracks. */
FLAC__StreamMetadata_CueSheet_Track *tracks;
/**< NULL if num_tracks == 0, else pointer to array of tracks. */
} FLAC__StreamMetadata_CueSheet;
extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */
......@@ -670,7 +676,9 @@ extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**<
extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */
/** Structure that is used when a metadata block of unknown type is loaded. The contents are opaque.
/** Structure that is used when a metadata block of unknown type is loaded.
* The contents are opaque. The structure is used only internally to
* correctly handle unknown metadata.
*/
typedef struct {
FLAC__byte *data;
......
......@@ -1172,6 +1172,7 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__
*/
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_resize_comments(FLAC__StreamMetadata *object, unsigned new_num_comments);
/*@@@@ code and docs need to assert on track_num */
/** Sets a comment in a VORBIS_COMMENT block.
*
* If \a copy is \c true, a copy of the entry is stored; otherwise, the object
......@@ -1217,10 +1218,6 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_comment(FLAC__Stream
FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_insert_comment(FLAC__StreamMetadata *object, unsigned comment_num, FLAC__StreamMetadata_VorbisComment_Entry entry, FLAC__bool copy);
/** Delete a comment in a VORBIS_COMMENT block at the given index.
*
* If \a copy is \c true, a copy of the entry is stored; otherwise, the object
* takes ownership of the \c entry->entry pointer. Returns \c false if
* \a copy == \c true and malloc fails.
*
* \param object A pointer to an existing VORBIS_COMMENT object.
* \param comment_num The index of the comment to delete.
......@@ -1310,30 +1307,147 @@ FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_C
/*@@@@ document */
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_resize_indices(FLAC__StreamMetadata *object, unsigned track_num, unsigned new_num_indices);
/*@@@@ document */
/** Insert an index point in a CUESHEET track at the given index.
*
* \param object A pointer to an existing CUESHEET object.
* \param track_num The index of the track to modify. NOTE: this is not
* necessarily the same as the track's \a number field.
* \param index_num The index into the track's index array at which to
* insert the index point. NOTE: this is not necessarily
* the same as the index point's \a number field. The
* indices at and after \a index_num move right one
* position. To append an index point to the end, set
* \a index_num to
* \c object->data.cue_sheet.tracks[track_num].num_indices .
* \param index The index point to insert.
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
* \code object->data.cue_sheet.num_tracks >= track_num \endcode
* \code object->data.cue_sheet.num_tracks > track_num \endcode
* \code object->data.cue_sheet.tracks[track_num].num_indices >= index_num \endcode
* \retval FLAC__bool
* \c false if realloc fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num, FLAC__StreamMetadata_CueSheet_Index index);
/*@@@@ document, add to unit tests */
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_insert_blank_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
/*@@@@ document */
/** Delete an index point in a CUESHEET track at the given index.
*
* \param object A pointer to an existing CUESHEET object.
* \param track_num The index into the track array of the track to
* modify. NOTE: this is not necessarily the same
* as the track's \a number field.
* \param index_num The index into the track's index array of the index
* to delete. NOTE: this is not necessarily the same
* as the index's \a number field.
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
* \code object->data.cue_sheet.num_tracks > track_num \endcode
* \code object->data.cue_sheet.tracks[track_num].num_indices > index_num \endcode
* \retval FLAC__bool
* \c false if realloc fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__StreamMetadata *object, unsigned track_num, unsigned index_num);
/*@@@@ document */
/** Resize the track array.
*
* If the size shrinks, elements will truncated; if it grows, new blank
* tracks will be added to the end.
*
* \param object A pointer to an existing CUESHEET object.
* \param new_num_tracks The desired length of the array; may be \c 0.
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
* \code (object->data.cue_sheet.tracks == NULL && object->data.cue_sheet.num_tracks == 0) ||
* (object->data.cue_sheet.tracks != NULL && object->data.cue_sheet.num_tracks > 0) \endcode
* \retval FLAC__bool
* \c false if memory allocation error, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_resize_tracks(FLAC__StreamMetadata *object, unsigned new_num_tracks);
/*@@@@ document */
/*@@@@ you may safely un-const the \a track pointer if \a copy is \c true */
/*@@@@ code and docs need to assert on track_num */
/** Sets a track in a CUESHEET block.
*
* If \a copy is \c true, a copy of the track is stored; otherwise, the object
* takes ownership of the \a track pointer. Returns \c false if
* \a copy == \c true and malloc fails.
*
* \param object A pointer to an existing CUESHEET object.
* \param track_num Index into track array to set. NOTE: this is not
* necessarily the same as the track's \a number field.
* \param track The track to set the track to. You may safely pass in
* a const pointer if \a copy is \c true.
* \param copy See above.
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
* \retval FLAC__bool
* \c false if \a copy is \c true and malloc fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_set_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
/*@@@@ document */
/*@@@@ you may safely un-const the \a track pointer if \a copy is \c true */
/** Insert a track in a CUESHEET block at the given index.
*
* If \a copy is \c true, a copy of the track is stored; otherwise, the object
* takes ownership of the \a track pointer. Returns \c false if
* \a copy == \c true and malloc fails.
*
* \param object A pointer to an existing CUESHEET object.
* \param track_num The index at which to insert the track. NOTE: this
* is not necessarily the same as the track's \a number
* field. The tracks at and after \a track_num move right
* one position. To append a track to the end, set
* \a track_num to \c object->data.cue_sheet.num_tracks .
* \param track The track to insert. You may safely pass in a const
* pointer if \a copy is \c true.
* \param copy See above.
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
* \code object->data.cue_sheet.num_tracks >= track_num \endcode
* \retval FLAC__bool
* \c false if \a copy is \c true and malloc fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_track(FLAC__StreamMetadata *object, unsigned track_num, FLAC__StreamMetadata_CueSheet_Track *track, FLAC__bool copy);
/*@@@@ document, add to unit tests */
/*@@@@ add to unit tests */
/** Insert a blank track in a CUESHEET block at the given index.
*
* A blank track is one in which all field values are zero.
*
* \param object A pointer to an existing CUESHEET object.
* \param track_num The index at which to insert the track. NOTE: this
* is not necessarily the same as the track's \a number
* field. The tracks at and after \a track_num move right
* one position. To append a track to the end, set
* \a track_num to \c object->data.cue_sheet.num_tracks .
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
* \code object->data.cue_sheet.num_tracks >= track_num \endcode
* \retval FLAC__bool
* \c false if \a copy is \c true and malloc fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_insert_blank_track(FLAC__StreamMetadata *object, unsigned track_num);
/*@@@@ document */
/** Delete a track in a CUESHEET block at the given index.
*
* \param object A pointer to an existing CUESHEET object.
* \param track_num The index into the track array of the track to
* delete. NOTE: this is not necessarily the same
* as the track's \a number field.
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_CUESHEET \endcode
* \code object->data.cue_sheet.num_tracks > track_num \endcode
* \retval FLAC__bool
* \c false if realloc fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_delete_track(FLAC__StreamMetadata *object, unsigned track_num);
/** Check a cue sheet to see if it conforms to the FLAC specification.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment