Classes
struct	MP4FileProvider_s
	Structure of functions implementing custom file provider. More...

struct	MP4IOCallbacks_s
	Structure of functions implementing custom I/O callbacks. More...

Macros
#define	MP4_CREATE_64BIT_DATA 0x01
	Bit: enable 64-bit data-atoms.

#define	MP4_CREATE_64BIT_TIME 0x02
	Bit: enable 64-bit time-atoms. More...

#define	MP4_CLOSE_DO_NOT_COMPUTE_BITRATE 0x01
	Bit: do not recompute avg/max bitrates on file close. More...

Typedefs
typedef enum MP4FileMode_e	MP4FileMode
	Enumeration of file modes for custom file provider.

typedef struct MP4FileProvider_s	MP4FileProvider
	Structure of functions implementing custom file provider. More...

typedef struct MP4IOCallbacks_s	MP4IOCallbacks
	Structure of functions implementing custom I/O callbacks. More...

Enumerations
enum	MP4FileMode_e { FILEMODE_UNDEFINED, FILEMODE_READ, FILEMODE_MODIFY, FILEMODE_CREATE }
	Enumeration of file modes for custom file provider. More...

Functions
void	MP4Close (MP4FileHandle hFile, uint32_t flags=0)
	Close an mp4 file. More...

MP4FileHandle	MP4Create (const char *fileName, uint32_t flags=0)
	Create a new mp4 file. More...

MP4FileHandle	MP4CreateEx (const char fileName, uint32_t flags=0, int add_ftyp=1, int add_iods=1, char majorBrand=0, uint32_t minorVersion=0, char **compatibleBrands=0, uint32_t compatibleBrandsCount=0)
	Create a new mp4 file with extended options. More...

MP4FileHandle	MP4CreateCallbacks (const MP4IOCallbacks callbacks, void handle=NULL, uint32_t flags=0)
	Create a new mp4 file using an I/O callbacks structure. More...

MP4FileHandle	MP4CreateCallbacksEx (const MP4IOCallbacks callbacks, void handle=NULL, uint32_t flags=0, int add_ftyp=1, int add_iods=1, char majorBrand=0, uint32_t minorVersion=0, char *compatibleBrands=0, uint32_t compatibleBrandsCount=0)
	Create a new mp4 file with extended options using an I/O callbacks structure. More...

bool	MP4Dump (MP4FileHandle hFile, bool dumpImplicits=0)
	Dump mp4 file contents as ASCII either to stdout or the log callback (see MP4SetLogCallback()) More...

char *	MP4FileInfo (const char *fileName, MP4TrackId trackId=MP4_INVALID_TRACK_ID)
	Return a textual summary of an mp4 file. More...

const char *	MP4GetFilename (MP4FileHandle hFile)
	Accessor for the filename associated with a file handle. More...

char *	MP4Info (MP4FileHandle hFile, MP4TrackId trackId=MP4_INVALID_TRACK_ID)
	Return a textual summary of an mp4 file. More...

MP4FileHandle	MP4Modify (const char *fileName, uint32_t flags=0)
	Modify an existing mp4 file. More...

MP4FileHandle	MP4ModifyCallbacks (const MP4IOCallbacks callbacks, void handle=NULL, uint32_t flags=0)
	Modify an existing mp4 file using an I/O callbacks structure. More...

bool	MP4Optimize (const char fileName, const char newFileName=NULL)
	Optimize the layout of an mp4 file. More...

MP4FileHandle	MP4Read (const char *fileName)
	Read an existing mp4 file. More...

MP4FileHandle	MP4ReadProvider (const char fileName, const MP4FileProvider fileProvider=NULL)
	Read an existing mp4 file. More...

MP4FileHandle	MP4ReadCallbacks (const MP4IOCallbacks callbacks, void handle=NULL)
	Read an existing mp4 file using an I/O callbacks structure. More...

Detailed Description

Macro Definition Documentation

◆ MP4_CLOSE_DO_NOT_COMPUTE_BITRATE

#define MP4_CLOSE_DO_NOT_COMPUTE_BITRATE 0x01

Bit: do not recompute avg/max bitrates on file close.

Note: See http://code.google.com/p/mp4v2/issues/detail?id=66

◆ MP4_CREATE_64BIT_TIME

#define MP4_CREATE_64BIT_TIME 0x02

Bit: enable 64-bit time-atoms.

Note: Incompatible with QuickTime.

