| /////////////////////////////////////////////////////////////////////////////// |
| // |
| // The contents of this file are subject to the Mozilla Public License |
| // Version 1.1 (the "License"); you may not use this file except in |
| // compliance with the License. You may obtain a copy of the License at |
| // http://www.mozilla.org/MPL/ |
| // |
| // Software distributed under the License is distributed on an "AS IS" |
| // basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the |
| // License for the specific language governing rights and limitations |
| // under the License. |
| // |
| // The Original Code is MP4v2. |
| // |
| // The Initial Developer of the Original Code is Kona Blend. |
| // Portions created by Kona Blend are Copyright (C) 2008. |
| // All Rights Reserved. |
| // |
| // Contributors: |
| // Kona Blend, kona8lend@@gmail.com |
| // |
| /////////////////////////////////////////////////////////////////////////////// |
| |
| #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 */ |
