diff options
Diffstat (limited to 'include/mp4v2/chapter.h')
| -rw-r--r-- | include/mp4v2/chapter.h | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/include/mp4v2/chapter.h b/include/mp4v2/chapter.h new file mode 100644 index 0000000..5b493a5 --- /dev/null +++ b/include/mp4v2/chapter.h @@ -0,0 +1,176 @@ +#ifndef MP4V2_CHAPTER_H +#define MP4V2_CHAPTER_H + +/**************************************************************************//** + * + * @defgroup mp4_chapter MP4v2 Chapter + * @{ + * + *****************************************************************************/ + +/** The maximum length of a QuickTime chapter title (in 8-bit chars) + */ +#define MP4V2_CHAPTER_TITLE_MAX 1023 + +/** Chapter item. + * This item defines various attributes for a chapter. + * @ingroup mp4_chapter + */ +typedef struct MP4Chapter_s { + MP4Duration duration; /**< duration of chapter in milliseconds */ + char title[MP4V2_CHAPTER_TITLE_MAX+1]; /**< title of chapter */ +} MP4Chapter_t; + +/** Known chapter types. + * @ingroup mp4_chapter + */ +typedef enum { + MP4ChapterTypeNone = 0, /**< no chapters found return value */ + MP4ChapterTypeAny = 1, /**< any or all known chapter types */ + MP4ChapterTypeQt = 2, /**< QuickTime chapter type */ + MP4ChapterTypeNero = 4 /**< Nero chapter type */ +} MP4ChapterType; + +/** Add a QuickTime chapter. + * + * This function adds a QuickTime chapter to file <b>hFile</b>. + * + * @param hFile handle of file to add chapter. + * @param chapterTrackId ID of chapter track or #MP4_INVALID_TRACK_ID + * if unknown. + * @param chapterDuration duration (in the timescale of the chapter track). + * @param chapterTitle title text for the chapter or NULL to use default + * title format ("Chapter %03d", n) where n is the chapter number. + */ +MP4V2_EXPORT +void MP4AddChapter( + MP4FileHandle hFile, + MP4TrackId chapterTrackId, + MP4Duration chapterDuration, + const char* chapterTitle DEFAULT(0)); + +/** Add a QuickTime chapter track. + * + * This function adds a chapter (text) track to file <b>hFile</b>. + * The optional parameter <b>timescale</b> may be supplied to give the new + * chapter a specific timescale. Otherwise the chapter track will have + * the same timescale as the reference track defined in parameter refTrackId. + * + * @param hFile handle of file to add chapter track. + * @param refTrackId ID of the track that will reference the chapter track. + * @param timescale the timescale of the chapter track or 0 to use the + * timescale of track specified by <b>refTrackId</b>. + * + * @return ID of the created chapter track. + */ +MP4V2_EXPORT +MP4TrackId MP4AddChapterTextTrack( + MP4FileHandle hFile, + MP4TrackId refTrackId, + uint32_t timescale DEFAULT(0) ); + +/** Add a Nero chapter. + * + * This function adds a Nero chapter to file <b>hFile</b>. + * + * @param hFile handle of file to add chapter. + * @param chapterStart the start time of the chapter in 100 nanosecond units + * @param chapterTitle title text for the chapter or NULL to use default + * title format ("Chapter %03d", n) where n is the chapter number. + */ +MP4V2_EXPORT +void MP4AddNeroChapter( + MP4FileHandle hFile, + MP4Timestamp chapterStart, + const char* chapterTitle DEFAULT(0)); + +/** Convert chapters to another type. + * + * This function converts existing chapters in file <b>hFile</b> + * from one type to another type. + * Conversion from Nero to QuickTime or QuickTime to Nero is supported. + * + * @param hFile handle of file to convert. + * @param toChapterType the chapter type to convert to: + * @li #MP4ChapterTypeQt (convert from Nero to Qt) + * @li #MP4ChapterTypeNero (convert from Qt to Nero) + * + * @return the chapter type before conversion or #MP4ChapterTypeNone + * if the source chapters do not exist + * or invalid <b>toChapterType</b> was specified. + */ +MP4V2_EXPORT +MP4ChapterType MP4ConvertChapters( + MP4FileHandle hFile, + MP4ChapterType toChapterType DEFAULT(MP4ChapterTypeQt)); + +/** Delete chapters. + * + * This function deletes existing chapters in file <b>hFile</b>. + * + * @param hFile handle of file to delete chapters. + * @param chapterType the type of chapters to delete: + * @li #MP4ChapterTypeAny (delete all known chapter types) + * @li #MP4ChapterTypeQt + * @li #MP4ChapterTypeNero + * @param chapterTrackId ID of the chapter track if known, + * or #MP4_INVALID_TRACK_ID. + * Only applies when <b>chapterType</b>=#MP4ChapterTypeQt. + * + * @return the type of deleted chapters + */ +MP4V2_EXPORT +MP4ChapterType MP4DeleteChapters( + MP4FileHandle hFile, + MP4ChapterType chapterType DEFAULT(MP4ChapterTypeQt), + MP4TrackId chapterTrackId DEFAULT(MP4_INVALID_TRACK_ID) ); + +/** Get list of chapters. + * + * This function gets a chpter list from file <b>hFile</b>. + * + * @param hFile handle of file to read. + * @param chapterList address receiving array of chapter items. + * If a non-NULL is received the caller is responsible for freeing the + * memory with MP4Free(). + * @param chapterCount address receiving count of items in array. + * @param chapterType the type of chapters to read: + * @li #MP4ChapterTypeAny (any chapters, searched in order of Qt, Nero) + * @li #MP4ChapterTypeQt + * @li #MP4ChapterTypeNero + * + * @result the first type of chapters found. + */ +MP4V2_EXPORT +MP4ChapterType MP4GetChapters( + MP4FileHandle hFile, + MP4Chapter_t** chapterList, + uint32_t* chapterCount, + MP4ChapterType chapterType DEFAULT(MP4ChapterTypeQt)); + +/** Set list of chapters OKOK. + * + * This functions sets the complete chapter list in file <b>hFile</b>. + * If any chapters of the same type already exist they will first + * be deleted. + * + * @param hFile handle of file to modify. + * @param chapterList array of chapters items. + * @param chapterCount count of items in array. + * @param chapterType type of chapters to write: + * @li #MP4ChapterTypeAny (chapters of all types are written) + * @li #MP4ChapterTypeQt + * @li #MP4ChapterTypeNero + * + * @return the type of chapters written. + */ +MP4V2_EXPORT +MP4ChapterType MP4SetChapters( + MP4FileHandle hFile, + MP4Chapter_t* chapterList, + uint32_t chapterCount, + MP4ChapterType chapterType DEFAULT(MP4ChapterTypeQt)); + +/** @} ***********************************************************************/ + +#endif /* MP4V2_CHAPTER_H */ |