cxh/kunlang_video
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

mp4库

Browse Source
This commit is contained in:
cxh 2025-11-14 10:34:09 +08:00
parent e95d98f983
commit df4e3317f4
17 changed files with 5863 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
third_party/include/mp4v2/chapter.h vendored Normal file
View File

@ -0,0 +1,198 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.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 */

548
third_party/include/mp4v2/file.h vendored Normal file
View File

@ -0,0 +1,548 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.com
* Kona Blend, kona8lend@gmail.com
* Robert Kausch, robert.kausch@freac.org
*/
#ifndef MP4V2_FILE_H
#define MP4V2_FILE_H
/**************************************************************************//**
*
* @defgroup mp4_file MP4v2 File I/O
* @{
*
*****************************************************************************/
/** Bit: enable 64-bit data-atoms. */
#define MP4_CREATE_64BIT_DATA 0x01
/** Bit: enable 64-bit time-atoms. @note Incompatible with QuickTime. */
#define MP4_CREATE_64BIT_TIME 0x02
/** Bit: do not recompute avg/max bitrates on file close. @note See http://code.google.com/p/mp4v2/issues/detail?id=66 */
#define MP4_CLOSE_DO_NOT_COMPUTE_BITRATE 0x01
/** Enumeration of file modes for custom file provider. */
typedef enum MP4FileMode_e
{
FILEMODE_UNDEFINED, /**< undefined */
FILEMODE_READ, /**< file may be read */
FILEMODE_MODIFY, /**< file may be read/written */
FILEMODE_CREATE /**< file will be created/truncated for read/write */
} MP4FileMode;
/** Structure of functions implementing custom file provider.
*
* @deprecated The file provider API is deprecated since MP4v2 2.1.0. Please
* use MP4IOCallbacks instead.
*
* Except for <b>open</b>, all the functions must return 0 upon success
* or a non-zero value to indicate failure. The open function must return
* a pointer or handle which represents the open file, otherwise NULL.
*
* The reserved argument is currently always 0 and should be ignored.
*
* @see MP4IOCallbacks
*/
typedef struct MP4FileProvider_s
{
void* ( *open )( const char* name, MP4FileMode mode );
int ( *seek )( void* handle, int64_t pos );
int ( *read )( void* handle, void* buffer, int64_t size, int64_t* nin, int64_t reserved );
int ( *write )( void* handle, const void* buffer, int64_t size, int64_t* nout, int64_t reserved );
int ( *close )( void* handle );
} MP4FileProvider;
/** Structure of functions implementing custom I/O callbacks.
*
* Except for <b>size</b>, all the functions must return 0 upon success
* or a non-zero value to indicate failure. The size function must return
* the size of the file/buffer or -1 in case of failure.
*
* @see MP4CreateCallbacks()
* @see MP4ModifyCallbacks()
* @see MP4ReadCallbacks()
*/
typedef struct MP4IOCallbacks_s
{
int64_t ( *size )( void* handle );
int ( *seek )( void* handle, int64_t pos );
int ( *read )( void* handle, void* buffer, int64_t size, int64_t* nin );
int ( *write )( void* handle, const void* buffer, int64_t size, int64_t* nout );
int ( *truncate )( void* handle, int64_t size );
} MP4IOCallbacks;
/** Close an mp4 file.
* MP4Close closes a previously opened mp4 file. If the file was opened
* writable with MP4Create() or MP4Modify(), then MP4Close() will write
* out all pending information to disk.
*
* @param hFile handle of file to close.
* @param flags bitmask that allows the user to set extra options for the
* close commands. Valid options include:
* @li #MP4_CLOSE_DO_NOT_COMPUTE_BITRATE
*/
MP4V2_EXPORT
void MP4Close(
MP4FileHandle hFile,
uint32_t flags DEFAULT(0) );
/** Create a new mp4 file.
*
* MP4Create is the first call that should be used when you want to create a
* new, empty mp4 file. It is equivalent to opening a file for writing, but is
* also involved with the creation of necessary mp4 framework structures. I.e.
* invoking MP4Create() followed by MP4Close() will result in a file with a
* non-zero size.
*
* @param fileName pathname of the file to be created.
* On Windows, this should be a UTF-8 encoded string.
* On other platforms, it should be an 8-bit encoding that is
* appropriate for the platform, locale, file system, etc.
* (prefer to use UTF-8 when possible).
* @param flags bitmask that allows the user to set 64-bit values for
* data or time atoms. Valid bits may be any combination of:
* @li #MP4_CREATE_64BIT_DATA
* @li #MP4_CREATE_64BIT_TIME
*
* @return On success a handle of the newly created file for use in subsequent
* calls to the library. On error, #MP4_INVALID_FILE_HANDLE.
*
* @see MP4CreateEx()
*/
MP4V2_EXPORT
MP4FileHandle MP4Create(
const char* fileName,
uint32_t flags DEFAULT(0) );
/** Create a new mp4 file with extended options.
*
* MP4CreateEx is an extended version of MP4Create().
*
* @param fileName pathname of the file to be created.
* On Windows, this should be a UTF-8 encoded string.
* On other platforms, it should be an 8-bit encoding that is
* appropriate for the platform, locale, file system, etc.
* (prefer to use UTF-8 when possible).
* @param flags bitmask that allows the user to set 64-bit values for
* data or time atoms. Valid bits may be any combination of:
* @li #MP4_CREATE_64BIT_DATA
* @li #MP4_CREATE_64BIT_TIME
* @param add_ftyp if true an <b>ftyp</b> atom is automatically created.
* @param add_iods if true an <b>iods</b> atom is automatically created.
* @param majorBrand <b>ftyp</b> brand identifier.
* @param minorVersion <b>ftyp</b> informative integer for the minor version
* of the major brand.
* @param compatibleBrands <b>ftyp</b> list of compatible brands.
* @param compatibleBrandsCount is the count of items specified in
* compatibleBrands.
*
* @return On success a handle of the newly created file for use in subsequent
* calls to the library. On error, #MP4_INVALID_FILE_HANDLE.
*
* @see MP4Create()
*/
MP4V2_EXPORT
MP4FileHandle MP4CreateEx(
const char* fileName,
uint32_t flags DEFAULT(0),
int add_ftyp DEFAULT(1),
int add_iods DEFAULT(1),
char* majorBrand DEFAULT(0),
uint32_t minorVersion DEFAULT(0),
char** compatibleBrands DEFAULT(0),
uint32_t compatibleBrandsCount DEFAULT(0) );
/** Create a new mp4 file using an I/O callbacks structure.
*
* MP4CreateCallbacks is the first call that should be used when you want to
* create a new, empty mp4 file using custom I/O functions provided in an
* MP4IOCallbacks structure.
*
* Using MP4CreateCallbacks is equivalent to opening a file for writing, but
* is also involved with the creation of necessary mp4 framework structures.
* I.e. invoking MP4CreateCallbacks() followed by MP4Close() will result in a
* file with a non-zero size.
*
* @param callbacks custom implementation of I/O operations.
* The size, seek and write callbacks must be implemented.
* The callbacks structure is immediately copied internally.
* @param handle a custom handle that will be passed as the first argument to
* any callback function call. This can be used to pass a handle to an
* application specific I/O object or an application defined struct
* containing a pointer to a buffer.
* @param flags bitmask that allows the user to set 64-bit values for
* data or time atoms. Valid bits may be any combination of:
* @li #MP4_CREATE_64BIT_DATA
* @li #MP4_CREATE_64BIT_TIME
*
* @return On success a handle of the newly created file for use in subsequent
* calls to the library. On error, #MP4_INVALID_FILE_HANDLE.
*
* @see MP4CreateCallbacksEx()
*/
MP4V2_EXPORT
MP4FileHandle MP4CreateCallbacks(
const MP4IOCallbacks* callbacks,
void* handle DEFAULT(NULL),
uint32_t flags DEFAULT(0));
/** Create a new mp4 file with extended options using an I/O callbacks
* structure.
*
* MP4CreateCallbacksEx is an extended version of MP4CreateCallbacks().
*
* @param callbacks custom implementation of I/O operations.
* The size, seek and write callbacks must be implemented.
* The callbacks structure is immediately copied internally.
* @param handle a custom handle that will be passed as the first argument to
* any callback function call. This can be used to pass a handle to an
* application specific I/O object or an application defined struct
* containing a pointer to a buffer.
* @param flags bitmask that allows the user to set 64-bit values for
* data or time atoms. Valid bits may be any combination of:
* @li #MP4_CREATE_64BIT_DATA
* @li #MP4_CREATE_64BIT_TIME
* @param add_ftyp if true an <b>ftyp</b> atom is automatically created.
* @param add_iods if true an <b>iods</b> atom is automatically created.
* @param majorBrand <b>ftyp</b> brand identifier.
* @param minorVersion <b>ftyp</b> informative integer for the minor version
* of the major brand.
* @param compatibleBrands <b>ftyp</b> list of compatible brands.
* @param compatibleBrandsCount is the count of items specified in
* compatibleBrands.
*
* @return On success a handle of the newly created file for use in subsequent
* calls to the library. On error, #MP4_INVALID_FILE_HANDLE.
*
* @see MP4CreateCallbacks()
*/
MP4V2_EXPORT
MP4FileHandle MP4CreateCallbacksEx(
const MP4IOCallbacks* callbacks,
void* handle DEFAULT(NULL),
uint32_t flags DEFAULT(0),
int add_ftyp DEFAULT(1),
int add_iods DEFAULT(1),
char* majorBrand DEFAULT(0),
uint32_t minorVersion DEFAULT(0),
char** compatibleBrands DEFAULT(0),
uint32_t compatibleBrandsCount DEFAULT(0) );
/** Dump mp4 file contents as ASCII either to stdout or the
* log callback (see MP4SetLogCallback())
*
* Dump is an invaluable debugging tool in that in can reveal all the details
* of the mp4 control structures. However, the output will not make much sense
* until you familiarize yourself with the mp4 specification (or the Quicktime
* File Format specification).
*
* Note that MP4Dump() will not print the individual values of control tables,
* such as the size of each sample, unless the current log level is at least
* @b MP4_LOG_VERBOSE2. See MP4LogSetLevel() for how to set this.
*
* @param hFile handle of file to dump.
* @param dumpImplicits prints properties which would not actually be written
* to the mp4 file, but still exist in mp4 control structures. I.e. they
* are implicit given the current values of other controlling properties.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4Dump(
MP4FileHandle hFile,
bool dumpImplicits DEFAULT(0) );
/** Return a textual summary of an mp4 file.
*
* MP4FileInfo provides a string that contains a textual summary of the
* contents of an mp4 file. This includes the track id's, the track type, and
* track specific information. For example, for a video track, media encoding,
* image size, frame rate, and bitrate are summarized.
*
* Note that the returned string is allocated by the library, so it is the
* caller's responsibility to release the string with MP4Free(). Also note
* that the returned string contains newlines and tabs which may or may not be
* desirable.
*
* The following is an example of the output of MP4Info():
* @verbatim
Track Type Info
1 video MPEG-4 Simple @ L3, 119.625 secs, 1008 kbps, 352x288 @ 24.00 fps
2 audio MPEG-4, 119.327 secs, 128 kbps, 44100 Hz
3 hint Payload MP4V-ES for track 1
4 hint Payload mpeg4-generic for track 2
5 od Object Descriptors
6 scene BIFS
@endverbatim
*
* @param fileName pathname to mp4 file to summarize.
* On Windows, this should be a UTF-8 encoded string.
* On other platforms, it should be an 8-bit encoding that is
* appropriate for the platform, locale, file system, etc.
* (prefer to use UTF-8 when possible).
* @param trackId specifies track to summarize. If the value is
* #MP4_INVALID_TRACK_ID, the summary info is created for all
* tracks in the file.
*
* @return On success a newly allocated string containing summary information.
* On failure, <b>NULL</b>.
*
* @see MP4Info()
*/
MP4V2_EXPORT
char* MP4FileInfo(
const char* fileName,
MP4TrackId trackId DEFAULT(MP4_INVALID_TRACK_ID) );
/** Accessor for the filename associated with a file handle
*
* @param hFile a file handle
*
* @return the NUL-terminated, UTF-8 encoded filename associated with @p
* hFile.
*/
MP4V2_EXPORT
const char* MP4GetFilename(
MP4FileHandle hFile );
/** Return a textual summary of an mp4 file.
*
* MP4FileInfo provides a string that contains a textual summary of the
* contents of an mp4 file. This includes the track id's, the track type, and
* track specific information. For example, for a video track, media encoding,
* image size, frame rate, and bitrate are summarized.
*
* Note that the returned string is allocated by the library, so it is the
* caller's responsibility to release the string with MP4Free(). Also note
* that the returned string contains newlines and tabs which may or may not be
* desirable.
*
* The following is an example of the output of MP4Info():
* @verbatim
Track Type Info
1 video MPEG-4 Simple @ L3, 119.625 secs, 1008 kbps, 352x288 @ 24.00 fps
2 audio MPEG-4, 119.327 secs, 128 kbps, 44100 Hz
3 hint Payload MP4V-ES for track 1
4 hint Payload mpeg4-generic for track 2
5 od Object Descriptors
6 scene BIFS
@endverbatim
*
* @param hFile handle of file to summarize.
* @param trackId specifies track to summarize. If the value is
* #MP4_INVALID_TRACK_ID, the summary info is created for all tracks in
* the file.
*
* @return On success a newly allocated string containing summary information.
* On failure, <b>NULL</b>.
*
* @see MP4FileInfo()
*/
MP4V2_EXPORT
char* MP4Info(
MP4FileHandle hFile,
MP4TrackId trackId DEFAULT(MP4_INVALID_TRACK_ID) );
/** Modify an existing mp4 file.
*
* MP4Modify is the first call that should be used when you want to modify
* an existing mp4 file. It is roughly equivalent to opening a file in
* read/write mode.
*
* Since modifications to an existing mp4 file can result in a sub-optimal
* file layout, you may want to use MP4Optimize() after you have modified
* and closed the mp4 file.
*
* @param fileName pathname of the file to be modified.
* On Windows, this should be a UTF-8 encoded string.
* On other platforms, it should be an 8-bit encoding that is
* appropriate for the platform, locale, file system, etc.
* (prefer to use UTF-8 when possible).
* @param flags currently ignored.
*
* @return On success a handle of the target file for use in subsequent calls
* to the library. On error, #MP4_INVALID_FILE_HANDLE.
*/
MP4V2_EXPORT
MP4FileHandle MP4Modify(
const char* fileName,
uint32_t flags DEFAULT(0) );
/** Modify an existing mp4 file using an I/O callbacks structure.
*
* MP4ModifyCallbacks is the first call that should be used when you want to
* modify an existing mp4 file using custom I/O functions provided in an
* MP4IOCallbacks structure.
* Using MP4ModifyCallbacks is roughly equivalent to opening a file in
* read/write mode.
*
* Since modifications to an existing mp4 file can result in a sub-optimal
* file layout, you may want to use MP4Optimize() after you have modified and
* closed the mp4 file.
*
* @param callbacks custom implementation of I/O operations. The size, seek,
* read and write callbacks must be implemented. Implementing the truncate
* callback is optional, but strongly recommended. If the truncate
* callback is not implemented, it must be set to NULL. The callbacks
* structure is immediately copied internally.
* @param handle a custom handle that will be passed as the first argument to
* any callback function call. This can be used to pass a handle to an
* application specific I/O object or an application defined struct
* containing a pointer to a buffer.
* @param flags currently ignored.
*
* @return On success a handle of the target file for use in subsequent calls
* to the library. On error, #MP4_INVALID_FILE_HANDLE.
*/
MP4V2_EXPORT
MP4FileHandle MP4ModifyCallbacks(
const MP4IOCallbacks* callbacks,
void* handle DEFAULT(NULL),
uint32_t flags DEFAULT(0) );
/** Optimize the layout of an mp4 file.
*
* MP4Optimize reads an existing mp4 file and writes a new version of the
* file with the two important changes:
*
* First, the mp4 control information is moved to the beginning of the file.
* (Frequenty it is at the end of the file due to it being constantly
* modified as track samples are added to an mp4 file). This optimization
* is useful in that in allows the mp4 file to be HTTP streamed.
*
* Second, the track samples are interleaved so that the samples for a
* particular instant in time are colocated within the file. This
* eliminates disk seeks during playback of the file which results in
* better performance.
*
* There are also two important side effects of MP4Optimize():
*
* First, any free blocks within the mp4 file are eliminated.
*
* Second, as a side effect of the sample interleaving process any media
* data chunks that are not actually referenced by the mp4 control
* structures are deleted. This is useful if you have called MP4DeleteTrack()
* which only deletes the control information for a track, and not the
* actual media data.
*
* @param fileName pathname of (existing) file to be optimized.
* On Windows, this should be a UTF-8 encoded string.
* On other platforms, it should be an 8-bit encoding that is
* appropriate for the platform, locale, file system, etc.
* (prefer to use UTF-8 when possible).
* @param newFileName pathname of the new optimized file.
* On Windows, this should be a UTF-8 encoded string.
* On other platforms, it should be an 8-bit encoding that is
* appropriate for the platform, locale, file system, etc.
* (prefer to use UTF-8 when possible).
* If NULL a temporary file in the same directory as the
* <b>fileName</b> will be used and <b>fileName</b>
* will be over-written upon successful completion.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4Optimize(
const char* fileName,
const char* newFileName DEFAULT(NULL) );
/** Read an existing mp4 file.
*
* MP4Read is the first call that should be used when you want to just
* read an existing mp4 file. It is equivalent to opening a file for
* reading, but in addition the mp4 file is parsed and the control
* information is loaded into memory. Note that actual track samples are not
* read into memory until MP4ReadSample() is called.
*
* @param fileName pathname of the file to be read.
* On Windows, this should be a UTF-8 encoded string.
* On other platforms, it should be an 8-bit encoding that is
* appropriate for the platform, locale, file system, etc.
* (prefer to use UTF-8 when possible).
*
* @return On success a handle of the file for use in subsequent calls to
* the library. On error, #MP4_INVALID_FILE_HANDLE.
*/
MP4V2_EXPORT
MP4FileHandle MP4Read(
const char* fileName );
/** Read an existing mp4 file.
*
* @deprecated The file provider API is deprecated since MP4v2 2.1.0. Please
* use MP4ReadCallbacks() instead.
*
* MP4ReadProvider is the first call that should be used when you want to just
* read an existing mp4 file. It is equivalent to opening a file for reading,
* but in addition the mp4 file is parsed and the control information is
* loaded into memory. Note that actual track samples are not read into memory
* until MP4ReadSample() is called.
*
* @param fileName pathname of the file to be read.
* On Windows, this should be a UTF-8 encoded string.
* On other platforms, it should be an 8-bit encoding that is
* appropriate for the platform, locale, file system, etc.
* (prefer to use UTF-8 when possible).
* @param fileProvider custom implementation of file I/O operations.
* All functions in structure must be implemented.
* The structure is immediately copied internally.
*
* @return On success a handle of the file for use in subsequent calls to
* the library. On error, #MP4_INVALID_FILE_HANDLE.
*
* @see MP4ReadCallbacks()
*/
MP4V2_EXPORT
MP4FileHandle MP4ReadProvider(
const char* fileName,
const MP4FileProvider* fileProvider DEFAULT(NULL) );
/** Read an existing mp4 file using an I/O callbacks structure.
*
* MP4ReadCallbacks is the first call that should be used when you want to
* read an existing mp4 file using custom I/O functions provided in an
* MP4IOCallbacks structure.
*
* Using MP4ReadCallbacks is equivalent to opening a file for reading, but in
* addition the mp4 file is parsed and the control information is loaded into
* memory. Note that actual track samples are not read into memory until
* MP4ReadSample() is called.
*
* @param callbacks custom implementation of I/O operations.
* The size, seek and read callbacks must be implemented.
* The callbacks structure is immediately copied internally.
* @param handle a custom handle that will be passed as the first argument to
* any callback function call. This can be used to pass a handle to an
* application specific I/O object or an application defined struct
* containing a pointer to a buffer.
*
* @return On success a handle of the file for use in subsequent calls to
* the library. On error, #MP4_INVALID_FILE_HANDLE.
*/
MP4V2_EXPORT
MP4FileHandle MP4ReadCallbacks(
const MP4IOCallbacks* callbacks,
void* handle DEFAULT(NULL) );
/** @} ***********************************************************************/
#endif /* MP4V2_FILE_H */

532
third_party/include/mp4v2/file_prop.h vendored Normal file
View File

