Classes | |
struct | MP4FileProvider_s |
Structure of functions implementing custom file provider. 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. | |
#define | MP4_CLOSE_DO_NOT_COMPUTE_BITRATE 0x01 |
Bit: do not recompute avg/max bitrates on file close. | |
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. | |
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. | |
MP4FileHandle | MP4Create (const char *fileName, uint32_t flags=0) |
Create a new mp4 file. | |
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. | |
MP4FileHandle | MP4CreateProvider (const char *fileName, uint32_t flags=0, const MP4FileProvider *fileProvider=NULL) |
Create a new mp4 file. | |
MP4FileHandle | MP4CreateProviderEx (const char *fileName, uint32_t flags=0, const MP4FileProvider *fileProvider=NULL, 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. | |
bool | MP4Dump (MP4FileHandle hFile, bool dumpImplicits=0) |
Dump mp4 file contents as ASCII either to stdout or the log callback (see MP4SetLogCallback) | |
char * | MP4FileInfo (const char *fileName, MP4TrackId trackId=MP4_INVALID_TRACK_ID) |
Return a textual summary of an mp4 file. | |
const char * | MP4GetFilename (MP4FileHandle hFile) |
Accessor for the filename associated with a file handle. | |
char * | MP4Info (MP4FileHandle hFile, MP4TrackId trackId=MP4_INVALID_TRACK_ID) |
Return a textual summary of an mp4 file. | |
MP4FileHandle | MP4Modify (const char *fileName, uint32_t flags=0) |
Modify an existing mp4 file. | |
bool | MP4Optimize (const char *fileName, const char *newFileName=NULL) |
Optimize the layout of an mp4 file. | |
MP4FileHandle | MP4Read (const char *fileName) |
Read an existing mp4 file. | |
MP4FileHandle | MP4ReadProvider (const char *fileName, const MP4FileProvider *fileProvider=NULL) |
Read an existing mp4 file. | |
#define MP4_CLOSE_DO_NOT_COMPUTE_BITRATE 0x01 |
Bit: do not recompute avg/max bitrates on file close.
#define MP4_CREATE_64BIT_TIME 0x02 |
Bit: enable 64-bit time-atoms.
typedef struct MP4FileProvider_s MP4FileProvider |
Structure of functions implementing custom file provider.
Except for open, all the functions must return a true value to indicate failure or false on success. The open function must return a pointer or handle which represents the open file, otherwise NULL.
maxChunkSize is a hint suggesting what the max size of data should be read as in underlying read/write operations. A value of 0 indicates there is no hint.
enum MP4FileMode_e |
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.
hFile | handle of file to close. |
flags | bitmask that allows the user to set extra options for the close commands. Valid options include: |
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 also involved with creation of necessary mp4 framework structures. ie. invoking MP4Create() followed by MP4Close() will result in a file with a non-zero size.
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: |
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().
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: |
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. |
MP4FileHandle MP4CreateProvider | ( | const char * | fileName, |
uint32_t | flags = 0, | ||
const MP4FileProvider * | fileProvider = NULL ) |
Create a new mp4 file.
MP4CreateProvider 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 also involved with creation of necessary mp4 framework structures. ie. invoking MP4CreateProvider() followed by MP4Close() will result in a file with a non-zero size.
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: |
fileProvider | custom implementation of file I/O operations. All functions in structure must be implemented. The structure is immediately copied internally. |
MP4FileHandle MP4CreateProviderEx | ( | const char * | fileName, |
uint32_t | flags = 0, | ||
const MP4FileProvider * | fileProvider = NULL, | ||
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.
MP4CreateProviderEx is an extended version of MP4CreateProvider().
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: |
fileProvider | custom implementation of file I/O operations. All functions in structure must be implemented. The structure is immediately copied internally. |
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. |
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.
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. ie. they are implicit given the current values of other controlling properties. |
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 malloc'ed, so it is the caller's responsibility to free() the string. 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
@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 malloc'd string containing summary information. On failure, <b>NULL</b>. @see MP4Info().
const char * MP4GetFilename | ( | MP4FileHandle | hFile | ) |
Accessor for the filename associated with a file handle.
hFile | a file handle |
hFile
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 malloc'ed, so it is the caller's responsibility to free() the string. 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
@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 malloc'd string containing summary information. On failure, <b>NULL</b>. @see MP4FileInfo().
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.
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. |
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.
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. |
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.
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). ( |
MP4FileHandle MP4ReadProvider | ( | const char * | fileName, |
const MP4FileProvider * | fileProvider = NULL ) |
Read an existing mp4 file.
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.
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. |