Typedef Documentation

◆ MP4FileProvider

typedef struct MP4FileProvider_s MP4FileProvider

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 open, 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 also: MP4IOCallbacks

◆ MP4IOCallbacks

typedef struct MP4IOCallbacks_s MP4IOCallbacks

Structure of functions implementing custom I/O callbacks.

Except for size, 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 also: MP4CreateCallbacks(); MP4ModifyCallbacks(); MP4ReadCallbacks()

Enumeration Type Documentation

◆ MP4FileMode_e

enum MP4FileMode_e

Enumeration of file modes for custom file provider.

Enumerator
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

Function Documentation

◆ MP4Close()

void MP4Close	(	MP4FileHandle	hFile,
		uint32_t	flags = `0`
	)

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.

Parameters

hFile	handle of file to close.
flags	bitmask that allows the user to set extra options for the close commands. Valid options include: MP4_CLOSE_DO_NOT_COMPUTE_BITRATE

Examples: example/callbacks/callbacks.c, example/itmf/generic.c, and example/itmf/tags.c.

◆ MP4Create()

MP4FileHandle MP4Create	(	const char *	fileName,
		uint32_t	flags = `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.

Parameters

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).
flags	bitmask that allows the user to set 64-bit values for data or time atoms. Valid bits may be any combination of: MP4_CREATE_64BIT_DATA MP4_CREATE_64BIT_TIME

Returns: On success a handle of the newly created file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

See also: MP4CreateEx()

◆ MP4CreateCallbacks()

MP4FileHandle MP4CreateCallbacks	(	const MP4IOCallbacks *	callbacks,
		void *	handle = `NULL`,
		uint32_t	flags = `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.

Parameters

callbacks	custom implementation of I/O operations. The size, seek and write callbacks must be implemented. The callbacks structure is immediately copied internally.
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.
flags	bitmask that allows the user to set 64-bit values for data or time atoms. Valid bits may be any combination of: MP4_CREATE_64BIT_DATA MP4_CREATE_64BIT_TIME

Returns: On success a handle of the newly created file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

See also: MP4CreateCallbacksEx()

◆ MP4CreateCallbacksEx()

MP4FileHandle MP4CreateCallbacksEx	(	const MP4IOCallbacks *	callbacks,
		void *	handle = `NULL`,
		uint32_t	flags = `0`,
		int	add_ftyp = `1`,
		int	add_iods = `1`,
		char *	majorBrand = `0`,
		uint32_t	minorVersion = `0`,
		char **	compatibleBrands = `0`,
		uint32_t	compatibleBrandsCount = `0`
	)

Create a new mp4 file with extended options using an I/O callbacks structure.

MP4CreateCallbacksEx is an extended version of MP4CreateCallbacks().

Parameters

callbacks	custom implementation of I/O operations. The size, seek and write callbacks must be implemented. The callbacks structure is immediately copied internally.
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.
flags	bitmask that allows the user to set 64-bit values for data or time atoms. Valid bits may be any combination of: MP4_CREATE_64BIT_DATA MP4_CREATE_64BIT_TIME
add_ftyp	if true an ftyp atom is automatically created.
add_iods	if true an iods atom is automatically created.
majorBrand	ftyp brand identifier.
minorVersion	ftyp informative integer for the minor version of the major brand.
compatibleBrands	ftyp list of compatible brands.
compatibleBrandsCount	is the count of items specified in compatibleBrands.

Returns: On success a handle of the newly created file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

See also: MP4CreateCallbacks()

◆ MP4CreateEx()

MP4FileHandle MP4CreateEx	(	const char *	fileName,
		uint32_t	flags = `0`,
		int	add_ftyp = `1`,
		int	add_iods = `1`,
		char *	majorBrand = `0`,
		uint32_t	minorVersion = `0`,
		char **	compatibleBrands = `0`,
		uint32_t	compatibleBrandsCount = `0`
	)

Create a new mp4 file with extended options.

MP4CreateEx is an extended version of MP4Create().

Parameters

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).
flags	bitmask that allows the user to set 64-bit values for data or time atoms. Valid bits may be any combination of: MP4_CREATE_64BIT_DATA MP4_CREATE_64BIT_TIME
add_ftyp	if true an ftyp atom is automatically created.
add_iods	if true an iods atom is automatically created.
majorBrand	ftyp brand identifier.
minorVersion	ftyp informative integer for the minor version of the major brand.
compatibleBrands	ftyp list of compatible brands.
compatibleBrandsCount	is the count of items specified in compatibleBrands.