@ -0,0 +1,532 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.com
* Kona Blend, kona8lend@gmail.com
* Robert Kausch, robert.kausch@freac.org
*/
#ifndef MP4V2_FILE_PROP_H
#define MP4V2_FILE_PROP_H
/**************************************************************************//**
*
* @defgroup mp4_file_prop MP4v2 File Properties
* @{
*
*****************************************************************************/
/* generic props */
/** Check for presence of an atom.
*
* MP4HaveAtom checks for the presence of the atom passed in @p atomName. @p
* atomName can specify an atom path to check for atoms that are not top level
* atoms, e.g. "moov.udta.meta.ilst".
*
* @param hFile handle of file for operation.
* @param atomName name of the atom to check for.
*
* @return true (1) if the atom is present, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4HaveAtom(
MP4FileHandle hFile,
const char* atomName );
/** Get the value of an integer property.
*
* MP4GetIntegerProperty determines the value of the integer property
* identified by @p propName, e.g. "moov.iods.audioProfileLevelId". The value
* is stored in the variable pointed to by @p retVal.
*
* @param hFile handle of file for operation.
* @param propName path to the property to get.
* @param retVal pointer to a variable to receive the return value.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4GetIntegerProperty(
MP4FileHandle hFile,
const char* propName,
uint64_t* retVal );
/** Get the value of a float property.
*
* MP4GetFloatProperty determines the value of the float property identified
* by @p propName, e.g. "moov.mvhd.rate". The value is stored in the variable
* pointed to by @p retVal.
*
* @param hFile handle of file for operation.
* @param propName path to the property to get.
* @param retVal pointer to a variable to receive the return value.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4GetFloatProperty(
MP4FileHandle hFile,
const char* propName,
float* retVal );
/** Get the value of a string property.
*
* MP4GetStringProperty determines the value of the string property identified
* by @p propName, e.g. "ftyp.majorBrand". The value is stored in the variable
* pointed to by @p retVal.
*
* @param hFile handle of file for operation.
* @param propName path to the property to get.
* @param retVal pointer to a variable to receive the return value.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4GetStringProperty(
MP4FileHandle hFile,
const char* propName,
const char** retVal );
/** Get the value of a bytes property.
*
* MP4GetBytesProperty determines the value of the bytes property identified
* by @p propName, e.g. "moov.udta.meta.metadata". The value is stored in a
* newly allocated buffer the location of which is assigned to the variable
* pointed to by ppValue. The caller is responsible for freeing the memory
* with MP4Free().
*
* @param hFile handle of file for operation.
* @param propName path to the property to get.
* @param ppValue pointer to a variable to receive the memory location
* containing the property bytes.
* @param pValueSize pointer to a variable to receive the length of the
* property bytes value.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4GetBytesProperty(
MP4FileHandle hFile,
const char* propName,
uint8_t** ppValue,
uint32_t* pValueSize );
/** Set the value of an integer property.
*
* MP4SetIntegerProperty sets the value of the integer property identified by
* @p propName, e.g. "moov.iods.audioProfileLevelId".
*
* @param hFile handle of file for operation.
* @param propName path to the property to set.
* @param value the new value of the property.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4SetIntegerProperty(
MP4FileHandle hFile,
const char* propName,
int64_t value );
/** Set the value of a float property.
*
* MP4SetFloatProperty sets the value of the float property identified by @p
* propName, e.g. "moov.mvhd.rate".
*
* @param hFile handle of file for operation.
* @param propName path to the property to set.
* @param value the new value of the property.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4SetFloatProperty(
MP4FileHandle hFile,
const char* propName,
float value );
/** Set the value of a string property.
*
* MP4SetStringProperty sets the value of the string property identified by @p
* propName, e.g. "ftyp.majorBrand".
*
* @param hFile handle of file for operation.
* @param propName path to the property to set.
* @param value the new value of the property.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4SetStringProperty(
MP4FileHandle hFile,
const char* propName,
const char* value );
/** Set the value of a bytes property.
*
* MP4SetBytesProperty sets the value of the bytes property identified by @p
* propName, e.g. "moov.udta.meta.metadata".
*
* @param hFile handle of file for operation.
* @param propName path to the property to set.
* @param pValue pointer the bytes representing the new value of the property.
* @param valueSize the size of the bytes value pointed to by <b>pValue</b>.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4SetBytesProperty(
MP4FileHandle hFile,
const char* propName,
const uint8_t* pValue,
uint32_t valueSize );
/* specific props */
/** Get the duration of the movie (file).
*
* MP4GetDuration returns the maximum duration of all the tracks in the
* specified mp4 file.
*
* Caveat: the duration is the movie (file) time scale units.
*
* @param hFile specifies the mp4 file to which the operation applies.
*
* @return The duration of the movie (file) in movie (file) time scale units.
*
* @see MP4GetTimeScale()
* @see MP4ConvertFromMovieDuration()
*/
MP4V2_EXPORT
MP4Duration MP4GetDuration(
MP4FileHandle hFile );
/** Get the time scale of the movie (file).
*
* MP4GetTimeScale returns the time scale in units of ticks per second for
* the mp4 file. Caveat: tracks may use the same time scale as the movie
* or may use their own time scale.
*
* @param hFile handle of file for operation.
*
* @return timescale (ticks per second) of the mp4 file.
*/
MP4V2_EXPORT
uint32_t MP4GetTimeScale(
MP4FileHandle hFile );
/** Set the time scale of the movie (file).
*
* MP4SetTimeScale sets the time scale of the mp4 file. The time scale is
* in the number of clock ticks per second. Caveat: tracks may use the
* same time scale as the movie or may use their own time scale.
*
* @param hFile handle of file for operation.
* @param value desired timescale for the movie.
*
* @return On success, true. On failure, false.
*/
MP4V2_EXPORT
bool MP4SetTimeScale(
MP4FileHandle hFile,
uint32_t value );
/** Change the general timescale of file hFile.
*
* This function changes the general timescale of the file <b>hFile</b>
* to the new timescale <b>value</b> by recalculating all values that depend
* on the timescale in "moov.mvhd".
*
* If the timescale is already equal to value nothing is done.
*
* @param hFile handle of file to change.
* @param value the new timescale.
*/
MP4V2_EXPORT
void MP4ChangeMovieTimeScale(
MP4FileHandle hFile,
uint32_t value );
/** Gets the minimum MPEG-4 object descriptor profile and level required to
* render the contents of the file.
*
* MP4GetODProfileLevel returns the minimum profile/level of MPEG-4 object
* descriptor support necessary to render the contents of the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
*
* @return The current object descriptor profile/level for the file. See
* MP4SetODProfileLevel() for known values.
*
* @see MP4SetODProfileLevel()
*/
MP4V2_EXPORT
uint8_t MP4GetODProfileLevel(
MP4FileHandle hFile );
/** Sets the minimum MPEG-4 object descriptor profile and level required to
* render the contents of the file.
*
* MP4SetODProfileLevel sets the minimum profile/level of MPEG-4 object
* descriptor support necessary to render the contents of the file.
*
* ISO/IEC 14496-1:2001 MPEG-4 Systems defines the following values:
*
* Value | Meaning
* ----------|-----------------------------
* 0x00 | Reserved
* 0x01-0x7F | Reserved
* 0x80-0xFD | User private
* 0xFE | No object descriptor profile specified
* 0xFF | No object descriptor required
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param value specifies the profile/level to set.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetODProfileLevel()
*/
MP4V2_EXPORT
bool MP4SetODProfileLevel(
MP4FileHandle hFile,
uint8_t value );
/** Gets the minimum MPEG-4 scene graph profile and level required to render
* the contents of the file.
*
* MP4GetSceneProfileLevel returns the minimum profile/level of MPEG-4 scene
* graph support necessary to render the contents of the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
*
* @return The current scene graph profile/level for the file. See
* MP4SetSceneProfileLevel() for known values.
*
* @see MP4SetSceneProfileLevel()
*/
MP4V2_EXPORT
uint8_t MP4GetSceneProfileLevel(
MP4FileHandle hFile );
/** Sets the minimum MPEG-4 scene graph profile and level required to render
* the contents of the file.
*
* MP4SetSceneProfileLevel sets the minimum profile/level of MPEG-4 scene
* graph support necessary to render the contents of the file.
*
* ISO/IEC 14496-1:2001 MPEG-4 Systems defines the following values:
*
* Value | Meaning
* ----------|-----------------------------
* 0x00 | Reserved
* 0x01 | Simple 2D Profile @@ Level 1
* 0x02-0x7F | Reserved
* 0x80-0xFD | User private
* 0xFE | No scene graph profile specified
* 0xFF | No scene graph required
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param value specifies the profile/level to set.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetSceneProfileLevel()
*/
MP4V2_EXPORT
bool MP4SetSceneProfileLevel(
MP4FileHandle hFile,
uint8_t value );
/** Gets the minimum MPEG-4 video profile and level required to render the
* contents of the file.
*
* MP4GetVideoProfileLevel returns the minimum profile/level of MPEG-4 video
* support necessary to render the contents of the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the profile/level is
* requested.
*
* @return The current video profile/level for the file/track. See
* MP4SetVideoProfileLevel() for known values.
*
* @see MP4SetVideoProfileLevel()
*/
MP4V2_EXPORT
uint8_t MP4GetVideoProfileLevel(
MP4FileHandle hFile,
MP4TrackId trackId DEFAULT(MP4_INVALID_TRACK_ID) );
/** Sets the minimum MPEG-4 video profile and level required to render the
* contents of the file.
*
* MP4SetVideoProfileLevel sets the minimum profile/level of MPEG-4 video
* support necessary to render the contents of the file.
*
* ISO/IEC 14496-1:2001 MPEG-4 Systems defines the following values:
*
* Value | Meaning
* ----------|-----------------------------------
* 0x00 | Reserved
* 0x01 | Simple Profile @@ Level 3
* 0x02 | Simple Profile @@ Level 2
* 0x03 | Simple Profile @@ Level 1
* 0x04 | Simple Scalable Profile @@ Level 2
* 0x05 | Simple Scalable Profile @@ Level 1
* 0x06 | Core Profile @@ Level 2
* 0x07 | Core Profile @@ Level 1
* 0x08 | Main Profile @@ Level 4
* 0x09 | Main Profile @@ Level 3
* 0x0A | Main Profile @@ Level 2
* 0x0B | N-Bit Profile @@ Level 2
* 0x0C | Hybrid Profile @@ Level 2
* 0x0D | Hybrid Profile @@ Level 1
* 0x0E | Basic Animated Texture @@ Level 2
* 0x0F | Basic Animated Texture @@ Level 1
* 0x10 | Scalable Texture @@ Level 3
* 0x11 | Scalable Texture @@ Level 2
* 0x12 | Scalable Texture @@ Level 1
* 0x13 | Simple Face Animation @@ Level 2
* 0x14 | Simple Face Animation @@ Level 1
* 0x15-0x7F | Reserved
* 0x80-0xFD | User private
* 0xFE | No video profile specified
* 0xFF | No video required
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param value specifies the profile/level to set.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetVideoProfileLevel()
*/
MP4V2_EXPORT
void MP4SetVideoProfileLevel(
MP4FileHandle hFile,
uint8_t value );
/** Gets the minimum MPEG-4 audio profile and level required to render the
* contents of the file.
*
* MP4GetAudioProfileLevel returns the minimum profile/level of MPEG-4 audio
* support necessary to render the contents of the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
*
* @return The current audio profile/level for the file. See
* MP4SetAudioProfileLevel() for known values.
*
* @see MP4SetAudioProfileLevel()
*/
MP4V2_EXPORT
uint8_t MP4GetAudioProfileLevel(
MP4FileHandle hFile );
/** Sets the minimum MPEG-4 audio profile and level required to render the
* contents of the file.
*
* MP4SetAudioProfileLevel sets the minimum profile/level of MPEG-4 audio
* support necessary to render the contents of the file.
*
* ISO/IEC 14496-1:2001 MPEG-4 Systems defines the following values:
*
* Value | Meaning
* ----------|-----------------------------
* 0x00 | Reserved
* 0x01 | Main Profile @@ Level 1
* 0x02 | Main Profile @@ Level 2
* 0x03 | Main Profile @@ Level 3
* 0x04 | Main Profile @@ Level 4
* 0x05 | Scalable Profile @@ Level 1
* 0x06 | Scalable Profile @@ Level 2
* 0x07 | Scalable Profile @@ Level 3
* 0x08 | Scalable Profile @@ Level 4
* 0x09 | Speech Profile @@ Level 1
* 0x0A | Speech Profile @@ Level 2
* 0x0B | Synthesis Profile @@ Level 1
* 0x0C | Synthesis Profile @@ Level 2
* 0x0D | Synthesis Profile @@ Level 3
* 0x0E-0x7F | Reserved
* 0x80-0xFD | User private
* 0xFE | No audio profile specified
* 0xFF | No audio required
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param value specifies the profile/level to set.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetAudioProfileLevel()
*/
MP4V2_EXPORT
void MP4SetAudioProfileLevel(
MP4FileHandle hFile,
uint8_t value );
/** Gets the minimum MPEG-4 graphics profile and level required to render the
* contents of the file.
*
* MP4GetGraphicsProfileLevel returns the minimum profile/level of MPEG-4
* graphics support necessary to render the contents of the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
*
* @return The current graphics profile/level for the file. See
* MP4SetGraphicsProfileLevel() for known values.
*
* @see MP4SetGraphicsProfileLevel()
*/
MP4V2_EXPORT
uint8_t MP4GetGraphicsProfileLevel(
MP4FileHandle hFile );
/** Sets the minimum MPEG-4 graphics profile and level required to render the
* contents of the file.
*
* MP4SetGraphicsProfileLevel sets the minimum profile/level of MPEG-4
* graphics support necessary to render the contents of the file.
*
* ISO/IEC 14496-1:2001 MPEG-4 Systems defines the following values:
*
* Value | Meaning
* ----------|-----------------------------
* 0x00 | Reserved
* 0x01 | Simple 2D Profile @@ Level 1
* 0x02-0x7F | Reserved
* 0x80-0xFD | User private
* 0xFE | No graphics profile specified
* 0xFF | No graphics required
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param value specifies the profile/level to set.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetGraphicsProfileLevel()
*/
MP4V2_EXPORT
bool MP4SetGraphicsProfileLevel(
MP4FileHandle hFile,
uint8_t value );
/** @} ***********************************************************************/
#endif /* MP4V2_FILE_PROP_H */

973
third_party/include/mp4v2/general.h vendored Normal file
View File

