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) */
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) */
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) */
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;
*/
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
/** 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.
* \assert
/*@@@@ 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.
projects / platform / upstream / flac.git / commitdiff