MP4v2

Classes | Macros | Typedefs | Enumerations | Functions
MP4v2 File I/O

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