@ -0,0 +1,973 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* 3GPP features implementation is based on 3GPP's TS26.234-v5.60,
* and was contributed by Ximpo Group Ltd.
*
* Portions created by Ximpo Group Ltd. are
* Copyright (C) Ximpo Group Ltd. 2003, 2004. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Ximpo Group Ltd., mp4v2@ximpo.com
* Bill May, wmay@cisco.com
* Kona Blend, kona8lend@gmail.com
*/
#ifndef MP4V2_GENERAL_H
#define MP4V2_GENERAL_H
/**************************************************************************//**
*
* @defgroup mp4_general MP4v2 General
* @{
*
*****************************************************************************/
/* MP4 API types */
typedef void* MP4FileHandle;
typedef uint32_t MP4TrackId;
typedef uint32_t MP4SampleId;
typedef uint64_t MP4Timestamp;
typedef uint64_t MP4Duration;
typedef uint32_t MP4EditId;
typedef enum {
MP4_LOG_NONE = 0,
MP4_LOG_ERROR = 1,
MP4_LOG_WARNING = 2,
MP4_LOG_INFO = 3,
MP4_LOG_VERBOSE1 = 4,
MP4_LOG_VERBOSE2 = 5,
MP4_LOG_VERBOSE3 = 6,
MP4_LOG_VERBOSE4 = 7
} MP4LogLevel;
/*****************************************************************************/
typedef void (*MP4LogCallback)(
MP4LogLevel loglevel,
const char* fmt,
va_list ap );
/*****************************************************************************/
/** Encryption function pointer.
*
* @see MP4EncAndCopySample()
* @see MP4EncAndCopyTrack()
*/
typedef uint32_t (*encryptFunc_t)( uint32_t, uint32_t, uint8_t*, uint32_t*, uint8_t** );
/*****************************************************************************/
#define MP4_INVALID_FILE_HANDLE ((MP4FileHandle)NULL) /**< Constant: invalid MP4FileHandle. */
#define MP4_INVALID_TRACK_ID ((MP4TrackId)0) /**< Constant: invalid MP4TrackId. */
#define MP4_INVALID_SAMPLE_ID ((MP4SampleId)0) /**< Constant: invalid MP4SampleId. */
#define MP4_INVALID_TIMESTAMP ((MP4Timestamp)-1) /**< Constant: invalid MP4Timestamp. */
#define MP4_INVALID_DURATION ((MP4Duration)-1) /**< Constant: invalid MP4Duration. */
#define MP4_INVALID_EDIT_ID ((MP4EditId)0) /**< Constant: invalid MP4EditId. */
/* Macros to test for API type validity */
#define MP4_IS_VALID_FILE_HANDLE(x) ((x) != MP4_INVALID_FILE_HANDLE)
#define MP4_IS_VALID_TRACK_ID(x) ((x) != MP4_INVALID_TRACK_ID)
#define MP4_IS_VALID_SAMPLE_ID(x) ((x) != MP4_INVALID_SAMPLE_ID)
#define MP4_IS_VALID_TIMESTAMP(x) ((x) != MP4_INVALID_TIMESTAMP)
#define MP4_IS_VALID_DURATION(x) ((x) != MP4_INVALID_DURATION)
#define MP4_IS_VALID_EDIT_ID(x) ((x) != MP4_INVALID_EDIT_ID)
/*
* MP4 Known track type names - e.g. MP4GetNumberOfTracks(type)
*
* Note this first group of track types should be created
* via the MP4Add<Type>Track() functions, and not MP4AddTrack(type)
*/
#define MP4_OD_TRACK_TYPE "odsm" /**< Constant: OD track. */
#define MP4_SCENE_TRACK_TYPE "sdsm" /**< Constant: scene track. */
#define MP4_AUDIO_TRACK_TYPE "soun" /**< Constant: audio track. */
#define MP4_VIDEO_TRACK_TYPE "vide" /**< Constant: video track. */
#define MP4_HINT_TRACK_TYPE "hint" /**< Constant: hint track. */
#define MP4_CNTL_TRACK_TYPE "cntl" /**< Constant: control track. */
#define MP4_TEXT_TRACK_TYPE "text" /**< Constant: text track. */
#define MP4_SUBTITLE_TRACK_TYPE "sbtl" /**< Constant: subtitle track. */
#define MP4_SUBPIC_TRACK_TYPE "subp" /**< Constant: subpic track. */
/*
* This second set of track types should be created
* via MP4AddSystemsTrack(type)
*/
#define MP4_CLOCK_TRACK_TYPE "crsm" /**< Constant: clock track. */
#define MP4_MPEG7_TRACK_TYPE "m7sm" /**< Constant: mpeg7 track. */
#define MP4_OCI_TRACK_TYPE "ocsm" /**< Constant: OCI track. */
#define MP4_IPMP_TRACK_TYPE "ipsm" /**< Constant: IPMP track. */
#define MP4_MPEGJ_TRACK_TYPE "mjsm" /**< Constant: MPEGJ track. */
#define MP4_IS_VIDEO_TRACK_TYPE(type) \
(!strcasecmp(type, MP4_VIDEO_TRACK_TYPE))
#define MP4_IS_AUDIO_TRACK_TYPE(type) \
(!strcasecmp(type, MP4_AUDIO_TRACK_TYPE))
#define MP4_IS_CNTL_TRACK_TYPE(type) \
(!strcasecmp(type, MP4_CNTL_TRACK_TYPE))
#define MP4_IS_OD_TRACK_TYPE(type) \
(!strcasecmp(type, MP4_OD_TRACK_TYPE))
#define MP4_IS_SCENE_TRACK_TYPE(type) \
(!strcasecmp(type, MP4_SCENE_TRACK_TYPE))
#define MP4_IS_HINT_TRACK_TYPE(type) \
(!strcasecmp(type, MP4_HINT_TRACK_TYPE))
#define MP4_IS_SYSTEMS_TRACK_TYPE(type) \
(!strcasecmp(type, MP4_CLOCK_TRACK_TYPE) \
|| !strcasecmp(type, MP4_MPEG7_TRACK_TYPE) \
|| !strcasecmp(type, MP4_OCI_TRACK_TYPE) \
|| !strcasecmp(type, MP4_IPMP_TRACK_TYPE) \
|| !strcasecmp(type, MP4_MPEGJ_TRACK_TYPE))
/* MP4 Audio track types - see MP4AddAudioTrack()*/
#define MP4_INVALID_AUDIO_TYPE 0x00
#define MP4_MPEG1_AUDIO_TYPE 0x6B
#define MP4_MPEG2_AUDIO_TYPE 0x69
#define MP4_MP3_AUDIO_TYPE MP4_MPEG2_AUDIO_TYPE
#define MP4_MPEG2_AAC_MAIN_AUDIO_TYPE 0x66
#define MP4_MPEG2_AAC_LC_AUDIO_TYPE 0x67
#define MP4_MPEG2_AAC_SSR_AUDIO_TYPE 0x68
#define MP4_MPEG2_AAC_AUDIO_TYPE MP4_MPEG2_AAC_MAIN_AUDIO_TYPE
#define MP4_MPEG4_AUDIO_TYPE 0x40
#define MP4_PRIVATE_AUDIO_TYPE 0xC0
#define MP4_PCM16_LITTLE_ENDIAN_AUDIO_TYPE 0xE0 /* a private definition */
#define MP4_VORBIS_AUDIO_TYPE 0xE1 /* a private definition */
#define MP4_AC3_AUDIO_TYPE 0xE2 /* a private definition */
#define MP4_ALAW_AUDIO_TYPE 0xE3 /* a private definition */
#define MP4_ULAW_AUDIO_TYPE 0xE4 /* a private definition */
#define MP4_G723_AUDIO_TYPE 0xE5 /* a private definition */
#define MP4_PCM16_BIG_ENDIAN_AUDIO_TYPE 0xE6 /* a private definition */
/* MP4 MPEG-4 Audio types from 14496-3 Table 1.5.1 */
#define MP4_MPEG4_INVALID_AUDIO_TYPE 0
#define MP4_MPEG4_AAC_MAIN_AUDIO_TYPE 1
#define MP4_MPEG4_AAC_LC_AUDIO_TYPE 2
#define MP4_MPEG4_AAC_SSR_AUDIO_TYPE 3
#define MP4_MPEG4_AAC_LTP_AUDIO_TYPE 4
#define MP4_MPEG4_AAC_HE_AUDIO_TYPE 5
#define MP4_MPEG4_AAC_SCALABLE_AUDIO_TYPE 6
#define MP4_MPEG4_CELP_AUDIO_TYPE 8
#define MP4_MPEG4_HVXC_AUDIO_TYPE 9
#define MP4_MPEG4_TTSI_AUDIO_TYPE 12
#define MP4_MPEG4_MAIN_SYNTHETIC_AUDIO_TYPE 13
#define MP4_MPEG4_WAVETABLE_AUDIO_TYPE 14
#define MP4_MPEG4_MIDI_AUDIO_TYPE 15
#define MP4_MPEG4_ALGORITHMIC_FX_AUDIO_TYPE 16
#define MP4_MPEG4_ALS_AUDIO_TYPE 31
#define MP4_MPEG4_LAYER1_AUDIO_TYPE 32
#define MP4_MPEG4_LAYER2_AUDIO_TYPE 33
#define MP4_MPEG4_LAYER3_AUDIO_TYPE 34
#define MP4_MPEG4_SLS_AUDIO_TYPE 35
/* MP4 Audio type utilities following common usage */
#define MP4_IS_MP3_AUDIO_TYPE(type) \
((type) == MP4_MPEG1_AUDIO_TYPE || (type) == MP4_MPEG2_AUDIO_TYPE)
#define MP4_IS_MPEG2_AAC_AUDIO_TYPE(type) \
(((type) >= MP4_MPEG2_AAC_MAIN_AUDIO_TYPE \
&& (type) <= MP4_MPEG2_AAC_SSR_AUDIO_TYPE))
#define MP4_IS_MPEG4_AAC_AUDIO_TYPE(mpeg4Type) \
(((mpeg4Type) >= MP4_MPEG4_AAC_MAIN_AUDIO_TYPE \
&& (mpeg4Type) <= MP4_MPEG4_AAC_HE_AUDIO_TYPE) \
|| (mpeg4Type) == MP4_MPEG4_AAC_SCALABLE_AUDIO_TYPE \
|| (mpeg4Type) == 17)
#define MP4_IS_AAC_AUDIO_TYPE(type) \
(MP4_IS_MPEG2_AAC_AUDIO_TYPE(type) \
|| (type) == MP4_MPEG4_AUDIO_TYPE)
/* MP4 Video track types - see MP4AddVideoTrack() */
#define MP4_INVALID_VIDEO_TYPE 0x00
#define MP4_MPEG1_VIDEO_TYPE 0x6A
#define MP4_MPEG2_SIMPLE_VIDEO_TYPE 0x60
#define MP4_MPEG2_MAIN_VIDEO_TYPE 0x61
#define MP4_MPEG2_SNR_VIDEO_TYPE 0x62
#define MP4_MPEG2_SPATIAL_VIDEO_TYPE 0x63
#define MP4_MPEG2_HIGH_VIDEO_TYPE 0x64
#define MP4_MPEG2_442_VIDEO_TYPE 0x65
#define MP4_MPEG2_VIDEO_TYPE MP4_MPEG2_MAIN_VIDEO_TYPE
#define MP4_MPEG4_VIDEO_TYPE 0x20
#define MP4_JPEG_VIDEO_TYPE 0x6C
#define MP4_PRIVATE_VIDEO_TYPE 0xD0
#define MP4_YUV12_VIDEO_TYPE 0xF0 /* a private definition */
#define MP4_H263_VIDEO_TYPE 0xF2 /* a private definition */
#define MP4_H261_VIDEO_TYPE 0xF3 /* a private definition */
/* MP4 Video type utilities */
#define MP4_IS_MPEG1_VIDEO_TYPE(type) \
((type) == MP4_MPEG1_VIDEO_TYPE)
#define MP4_IS_MPEG2_VIDEO_TYPE(type) \
(((type) >= MP4_MPEG2_SIMPLE_VIDEO_TYPE \
&& (type) <= MP4_MPEG2_442_VIDEO_TYPE) \
|| MP4_IS_MPEG1_VIDEO_TYPE(type))
#define MP4_IS_MPEG4_VIDEO_TYPE(type) \
((type) == MP4_MPEG4_VIDEO_TYPE)
/* Mpeg4 Visual Profile Defines - ISO/IEC 14496-2:2001/Amd.2:2002(E) */
#define MPEG4_SP_L1 (0x1)
#define MPEG4_SP_L2 (0x2)
#define MPEG4_SP_L3 (0x3)
#define MPEG4_SP_L0 (0x8)
#define MPEG4_SSP_L1 (0x11)
#define MPEG4_SSP_L2 (0x12)
#define MPEG4_CP_L1 (0x21)
#define MPEG4_CP_L2 (0x22)
#define MPEG4_MP_L2 (0x32)
#define MPEG4_MP_L3 (0x33)
#define MPEG4_MP_L4 (0x34)
#define MPEG4_NBP_L2 (0x42)
#define MPEG4_STP_L1 (0x51)
#define MPEG4_SFAP_L1 (0x61)
#define MPEG4_SFAP_L2 (0x62)
#define MPEG4_SFBAP_L1 (0x63)
#define MPEG4_SFBAP_L2 (0x64)
#define MPEG4_BATP_L1 (0x71)
#define MPEG4_BATP_L2 (0x72)
#define MPEG4_HP_L1 (0x81)
#define MPEG4_HP_L2 (0x82)
#define MPEG4_ARTSP_L1 (0x91)
#define MPEG4_ARTSP_L2 (0x92)
#define MPEG4_ARTSP_L3 (0x93)
#define MPEG4_ARTSP_L4 (0x94)
#define MPEG4_CSP_L1 (0xa1)
#define MPEG4_CSP_L2 (0xa2)
#define MPEG4_CSP_L3 (0xa3)
#define MPEG4_ACEP_L1 (0xb1)
#define MPEG4_ACEP_L2 (0xb2)
#define MPEG4_ACEP_L3 (0xb3)
#define MPEG4_ACEP_L4 (0xb4)
#define MPEG4_ACP_L1 (0xc1)
#define MPEG4_ACP_L2 (0xc2)
#define MPEG4_AST_L1 (0xd1)
#define MPEG4_AST_L2 (0xd2)
#define MPEG4_AST_L3 (0xd3)
#define MPEG4_S_STUDIO_P_L1 (0xe1)
#define MPEG4_S_STUDIO_P_L2 (0xe2)
#define MPEG4_S_STUDIO_P_L3 (0xe3)
#define MPEG4_S_STUDIO_P_L4 (0xe4)
#define MPEG4_C_STUDIO_P_L1 (0xe5)
#define MPEG4_C_STUDIO_P_L2 (0xe6)
#define MPEG4_C_STUDIO_P_L3 (0xe7)
#define MPEG4_C_STUDIO_P_L4 (0xe8)
#define MPEG4_ASP_L0 (0xF0)
#define MPEG4_ASP_L1 (0xF1)
#define MPEG4_ASP_L2 (0xF2)
#define MPEG4_ASP_L3 (0xF3)
#define MPEG4_ASP_L4 (0xF4)
#define MPEG4_ASP_L5 (0xF5)
#define MPEG4_ASP_L3B (0xF7)
#define MPEG4_FGSP_L0 (0xf8)
#define MPEG4_FGSP_L1 (0xf9)
#define MPEG4_FGSP_L2 (0xfa)
#define MPEG4_FGSP_L3 (0xfb)
#define MPEG4_FGSP_L4 (0xfc)
#define MPEG4_FGSP_L5 (0xfd)
/*****************************************************************************/
/* 3GP specific utilities */
MP4V2_EXPORT
bool MP4Make3GPCompliant(
const char* fileName,
char* majorBrand DEFAULT(0),
uint32_t minorVersion DEFAULT(0),
char** supportedBrands DEFAULT(NULL),
uint32_t supportedBrandsCount DEFAULT(0),
bool deleteIodsAtom DEFAULT(true) );
/* NOTE this section of functionality has not yet been fully tested */
/** Add an edit segment to a track.
*
* MP4AddTrackEdit adds an edit segment to the track edit list.
*
* The track edit list is a feature that allows creation of an alternate
* timeline for the track, typically cutting out segments of the full track to
* form a shortened, cleaned up version. The edit segments that form the edit
* list are a sequence of track start times and durations, they do not alter
* the track media in any way, i.e. no data can be lost via edit list
* operations.
*
* To read out the editted version of the track, use
* MP4ReadSampleFromEditTime() instead of MP4ReadSample().
*
* To export the editted version of the track to a new track, potentially in a
* new mp4 file, see MP4CopyTrack().
*
* Note with many media encodings such as MPEG-4, AAC and MP3, care must be
* taken when choosing the edit segment start times. E.g. for video tracks a
* reference or key frame should be selected as the starting sample of any
* edit segment. For audio tracks, an audio sample start time should be used.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the desired position in the edit list sequence for
* the new edit segment. If the value is MP4_INVALID_EDIT_ID, then the
* edit segment is added at the end of the existing edit list. Note
* editId's start with the value of 1, not 0.
* @param startTime specifies the starting time of the edit segment in the
* track time scale.
* @param duration specifies the duration of the edit segment in the track
* time scale.
* @param dwell If false, the track media should be played at its normal rate.
* If true, the media should be paused for the duration of this edit
* segment. This is a mechanism by which one can delay the start of a
* media track.
*
* @return Upon success, the edit id of the new edit segment. Upon an error,
* MP4_INVALID_EDIT_ID.
*
* @see MP4DeleteTrackEdit()
* @see MP4ReadSampleFromEditTime()
* @see MP4CopyTrack()
*/
MP4V2_EXPORT
MP4EditId MP4AddTrackEdit(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId DEFAULT(MP4_INVALID_EDIT_ID),
MP4Timestamp startTime DEFAULT(0),
MP4Duration duration DEFAULT(0),
bool dwell DEFAULT(false) );
/** Delete a track edit segment.
*
* MP4DeleteTrackEdit deletes the specified track edit segment. Note that
* since editId's form a sequence, deleting an editId will cause all edit
* segments with editId's greater than the deleted one to be reassigned to
* their editId minus one.
*
* Deleting an edit segment does not delete any media samples.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment to be deleted.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4AddTrackEdit()
*/
MP4V2_EXPORT
bool MP4DeleteTrackEdit(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId );
/** Get the number of edit segments for a track.
*
* MP4GetTrackNumberOfEdits returns the number of edit segments in the
* specified track in the mp4 file. Edit id's are the consecutive sequence of
* numbers from 1 to the total number of edit segments, i.e. 1-based indexing,
* not 0-based indexing.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the number of edit segments is
* desired.
*
* @return Upon success, the number of edit segments for the track. Upon an
* error, 0.
*
* @see MP4AddTrackEdit()
* @see MP4DeleteTrackEdit()
*/
MP4V2_EXPORT
uint32_t MP4GetTrackNumberOfEdits(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the start time of a track edit segment.
*
* MP4GetTrackEditStart returns the start time of the specified track edit
* segment in the timeline of the track edit list.
*
* Caveat: The value is in units of the track time scale.
*
* Note that this differs from the edit segment media start time,
* MP4GetTrackEditMediaStart(). For example:
*
* EditId | Start | MediaStart | Duration
* -------|-------|------------|---------
* 1 | 0 | 15 | 30
* 2 | 30 | 120 | 20
* 3 | 50 | 3000 | 10
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment for which the start time is
* desired.
*
* @return The start time of the edit segment in track time scale units of the
* track in the mp4 file.
*
* @see MP4SetTrackEditStart()
*/
MP4V2_EXPORT
MP4Timestamp MP4GetTrackEditStart(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId );
/** Get the total duration of a sequence of track edit segments.
*
* MP4GetTrackEditTotalDuration returns the total duration of the specified
* sequence of track edit segments from the first edit segment up to and
* including the specified edit segment. If the edit id value is
* MP4_INVALID_EDIT_ID, then the total duration of all of the edit segments is
* returned.
*
* Caveat: The value is in units of the track time scale.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment for which the total duration is
* desired. A value of MP4_INVALID_EDIT_ID specifies that all edit
* segments should be included.
*
* @return The total duration of the edit segment sequence in track time scale
* units of the track in the mp4 file.
*
* @see MP4GetTrackEditDuration()
*/
MP4V2_EXPORT
MP4Duration MP4GetTrackEditTotalDuration(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId DEFAULT(MP4_INVALID_EDIT_ID) );
/** Get the media start time of a track edit segment.
*
* MP4GetTrackEditMediaStart returns the media start time of the specified
* track edit segment.
*
* Caveat: The value is in units of the track time scale.
*
* Note that this differs from the edit segment start time,
* MP4GetTrackEditStart(). For example:
*
* EditId | Start | MediaStart | Duration
* -------|-------|------------|---------
* 1 | 0 | 15 | 30
* 2 | 30 | 120 | 20
* 3 | 50 | 3000 | 10
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment for which the media start time is
* desired.
*
* @return The media start time of the edit segment in track time scale units
* of the track in the mp4 file.
*
* @see MP4SetTrackEditMediaStart()
*/
MP4V2_EXPORT
MP4Timestamp MP4GetTrackEditMediaStart(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId );
/** Set the media start time of a track edit segment.
*
* MP4SetTrackEditMediaStart sets the media start time of the specified edit
* segment from the specified track in the track time scale units. See
* MP4ConvertToTrackTimestamp() for how to map this value from another time
* scale.
*
* Note that this differs from the edit segment start time. For example:
*
* EditId | Start | MediaStart | Duration
* -------|-------|------------|---------
* 1 | 0 | 15 | 30
* 2 | 30 | 120 | 20
* 3 | 50 | 3000 | 10
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment to which the operation applies.
* Caveat: the first edit has id 1 not 0.
* @param startTime specifies the new value for the media start in track time
* scale units.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetTrackEditMediaStart()
*/
MP4V2_EXPORT
bool MP4SetTrackEditMediaStart(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId,
MP4Timestamp startTime );
/** Get the duration of a track edit segment.
*
* MP4GetTrackEditDuration returns the duration of the specified track edit
* segment.
*
* Caveat: The value is in units of the track time scale.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment for which the duration is desired.
*
* @return The duration of the edit segment in track time scale units of the
* track in the mp4 file.
*
* @see MP4SetTrackEditDuration()
*/
MP4V2_EXPORT
MP4Duration MP4GetTrackEditDuration(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId );
/** Set the duration of a track edit segment.
*
* MP4SetTrackEditDuration sets the duration of the specified edit segment
* from the specified track in the track time scale units. See
* MP4ConvertToTrackDuration() for how to map this value from another time
* scale.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment to which the operation applies.
* Caveat: the first edit has id 1 not 0.
* @param duration specifies the new value for the duration in track time
* scale units.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetTrackEditDuration()
*/
MP4V2_EXPORT
bool MP4SetTrackEditDuration(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId,
MP4Duration duration );
/** Get the dwell value of a track edit segment.
*
* MP4GetTrackEditDwell returns the dwell value of the specified track edit
* segment. A value of true (1) indicates that during this edit segment the
* media will be paused; a value of false (0) indicates that during this edit
* segment the media will be played at its normal rate.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment for which the dwell value is
* desired.
*
* @return The dwell value of the edit segment of the track in the mp4 file.
*
* @see MP4SetTrackEditDwell()
*/
MP4V2_EXPORT
int8_t MP4GetTrackEditDwell(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId );
/** Set the dwell value of a track edit segment.
*
* MP4SetTrackEditDwell sets the dwell value of the specified edit segment
* from the specified track.
*
* A value of true (1) indicates that during this edit segment the media will
* be paused; a value of false (0) indicates that during this edit segment the
* media will be played at its normal rate.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param editId specifies the edit segment to which the operation applies.
* Caveat: the first edit has id 1 not 0.
* @param dwell specifies the new dwell value.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetTrackEditDwell()
*/
MP4V2_EXPORT
bool MP4SetTrackEditDwell(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4EditId editId,
bool dwell );
/** Read a track sample based on a specified edit list time.
*
* MP4ReadSampleFromEditTime reads the sample corresponding to the time on the
* track edit list timeline from the specified track. Typically this sample is
* then decoded in a codec dependent fashion and rendered in an appropriate
* fashion.
*
* The argument, <b>ppBytes</b>, allows for two possible approaches for
* buffering:
*
* @li If the calling application wishes to handle its own buffering it can
* set <b>*ppBytes</b> to the buffer it wishes to use. The calling
* application is responsible for ensuring that the buffer is large enough
* to hold the sample. This can be done by using either MP4GetSampleSize()
* or MP4GetTrackMaxSampleSize() to determine beforehand how large the
* receiving buffer must be.
*
* @li If the value of <b>*ppBytes</b> is NULL, then an appropriately sized
* buffer is automatically allocated for the sample data and
* <b>*ppBytes</b> set to this pointer. The calling application is
* responsible for freeing this memory with MP4Free().
*
* The last four arguments are pointers to variables that can receive optional
* sample information.
*
* Typically for audio none of these are needed. MPEG audio such as MP3 or AAC
* has a fixed sample duration and every sample can be accessed at random.
*
* For video, all of these optional values could be needed. MPEG video can be
* encoded at a variable frame rate, with only occasional random access
* points, and with "B frames" which cause the rendering (display) order of
* the video frames to differ from the storage/decoding order.
*
* Other media types fall between these two extremes.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param when specifies which sample is to be read based on a time in the
* edit list timeline. See MP4GetSampleIdFromEditTime() for details.
* @param ppBytes Pointer to the pointer to the sample data. See function
* description above for details on this argument.
* @param pNumBytes Pointer to variable that will be hold the size in bytes of
* the sample.
* @param pStartTime If non-NULL, pointer to variable that will receive the
* starting timestamp for this sample. Caveat: The timestamp is in the
* track timescale.
* @param pDuration If non-NULL, pointer to variable that will receive the
* duration for this sample. Caveat: The duration is in the track
* timescale units.
* @param pRenderingOffset If non-NULL, pointer to variable that will receive
* the rendering offset for this sample. Currently the only media type
* that needs this feature is MPEG video. Caveat: The offset is in the
* track timescale units.
* @param pIsSyncSample If non-NULL, pointer to variable that will receive the
* state of the sync/random access flag for this sample.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4ReadSample()
* @see MP4GetSampleIdFromEditTime()
* @see MP4ReadSampleFromTime()
*/
MP4V2_EXPORT
bool MP4ReadSampleFromEditTime(
/* input parameters */
MP4FileHandle hFile,
MP4TrackId trackId,
MP4Timestamp when,
/* input/output parameters */
uint8_t** ppBytes,
uint32_t* pNumBytes,
/* output parameters */
MP4Timestamp* pStartTime DEFAULT(NULL),
MP4Duration* pDuration DEFAULT(NULL),
MP4Duration* pRenderingOffset DEFAULT(NULL),
bool* pIsSyncSample DEFAULT(NULL) );
/** Get the sample id of a specified time in the edit list timeline.
*
* MP4GetSampleIdFromEditTime returns the sample id of the track sample in
* which the specified time occurs in the edit list timeline.
*
* The specified time should be in the track time scale. See
* MP4ConvertToTrackTimestamp() for how to map a time value to this time
* scale.
*
* Since the edit list can cause the sample start time and duration to be
* different that it in the standard track timeline, it is strongly advised
* that the caller retrieve the new sample start time and duration via this
* function.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param when specifies the time in the track time scale that is desired.
* @param pStartTime If non-NULL, pointer to variable that will receive the
* starting timestamp for this sample. Caveat: The timestamp is in the
* track edit list timescale.
* @param pDuration If non-NULL, pointer to variable that will receive the
* duration for this sample in the edit list timeline. Caveat: The
* duration is in the track timescale units.
*
* @return Upon success, the sample id that occurs at the specified time. Upon
* an error, MP4_INVALID_SAMPLE_ID.
*
* @see MP4GetSampleIdFromTime()
*/
MP4V2_EXPORT
MP4SampleId MP4GetSampleIdFromEditTime(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4Timestamp when,
MP4Timestamp* pStartTime DEFAULT(NULL),
MP4Duration* pDuration DEFAULT(NULL) );
/* time conversion utilties */
/* predefined values for timeScale parameter below */
#define MP4_SECONDS_TIME_SCALE 1
#define MP4_MILLISECONDS_TIME_SCALE 1000
#define MP4_MICROSECONDS_TIME_SCALE 1000000
#define MP4_NANOSECONDS_TIME_SCALE 1000000000
#define MP4_SECS_TIME_SCALE MP4_SECONDS_TIME_SCALE
#define MP4_MSECS_TIME_SCALE MP4_MILLISECONDS_TIME_SCALE
#define MP4_USECS_TIME_SCALE MP4_MICROSECONDS_TIME_SCALE
#define MP4_NSECS_TIME_SCALE MP4_NANOSECONDS_TIME_SCALE
/** Convert a duration from the movie (file) time scale to a specified time
* scale.
*
* MP4ConvertFromMovieDuration converts a duration such as the total movie
* (file) duration from the movie time scale to another specified time scale.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param duration specifies the duration that is to be converted.
* @param timeScale specifies the new time scale in ticks per second to which
* the duration should be converted.
*
* @return Upon success, the duration in the new time scale units. Upon error,
* (uint64_t) MP4_INVALID_DURATION.
*
* @see MP4GetDuration()
*/
MP4V2_EXPORT
uint64_t MP4ConvertFromMovieDuration(
MP4FileHandle hFile,
MP4Duration duration,
uint32_t timeScale );
/** Convert a timestamp from the track time scale to a specified time scale.
*
* MP4ConvertFromTrackTimestamp converts a timestamp such as a sample start
* time from the track time scale to another specified time scale. This can be
* used by a player application to map all track samples to a common time
* scale.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track from which the timestamp originates.
* @param timeStamp specifies the timestamp that is to be converted.
* @param timeScale specifies the new time scale in ticks per second to which
* the timestamp should be converted.
*
* @return Upon success, the timestamp in the new time scale units. Upon
* error, (uint64_t) MP4_INVALID_TIMESTAMP.
*
* @see MP4ConvertToTrackTimestamp()
*/
MP4V2_EXPORT
uint64_t MP4ConvertFromTrackTimestamp(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4Timestamp timeStamp,
uint32_t timeScale );
/** Convert a timestamp from a specified time scale to the track time scale.
*
* MP4ConvertToTrackTimestamp converts a timestamp such as a sample start time
* from the specified time scale to the track time scale.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
* @param timeStamp specifies the timestamp that is to be converted.
* @param timeScale specifies the time scale in ticks per second in which the
* timestamp is currently expressed.
*
* @return Upon success, the timestamp in the track time scale units. Upon
* error, MP4_INVALID_TIMESTAMP.
*
* @see MP4ConvertFromTrackTimestamp()
*/
MP4V2_EXPORT
MP4Timestamp MP4ConvertToTrackTimestamp(
MP4FileHandle hFile,
MP4TrackId trackId,
uint64_t timeStamp,
uint32_t timeScale );
/** Convert duration from track time scale to an arbitrary time scale.
*
* MP4ConvertFromTrackDuration converts a duration such as a sample duration
* from the track time scale to another time scale. This can be used by a
* player application to map all track samples to a common time scale.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param duration value to be converted.
* @param timeScale time scale in ticks per second.
*
* @return On success, the duration in arbitrary time scale units.
* On error, (uint64_t) MP4_INVALID_DURATION.
*
* @see MP4GetSampleDuration()
* @see MP4ConvertToTrackDuration()
*/
MP4V2_EXPORT
uint64_t MP4ConvertFromTrackDuration(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4Duration duration,
uint32_t timeScale );
/** Convert duration from arbitrary time scale to track time scale.
*
* MP4ConvertToTrackDuration converts a duration such as a sample duration
* from the specified time scale to the track time scale.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param duration value to be converted.
* @param timeScale time scale in ticks per second.
*
* @return On success, the duration in track time scale units.
* On error, #MP4_INVALID_DURATION.
*
* @see MP4ConvertFromTrackDuration()
*/
MP4V2_EXPORT
MP4Duration MP4ConvertToTrackDuration(
MP4FileHandle hFile,
MP4TrackId trackId,
uint64_t duration,
uint32_t timeScale );
/** Convert binary data to a base 16 string.
*
* MP4BinaryToBase16 converts binary data to a base 16 string. This encoding
* maps groups of 4 bits into the character set [0-9a-f]. The string is in
* newly allocated memory, so the caller is responsible for freeing the memory
* with MP4Free().
*
* This utility is useful for generating the SDP descriptions for some RTP
* payloads.
*
* Example:
* @code
* 0x12, 0xAB -> "12ab"
* @endcode
*
* @param pData specifies the pointer to the binary data.
* @param dataSize specifies the size in bytes of the binary data.
*
* @return Upon success, a null terminated string representing the data in
* base 16. Upon error, NULL.
*/
MP4V2_EXPORT
char* MP4BinaryToBase16(
const uint8_t* pData,
uint32_t dataSize );
/** Convert binary data to a base 64 string.
*
* MP4BinaryToBase64 converts binary data to a base 64 string. This encoding
* maps groups of 6 bits into the character set [A-Za-z0-9+/=]. The string is
* in newly allocated memory, so the caller is responsible for freeing the
* memory with MP4Free().
*
* This utility is useful for generating the SDP descriptions for some RTP
* payloads.
*
* Example:
* @code
* 0x12, 0xAB -> "Eqs="
* @endcode
*
* @param pData specifies the pointer to the binary data.
* @param dataSize specifies the size in bytes of the binary data.
*
* @return Upon success, a null terminated string representing the data in
* base 64. Upon error, NULL.
*/
MP4V2_EXPORT
char* MP4BinaryToBase64(
const uint8_t* pData,
uint32_t dataSize );
/** Free memory allocated by other library functions.
*
* MP4Free frees a block of memory previously allocated by another library
* function.
*
* Generally, library functions that allocate memory specify in their
* documentation whether MP4Free or another function must be used to free that
* memory.
*
* @param p specifies a pointer to the memory block to free.
*/
MP4V2_EXPORT
void MP4Free(
void* p );
/** Set the current log handler function.
*
* MP4SetLogCallback sets the function to call to output diagnostic
* information in place of the default log handler. The signature of the
* specified function must be compatible with the MP4LogCallback typedef.
*
* @param cb_func specifies the new log handler function.
*
* @see MP4LogCallback
*/
MP4V2_EXPORT
void MP4SetLogCallback(
MP4LogCallback cb_func );
/** Get the current maximum log level.
*
* MP4LogGetLevel returns the currently set maximum level of diagnostic
* information passed to the log handler.
*
* @return the current maximum level of diagnostic information.
*
* @see MP4LogSetLevel()
*/
MP4V2_EXPORT
MP4LogLevel MP4LogGetLevel( void );
/** Set the maximum log level.
*
* MP4LogSetLevel sets the maximum level of diagnostic information passed to
* the current log handler.
*
* @param verbosity specifies the log level to set.
*
* @see MP4LogGetLevel()
*/
MP4V2_EXPORT
void MP4LogSetLevel(
MP4LogLevel verbosity );
/** @} ***********************************************************************/
#endif /* MP4V2_GENERAL_H */

140
third_party/include/mp4v2/isma.h vendored Normal file
View File

@ -0,0 +1,140 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.com
*/
#ifndef MP4V2_ISMA_H
#define MP4V2_ISMA_H
/**************************************************************************//**
*
* @defgroup mp4_isma MP4v2 ISMA (Internet Streaming Media Alliance)
* @{
*
*****************************************************************************/
/** something */
typedef struct mp4v2_ismacryp_session_params {
uint32_t scheme_type;
uint16_t scheme_version;
uint8_t key_ind_len;
uint8_t iv_len;
uint8_t selective_enc;
const char* kms_uri;
} mp4v2_ismacrypParams;
/*
* API to initialize ismacryp properties to sensible defaults
* if input param is null, a params struct is allocated
*/
MP4V2_EXPORT
mp4v2_ismacrypParams* MP4DefaultISMACrypParams(
mp4v2_ismacrypParams* ptr );
MP4V2_EXPORT
MP4TrackId MP4AddEncAudioTrack(
MP4FileHandle hFile,
uint32_t timeScale,
MP4Duration sampleDuration,
mp4v2_ismacrypParams* icPp,
uint8_t audioType DEFAULT(MP4_MPEG4_AUDIO_TYPE) );
MP4V2_EXPORT
MP4TrackId MP4AddEncVideoTrack(
MP4FileHandle hFile,
uint32_t timeScale,
MP4Duration sampleDuration,
uint16_t width,
uint16_t height,
mp4v2_ismacrypParams* icPp,
uint8_t videoType DEFAULT(MP4_MPEG4_VIDEO_TYPE),
const char* oFormat DEFAULT(NULL) );
MP4V2_EXPORT
MP4TrackId MP4AddEncH264VideoTrack(
MP4FileHandle dstFile,
uint32_t timeScale,
MP4Duration sampleDuration,
uint16_t width,
uint16_t height,
MP4FileHandle srcFile,
MP4TrackId srcTrackId,
mp4v2_ismacrypParams* icPp );
MP4V2_EXPORT
MP4TrackId MP4EncAndCloneTrack(
MP4FileHandle srcFile,
MP4TrackId srcTrackId,
mp4v2_ismacrypParams* icPp,
MP4FileHandle dstFile DEFAULT(MP4_INVALID_FILE_HANDLE),
MP4TrackId dstHintTrackReferenceTrack DEFAULT(MP4_INVALID_TRACK_ID) );
MP4V2_EXPORT
MP4TrackId MP4EncAndCopyTrack(
MP4FileHandle srcFile,
MP4TrackId srcTrackId,
mp4v2_ismacrypParams* icPp,
encryptFunc_t encfcnp,
uint32_t encfcnparam1,
MP4FileHandle dstFile DEFAULT(MP4_INVALID_FILE_HANDLE),
bool applyEdits DEFAULT(false),
MP4TrackId dstHintTrackReferenceTrack DEFAULT(MP4_INVALID_TRACK_ID) );
/** Add ISMA compliant OD and Scene tracks.
*
* MP4MakeIsmaCompliant modifies an mp4 file so that it complies with the
* minimal MPEG-4 Systems requirements defined by the Internet Streaming Media
* Alliance (ISMA).
*
* This involves creating an OD and Scene track, and using them to describe a
* simple scene of one audio, or one video, or one of each. Whether an SDP
* version of this information is added to the mp4 file can be controlled with
* the @p addIsmaComplianceSdp parameter.
*
* Caveat: whether the file is truly ISMA compliant also depends on the
* contents of the media and hint tracks. This function does not guarantee
* that these tracks are compliant.
*
* @param fileName specifies the path name of the file to be modified.
* @param addIsmaComplianceSdp specifies whether an SDP declaring ISMA
* compliance should be added to the file.
*
* @return Upon success, true (1). Upon an error, false (0).
*/
MP4V2_EXPORT
bool MP4MakeIsmaCompliant(
const char* fileName,
bool addIsmaComplianceSdp DEFAULT(true) );
MP4V2_EXPORT
char* MP4MakeIsmaSdpIod(
uint8_t videoProfile,
uint32_t videoBitrate,
uint8_t* videoConfig,
uint32_t videoConfigLength,
uint8_t audioProfile,
uint32_t audioBitrate,
uint8_t* audioConfig,
uint32_t audioConfigLength );
/** @} ***********************************************************************/
#endif /* MP4V2_ISMA_H */

243
third_party/include/mp4v2/itmf_generic.h vendored Normal file
View File

@ -0,0 +1,243 @@
/*
* 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) 2009.
* All Rights Reserved.
*
* Contributor(s):
* Kona Blend, kona8lend@gmail.com
*/
#ifndef MP4V2_ITMF_GENERIC_H
#define MP4V2_ITMF_GENERIC_H
/**************************************************************************//**
*
* @defgroup mp4_itmf_generic MP4v2 iTMF (iTunes Metadata Format) Generic
* @{
*
* This is a low-level API used to manage iTMF metadata.
*
* It provides support for virtually any kind of iTMF metadata item, including
* meaning atoms, sometimes referred to as reverse-DNS meanings. Structures
* are directly modified; i.e. there are no fuctions which modify values for
* you. There is little type-safety, logic checks, or specifications
* compliance checks. For these reasons it is recommended to use iTMF Tags API
* when possible.
*
* At the heart of this API is an #MP4ItmfItem which corresponds to an iTMF
* metadata item atom. The item, and any recursive data structures contained
* within require <b>manual</b> memory management. The general rule to follow
* is that you must always check/free a ptr if you intend to resize data. In
* cases where you know the existing data size is exactly what is needed, you
* may overwrite the buffer contents.
*
* Each item always has at least 1 data elements which corresponds to a data
* atom. Additionally, each item has optional <b>mean</b> and <b>name</b>
* values which correspond to mean and name atoms.
*
* Each #MP4ItmfItem has a list of #MP4ItmfData. Similarily, care must be
* taken to manage memory with one key difference; these structures also have
* a valueSize field. If value is NULL then set valueSize=0. Otherwise, set
* valueSize to the size (in bytes) of value buffer.
*
* In rare cases where the number of data elements in a single item is > 1,
* the user must manually free/alloc/copy the <b>elements</b> buffer and
* update <b>size</b> accordingly.
*
* The mp4 file structure is modified only when MP4AddItem(), MP4SetItem() and
* MP4RemoveItem() are used. Simply free'ing the item list does not modify the
* mp4 file.
*
* <b>iTMF Generic read workflow:</b>
*
* @li MP4ItmfGetItems()
* @li inspect each item...
* @li MP4ItmfItemListFree()
*
* <b>iTMF Generic read/modify/remove workflow:</b>
*
* @li MP4ItmfGetItems()
* @li inspect/modify item...
* @li MP4ItmfSetItem() each modified item...
* @li MP4ItmfRemoveItem()...
* @li MP4ItmfItemListFree()
*
* <b>iTMF Generic add workflow:</b>
*
* @li MP4ItmfItemAlloc()
* @li MP4ItmfAddItem()
* @li MP4ItmfItemFree()
*
* @par Warning:
* Care must be taken when using multiple mechanisms to modify an open mp4
* file as it is not thread-safe, nor does it permit overlapping different API
* workflows which have a begin/end to their workflow. That is to say do not
* interleave an iTMF Generic workflow with an iTMF Tags workflow.
*
*****************************************************************************/
/** Basic types of value data as enumerated in spec. */
typedef enum MP4ItmfBasicType_e
{
MP4_ITMF_BT_IMPLICIT = 0, /**< for use with tags for which no type needs to be indicated */
MP4_ITMF_BT_UTF8 = 1, /**< without any count or null terminator */
MP4_ITMF_BT_UTF16 = 2, /**< also known as UTF-16BE */
MP4_ITMF_BT_SJIS = 3, /**< deprecated unless it is needed for special Japanese characters */
MP4_ITMF_BT_HTML = 6, /**< the HTML file header specifies which HTML version */
MP4_ITMF_BT_XML = 7, /**< the XML header must identify the DTD or schemas */
MP4_ITMF_BT_UUID = 8, /**< also known as GUID; stored as 16 bytes in binary (valid as an ID) */
MP4_ITMF_BT_ISRC = 9, /**< stored as UTF-8 text (valid as an ID) */
MP4_ITMF_BT_MI3P = 10, /**< stored as UTF-8 text (valid as an ID) */
MP4_ITMF_BT_GIF = 12, /**< (deprecated) a GIF image */
MP4_ITMF_BT_JPEG = 13, /**< a JPEG image */
MP4_ITMF_BT_PNG = 14, /**< a PNG image */
MP4_ITMF_BT_URL = 15, /**< absolute, in UTF-8 characters */
MP4_ITMF_BT_DURATION = 16, /**< in milliseconds, 32-bit integer */
MP4_ITMF_BT_DATETIME = 17, /**< in UTC, counting seconds since midnight, January 1, 1904; 32 or 64-bits */
MP4_ITMF_BT_GENRES = 18, /**< a list of enumerated values */
MP4_ITMF_BT_INTEGER = 21, /**< a signed big-endian integer with length one of { 1,2,3,4,8 } bytes */
MP4_ITMF_BT_RIAA_PA = 24, /**< RIAA parental advisory; { -1=no, 1=yes, 0=unspecified }, 8-bit ingteger */
MP4_ITMF_BT_UPC = 25, /**< Universal Product Code, in text UTF-8 format (valid as an ID) */
MP4_ITMF_BT_BMP = 27, /**< Windows bitmap image */
MP4_ITMF_BT_UNDEFINED = 255 /**< undefined */
} MP4ItmfBasicType;
/** Data structure.
* Models an iTMF data atom contained in an iTMF metadata item atom.
*/
typedef struct MP4ItmfData_s
{
uint8_t typeSetIdentifier; /**< always zero. */
MP4ItmfBasicType typeCode; /**< iTMF basic type. */
uint32_t locale; /**< always zero. */
uint8_t* value; /**< may be NULL. */
uint32_t valueSize; /**< value size in bytes. */
} MP4ItmfData;
/** List of data. */
typedef struct MP4ItmfDataList_s
{
MP4ItmfData* elements; /**< flat array. NULL when size is zero. */
uint32_t size; /**< number of elements. */
} MP4ItmfDataList;
/** Item structure.
* Models an iTMF metadata item atom contained in an ilst atom.
*/
typedef struct MP4ItmfItem_s
{
void* __handle; /**< internal use only. */
char* code; /**< four-char code identifing atom type. NULL-terminated. */
char* mean; /**< may be NULL. UTF-8 meaning. NULL-terminated. */
char* name; /**< may be NULL. UTF-8 name. NULL-terminated. */
MP4ItmfDataList dataList; /**< list of data. can be zero length. */
} MP4ItmfItem;
/** List of items. */
typedef struct MP4ItmfItemList_s
{
MP4ItmfItem* elements; /**< flat array. NULL when size is zero. */
uint32_t size; /**< number of elements. */
} MP4ItmfItemList;
/** Allocate an item on the heap.
* @param code four-char code identifying atom type. NULL-terminated.
* @param numData number of data elements to allocate. Must be >= 1.
* @return newly allocated item.
*/
MP4V2_EXPORT
MP4ItmfItem* MP4ItmfItemAlloc(
const char* code,
uint32_t numData );
/** Free an item (deep free).
* @param item to be free'd.
*/
MP4V2_EXPORT
void MP4ItmfItemFree(
MP4ItmfItem* item );
/** Free an item list (deep free).
* @param itemList to be free'd.
*/
MP4V2_EXPORT
void MP4ItmfItemListFree(
MP4ItmfItemList* itemList );
/** Get list of all items from file.
* @param hFile handle of file to operate on.
* @return On succes, list of items, which must be free'd. On failure, NULL.
*/
MP4V2_EXPORT
MP4ItmfItemList* MP4ItmfGetItems(
MP4FileHandle hFile );
/** Get list of items by code from file.
* @param hFile handle of file to operate on.
* @param code four-char code identifying atom type. NULL-terminated.
* @return On succes, list of items, which must be free'd. On failure, NULL.
*/
MP4V2_EXPORT
MP4ItmfItemList* MP4ItmfGetItemsByCode(
MP4FileHandle hFile,
const char* code );
/** Get list of items by meaning from file.
* Implicitly only returns atoms of code <b>{----}</b>.
* @param hFile handle of file to operate on.
* @param meaning UTF-8 meaning. NULL-terminated.
* @param name may be NULL. UTF-8 name. NULL-terminated.
* @return On succes, list of items, which must be free'd. On failure, NULL.
*/
MP4V2_EXPORT
MP4ItmfItemList* MP4ItmfGetItemsByMeaning(
MP4FileHandle hFile,
const char* meaning,
const char* name );
/** Add an item to file.
* @param hFile handle of file to operate on.
* @param item object to add.
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4ItmfAddItem(
MP4FileHandle hFile,
const MP4ItmfItem* item );
/** Overwrite an existing item in file.
* @param hFile handle of file to operate on.
* @param item object to overwrite. Must have a valid index obtained from prior get.
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4ItmfSetItem(
MP4FileHandle hFile,
const MP4ItmfItem* item );
/** Remove an existing item from file.
* @param hFile handle of file to operate on.
* @param item object to remove. Must have a valid index obtained from prior get.
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4ItmfRemoveItem(
MP4FileHandle hFile,
const MP4ItmfItem* item );
/** @} ***********************************************************************/
#endif /* MP4V2_ITMF_GENERIC_H */

317
third_party/include/mp4v2/itmf_tags.h vendored Normal file
View File

@ -0,0 +1,317 @@
/*
* 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) 2009.
* All Rights Reserved.
*
* Contributor(s):
* Kona Blend, kona8lend@gmail.com
* David Byron, dbyron0@gmail.com
*/
#ifndef MP4V2_ITMF_TAGS_H
#define MP4V2_ITMF_TAGS_H
/**************************************************************************//**
*
* @defgroup mp4_itmf_tags MP4v2 iTMF (iTunes Metadata Format) Tags
* @{
*
* This is a high-level API used to manage iTMF metadata.
*
* It provides more type-safety and simplified memory management as compared
* to iTMF Generic API.
*
* At the heart of this API is a read-only structure that holds all known
* items and their current values. The value is always a pointer which if
* NULL indicates its corresponding atom does not exist. Thus, one must
* always check if the pointer is non-NULL before attempting to extract
* its value.
*
* The structure may not be directly modified. Instead, <b>set</b> functions
* corresponding to each item are used to modify the backing-store of
* the read-only structure. Setting the value ptr to NULL will effectively
* remove it. Setting the value ptr to real data will immediately make a
* copy of the value in the backing-store and the read-only structure
* will correctly reflect the change.
*
* The hidden data cache memory is automatically managed. Thus the user need
* only guarantee the data is available during the lifetime of the set-function
* call.
*
* <b>iTMF Tags read workflow:</b>
*
* @li MP4TagsAlloc()
* @li MP4TagsFetch()
* @li inspect each tag of interest...
* @li MP4TagsStore() (if modified)
* @li MP4TagsFree()
*
* <b>iTMF Tags read/modify/add/remove workflow:</b>
*
* @li MP4TagsAlloc()
* @li MP4TagsFetch()
* @li inspect each tag of interest...
* @li MP4TagsSetName(), MP4TagsSetArtist()...
* @li MP4TagsStore()
* @li MP4TagsFree()
*
* @par Warning:
* Care must be taken when using multiple mechanisms to modify an open mp4
* file as it is not thread-safe, nor does it permit overlapping different
* API workflows which have a begin/end to their workflow. That is to say
* do not interleave an iTMF Generic workflow with an iTMF Tags workflow.
*
*****************************************************************************/
/** Enumeration of possible MP4TagArtwork::type values. */
typedef enum MP4TagArtworkType_e
{
MP4_ART_UNDEFINED = 0,
MP4_ART_BMP = 1,
MP4_ART_GIF = 2,
MP4_ART_JPEG = 3,
MP4_ART_PNG = 4
} MP4TagArtworkType;
/** Data object representing a single piece of artwork. */
typedef struct MP4TagArtwork_s
{
void* data; /**< raw picture data */
uint32_t size; /**< data size in bytes */
MP4TagArtworkType type; /**< data type */
} MP4TagArtwork;
typedef struct MP4TagTrack_s
{
uint16_t index;
uint16_t total;
} MP4TagTrack;
typedef struct MP4TagDisk_s
{
uint16_t index;
uint16_t total;
} MP4TagDisk;
/** Tags <b>convenience</b> structure.
*
* This structure is used in the tags convenience API which allows for
* simplified retrieval and modification of the majority of known tags.
*
* This is a read-only structure and each tag is present if and only if the
* pointer is a <b>non-NULL</b> value. The actual data is backed by a hidden
* data cache which is only updated when the appropriate metadata <b>set</b>
* function is used, or if MP4TagsFetch() is invoked. Thus, if other API
* is used to manipulate relevent atom structure of the MP4 file, the user
* is responsible for re-fetching the data in this structure.
*/
typedef struct MP4Tags_s
{
void* __handle; /* internal use only */
const char* name;
const char* artist;
const char* albumArtist;
const char* album;
const char* grouping;
const char* composer;
const char* comments;
const char* genre;
const uint16_t* genreType;
const char* releaseDate;
const MP4TagTrack* track;
const MP4TagDisk* disk;
const uint16_t* tempo;
const uint8_t* compilation;
const char* tvShow;
const char* tvNetwork;
const char* tvEpisodeID;
const uint32_t* tvSeason;
const uint32_t* tvEpisode;
const char* description;
const char* longDescription;
const char* lyrics;
const char* sortName;
const char* sortArtist;
const char* sortAlbumArtist;
const char* sortAlbum;
const char* sortComposer;
const char* sortTVShow;
const MP4TagArtwork* artwork;
uint32_t artworkCount;
const char* copyright;
const char* encodingTool;
const char* encodedBy;
const char* purchaseDate;
const uint8_t* podcast;
const char* keywords; /* TODO: Needs testing */
const char* category;
const uint8_t* hdVideo;
const uint8_t* mediaType;
const uint8_t* contentRating;
const uint8_t* gapless;
const char* iTunesAccount;
const uint8_t* iTunesAccountType;
const uint32_t* iTunesCountry;
const uint32_t* contentID;
const uint32_t* artistID;
const uint64_t* playlistID;
const uint32_t* genreID;
const uint32_t* composerID;
const char* xid;
} MP4Tags;
/** Allocate tags convenience structure for reading and settings tags.
*
* This function allocates a new structure which represents a snapshot
* of all the tags therein, tracking if the tag is missing,
* or present and with value. It is the caller's responsibility to free
* the structure with MP4TagsFree().
*
* @return structure with all tags missing.
*/
MP4V2_EXPORT
const MP4Tags* MP4TagsAlloc( void );
/** Fetch data from mp4 file and populate structure.
*
* The tags structure and its hidden data-cache is updated to
* reflect the actual tags values found in the <b>hFile</b>.
*
* @param tags structure to fetch (write) into.
* @param hFile handle of file to fetch data from.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4TagsFetch(
const MP4Tags* tags,
MP4FileHandle hFile );
/** Store data to mp4 file from structure.
*
* The tags structure is pushed out to the mp4 file,
* adding tags if needed, removing tags if needed, and updating
* the values to modified tags.
*
* @param tags structure to store (read) from.
* @param hFile handle of file to store data to.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4TagsStore(
const MP4Tags* tags,
MP4FileHandle hFile );
/** Free tags convenience structure.
*
* This function frees memory associated with the structure.
*
* @param tags structure to destroy.
*/
MP4V2_EXPORT
void MP4TagsFree(
const MP4Tags* tags );
/** Accessor that indicates whether a tags structure
* contains any metadata
*
* @param tags the structure to inspect
*
* @param hasMetadata populated with false if @p tags
* contains no metadata, true if @p tags contains metadata
*
* @retval false error determining if @p tags contains
* metadata
*
* @retval true successfully determined if @p tags contains
* metadata
*/
MP4V2_EXPORT
bool MP4TagsHasMetadata (
const MP4Tags* tags,
bool* hasMetadata );
MP4V2_EXPORT bool MP4TagsSetName ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetArtist ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetAlbumArtist ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetAlbum ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetGrouping ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetComposer ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetComments ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetGenre ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetGenreType ( const MP4Tags*, const uint16_t* );
MP4V2_EXPORT bool MP4TagsSetReleaseDate ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetTrack ( const MP4Tags*, const MP4TagTrack* );
MP4V2_EXPORT bool MP4TagsSetDisk ( const MP4Tags*, const MP4TagDisk* );
MP4V2_EXPORT bool MP4TagsSetTempo ( const MP4Tags*, const uint16_t* );
MP4V2_EXPORT bool MP4TagsSetCompilation ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetTVShow ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetTVNetwork ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetTVEpisodeID ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetTVSeason ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetTVEpisode ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetDescription ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetLongDescription ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetLyrics ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortName ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortArtist ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortAlbumArtist ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortAlbum ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortComposer ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetSortTVShow ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsAddArtwork ( const MP4Tags*, MP4TagArtwork* );
MP4V2_EXPORT bool MP4TagsSetArtwork ( const MP4Tags*, uint32_t, MP4TagArtwork* );
MP4V2_EXPORT bool MP4TagsRemoveArtwork ( const MP4Tags*, uint32_t );
MP4V2_EXPORT bool MP4TagsSetCopyright ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetEncodingTool ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetEncodedBy ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetPurchaseDate ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetPodcast ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetKeywords ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetCategory ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetHDVideo ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetMediaType ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetContentRating ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetGapless ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetITunesAccount ( const MP4Tags*, const char* );
MP4V2_EXPORT bool MP4TagsSetITunesAccountType ( const MP4Tags*, const uint8_t* );
MP4V2_EXPORT bool MP4TagsSetITunesCountry ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetContentID ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetArtistID ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetPlaylistID ( const MP4Tags*, const uint64_t* );
MP4V2_EXPORT bool MP4TagsSetGenreID ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetComposerID ( const MP4Tags*, const uint32_t* );
MP4V2_EXPORT bool MP4TagsSetXID ( const MP4Tags*, const char* );
/** @} ***********************************************************************/
#endif /* MP4V2_ITMF_TAGS_H */

77
third_party/include/mp4v2/mp4v2.h vendored Normal file
View File

@ -0,0 +1,77 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.com
* Kona Blend, kona8lend@gmail.com
*/
#ifndef MP4V2_MP4V2_H
#define MP4V2_MP4V2_H
/*****************************************************************************/
#include <mp4v2/platform.h>
#include <mp4v2/project.h>
/*****************************************************************************/
/* exploit C++ ability of default values for function parameters */
#if defined( DEFAULT )
# define __MP4V2_SAVE_DEFAULT DEFAULT
#endif
#undef DEFAULT
#if defined( __cplusplus )
# define DEFAULT(x) =x
#else
# define DEFAULT(x)
#endif
#ifdef __cplusplus
extern "C" {
#endif
/*****************************************************************************/
#include <mp4v2/general.h>
#include <mp4v2/file.h>
#include <mp4v2/file_prop.h>
#include <mp4v2/track.h>
#include <mp4v2/track_prop.h>
#include <mp4v2/sample.h>
#include <mp4v2/chapter.h>
#include <mp4v2/itmf_generic.h>
#include <mp4v2/itmf_tags.h>
#include <mp4v2/streaming.h>
#include <mp4v2/isma.h>
/*****************************************************************************/
/* restore macro DEFAULT to state prior to mp4v2 headers */
#undef DEFAULT
#if defined( __MP4V2_SAVE_DEFAULT )
# define DEFAULT __MP4V2_SAVE_DEFAULT
#endif
#ifdef __cplusplus
} // extern "C"
#endif
/*****************************************************************************/
#endif /* MP4V2_MP4V2_H */

97
third_party/include/mp4v2/platform.h vendored Normal file
View File

@ -0,0 +1,97 @@
/*
* 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.
*
* Contributor(s):
* Kona Blend, kona8lend@gmail.com
*/
#ifndef MP4V2_PLATFORM_H
#define MP4V2_PLATFORM_H
/*****************************************************************************/
#include <stddef.h>
#include <stdio.h>
#include <stdarg.h>
#include <stdint.h>
#if defined( _WIN32 ) || defined( __MINGW32__ )
# if defined( MP4V2_EXPORTS )
# define MP4V2_EXPORT __declspec(dllexport)
# elif defined( MP4V2_USE_DLL_IMPORT ) || !defined( MP4V2_USE_STATIC_LIB )
# define MP4V2_EXPORT __declspec(dllimport)
# else
# define MP4V2_EXPORT
# endif
#else
# define MP4V2_EXPORT __attribute__((visibility("default")))
#endif
#if defined( __GNUC__ )
# define MP4V2_DEPRECATED __attribute__((deprecated))
#else
# define MP4V2_DEPRECATED
#endif
/******************************************************************************
*
* TODO-KB: cleanup -- absolutely no need for a C-API to fuss with reserved
* C++ keywords. This will involve changing the public interface and current
* plan of action:
*
* typdef enum {
* mp4_false,
* mp4_true,
* } mp4_bool_t;
*
* followed by updating all public signatures and implementation.
*/
#ifndef FALSE
#define FALSE 0
#endif
#ifndef TRUE
#define TRUE 1
#endif
#if !defined( __cplusplus )
#ifndef bool
#if SIZEOF_BOOL == 8
typedef uint64_t bool;
#else
#if SIZEOF_BOOL == 4
typedef uint32_t bool;
#else
#if SIZEOF_BOOL == 2
typedef uint16_t bool;
#else
typedef unsigned char bool;
#endif
#endif
#endif
#ifndef false
#define false FALSE
#endif
#ifndef true
#define true TRUE
#endif
#endif
#endif
/*****************************************************************************/
#endif /* MP4V2_PLATFORM_H */

25
third_party/include/mp4v2/project.h vendored Normal file
View File

@ -0,0 +1,25 @@
#ifndef MP4V2_PROJECT_H
#define MP4V2_PROJECT_H
/*****************************************************************************/
#define MP4V2_PROJECT_name "MP4v2"
#define MP4V2_PROJECT_name_lower "mp4v2"
#define MP4V2_PROJECT_name_upper "MP4V2"
#define MP4V2_PROJECT_name_formal "MP4v2 2.1.3"
#define MP4V2_PROJECT_url_website "https://mp4v2.org"
#define MP4V2_PROJECT_url_downloads "https://github.com/enzo1982/releases"
#define MP4V2_PROJECT_url_discussion "https://github.com/enzo1982/discussions"
#define MP4V2_PROJECT_url_bugreport "https://github.com/enzo1982/issues"
#define MP4V2_PROJECT_support "<support@mp4v2.org>"
#define MP4V2_PROJECT_version "2.1.3"
#define MP4V2_PROJECT_version_hex 0x00020103
#define MP4V2_PROJECT_version_major 2
#define MP4V2_PROJECT_version_minor 1
#define MP4V2_PROJECT_version_point 3
#define MP4V2_PROJECT_repo_url "git@github.com:enzo1982/mp4v2.git"
#define MP4V2_PROJECT_build "Fri Nov 14 02:25:57 UTC 2025"
/*****************************************************************************/
#endif /* MP4V2_PROJECT_H */

25
third_party/include/mp4v2/project.h.in vendored Normal file
View File

@ -0,0 +1,25 @@
#ifndef MP4V2_PROJECT_H
#define MP4V2_PROJECT_H
/*****************************************************************************/
#define MP4V2_PROJECT_name "@PROJECT_name@"
#define MP4V2_PROJECT_name_lower "@PROJECT_name_lower@"
#define MP4V2_PROJECT_name_upper "@PROJECT_name_upper@"
#define MP4V2_PROJECT_name_formal "@PROJECT_name_formal@"
#define MP4V2_PROJECT_url_website "@PROJECT_url_website@"
#define MP4V2_PROJECT_url_downloads "@PROJECT_url_downloads@"
#define MP4V2_PROJECT_url_discussion "@PROJECT_url_discussion@"
#define MP4V2_PROJECT_url_bugreport "@PROJECT_url_bugreport@"
#define MP4V2_PROJECT_support "@PROJECT_support@"
#define MP4V2_PROJECT_version "@PROJECT_version@"
#define MP4V2_PROJECT_version_hex @PROJECT_version_hex@
#define MP4V2_PROJECT_version_major @PROJECT_version_major@
#define MP4V2_PROJECT_version_minor @PROJECT_version_minor@
#define MP4V2_PROJECT_version_point @PROJECT_version_point@
#define MP4V2_PROJECT_repo_url "@PROJECT_repo_url@"
#define MP4V2_PROJECT_build "@PROJECT_build@"
/*****************************************************************************/
#endif /* MP4V2_PROJECT_H */

590
third_party/include/mp4v2/sample.h vendored Normal file
View File

@ -0,0 +1,590 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.com
* Kona Blend, kona8lend@gmail.com
*/
#ifndef MP4V2_SAMPLE_H
#define MP4V2_SAMPLE_H
/**************************************************************************//**
*
* @defgroup mp4_sample MP4v2 Sample
* @{
*
*****************************************************************************/
/** Sample dependency types.
*
* Bit combinations 0x03, 0x30, 0xc0 are reserved.
*/
typedef enum MP4SampleDependencyType_e {
MP4_SDT_UNKNOWN = 0x00, /**< unknown */
MP4_SDT_HAS_REDUNDANT_CODING = 0x01, /**< contains redundant coding */
MP4_SDT_HAS_NO_REDUNDANT_CODING = 0x02, /**< does not contain redundant coding */
MP4_SDT_HAS_DEPENDENTS = 0x04, /**< referenced by other samples */
MP4_SDT_HAS_NO_DEPENDENTS = 0x08, /**< not referenced by other samples */
MP4_SDT_IS_DEPENDENT = 0x10, /**< references other samples */
MP4_SDT_IS_INDEPENDENT = 0x20, /**< does not reference other samples */
MP4_SDT_EARLIER_DISPLAY_TIMES_ALLOWED = 0x40, /**< subequent samples in GOP may display earlier */
_MP4_SDT_RESERVED = 0x80 /**< reserved */
} MP4SampleDependencyType;
/** Read a track sample.
*
* MP4ReadSample reads the specified sample from the specified track.
* Typically this sample is then decoded in a codec dependent fashion and
* rendered in an appropriate fashion.
*
* The argument <b>ppBytes</b> allows for two possible approaches for
* buffering:
*
* If the calling application wishes to handle its own buffering it can set
* *ppBytes to the buffer it wishes to use. The calling application is
* responsible for ensuring that the buffer is large enough to hold the
* sample. This can be done by using either MP4GetSampleSize() or
* MP4GetTrackMaxSampleSize() to determine beforehand how large the
* receiving buffer must be.
*
* If the value of *ppBytes is NULL, then an appropriately sized buffer is
* automatically allocated for the sample data and *ppBytes set to this
* pointer. The calling application is responsible for freeing this memory
* with MP4Free().
*
* The last four arguments are pointers to variables that can receive
* optional sample information.
*
* Typically for audio none of these are needed. MPEG audio such as MP3 or
* AAC has a fixed sample duration and every sample can be accessed at
* random.
*
* For video, all of these optional values could be needed. MPEG video can
* be encoded at a variable frame rate, with only occasional random access
* points, and with "B frames" which cause the rendering (display) order
* of the video frames to differ from the storage/decoding order.
*
* Other media types fall between these two extremes.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param sampleId specifies which sample is to be read.
* Caveat: the first sample has id <b>1</b> not <b>0</b>.
* @param ppBytes pointer to the pointer to the sample data.
* @param pNumBytes pointer to variable that will be hold the size in bytes
* of the sample.
* @param pStartTime if non-NULL, pointer to variable that will receive the
* starting timestamp for this sample. Caveat: The timestamp is in
* <b>trackId</b>'s timescale.
* @param pDuration if non-NULL, pointer to variable that will receive the
* duration for this sample. Caveat: The duration is in
* <b>trackId</b>'s timescale.
* @param pRenderingOffset if non-NULL, pointer to variable that will
* receive the rendering offset for this sample. Currently the only
* media type that needs this feature is MPEG video. Caveat: The offset
* is in <b>trackId</b>'s timescale.
* @param pIsSyncSample if non-NULL, pointer to variable that will receive
* the state of the sync/random access flag for this sample.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*
* @see MP4GetSampleSize()
* @see MP4GetTrackMaxSampleSize()
*/
MP4V2_EXPORT
bool MP4ReadSample(
/* input parameters */
MP4FileHandle hFile,
MP4TrackId trackId,
MP4SampleId sampleId,
/* input/output parameters */
uint8_t** ppBytes,
uint32_t* pNumBytes,
/* output parameters */
MP4Timestamp* pStartTime DEFAULT(NULL),
MP4Duration* pDuration DEFAULT(NULL),
MP4Duration* pRenderingOffset DEFAULT(NULL),
bool* pIsSyncSample DEFAULT(NULL) );
/** Read a track sample based on a specified time.
*
* MP4ReadSampleFromTime is similar to MP4ReadSample() except the sample
* is specified by using a timestamp instead of sampleId.
* Typically this sample is then decoded in a codec dependent fashion and
* rendered in an appropriate fashion.
*
* The argument <b>ppBytes</b> allows for two possible approaches for
* buffering:
*
* If the calling application wishes to handle its own buffering it can set
* *ppBytes to the buffer it wishes to use. The calling application is
* responsible for ensuring that the buffer is large enough to hold the
* sample. This can be done by using either MP4GetSampleSize() or
* MP4GetTrackMaxSampleSize() to determine beforehand how large the
* receiving buffer must be.
*
* If the value of *ppBytes is NULL, then an appropriately sized buffer is
* automatically allocated for the sample data and *ppBytes set to this
* pointer. The calling application is responsible for freeing this memory
* with MP4Free().
*
* The last four arguments are pointers to variables that can receive
* optional sample information.
*
* Typically for audio none of these are needed. MPEG audio such as MP3 or
* AAC has a fixed sample duration and every sample can be accessed at
* random.
*
* For video, all of these optional values could be needed. MPEG video can
* be encoded at a variable frame rate, with only occasional random access
* points, and with "B frames" which cause the rendering (display) order
* of the video frames to differ from the storage/decoding order.
*
* Other media types fall between these two extremes.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param when specifies which sample is to be read based on a time in the
* track timeline. See MP4GetSampleIdFromTime() for details.
* @param ppBytes pointer to the pointer to the sample data.
* @param pNumBytes pointer to variable that will be hold the size in bytes
* of the sample.
* @param pStartTime if non-NULL, pointer to variable that will receive the
* starting timestamp for this sample. Caveat: The timestamp is in
* <b>trackId</b>'s timescale.
* @param pDuration if non-NULL, pointer to variable that will receive the
* duration for this sample. Caveat: The duration is in
* <b>trackId</b>'s timescale.
* @param pRenderingOffset if non-NULL, pointer to variable that will
* receive the rendering offset for this sample. Currently the only
* media type that needs this feature is MPEG video. Caveat: The offset
* is in <b>trackId</b>'s timescale.
* @param pIsSyncSample if non-NULL, pointer to variable that will receive
* the state of the sync/random access flag for this sample.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*
* @see MP4ReadSample()
* @see MP4GetSampleIdFromTime()
* @see MP4GetSampleSize()
* @see MP4GetTrackMaxSampleSize()
*/
MP4V2_EXPORT
bool MP4ReadSampleFromTime(
/* input parameters */
MP4FileHandle hFile,
MP4TrackId trackId,
MP4Timestamp when,
/* input/output parameters */
uint8_t** ppBytes,
uint32_t* pNumBytes,
/* output parameters */
MP4Timestamp* pStartTime DEFAULT(NULL),
MP4Duration* pDuration DEFAULT(NULL),
MP4Duration* pRenderingOffset DEFAULT(NULL),
bool* pIsSyncSample DEFAULT(NULL) );
/** Write a track sample.
*
* MP4WriteSample writes the given sample at the end of the specified track.
* Currently the library does not support random insertion of samples into
* the track timeline. Note that with mp4 there cannot be any holes or
* overlapping samples in the track timeline. The last three arguments give
* optional sample information.
*
* The value of duration can be given as #MP4_INVALID_DURATION if all samples
* in the track have the same duration. This can be specified with
* MP4AddTrack() and related functions.
*
* Typically for audio none of the optional arguments are needed. MPEG audio
* such as MP3 or AAC has a fixed sample duration and every sample can be
* accessed at random.
*
* For video, all of the optional arguments could be needed. MPEG video
* can be encoded at a variable frame rate, with only occasional random
* access points, and with "B frames" which cause the rendering (display)
* order of the video frames to differ from the storage/decoding order.
*
* Other media types fall between these two extremes.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param pBytes pointer to sample data.
* @param numBytes length of sample data in bytes.
* @param duration sample duration. Caveat: should be in track timescale.
* @param renderingOffset the rendering offset for this sample.
* Currently the only media type that needs this feature is MPEG
* video. Caveat: The offset should be in the track timescale.
* @param isSyncSample the sync/random access flag for this sample.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*
* @see MP4AddTrack()
*/
MP4V2_EXPORT
bool MP4WriteSample(
MP4FileHandle hFile,
MP4TrackId trackId,
const uint8_t* pBytes,
uint32_t numBytes,
MP4Duration duration DEFAULT(MP4_INVALID_DURATION),
MP4Duration renderingOffset DEFAULT(0),
bool isSyncSample DEFAULT(true) );
/** Write a track sample and supply dependency information.
*
* MP4WriteSampleDependency writes the given sample at the end of the
* specified track. Currently the library does not support random insertion of
* samples into the track timeline. Note that with mp4 there cannot be any
* holes or overlapping samples in the track timeline. The last three
* arguments give optional sample information.
*
* The value of duration can be given as #MP4_INVALID_DURATION if all samples
* in the track have the same duration. This can be specified with
* MP4AddTrack() and related functions.
*
* When this method is used instead of MP4WriteSample() it enables <b>sdtp</b>
* atom to be written out. This atom may be used by advanced players to
* optimize trick-operations such as fast-fwd, reverse or scrubbing.
*
* An <b>sdtp</b> atom will always be written out if this method is used.
* To avoid writing the atom, use MP4WriteSample() instead.
*
* Intermixing use of MP4WriteSampleDependency() and MP4WriteSample() on the
* same track is not permitted.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param pBytes pointer to sample data.
* @param numBytes length of sample data in bytes.
* @param duration sample duration. Caveat: should be in track timescale.
* @param renderingOffset the rendering offset for this sample.
* Currently the only media type that needs this feature is MPEG
* video. Caveat: The offset should be in the track timescale.
* @param isSyncSample the sync/random access flag for this sample.
* @param dependencyFlags bitmask specifying sample dependency characteristics.
* See #MP4SampleDependencyType for bit constants.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*
* @see MP4AddTrack()
*/
MP4V2_EXPORT
bool MP4WriteSampleDependency(
MP4FileHandle hFile,
MP4TrackId trackId,
const uint8_t* pBytes,
uint32_t numBytes,
MP4Duration duration,
MP4Duration renderingOffset,
bool isSyncSample,
uint32_t dependencyFlags );
/** Make a copy of a sample.
*
* MP4CopySample creates a new sample based on an existing sample. Note that
* another copy of the media sample data is created in the file using this
* function. I.e. this call is equivalent to MP4ReadSample() followed by
* MP4WriteSample().
*
* Note that is the responsibility of the caller to ensure that the copied
* media sample makes sense in the destination track, e.g. copying a video
* sample to an audio track is unlikely to result in anything good happening,
* even copying a sample from video track to another requires that the tracks
* use the same encoding and that issues such as image size are addressed.
*
* @param srcFile source sample file handle.
* @param srcTrackId source sample track id.
* @param srcSampleId source sample id.
* @param dstFile destination file handle for new (copied) sample.
* If the value is #MP4_INVALID_FILE_HANDLE, the copy is created in
* the same file as <b>srcFile</b>.
* @param dstTrackId destination track id for new sample.
* If the value is #MP4_INVALID_TRACK_ID, the the copy is created in
* the same track as the <b>srcTrackId</b>.
* @param dstSampleDuration duration in track timescale for new sample.
* If the value is #MP4_INVALID_DURATION, then the duration of
* the source sample is used.
*
* @return On success, thew id of the new sample.
* On error, #MP4_INVALID_SAMPLE_ID.
*
* @see MP4ReadSample()
* @see MP4WriteSample()
*/
MP4V2_EXPORT
bool MP4CopySample(
MP4FileHandle srcFile,
MP4TrackId srcTrackId,
MP4SampleId srcSampleId,
MP4FileHandle dstFile DEFAULT(MP4_INVALID_FILE_HANDLE),
MP4TrackId dstTrackId DEFAULT(MP4_INVALID_TRACK_ID),
MP4Duration dstSampleDuration DEFAULT(MP4_INVALID_DURATION) );
/** Make a copy of a sample.
*
* MP4EncAndCopySample is similar to MP4CopySample() except that it
* offers an encryption hook to the caller.
*
* @param srcFile source sample file handle.
* @param srcTrackId source sample track id.
* @param srcSampleId source sample id.
* @param encfcnp undocumented.
* @param encfcnparam1 undocumented.
* @param dstFile destination file handle for new (copied) sample.
* If the value is #MP4_INVALID_FILE_HANDLE, the copy is created in
* the same file as <b>srcFile</b>.
* @param dstTrackId destination track id for new sample.
* If the value is #MP4_INVALID_TRACK_ID, the the copy is created in
* the same track as the <b>srcTrackId</b>.
* @param dstSampleDuration duration in track timescale for new sample.
* If the value is #MP4_INVALID_DURATION, then the duration of
* the source sample is used.
*
* @return On success, thew id of the new sample.
* On error, #MP4_INVALID_SAMPLE_ID.
*
* @see MP4CopySample()
*/
MP4V2_EXPORT
bool MP4EncAndCopySample(
MP4FileHandle srcFile,
MP4TrackId srcTrackId,
MP4SampleId srcSampleId,
encryptFunc_t encfcnp,
uint32_t encfcnparam1,
MP4FileHandle dstFile DEFAULT(MP4_INVALID_FILE_HANDLE),
MP4TrackId dstTrackId DEFAULT(MP4_INVALID_TRACK_ID),
MP4Duration dstSampleDuration DEFAULT(MP4_INVALID_DURATION) );
/** Not implemented.
*/
MP4V2_EXPORT
bool MP4ReferenceSample(
MP4FileHandle srcFile,
MP4TrackId srcTrackId,
MP4SampleId srcSampleId,
MP4FileHandle dstFile,
MP4TrackId dstTrackId,
MP4Duration dstSampleDuration DEFAULT(MP4_INVALID_DURATION) );
/** Get size of a track sample.
*
* MP4GetSampleSize returns the size in bytes of the specified sample from the
* the specified track.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param sampleId id of sample for operation. Caveat: the first sample has
* id <b>1</b>, not <b>0</b>.
*
* @return On success the sample size in bytes. On error, <b>0</b>.
*/
MP4V2_EXPORT
uint32_t MP4GetSampleSize(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4SampleId sampleId);
/** Get the maximum sample size of a track.
*
* MP4GetTrackMaxSampleSize returns the maximum size in bytes of all the
* samples in the specified track.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
*
* @return On success, the maximum sample size in bytes. On error, <b>0</b>.
*
* @see MP4GetSampleSize()
*/
MP4V2_EXPORT
uint32_t MP4GetTrackMaxSampleSize(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get sample id of a specified time.
*
* MP4GetSampleIdFromTime returns the sample id of the track sample in which
* the specified time occurs.
*
* The specified time should be in the track timescale.
*
* It is wise to use MP4GetSampleTime() with the returned sample id so one
* can adjust for any difference between the specified time and the actual
* start time of the sample.
*
* If the calling application needs a sample that can be accessed randomly
* then the <b>wantSyncSample</b> argument should be set to true. This could
* be the case for a player that is implementing a positioning function and
* needs to be able to start decoding a track from the returned sample id.
*
* See MP4ConvertToTrackTimestamp() for how to map a time value to this
* timescale.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param when time in track timescale.
* @param wantSyncSample specifies if the result sample id must correspond
* to a sample whose sync/random access flag is true.
*
* @return On success, the sample id that occurs at the specified time.
* On error, #MP4_INVALID_SAMPLE_ID.
*
* @see MP4ConvertToTrackTimestamp()
*/
MP4V2_EXPORT
MP4SampleId MP4GetSampleIdFromTime(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4Timestamp when,
bool wantSyncSample DEFAULT(false) );
/** Get start time of track sample.
*
* MP4GetSampleTime returns the start time of the specified sample from
* the specified track in the track timescale units.
*
* See MP4ConvertFromTrackTimestamp() for how to map this value to another
* timescale.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param sampleId id of sample for operation. Caveat: the first sample has
* id <b>1</b>, not <b>0</b>.
*
* @return On success, sample start time in track timescale units.
* On error, #MP4_INVALID_TIMESTAMP.
*
* @see MP4ConvertFromTrackTimestamp()
*/
MP4V2_EXPORT
MP4Timestamp MP4GetSampleTime(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4SampleId sampleId );
/** Get the duration of a track sample.
*
* MP4GetSampleDuration returns the duration of the specified sample from
* the specified track in the track timescale units.
*
* See MP4ConvertFromTrackDuration() for how to map this value to another
* timescale.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param sampleId id of sample for operation. Caveat: the first sample has
* id <b>1</b>, not <b>0</b>.
*
* @return On success, the sample duration in track timescale units.
* On error, #MP4_INVALID_DURATION.
*
* @see MP4ConvertFromTrackDuration()
*/
MP4V2_EXPORT
MP4Duration MP4GetSampleDuration(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4SampleId sampleId );
/** Get the rendering offset of a track sample.
*
* MP4GetSampleRenderingOffset returns the rendering offset of the specified
* sample from the specified track in the track timescale units.
*
* The sample rendering offset is typically zero for all media types other
* than video. For video, encodings such as those defined by MPEG have
* three types of frames: I, P, and B. To increase coding efficiency B
* frames can depend on I or P frames that should be rendered after the B
* frame. However to decode the B frame the I or P frame must already have
* been decoded. This situation is addressed by placing the frames in
* decoding order in the video track, and then setting the rendering offset
* property to indicate when the video frame should actually be rendered to
* the screen. Hence the start time of a sample indicates when it should be
* decoded, the start time plus the rendering offset indicates when it
* should be rendered.
*
* See MP4ConvertFromTrackDuration() for how to map this value to another
* timescale.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param sampleId id of sample for operation. Caveat: the first sample has
* id <b>1</b>, not <b>0</b>.
*
* @return On success, the rendering offset in track timescale units.
* On error, #MP4_INVALID_DURATION.
*
* @see MP4ConvertFromTrackDuration()
*/
MP4V2_EXPORT
MP4Duration MP4GetSampleRenderingOffset(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4SampleId sampleId );
/** Set the rendering offset of a track sample.
*
* MP4SetSampleRenderingOffset sets the rendering offset of the specified
* sample from the specified track in the track timescale units.
*
* See MP4ConvertToTrackDuration() for how to map this value from another
* timescale and MP4GetSampleRenderingOffset() for a description of this
* sample property.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param sampleId id of sample for operation. Caveat: the first sample has
* id <b>1</b>, not <b>0</b>.
* @param renderingOffset new offset value in timescale units.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*
* @see MP4ConvertToTrackDuration()
* @see MP4GetSampleRenderingOffset()
*/
MP4V2_EXPORT
bool MP4SetSampleRenderingOffset(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4SampleId sampleId,
MP4Duration renderingOffset );
/** Get sync/random access state of sample.
*
* MP4GetSampleSync returns the state of the sync/random access flag of
* the specified sample from the specified track.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param sampleId id of sample for operation. Caveat: the first sample has
* id <b>1</b>, not <b>0</b>.
*
* @return <b>1</b> when true, <b>0</b> when false. On error, <b>-1</b>.
*/
MP4V2_EXPORT
int8_t MP4GetSampleSync(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4SampleId sampleId );
/** @} ***********************************************************************/
#endif /* MP4V2_SAMPLE_H */

699
third_party/include/mp4v2/streaming.h vendored Normal file
View File

@ -0,0 +1,699 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.com
* Robert Kausch, robert.kausch@freac.org
*/
#ifndef MP4V2_STREAMING_H
#define MP4V2_STREAMING_H
/**************************************************************************//**
*
* @defgroup mp4_hint MP4v2 Streaming
* @{
*
*****************************************************************************/
/** Get the RTP payload parameters of the hint track.
*
* MP4GetHintTrackRtpPayload gets the RTP payload parameters for the hint
* track. The RTP payload is the set of rules by which media samples are
* packed into RTP packets. This call is typically used in constructing the
* SDP media level description for the hint track.
*
* The payloadName identifies which RTP payload is being used for the RTP
* packets created from the hint track. This value is sent to the receiver in
* the SDP description. For example, MP3 audio sent according to the rules in
* IETF RFC 2250 uses the name "MPA" for the RTP payload.
*
* The payloadNumber is a shorter form of the payloadName. This value is
* associated with the payload name in the SDP description and then sent in
* every RTP packet. Payload numbers 1 thru 95 are statically assigned in IETF
* RFC 1890, numbers 96 thru 127 are dynamically assigned within a session.
*
* The maxPayloadSize specifies the maximum number of bytes that should be
* placed in the RTP payload section of the RTP packets.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param ppPayloadName specifies a pointer to the variable to receive the
* string RTP payload name.
* @param pPayloadNumber specifies a pointer to the variable to receive the
* RTP payload number.
* @param pMaxPayloadSize specifies a pointer to the variable to receive the
* maximum RTP payload size in bytes.
* @param ppEncodingParams
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4SetHintTrackRtpPayload()
*/
MP4V2_EXPORT
bool MP4GetHintTrackRtpPayload(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
char** ppPayloadName DEFAULT(NULL),
uint8_t* pPayloadNumber DEFAULT(NULL),
uint16_t* pMaxPayloadSize DEFAULT(NULL),
char** ppEncodingParams DEFAULT(NULL) );
#define MP4_SET_DYNAMIC_PAYLOAD 0xff
/** Set the RTP payload parameters of the hint track.
*
* MP4SetHintTrackRtpPayload sets the RTP payload parameters for the hint
* track. The RTP payload is the set of rules by which media samples are
* packed into RTP packets.
*
* The payload name identifies which RTP payload is being used for the RTP
* packets created from the hint track. This value is sent to the receiver in
* the SDP description. For example, MP3 audio sent according to the rules in
* IETF RFC 2250 uses the name "MPA" for the RTP payload.
*
* The payload number is a shorter form of the payload name. This value is
* associated with the payload name in the SDP description and then sent in
* every RTP packet. Payload numbers 1 thru 95 are statically assigned in IETF
* RFC 1890, numbers 96 thru 127 are dynamically assigned within a session. If
* the RTP payload in use is one of the statically assigned ones, you should
* pass this value to the library. If you need a dynamic payload number
* assigned, pass the define value MP4_SET_DYNAMIC_PAYLOAD for this parameter
* and the library will choose an valid available number and return this
* value.
*
* The maxPayloadSize specifies the maximum number of bytes that should be
* placed in the RTP payload section of the RTP packets. It is desirable that
* RTP packets not exceed the maximum transmission unit (MTU) of the IP
* network they travel over since otherwise the packets must be fragmented at
* the IP level which consumes router resources and can lead to less robust
* behavior in the face of packet loss.
*
* The default value for maxPayloadSize is 1460, which is the MTU for an
* Ethernet or similar network minus the standard sizes of the IP, UDP, and
* RTP headers (1500 - 20 - 8 - 12 = 1460).
*
* If you anticipate streaming over IP networks with smaller MTU sizes, or
* that extensions to the network headers might be used, a more conservative
* value should be chosen. The minimum MTU for an IP network is 576 bytes.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param pPayloadName specifies the RTP payload name.
* @param pPayloadNumber specifies a pointer to the RTP payload number.
* @param maxPayloadSize specifies the maximum RTP payload size in bytes.
* @param encode_params
* @param include_rtp_map specifies if the a=rtpmap statement is included.
* @param include_mpeg4_esid specifies if the a=mpeg4-esid statement is
* included.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetHintTrackRtpPayload()
*/
MP4V2_EXPORT
bool MP4SetHintTrackRtpPayload(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
const char* pPayloadName,
uint8_t* pPayloadNumber,
uint16_t maxPayloadSize DEFAULT(0),
const char * encode_params DEFAULT(NULL),
bool include_rtp_map DEFAULT(true),
bool include_mpeg4_esid DEFAULT(true) );
/** Get the SDP session level description of the file.
*
* MP4GetSessionSdp returns the SDP (IETF RFC 2327) session level fragment for
* the file. This is used by a streaming server to create a complete SDP
* description of the multimedia session represented by the file.
*
* The mp4broadcaster test program provided with the MP4v2 library gives an
* example of using this call to create the complete SDP description.
*
* @param hFile specifies the mp4 file to which the operation applies.
*
* @return The SDP session level description fragment of the mp4 file.
*
* @see MP4SetSessionSdp()
* @see MP4AppendSessionSdp()
* @see MP4GetHintTrackSdp()
*/
MP4V2_EXPORT
const char* MP4GetSessionSdp(
MP4FileHandle hFile );
/** Set the SDP session level description of the file.
*
* MP4SetSessionSdp sets the SDP (IETF RFC 2327) session level fragment for
* the file. This is used by a streaming server to create a complete SDP
* description of the multimedia session represented by the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param sdpString specifies the new value of the session SDP string.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetSessionSdp()
* @see MP4AppendSessionSdp()
*/
MP4V2_EXPORT
bool MP4SetSessionSdp(
MP4FileHandle hFile,
const char* sdpString );
/** Add to the SDP session level description of the file.
*
* MP4AppendSessionSdp appends the specified string to the SDP (IETF RFC 2327)
* session level fragment for the file. This is used by a streaming server to
* create a complete SDP description of the multimedia session represented by
* the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param sdpString specifies the addition to the session SDP string.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetSessionSdp()
* @see MP4SetSessionSdp()
*/
MP4V2_EXPORT
bool MP4AppendSessionSdp(
MP4FileHandle hFile,
const char* sdpString );
/** Get the SDP media level description associated with a hint track.
*
* MP4GetHintTrackSdp returns the SDP (IETF RFC 2327) media level fragment
* associated with the hint track. This is used by a streaming server to
* create a complete SDP description of the multimedia session represented by
* the file.
*
* The mp4broadcaster test program provided with the MP4 library gives an
* example of using this call to create the complete SDP description.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
*
* @return SDP media level description fragment associated with the hint
* track.
*
* @see MP4SetHintTrackSdp()
* @see MP4AppendHintTrackSdp()
* @see MP4GetSessionSdp()
*/
MP4V2_EXPORT
const char* MP4GetHintTrackSdp(
MP4FileHandle hFile,
MP4TrackId hintTrackId );
/** Set the SDP media level description of the hint track.
*
* MP4SetHintTrackSdp sets the SDP (IETF RFC 2327) media level fragment for
* the hint track. This is used by a streaming server to create a complete SDP
* description of the multimedia session represented by the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param sdpString specifies the new value of the hint track SDP string.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetHintTrackSdp()
* @see MP4AppendHintTrackSdp()
*/
MP4V2_EXPORT
bool MP4SetHintTrackSdp(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
const char* sdpString );
/** Add to the SDP media level description of the hint track.
*
* MP4AppendHintTrackSdp appends the specified string to the SDP (IETF RFC
* 2327) media level fragment for the hint track. This is used by a streaming
* server to create a complete SDP description of the multimedia session
* represented by the file.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param sdpString specifies the addition to the hint track SDP string.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetHintTrackSdp()
* @see MP4AppendHintTrackSdp()
*/
MP4V2_EXPORT
bool MP4AppendHintTrackSdp(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
const char* sdpString );
/** Get the reference track id for a hint track.
*
* MP4GetHintTrackReferenceTrackId gets the track id of the reference media
* track associated with the specified hint track.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
*
* @return Upon success, the track id of the reference media track. Upon an
* error, MP4_INVALID_TRACK_ID.
*
* @see MP4AddHintTrack()
*/
MP4V2_EXPORT
MP4TrackId MP4GetHintTrackReferenceTrackId(
MP4FileHandle hFile,
MP4TrackId hintTrackId );
/** Read an RTP hint.
*
* MP4ReadRtpHint reads the specified hint sample from the specified hint
* track and enables subsequent calls to MP4ReadRtpPacket() to read the
* individual RTP packets associated with this hint. If desired, the number of
* RTP packets associated with this hint is returned.
*
* Note that a hint track sample is just like any other track sample. I.e.
* MP4ReadSample(), MP4GetSampleSize(), MP4GetSampleTime(), etc. are all
* valid. The RTP specific functions are provided to interpret the information
* contain in the hint track samples that give instructions on how to form the
* actual RTP packets.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param hintSampleId specifies which hint sample is to be read. Caveat: the
* first sample has id 1 not 0.
* @param pNumPackets Pointer to variable that will be hold the number of
* packets in the hint.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4ReadRtpPacket()
*/
MP4V2_EXPORT
bool MP4ReadRtpHint(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
MP4SampleId hintSampleId,
uint16_t* pNumPackets DEFAULT(NULL) );
/** Get the number of packets in an RTP hint.
*
* MP4GetRtpHintNumberOfPackets returns the number of packets contained in the
* current RTP hint as established by a call to MP4ReadRtpHint().
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
*
* @return Upon success, the number of packets in the current RTP hint. Upon
* an error, 0.
*
* @see MP4ReadRtpHint()
*/
MP4V2_EXPORT
uint16_t MP4GetRtpHintNumberOfPackets(
MP4FileHandle hFile,
MP4TrackId hintTrackId );
/** Get the B frame flag of an RTP packet.
*
* MP4GetRtpPacketBFrame returns the state of the B Frame flag of an RTP
* packet. See MP4AddRtpHint() for a description of this flag.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param packetIndex specifies the packet to which the operation applies.
*
* @return Upon success, the state of the B frame flag for the specified
* packet. Upon an error, -1.
*
* @see MP4AddRtpHint()
* @see MP4ReadRtpPacket()
*/
MP4V2_EXPORT
int8_t MP4GetRtpPacketBFrame(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
uint16_t packetIndex );
/** Get the transmit offset of an RTP packet.
*
* MP4GetRtpPacketTransmitOffset returns the transmit offset of an RTP packet.
* This offset may be set by some hinters to smooth out the packet
* transmission times and reduce network burstiness. A transmitter would need
* to apply this offset to the calculated transmission time based on the hint
* start time.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param packetIndex specifies the packet to which the operation applies.
*
* @return The transmit offset for the specified packet in the hint track
* timescale.
*
* @see MP4AddRtpHint()
* @see MP4ReadRtpPacket()
*/
MP4V2_EXPORT
int32_t MP4GetRtpPacketTransmitOffset(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
uint16_t packetIndex );
/** Read an RTP packet.
*
* MP4ReadRtpPacket reads the specified packet from the current hint sample,
* as previously read by MP4ReadRtpHint().
*
* The argument ppBytes allows for two possible approaches for buffering:
*
* @li If the calling application wishes to handle its own buffering it can
* set *ppBytes to the buffer it wishes to use. The calling application is
* responsible for ensuring that the buffer is large enough to hold the
* packet. This can be done by using MP4GetRtpPayload() to retrieve the
* maximum packet payload size and hence how large the receiving buffer
* must be. Caveat: the value returned by MP4GetRtpPayload() is the
* maximum payload size, if the RTP packet header is going to be included
* by the library this value should be incremented by 12.
*
* @li If the value of *ppBytes is NULL, then an appropriately sized buffer is
* automatically allocated for the sample data and *ppBytes set to this
* pointer. The calling application is responsible for freeing this memory
* with MP4Free().
*
* The application is expected to provide the value of the RTP SSRC identifier
* which uniquely identifies the originator of the media stream. For most
* applications, a single random value can be provided. The value should be
* the same for all packets for the duration of the RTP transmission. If the
* parameter @p includeHeader is false, then this value has no effect.
*
* By default the library constructs the standard 12 byte RTP header from the
* information in the hint sample, and the specified SSRC. It then
* concatenates the RTP header with the packet payload, that is the RTP
* payload specific header and the media data for the packet. The @p
* includeHeader and @p includePayload parameters allow control over these
* steps, so that either just the packet payloads or just the RTP headers can
* be returned. A potential use of this feature is if the calling application
* wishes to construct an extended RTP header with non-standard options.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param packetIndex specifies which packet is to be read. Valid values range
* from zero to the number of packets in this hint minus one.
* @param ppBytes Pointer to the pointer to the packet data. See the function
* description for details on this argument.
* @param pNumBytes Pointer to variable that will be hold the size in bytes of
* the packet.
* @param ssrc specifies the RTP SSRC to be used when constructing the RTP
* packet header.
* @param includeHeader specifies whether the library should include the
* standard 12 byte RTP header to the returned packet. The header is
* constructed from the information in the hint sample and the specified
* ssrc.
* @param includePayload specifies whether the library should include the
* packet payload (RTP payload header and media data) in the returned
* packet.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4ReadRtpHint()
*/
MP4V2_EXPORT
bool MP4ReadRtpPacket(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
uint16_t packetIndex,
uint8_t** ppBytes,
uint32_t* pNumBytes,
uint32_t ssrc DEFAULT(0),
bool includeHeader DEFAULT(true),
bool includePayload DEFAULT(true) );
/** Get the RTP start time of a hint track.
*
* MP4GetRtpTimestampStart returns the RTP timestamp start of the specified
* hint track. Typically this is a random value that is chosen when the first
* RTP packet is constructed by the MP4 library. However the value can be set
* explicitly for the hint track and stored. Typically this is used if it is
* desired that timestamps start at zero.
*
* An application will need this value in order to construct RTCP Sender
* Reports that relate the hint track time to an real time clock. The
* mp4broadcaster test program provided with the MP4 library gives an example
* of this.
*
* See IETF RFC 1889 for details regarding RTP timestamps and RTCP.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
*
* @return Upon success, the RTP start time in the RTP time scale which is
* identical to the hint track time scale. Upon an error,
* MP4_INVALID_TIMESTAMP.
*
* @see MP4SetRtpTimestampStart()
*/
MP4V2_EXPORT
MP4Timestamp MP4GetRtpTimestampStart(
MP4FileHandle hFile,
MP4TrackId hintTrackId );
/** Get the RTP start time of a hint track.
*
* MP4SetRtpTimestampStart sets the RTP timestamp start of the specified hint
* track. Typically this is a random value that is chosen when the first RTP
* packet is constructed by the MP4 library. However the value can be set
* explicitly for the hint track and stored. Typically this is used if it is
* desired that timestamps start at zero.
*
* See IETF RFC 1889 for details regarding RTP timestamps and RTCP.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param rtpStart specifies the desired RTP start timestamp for the hint
* track.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetRtpTimestampStart()
*/
MP4V2_EXPORT
bool MP4SetRtpTimestampStart(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
MP4Timestamp rtpStart );
/** Add an RTP hint.
*
* MP4AddRtpHint creates a new hint sample for the specified hint track and
* enables subsequent calls to MP4AddRtpPacket() to create the RTP packets
* associated with this hint. After all the RTP packets for the hint have been
* created, MP4WriteRtpHint() should be called to write the hint to the track.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4AddRtpPacket()
* @see MP4WriteRtpHint()
*/
MP4V2_EXPORT
bool MP4AddRtpHint(
MP4FileHandle hFile,
MP4TrackId hintTrackId );
/** Add an RTP video specific hint.
*
* MP4AddRtpVideoHint is an extended version of MP4AddRtpHint specifically to
* handle MPEG video frames.
*
* The isBFrame parameter allows the packets in the RTP hint to be marked as
* belonging to a video B frame. This can be useful to a streaming server if
* packets must be dropped due to system load or network congestion. No other
* video frames are dependent on the contents of B frames, so they are least
* damaging type of frames to drop.
*
* The timestampOffset parameter allows an offset to be added to the RTP
* timestamp of the packets in the RTP hint. This is necessary for MPEG video
* that contains B frames since the video frames are transmitted out of order
* with respect to when they should be rendered. I.e. I and P frames are
* transmitted before any B frames that depend on them. The RTP timestamp must
* represent the rendering time of the data in the packets hence an offset
* must be added.
*
* Note: The timestampOffset is equivalent to the sample rendering offset of a
* video media track. See MP4GetSampleRenderingOffset().
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param isBFrame specifies if this hint will contain packets for a video B
* frame.
* @param timestampOffset specifies a positive offset to add to the RTP
* timestamp for this hint. Caveat: the value is in the hint track
* timescale.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4AddRtpHint()
* @see MP4AddRtpPacket()
* @see MP4WriteRtpHint()
*/
MP4V2_EXPORT
bool MP4AddRtpVideoHint(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
bool isBFrame DEFAULT(false),
uint32_t timestampOffset DEFAULT(0) );
/** Add an RTP packet.
*
* MP4AddRtpPacket creates a new RTP packet for the currently pending RTP hint
* sample for the specified hint track. It also enables subsequent calls to
* MP4AddRtpImmediateData() and MP4AddRtpSampleData to add data to the RTP
* packets. After all the RTP packets for the hint have been created,
* MP4WriteRtpHint() should be called to write the hint to the track.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param setMBit specifies the value of the RTP packet header marker bit for
* this packet. The value depends on the rules of the RTP payload used for
* this hint track.
* @param transmitOffset specifies an offset to apply to the normal
* transmission time of this packet. The purpose of this offset is to
* allow smoothing of packet transmission over the duration of the hint.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4AddRtpHint()
* @see MP4AddRtpImmediateData()
* @see MP4AddRtpSampleData()
* @see MP4WriteRtpHint()
*/
MP4V2_EXPORT
bool MP4AddRtpPacket(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
bool setMBit DEFAULT(false),
int32_t transmitOffset DEFAULT(0) );
/** Add immediate data to an RTP packet.
*
* MP4AddRtpImmediateData adds immediate data to the current pending RTP
* packet. Typically, this is used to add RTP payload specific headers to RTP
* packets. Note that the size of a block of immediate data is limited to 14
* bytes. But multiple immediate data blocks can be added if more space is
* needed.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param pBytes specifies a pointer to the immediate data that should be
* included in the current RTP packet.
* @param numBytes specifies the length in bytes of the immediate data that
* should be included in the current RTP packet.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4AddRtpPacket()
* @see MP4AddRtpSampleData()
*/
MP4V2_EXPORT
bool MP4AddRtpImmediateData(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
const uint8_t* pBytes,
uint32_t numBytes );
/** Add media sample data to an RTP packet.
*
* MP4AddRtpSampleData adds a reference in the current pending RTP packet to
* the media data in the specified media sample of the reference media track.
* Note this is a reference, not a copy, of the media data.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param sampleId specifies the reference media sample id from which the
* media data should be taken.
* @param dataOffset specifies the byte offset in the specified media sample
* where data should be taken from for the current RTP packet.
* @param dataLength specifies the length in bytes of the media data that
* should be included in the current RTP packet.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4AddRtpPacket()
* @see MP4AddRtpImmediateData()
*/
MP4V2_EXPORT
bool MP4AddRtpSampleData(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
MP4SampleId sampleId,
uint32_t dataOffset,
uint32_t dataLength );
/** Add ES configuration information to an RTP hint.
*
* MP4AddRtpESConfigurationPacket adds a packet to the current RTP hint that
* contains a copy of the elementary stream configuration information of the
* reference media track. Some RTP payloads require this information to be
* transmitted at the start of streaming or periodically during streaming.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4SetTrackESConfiguration()
*/
MP4V2_EXPORT
bool MP4AddRtpESConfigurationPacket(
MP4FileHandle hFile,
MP4TrackId hintTrackId );
/** Write an RTP hint.
*
* MP4WriteRtpHint writes the current pending hint created with
* MP4AddRtpHint() to the specified hint track.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param hintTrackId specifies the hint track to which the operation applies.
* @param duration specifies the duration for this hint sample. Typically this
* is the same duration as for the corresponding sample in the reference
* media track. Caveat: The duration should be in the hint track timescale
* units, again typically the same as the reference media track.
* @param isSyncSample specifies the sync/random access flag for this sample.
* Typically this is the same as for the corresponding sample in the
* reference media track.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4AddRtpHint()
*/
MP4V2_EXPORT
bool MP4WriteRtpHint(
MP4FileHandle hFile,
MP4TrackId hintTrackId,
MP4Duration duration,
bool isSyncSample DEFAULT(true) );
/** @} ***********************************************************************/
#endif /* MP4V2_STREAMING_H */

615
third_party/include/mp4v2/track.h vendored Normal file
View File

@ -0,0 +1,615 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.com
* Kona Blend, kona8lend@gmail.com
*/
#ifndef MP4V2_TRACK_H
#define MP4V2_TRACK_H
/**************************************************************************//**
*
* @defgroup mp4_track MP4v2 Track
* @{
*
*****************************************************************************/
/** Add a user defined track.
*
* MP4AddTrack adds a user defined track to the mp4 file. Care should be
* taken to avoid any of the standardized track type names. A useful
* convention is use only uppercase characters for user defined track types.
* The string should be exactly four characters in length, e.g. "MINE".
*
* Note this should not be used to add any of the known track types defined
* in the MP4 standard (ISO/IEC 14496-1:2001).
*
* @param hFile handle of file for operation.
* @param type specifies the type of track to be added.
* @param timeScale the time scale in ticks per second of the track. Default is 1000.
*
* @return On success, the track-id of new track.
* On failure, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddTrack(
MP4FileHandle hFile,
const char* type,
uint32_t timeScale DEFAULT(MP4_MSECS_TIME_SCALE) );
/** Add an MPEG-4 systems track.
*
* MP4AddSystemsTrack adds an MPEG-4 Systems track to the mp4 file. Note
* this should not be used to add OD or scene tracks, MP4AddODTrack() and
* MP4AddSceneTrack() should be used for those purposes. Other known
* MPEG-4 System track types are:
*
* @li #MP4_CLOCK_TRACK_TYPE
* @li #MP4_MPEG7_TRACK_TYPE
* @li #MP4_OCI_TRACK_TYPE
* @li #MP4_IPMP_TRACK_TYPE
* @li #MP4_MPEGJ_TRACK_TYPE
*
* @param hFile handle of file for operation.
* @param type specifies the type of track to be added.
*
* @return On success, the track-id of new track.
* On failure, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddSystemsTrack(
MP4FileHandle hFile,
const char* type );
/** Add a object descriptor (OD) track.
*
* MP4AddODTrack adds an object descriptor (aka OD) track to the mp4 file.
* MP4WriteSample() can then be used to add the desired OD commands to the
* track. The burden is currently on the calling application to understand
* OD.
*
* Those wishing to have a simple audio/video scene without understanding
* OD may wish to use MP4MakeIsmaCompliant() to create the minimal OD and
* BIFS information.
*
* @param hFile handle of file for operation.
*
* @return On success, the track-id of new track.
* On failure, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddODTrack(
MP4FileHandle hFile );
/** Add a scene (BIFS) track.
*
* MP4AddSceneTrack adds a scene (aka BIFS) track to the mp4 file.
* MP4WriteSample() can then be used to add the desired BIFS commands to
* the track. The burden is currently on the calling application to
* understand BIFS.
*
* Those wishing to have a simple audio/video scene without understanding
* BIFS may wish to use MP4MakeIsmaCompliant() to create the minimal OD
* and BIFS information.
*
* @param hFile handle of file for operation.
*
* @return On success, the track-id of new track.
* On failure, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddSceneTrack(
MP4FileHandle hFile );
/** Add audio track to mp4 file.
*
* MP4AddAudioTrack adds an audio track to the mp4 file. MP4WriteSample()
* can then be used to add the desired audio samples.
*
* It is recommended that the time scale be set to the sampling frequency
* (e.g. 44100 Hz) of the audio so as to preserve the timing information
* accurately.
*
* If the audio encoding uses a fixed duration for each sample that should
* be specified here. If not then the value #MP4_INVALID_DURATION
* should be given for the sampleDuration argument.
*
* @param hFile handle of file for operation.
* @param timeScale the time scale in ticks per second of the track.
* @param sampleDuration the fixed duration for all track samples.
* Caveat: the value should be in track-timescale units.
* @param audioType the audio encoding type.
* See MP4GetTrackEsdsObjectTypeId() for known values.
*
* @return On success, the track-id of the new track.
* On error, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddAudioTrack(
MP4FileHandle hFile,
uint32_t timeScale,
MP4Duration sampleDuration,
uint8_t audioType DEFAULT(MP4_MPEG4_AUDIO_TYPE) );
/** Add ulaw track to mp4 file.
*
* MP4AddULawAudioTrack adds a ulaw track to the mp4 file. MP4WriteSample()
* can then be used to add the desired audio samples.
*
* @param hFile handle of file for operation.
* @param timeScale the time scale in ticks per second of the track.
*
* @return On success, the track-id of the new track.
* On error, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddULawAudioTrack(
MP4FileHandle hFile,
uint32_t timeScale);
/** Add alaw track to mp4 file.
*
* MP4AddALawAudioTrack adds a alaw track to the mp4 file. MP4WriteSample()
* can then be used to add the desired audio samples.
*
* @param hFile handle of file for operation.
* @param timeScale the time scale in ticks per second of the track.
*
* @return On success, the track-id of the new track.
* On error, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddALawAudioTrack(
MP4FileHandle hFile,
uint32_t timeScale);
MP4V2_EXPORT
MP4TrackId MP4AddAC3AudioTrack(
MP4FileHandle hFile,
uint32_t samplingRate,
uint8_t fscod,
uint8_t bsid,
uint8_t bsmod,
uint8_t acmod,
uint8_t lfeon,
uint8_t bit_rate_code );
MP4V2_EXPORT
MP4TrackId MP4AddAmrAudioTrack(
MP4FileHandle hFile,
uint32_t timeScale,
uint16_t modeSet,
uint8_t modeChangePeriod,
uint8_t framesPerSample,
bool isAmrWB );
MP4V2_EXPORT
void MP4SetAmrVendor(
MP4FileHandle hFile,
MP4TrackId trackId,
uint32_t vendor );
MP4V2_EXPORT
void MP4SetAmrDecoderVersion(
MP4FileHandle hFile,
MP4TrackId trackId,
uint8_t decoderVersion );
MP4V2_EXPORT
void MP4SetAmrModeSet(
MP4FileHandle hFile,
MP4TrackId trakId,
uint16_t modeSet );
MP4V2_EXPORT
uint16_t MP4GetAmrModeSet(
MP4FileHandle hFile,
MP4TrackId trackId );
MP4V2_EXPORT
MP4TrackId MP4AddHrefTrack(
MP4FileHandle hFile,
uint32_t timeScale,
MP4Duration sampleDuration,
const char* base_url DEFAULT(NULL) );
MP4V2_EXPORT
const char* MP4GetHrefTrackBaseUrl(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Add a video track.
*
* MP4AddVideoTrack adds a video track to the mp4 file. MP4WriteSample()
* can then be used to add the desired video samples.
*
* It is recommended that the time scale be set to 90000 so as to preserve
* the timing information accurately for the range of video frame rates
* commonly in use.
*
* If the video frame rate is to be fixed then the sampleDuration argument
* should be give the appropriate fixed value. If the video frame rate is
* to be variable then the value #MP4_INVALID_DURATION should be
* given for the sampleDuration argument.
*
* @param hFile handle of file for operation.
* @param timeScale the timescale in ticks per second of the track.
* @param sampleDuration specifies fixed sample duration for all track
* samples. Caveat: the value should be in track timescale units.
* @param width specifies the video frame width in pixels.
* @param height specifies the video frame height in pixels.
* @param videoType specifies the video encoding type.
* See MP4GetTrackVideoType() for known values.
*
* @return On success, the track-id of the new track.
* On error, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddVideoTrack(
MP4FileHandle hFile,
uint32_t timeScale,
MP4Duration sampleDuration,
uint16_t width,
uint16_t height,
uint8_t videoType DEFAULT(MP4_MPEG4_VIDEO_TYPE) );
MP4V2_EXPORT
MP4TrackId MP4AddH264VideoTrack(
MP4FileHandle hFile,
uint32_t timeScale,
MP4Duration sampleDuration,
uint16_t width,
uint16_t height,
uint8_t AVCProfileIndication,
uint8_t profile_compat,
uint8_t AVCLevelIndication,
uint8_t sampleLenFieldSizeMinusOne );
MP4V2_EXPORT
void MP4AddH264SequenceParameterSet(
MP4FileHandle hFile,
MP4TrackId trackId,
const uint8_t* pSequence,
uint16_t sequenceLen );
MP4V2_EXPORT
void MP4AddH264PictureParameterSet(
MP4FileHandle hFile,
MP4TrackId trackId,
const uint8_t* pPict,
uint16_t pictLen );
MP4V2_EXPORT
void MP4SetH263Vendor(
MP4FileHandle hFile,
MP4TrackId trackId,
uint32_t vendor );
MP4V2_EXPORT
void MP4SetH263DecoderVersion(
MP4FileHandle hFile,
MP4TrackId trackId,
uint8_t decoderVersion );
MP4V2_EXPORT
void MP4SetH263Bitrates(
MP4FileHandle hFile,
MP4TrackId trackId,
uint32_t avgBitrate,
uint32_t maxBitrate );
MP4V2_EXPORT
MP4TrackId MP4AddH263VideoTrack(
MP4FileHandle hFile,
uint32_t timeScale,
MP4Duration sampleDuration,
uint16_t width,
uint16_t height,
uint8_t h263Level,
uint8_t h263Profile,
uint32_t avgBitrate,
uint32_t maxBitrate );
/** Add a hint track.
*
* MP4AddHintTrack adds a hint track to the mp4 file. A hint track is used
* to describe how to send the reference media track over a particular
* network transport. In the case of the IETF RTP protocol, the hint track
* describes how the media data should be placed into packets and any
* media specific protocol headers that should be added.
*
* Typically there is a one to one correspondence between reference media
* track samples and hint track samples. The start time, duration, and
* sync flags are typically the same, however provisions are made for
* deviations from this rule.
*
* The MP4 library provides extensive support for RTP hint tracks. This
* includes a easy to use API to create RTP hint tracks, and read out
* fully constructed RTP packets based on the hint track.
*
* @param hFile handle of file for operation.
* @param refTrackId specifies the reference media track for this hint track.
*
* @return On success, the track-id of the new track.
* On error, #MP4_INVALID_TRACK_ID.
*/
MP4V2_EXPORT
MP4TrackId MP4AddHintTrack(
MP4FileHandle hFile,
MP4TrackId refTrackId );
MP4V2_EXPORT
MP4TrackId MP4AddTextTrack(
MP4FileHandle hFile,
MP4TrackId refTrackId );
MP4V2_EXPORT
MP4TrackId MP4AddSubtitleTrack(
MP4FileHandle hFile,
uint32_t timescale,
uint16_t width,
uint16_t height );
MP4V2_EXPORT
MP4TrackId MP4AddSubpicTrack(
MP4FileHandle hFile,
uint32_t timescale,
uint16_t width,
uint16_t height );
MP4V2_EXPORT
MP4TrackId MP4AddPixelAspectRatio(
MP4FileHandle hFile,
MP4TrackId refTrackId,
uint32_t hSpacing,
uint32_t vSpacing );
MP4V2_EXPORT
MP4TrackId MP4AddColr(
MP4FileHandle hFile,
MP4TrackId refTrackId,
uint16_t primary,
uint16_t transfer,
uint16_t matrix );
/** Make a clone of a specified track.
*
* MP4CloneTrack creates a new track to an mp4 file that is a copy of an
* existing track with respect to the track media type, and other control
* information.
*
* Note this function does not copy the media samples of the source track to
* the new track. If you want to do that use MP4CopyTrack() instead.
*
* @param srcFile specifies the mp4 file of the source track of the operation.
* @param srcTrackId specifies the track id of the track to be cloned.
* @param dstFile specifies the mp4 file of the new, cloned track. If the
* value is MP4_INVALID_FILE_HANDLE, the new track is created in the same
* file as the source track.
* @param dstHintTrackReferenceTrack specifies the track id of the reference
* track in the destination file when cloning a hint track.
*
* @return Upon success, the track id of the new track. Upon an error,
* MP4_INVALID_TRACK_ID.
*
* @see MP4CopyTrack()
*/
MP4V2_EXPORT
MP4TrackId MP4CloneTrack(
MP4FileHandle srcFile,
MP4TrackId srcTrackId,
MP4FileHandle dstFile DEFAULT(MP4_INVALID_FILE_HANDLE),
MP4TrackId dstHintTrackReferenceTrack DEFAULT(MP4_INVALID_TRACK_ID) );
/** Make a copy of a specified track.
*
* MP4CopyTrack creates a new track to an mp4 file that is a copy of an
* existing track with respect to the track media type, other control
* information, and media samples.
*
* The applyEdits parameter of this function allows for easy creation of
* standalone clips from a larger mp4 file. To do this use MP4AddTrackEdit()
* to specify the start and duration of the clip, and then use MP4CopyTrack()
* to export that portion of the media to a new mp4 file.
*
* Note if you do not want to copy the media samples, but just want to create
* a track with the same type and control information of the source track use
* MP4CloneTrack().
*
* @param srcFile specifies the mp4 file of the source track of the operation.
* @param srcTrackId specifies the track id of the track to be copied.
* @param dstFile specifies the mp4 file of the new, copied track. If the
* value is MP4_INVALID_FILE_HANDLE, the new track is created in the same
* file as the source track.
* @param applyEdits specifies if the track edit list is to be applied during
* the copying of media samples. If false, then all samples are copied, if
* true then only those samples included by the track edit list are
* copied.
* @param dstHintTrackReferenceTrack specifies the track id of the reference
* track in the destination file when cloning a hint track.
*
* @return Upon success, the track id of the new track. Upon an error,
* MP4_INVALID_TRACK_ID.
*
* @see MP4CloneTrack()
* @see MP4AddTrackEdit()
*/
MP4V2_EXPORT
MP4TrackId MP4CopyTrack(
MP4FileHandle srcFile,
MP4TrackId srcTrackId,
MP4FileHandle dstFile DEFAULT(MP4_INVALID_FILE_HANDLE),
bool applyEdits DEFAULT(false),
MP4TrackId dstHintTrackReferenceTrack DEFAULT(MP4_INVALID_TRACK_ID) );
/** Delete a track.
*
* MP4DeleteTrack deletes the control information associated with the
* specified track. The trackId will become invalid if this call succeeds.
*
* Note that the samples associated with this track are not deleted with this
* call. This can be accomplished via MP4Optimize(). The reason for this is
* that multiple tracks can reference the same samples so a global view must
* be taken when deleting them.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
*
* @return Upon success, true (1). Upon an error, false (0).
*/
MP4V2_EXPORT
bool MP4DeleteTrack(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the number of tracks.
*
* MP4GetNumberOfTracks returns how many tracks of the specified type and
* subtype exist in the mp4 file. This can be used to determine if an mp4 file
* contains a track of a given type of media, for instance audio or video. It
* can also be used to determine if multiple options may be available. For
* instance multiple audio tracks in different languages.
*
* For audio and video tracks, a subtype can be specified to only count tracks
* of a particular encoding.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param type specifies the type of track for which a count is desired. A
* NULL value implies any type of track. See MP4GetTrackType() for
* predefined values.
* @param subType specifies the subtype of the tracks to be counted. Subtypes
* are only defined for audio and video tracks, see
* MP4GetTrackEsdsObjectTypeId() for predefined values. A zero value
* implies any subtype.
*
* @return The number of tracks of the specified type and subType in the mp4
* file.
*/
MP4V2_EXPORT
uint32_t MP4GetNumberOfTracks(
MP4FileHandle hFile,
const char* type DEFAULT(NULL),
uint8_t subType DEFAULT(0) );
/** Find a track id.
*
* MP4FindTrackId gets the track id associated with the index'th track of the
* specified track type. For example, to get the track id of the first video
* track:
*
* @code
* MP4FindTrackId(hFile, 0, MP4_VIDEO_TRACK_TYPE);
* @endcode
*
* For audio and video tracks, a subtype can be specified to find a track of a
* particular encoding. For example, to get the track id of the first audio
* track encoded with MPEG-1 audio:
*
* @code
* MP4FindTrackId(hFile, 0, MP4_AUDIO_TRACK_TYPE, MP4_MPEG1_AUDIO_TYPE);
* @endcode
*
* Caveat: The track id's do not imply anything about the ordering of the
* track information within the mp4 file.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param index specifies which track is desired from matching tracks.
* @param type specifies the type of track to be matched. A NULL value implies
* any type of track. See MP4GetTrackType() for predefined values.
* @param subType specifies the subtype of the track to be matched. Subtypes
* are only defined for audio and video tracks, see
* MP4GetTrackEsdsObjectTypeId() for predefined values. A zero value
* implies any subtype.
*
* @return Upon success, the track index of the specified track. Upon an
* error, 0xFFFF.
*
* @see MP4FindTrackIndex()
*/
MP4V2_EXPORT
MP4TrackId MP4FindTrackId(
MP4FileHandle hFile,
uint16_t index,
const char* type DEFAULT(NULL),
uint8_t subType DEFAULT(0) );
/** Find a track index.
*
* MP4FindTrackIndex gets the index of the track with the specified track id.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the index is desired.
*
* @return Upon success, the track index of the specified track. Upon an
* error, 0xFFFF.
*
* @see MP4FindTrackId()
*/
MP4V2_EXPORT
uint16_t MP4FindTrackIndex(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get maximum duration of chunk.
*
* MP4GetTrackDurationPerChunk gets the maximum duration for each chunk.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param duration out value of duration in track timescale units.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4GetTrackDurationPerChunk(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4Duration* duration );
/** Set maximum duration of chunk.
*
* MP4SetTrackDurationPerChunk sets the maximum duration for each chunk.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param duration in timescale units.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4SetTrackDurationPerChunk(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4Duration duration );
/**
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4AddIPodUUID(
MP4FileHandle hFile,
MP4TrackId trackId );
/** @} ***********************************************************************/
#endif /* MP4V2_TRACK_H */

784
third_party/include/mp4v2/track_prop.h vendored Normal file
View File

@ -0,0 +1,784 @@
/*
* 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 MPEG4IP.
*
* The Initial Developer of the Original Code is Cisco Systems Inc.
* Portions created by Cisco Systems Inc. are
* Copyright (C) Cisco Systems Inc. 2001 - 2005. All Rights Reserved.
*
* Contributor(s):
* Dave Mackie, dmackie@cisco.com
* Alix Marchandise-Franquet, alix@cisco.com
* Bill May, wmay@cisco.com
* Kona Blend, kona8lend@gmail.com
* Robert Kausch, robert.kausch@freac.org
*/
#ifndef MP4V2_TRACK_PROP_H
#define MP4V2_TRACK_PROP_H
/**************************************************************************//**
*
* @defgroup mp4_track_prop MP4v2 Track Properties
* @{
*
*****************************************************************************/
/* specific track properties */
/** Get the track type.
*
* MP4GetTrackType gets the type of the track with the specified track id.
*
* Note: the library does not provide a MP4SetTrackType function, the
* track type needs to be specified when the track is created, e.g.
* MP4AddSystemsTrack(MP4_OCI_TRACK_TYPE).
*
* Known track types are:
*
* @li #MP4_OD_TRACK_TYPE
* @li #MP4_SCENE_TRACK_TYPE
* @li #MP4_AUDIO_TRACK_TYPE
* @li #MP4_VIDEO_TRACK_TYPE
* @li #MP4_HINT_TRACK_TYPE
* @li #MP4_CNTL_TRACK_TYPE
* @li #MP4_TEXT_TRACK_TYPE
* @li #MP4_CLOCK_TRACK_TYPE
* @li #MP4_MPEG7_TRACK_TYPE
* @li #MP4_OCI_TRACK_TYPE
* @li #MP4_IPMP_TRACK_TYPE
* @li #MP4_MPEGJ_TRACK_TYPE
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
*
* @return On success, a string indicating track type. On failure, NULL.
*/
MP4V2_EXPORT
const char* MP4GetTrackType(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the name of the track's media data atom.
*
* MP4GetTrackMediaDataName returns the four character name of the specified
* track's media data atom, i.e. the child atom of the track's @b stsd atom.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the media data atom name is
* desired.
*
* @return The name of the track's media data atom or NULL in case of an
* error.
*/
MP4V2_EXPORT
const char* MP4GetTrackMediaDataName(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the name of an encrypted track's original media data atom.
*
* MP4GetTrackMediaDataOriginalFormat is used to get the original media data
* atom name if a track has been encrypted. The track identified by @p trackId
* must be an encrypted track with @b encv as the media data name returned by
* MP4GetTrackMediaDataName.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the encoded track for which the original media
* data atom name is desired.
* @param originalFormat specifies a buffer to receive the original media data
atom name.
* @param buflen specifies the size of the buffer pointed to by @p
* originalFormat.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4GetTrackMediaDataOriginalFormat(
MP4FileHandle hFile,
MP4TrackId trackId,
char* originalFormat,
uint32_t buflen );
/** Get the duration of a track.
*
* MP4GetTrackDuration returns the total duration of all the samples in the
* specified track in the mp4 file.
*
* Caveat: The value is in units of the track time scale.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the duration is desired.
*
* @return The duration in track time scale units of the track in the mp4
* file.
*/
MP4V2_EXPORT
MP4Duration MP4GetTrackDuration(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the time scale of a track.
*
* MP4GetTrackTimeScale returns the time scale of the specified track in
* the mp4 file. The time scale determines the number of clock ticks per
* second for this track.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
*
* @return timescale (ticks per second) of the track in the mp4 file.
*/
MP4V2_EXPORT
uint32_t MP4GetTrackTimeScale(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Set the time scale of a track.
*
* MP4SetTrackTimeScale sets the time scale of the specified track in the
* mp4 file. The time scale determines the number of clock ticks per
* second for this track.
*
* Typically this value is set once when the track is created. However
* this call can be used to modify the value if that is desired. Since
* track sample durations are expressed in units of the track time scale,
* any change to the time scale value will effect the real time duration
* of the samples.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param value desired time scale for the track.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4SetTrackTimeScale(
MP4FileHandle hFile,
MP4TrackId trackId,
uint32_t value );
/** Get ISO-639-2/T language code of a track.
* The language code is a 3-char alpha code consisting of lower-case letters.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param code buffer to hold 3-char+null (4-bytes total).
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4GetTrackLanguage(
MP4FileHandle hFile,
MP4TrackId trackId,
char* code );
/** Set ISO-639-2/T language code of a track.
* The language code is a 3-char alpha code consisting of lower-case letters.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param code 3-char language code.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4SetTrackLanguage(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* code );
/** Get track name.
*
* MP4GetTrackName gets the name of the track via udta.name property.
*
* The memory to store the track name is allocated by the library, so the
* caller is responsible for freeing it with MP4Free().
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param name pointer to a variable to receive the track name.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4GetTrackName(
MP4FileHandle hFile,
MP4TrackId trackId,
char** name );
/** Set track name.
*
* MP4SetTrackName sets the name of the track via udta.name property.
* The udta atom is created if needed.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param name the name to set as the track name.
*
* @return <b>true</b> on success, <b>false</b> on failure.
*/
MP4V2_EXPORT
bool MP4SetTrackName(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* name );
/** Get the encoding type of an MPEG-4 audio track.
*
* MP4GetTrackAudioMpeg4Type returns the MPEG-4 encoding type of the specified
* MPEG-4 audio track in the mp4 file. If an mp4 audio track has type
* MP4_MPEG4_AUDIO_TYPE, this call can be used to determine which specific
* MPEG-4 audio encoding is contained in the track.
*
* Known MPEG-4 audio encoding types are:
*
* Type | Description
* ------------------------------------|--------------------------------------
* MP4_MPEG4_AAC_MAIN_AUDIO_TYPE | MPEG-4 AAC Main profile
* MP4_MPEG4_AAC_LC_AUDIO_TYPE | MPEG-4 AAC Low Complexity profile
* MP4_MPEG4_AAC_SSR_AUDIO_TYPE | MPEG-4 AAC SSR profile
* MP4_MPEG4_AAC_LTP_AUDIO_TYPE | MPEG-4 AAC Long Term Prediction profile
* MP4_MPEG4_AAC_SCALABLE_AUDIO_TYPE | MPEG-4 AAC Scalable
* MP4_MPEG4_CELP_AUDIO_TYPE | MPEG-4 CELP
* MP4_MPEG4_HVXC_AUDIO_TYPE | MPEG-4 HVXC
* MP4_MPEG4_TTSI_AUDIO_TYPE | MPEG-4 Text To Speech
* MP4_MPEG4_MAIN_SYNTHETIC_AUDIO_TYPE | MPEG-4 Main Synthetic profile
* MP4_MPEG4_WAVETABLE_AUDIO_TYPE | MPEG-4 Wavetable Synthesis profile
* MP4_MPEG4_MIDI_AUDIO_TYPE | MPEG-4 MIDI profile
* MP4_MPEG4_ALGORITHMIC_FX_AUDIO_TYPE | MPEG-4 Algorithmic Synthesis and Audio FX profile
*
* Note: This information is retrieved from the audio track ES configuration.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the MPEG-4 audio type is
* desired.
*
* @return Upon success, the MPEG-4 audio type of the track. Upon error,
* MP4_MPEG4_INVALID_AUDIO_TYPE is returned.
*
* @see MP4GetTrackAudioType()
*/
MP4V2_EXPORT
uint8_t MP4GetTrackAudioMpeg4Type(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the encoding object type id from a track's esds atom.
*
* MP4GetTrackEsdsObjectTypeId returns the encoding object type of the
* specified audio or video track in the mp4 file.
*
* Known audio object types are:
*
* Type | Description
* ------------------------------|--------------------------------------------
* MP4_MPEG1_AUDIO_TYPE | MPEG-1 Audio Layers I, II, & III
* MP4_MPEG2_AUDIO_TYPE | MPEG-2 low bitrate extensions to MPEG-1 Audio
* ^ | MP4_MP3_AUDIO_TYPE is an alias for this value
* MP4_MPEG2_AAC_MAIN_AUDIO_TYPE | MPEG-2 AAC Main profile
* MP4_MPEG2_AAC_LC_AUDIO_TYPE | MPEG-2 AAC Low Complexity profile
* MP4_MPEG2_AAC_SSR_AUDIO_TYPE | MPEG-2 AAC SSR profile
* MP4_MPEG4_AUDIO_TYPE | MPEG-4 Audio, includes MPEG-4 extensions to AAC
* MP4_PRIVATE_AUDIO_TYPE | User private type
*
* Known video object types are:
*
* Type | Description
* -----------------------------|---------------------------------------------
* MP4_MPEG1_VIDEO_TYPE | MPEG-1 Video
* MP4_MPEG2_SIMPLE_VIDEO_TYPE | MPEG-2 Simple Profile Video
* MP4_MPEG2_MAIN_VIDEO_TYPE | MPEG-2 Main Profile Video (Broadcast/DVD)
* MP4_MPEG2_SNR_VIDEO_TYPE | MPEG-2 SNR Profile Video
* MP4_MPEG2_SPATIAL_VIDEO_TYPE | MPEG-2 Spatial Scalability Profile Video
* MP4_MPEG2_HIGH_VIDEO_TYPE | MPEG-2 High Profile Video (HDTV)
* MP4_MPEG2_442_VIDEO_TYPE | MPEG-2 442 Profile Video (Studio)
* MP4_MPEG4_VIDEO_TYPE | MPEG-4 Video
* MP4_JPEG_VIDEO_TYPE | JPEG stills or motion JPEG
* MP4_PRIVATE_VIDEO_TYPE | User private type
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the encoding object type is
* desired.
*
* @return Upon success, the encoding object type of the track. Upon error,
* MP4_INVALID_AUDIO_TYPE is returned.
*/
MP4V2_EXPORT
uint8_t MP4GetTrackEsdsObjectTypeId(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the fixed duration of samples in a track.
*
* MP4GetTrackFixedSampleDuration returns the duration of samples in the
* specified track in the mp4 file, if this value is fixed for all samples.
* This is typically the case for audio tracks and video tracks. If the track
* samples have variable duration, then MP4_INVALID_DURATION is returned.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track to which the operation applies.
*
* @return Upon success, the number of fixed duration of the samples in the
* track in track time scale units. Upon an error, MP4_INVALID_DURATION.
*/
MP4V2_EXPORT
MP4Duration MP4GetTrackFixedSampleDuration(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the average bit rate in bits per second of the specified track.
*
* MP4GetTrackBitRate returns the average bit rate in bits per second in the
* specified track in the mp4 file.
*
* Note: hint tracks will not return their bit rate via this mechanism.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the bit rate is desired.
*
* @return Upon success, the average bit rate in bits per second of the track.
* Upon an error, 0.
*/
MP4V2_EXPORT
uint32_t MP4GetTrackBitRate(
MP4FileHandle hFile,
MP4TrackId trackId );
MP4V2_EXPORT
bool MP4GetTrackVideoMetadata(
MP4FileHandle hFile,
MP4TrackId trackId,
uint8_t** ppConfig,
uint32_t* pConfigSize );
/** Get the elementary stream (ES) configuration of a track.
*
* MP4GetTrackESConfiguration returns the elementary stream (ES) configuration
* of the specified track in the mp4 file. This information is codec specific
* and contains the configuration necessary for the given codec to decode the
* samples in the track.
*
* Caveat: the returned block of memory has been allocated by the library. The
* caller may safely modify the value without effecting the library, but the
* caller takes responsiblity for freeing the memory with MP4Free().
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the ES configuration is
* desired.
* @param ppConfig specifies a pointer to a pointer variable that will be
* given the address of the configuration information.
* @param pConfigSize specifies a pointer to a variable to hold the size of
* the ES configuration information.
*
* @return Upon success, *ppConfig will point to a newly allocated block of
* memory with the ES configuration, and *pConfigSize will indicated the
* number of bytes of the ES configuration. Upon error, *ppConfig will be
* NULL, and *pConfigSize will be 0.
*
* @see MP4SetTrackESConfiguration()
*/
MP4V2_EXPORT
bool MP4GetTrackESConfiguration(
MP4FileHandle hFile,
MP4TrackId trackId,
uint8_t** ppConfig,
uint32_t* pConfigSize );
/** Set the elementary stream (ES) configuration of a track.
*
* MP4SetTrackESConfiguration sets the elementary stream (ES) configuration of
* the specified track in the mp4 file. This information is codec specific and
* contains the configuration necessary for the given codec to decode the
* samples in the track.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId the track to which the operation applies.
* @param pConfig specifies a pointer to the ES configuration information.
* @param configSize specifies the size of the ES configuration information.
*
* @return Upon success, true (1). Upon an error, false (0).
*
* @see MP4GetTrackESConfiguration()
*/
MP4V2_EXPORT
bool MP4SetTrackESConfiguration(
MP4FileHandle hFile,
MP4TrackId trackId,
const uint8_t* pConfig,
uint32_t configSize );
/* h264 information routines */
MP4V2_EXPORT
bool MP4GetTrackH264ProfileLevel(
MP4FileHandle hFile,
MP4TrackId trackId,
uint8_t* pProfile,
uint8_t* pLevel );
MP4V2_EXPORT
bool MP4GetTrackH264SeqPictHeaders(
MP4FileHandle hFile,
MP4TrackId trackId,
uint8_t*** pSeqHeaders,
uint32_t** pSeqHeaderSize,
uint8_t*** pPictHeader,
uint32_t** pPictHeaderSize );
/** Frees the memory allocated by MP4GetTrackH264SeqPictHeaders.
*
* MP4FreeH264SeqPictHeaders frees the memory that was allocated by a
* call to the MP4GetTrackH264SeqPictHeaders function.
*
* When a client application wants to extract the H.264 video data from
* an MP4 file it will call MP4GetTrackH264SeqPictHeaders to obtain the
* sequence and picture parameter sets. These parameter sets are
* required for decoding a sequence of one, or more, coded slices. When
* the client application is done with the data it must free it. On the
* Windows platform this cannot be done directly by the client
* application because the C runtime of the client application and the C
* runtime of the mp4v2 DLL may be different, which will result in an
* error at runtime. This function allows the client application to let
* the mp4v2 DLL free the memory with the appropriate CRT heap manager.
*
* @param pSeqHeaders pointer to an array of SPS pointers.
* @param pSeqHeaderSize pointer to array of SPS sizes.
* @param pPictHeader pointer to an array of PPS pointers.
* @param pPictHeaderSize pointer to array of PPS sizes.
*/
MP4V2_EXPORT
void MP4FreeH264SeqPictHeaders(
uint8_t** pSeqHeaders,
uint32_t* pSeqHeaderSize,
uint8_t** pPictHeader,
uint32_t* pPictHeaderSize );
MP4V2_EXPORT
bool MP4GetTrackH264LengthSize(
MP4FileHandle hFile,
MP4TrackId trackId,
uint32_t* pLength );
/** Get the number of samples in a track.
*
* MP4GetTrackNumberOfSamples returns the number of samples in the specified
* track in the mp4 file. Sample id's are the consecutive sequence of numbers
* from 1 to the total number of samples, i.e. 1-based indexing, not 0-based
* indexing.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the number of samples is
* desired.
*
* @return Upon success, the number of samples in the track. Upon an error, 0.
*/
MP4V2_EXPORT
MP4SampleId MP4GetTrackNumberOfSamples(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the video width in pixels of the specified video track.
*
* MP4GetTrackVideoWidth returns the width of the video in pixels in the
* specified track in the mp4 file.
*
* Caveat: Not all mp4 implementations set this value accurately. The mp4
* specification states that the authoritative values are contained in the
* track ES configuration which is video encoding specific, and hence not
* interpretable by the mp4 library.
*
* If the value of 320 is returned, care should be taken to verify the
* accuracy of this value since this is the default value in the mp4
* specification.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the video width is desired.
*
* @return Upon success, the number of pixels of the video width in the
* track. Upon an error, 0.
*
* @see MP4GetTrackVideoHeight()
* @see MP4GetTrackESConfiguration()
*/
MP4V2_EXPORT
uint16_t MP4GetTrackVideoWidth(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the video height in pixels of the specified video track.
*
* MP4GetTrackVideoHeight returns the height of the video in pixels in the
* specified track in the mp4 file.
*
* Caveat: Not all mp4 implementations set this value accurately. The mp4
* specification states that the authoritative values are contained in the
* track ES configuration which is video encoding specific, and hence not
* interpretable by the mp4 library.
*
* If the value of 240 is returned, care should be taken to verify the
* accuracy of this value since this is the default value in the mp4
* specification.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the video height is desired.
*
* @return Upon success, the number of pixels of the video height in the
* track. Upon an error, 0.
*
* @see MP4GetTrackVideoWidth()
* @see MP4GetTrackESConfiguration()
*/
MP4V2_EXPORT
uint16_t MP4GetTrackVideoHeight(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the video frame rate of the specified video track.
*
* MP4GetTrackVideoFrameRate returns the frame rate of the video in the
* specified track in the mp4 file. If the video is variable rate, the average
* frame rate is returned.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the video frame rate is
* desired.
*
* @return Upon success, the number of video frames per second of the track.
* Upon an error, 0.
*/
MP4V2_EXPORT
double MP4GetTrackVideoFrameRate(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Get the number of channels of the specified audio track.
*
* MP4GetTrackAudioChannels returns the number of audio channels in the
* specified track in the mp4 file.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the number of audio channels
* is desired.
*
* @return Upon success, the number of audio channels of the track. Upon an
* error, -1.
*/
MP4V2_EXPORT
int MP4GetTrackAudioChannels(
MP4FileHandle hFile,
MP4TrackId trackId );
/** Check whether a track is ISMACrypt encrypted.
*
* MP4IsIsmaCrypMediaTrack checks whether the specified track is encrypted
* using ISMACrypt.
*
* @param hFile specifies the mp4 file to which the operation applies.
* @param trackId specifies the track for which the information is desired.
*
* @return true (1) if the track is ISMACrypt encrypted, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4IsIsmaCrypMediaTrack(
MP4FileHandle hFile,
MP4TrackId trackId );
/* generic track properties */
/** Check for presence of a track atom.
*
* MP4HaveTrackAtom checks for the presence of the track atom passed in @p
* atomName. @p atomName can specify an atom path to check for atoms that are
* not direct children of the @b trak atom, e.g. "mdia.minf.stbl".
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param atomName name of the atom to check for.
*
* @return true (1) if the atom is present, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4HaveTrackAtom(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* atomName );
/** Get the value of an integer property for a track.
*
* MP4GetTrackIntegerProperty determines the value of the integer property
* identified by @p propName, e.g. "tkhd.layer", for the track identified by
* @p trackId. The value is stored in the variable pointed to by @p retVal.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param propName path to the property to get.
* @param retVal pointer to a variable to receive the return value.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4GetTrackIntegerProperty(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* propName,
uint64_t* retVal );
/** Get the value of a float property for a track.
*
* MP4GetTrackFloatProperty determines the value of the float property
* identified by @p propName, e.g. "tkhd.volume", for the track identified by
* @p trackId. The value is stored in the variable pointed to by @p retVal.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param propName path to the property to get.
* @param retVal pointer to a variable to receive the return value.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4GetTrackFloatProperty(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* propName,
float* retVal );
/** Get the value of a string property for a track.
*
* MP4GetTrackStringProperty determines the value of the string property
* identified by @p propName, e.g. "udta.hnti.sdp .sdpText", for the track
* identified by @p trackId. The value is stored in the variable pointed to by
* @p retVal.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param propName path to the property to get.
* @param retVal pointer to a variable to receive the return value.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4GetTrackStringProperty(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* propName,
const char** retVal );
/** Get the value of a bytes property for a track.
*
* MP4GetTrackBytesProperty determines the value of the bytes property
* identified by @p propName, e.g. "tkhd.matrix", for the track identified by
* @p trackId. The value is stored in a newly allocated buffer the location of
* which is assigned to the variable pointed to by ppValue. The caller is
* responsible for freeing the memory with MP4Free().
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param propName path to the property to get.
* @param ppValue pointer to a variable to receive the memory location
* containing the property bytes.
* @param pValueSize pointer to a variable to receive the length of the
* property bytes value.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4GetTrackBytesProperty(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* propName,
uint8_t** ppValue,
uint32_t* pValueSize );
/** Set the value of an integer property for a track.
*
* MP4SetTrackIntegerProperty sets the value of the integer property
* identified by @p propName, e.g. "tkhd.layer", for the track identified by
* @p trackId.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param propName path to the property to set.
* @param value the new value of the property.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4SetTrackIntegerProperty(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* propName,
int64_t value );
/** Set the value of a float property for a track.
*
* MP4SetTrackFloatProperty sets the value of the float property identified by
* @p propName, e.g. "tkhd.volume", for the track identified by @p trackId.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param propName path to the property to set.
* @param value the new value of the property.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4SetTrackFloatProperty(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* propName,
float value );
/** Set the value of a string property for a track.
*
* MP4SetTrackStringProperty sets the value of the string property identified
* by @p propName, e.g. "udta.hnti.sdp .sdpText", for the track identified by
* @p trackId.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param propName path to the property to set.
* @param value the new value of the property.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4SetTrackStringProperty(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* propName,
const char* value );
/** Set the value of a bytes property for a track.
*
* MP4SetTrackBytesProperty sets the value of the bytes property identified by
* @p propName, e.g. "tkhd.matrix", for the track identified by @p trackId.
*
* @param hFile handle of file for operation.
* @param trackId id of track for operation.
* @param propName path to the property to set.
* @param pValue pointer the bytes representing the new value of the property.
* @param valueSize the size of the bytes value pointed to by <b>pValue</b>.
*
* @return true (1) on success, false (0) otherwise.
*/
MP4V2_EXPORT
bool MP4SetTrackBytesProperty(
MP4FileHandle hFile,
MP4TrackId trackId,
const char* propName,
const uint8_t* pValue,
uint32_t valueSize);
/** @} ***********************************************************************/
#endif /* MP4V2_TRACK_PROP_H */

BIN
third_party/lib/libmp4v2.a vendored Normal file
View File

Binary file not shown.

BIN
third_party/lib/libutil.a vendored Normal file
View File

Binary file not shown.