Returns: On success a handle of the newly created file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

See also: MP4Create()

◆ MP4Dump()

bool MP4Dump	(	MP4FileHandle	hFile,
		bool	dumpImplicits = `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 MP4_LOG_VERBOSE2. See MP4LogSetLevel() for how to set this.

Parameters

hFile	handle of file to dump.
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.

Returns: true on success, false on failure.

Examples: example/callbacks/callbacks.c.

◆ MP4FileInfo()

char* MP4FileInfo	(	const char *	fileName,
		MP4TrackId	trackId = `MP4_INVALID_TRACK_ID`
	)

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():

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

Parameters

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).
trackId	specifies track to summarize. If the value is MP4_INVALID_TRACK_ID, the summary info is created for all tracks in the file.

Returns: On success a newly allocated string containing summary information. On failure, NULL.

See also: MP4Info()

◆ MP4GetFilename()

const char* MP4GetFilename ( MP4FileHandle hFile )

Accessor for the filename associated with a file handle.

Parameters

hFile a file handle

Returns: the NUL-terminated, UTF-8 encoded filename associated with hFile.

◆ MP4Info()

char* MP4Info	(	MP4FileHandle	hFile,
		MP4TrackId	trackId = `MP4_INVALID_TRACK_ID`
	)

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():

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

Parameters

hFile	handle of file to summarize.
trackId	specifies track to summarize. If the value is MP4_INVALID_TRACK_ID, the summary info is created for all tracks in the file.

Returns: On success a newly allocated string containing summary information. On failure, NULL.

See also: MP4FileInfo()

◆ MP4Modify()

MP4FileHandle MP4Modify	(	const char *	fileName,
		uint32_t	flags = `0`
	)

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.

Parameters

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).
flags	currently ignored.

Returns: On success a handle of the target file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

Examples: example/itmf/generic.c, and example/itmf/tags.c.

◆ MP4ModifyCallbacks()

MP4FileHandle MP4ModifyCallbacks	(	const MP4IOCallbacks *	callbacks,
		void *	handle = `NULL`,
		uint32_t	flags = `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.

Parameters

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.
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.
flags	currently ignored.

Returns: On success a handle of the target file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

◆ MP4Optimize()

bool MP4Optimize	(	const char *	fileName,
		const char *	newFileName = `NULL`
	)

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.

Parameters

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).
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 fileName will be used and fileName will be over-written upon successful completion.

Returns: true on success, false on failure.

◆ MP4Read()

MP4FileHandle MP4Read ( const char * fileName )

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.

Parameters

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).

Returns: On success a handle of the file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

◆ MP4ReadCallbacks()

MP4FileHandle MP4ReadCallbacks	(	const MP4IOCallbacks *	callbacks,
		void *	handle = `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.

Parameters

callbacks	custom implementation of I/O operations. The size, seek and read callbacks must be implemented. The callbacks structure is immediately copied internally.
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.

Returns: On success a handle of the file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

Examples: example/callbacks/callbacks.c.

◆ MP4ReadProvider()

MP4FileHandle MP4ReadProvider	(	const char *	fileName,
		const MP4FileProvider *	fileProvider = `NULL`
	)

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.

Parameters

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).
fileProvider	custom implementation of file I/O operations. All functions in structure must be implemented. The structure is immediately copied internally.

Returns: On success a handle of the file for use in subsequent calls to the library. On error, MP4_INVALID_FILE_HANDLE.

See also: MP4ReadCallbacks()

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MP4_CLOSE_DO_NOT_COMPUTE_BITRATE

◆ MP4_CREATE_64BIT_TIME

Typedef Documentation

◆ MP4FileProvider

◆ MP4IOCallbacks

Enumeration Type Documentation

◆ MP4FileMode_e

Function Documentation

◆ MP4Close()

◆ MP4Create()

◆ MP4CreateCallbacks()

◆ MP4CreateCallbacksEx()

◆ MP4CreateEx()

◆ MP4Dump()

◆ MP4FileInfo()

◆ MP4GetFilename()

◆ MP4Info()

◆ MP4Modify()

◆ MP4ModifyCallbacks()

◆ MP4Optimize()

◆ MP4Read()

◆ MP4ReadCallbacks()

◆ MP4ReadProvider()