Typedefs
typedef enum MP4SampleDependencyType_e	MP4SampleDependencyType
	Sample dependency types. More...

Enumerations
enum	MP4SampleDependencyType_e { MP4_SDT_UNKNOWN = 0x00, MP4_SDT_HAS_REDUNDANT_CODING = 0x01, MP4_SDT_HAS_NO_REDUNDANT_CODING = 0x02, MP4_SDT_HAS_DEPENDENTS = 0x04, MP4_SDT_HAS_NO_DEPENDENTS = 0x08, MP4_SDT_IS_DEPENDENT = 0x10, MP4_SDT_IS_INDEPENDENT = 0x20, MP4_SDT_EARLIER_DISPLAY_TIMES_ALLOWED = 0x40, _MP4_SDT_RESERVED = 0x80 }
	Sample dependency types. More...

Functions
bool	MP4ReadSample (MP4FileHandle hFile, MP4TrackId trackId, MP4SampleId sampleId, uint8_t *ppBytes, uint32_t pNumBytes, MP4Timestamp pStartTime=NULL, MP4Duration pDuration=NULL, MP4Duration pRenderingOffset=NULL, bool pIsSyncSample=NULL)
	Read a track sample. More...

bool	MP4ReadSampleFromTime (MP4FileHandle hFile, MP4TrackId trackId, MP4Timestamp when, uint8_t *ppBytes, uint32_t pNumBytes, MP4Timestamp pStartTime=NULL, MP4Duration pDuration=NULL, MP4Duration pRenderingOffset=NULL, bool pIsSyncSample=NULL)
	Read a track sample based on a specified time. More...

bool	MP4WriteSample (MP4FileHandle hFile, MP4TrackId trackId, const uint8_t *pBytes, uint32_t numBytes, MP4Duration duration=MP4_INVALID_DURATION, MP4Duration renderingOffset=0, bool isSyncSample=true)
	Write a track sample. More...

bool	MP4WriteSampleDependency (MP4FileHandle hFile, MP4TrackId trackId, const uint8_t *pBytes, uint32_t numBytes, MP4Duration duration, MP4Duration renderingOffset, bool isSyncSample, uint32_t dependencyFlags)
	Write a track sample and supply dependency information. More...

bool	MP4CopySample (MP4FileHandle srcFile, MP4TrackId srcTrackId, MP4SampleId srcSampleId, MP4FileHandle dstFile=MP4_INVALID_FILE_HANDLE, MP4TrackId dstTrackId=MP4_INVALID_TRACK_ID, MP4Duration dstSampleDuration=MP4_INVALID_DURATION)
	Make a copy of a sample. More...

bool	MP4EncAndCopySample (MP4FileHandle srcFile, MP4TrackId srcTrackId, MP4SampleId srcSampleId, encryptFunc_t encfcnp, uint32_t encfcnparam1, MP4FileHandle dstFile=MP4_INVALID_FILE_HANDLE, MP4TrackId dstTrackId=MP4_INVALID_TRACK_ID, MP4Duration dstSampleDuration=MP4_INVALID_DURATION)
	Make a copy of a sample. More...

bool	MP4ReferenceSample (MP4FileHandle srcFile, MP4TrackId srcTrackId, MP4SampleId srcSampleId, MP4FileHandle dstFile, MP4TrackId dstTrackId, MP4Duration dstSampleDuration=MP4_INVALID_DURATION)
	Not implemented.

uint32_t	MP4GetSampleSize (MP4FileHandle hFile, MP4TrackId trackId, MP4SampleId sampleId)
	Get size of a track sample. More...

uint32_t	MP4GetTrackMaxSampleSize (MP4FileHandle hFile, MP4TrackId trackId)
	Get the maximum sample size of a track. More...

MP4SampleId	MP4GetSampleIdFromTime (MP4FileHandle hFile, MP4TrackId trackId, MP4Timestamp when, bool wantSyncSample=false)
	Get sample id of a specified time. More...

MP4Timestamp	MP4GetSampleTime (MP4FileHandle hFile, MP4TrackId trackId, MP4SampleId sampleId)
	Get start time of track sample. More...

MP4Duration	MP4GetSampleDuration (MP4FileHandle hFile, MP4TrackId trackId, MP4SampleId sampleId)
	Get the duration of a track sample. More...

MP4Duration	MP4GetSampleRenderingOffset (MP4FileHandle hFile, MP4TrackId trackId, MP4SampleId sampleId)
	Get the rendering offset of a track sample. More...

bool	MP4SetSampleRenderingOffset (MP4FileHandle hFile, MP4TrackId trackId, MP4SampleId sampleId, MP4Duration renderingOffset)
	Set the rendering offset of a track sample. More...

int8_t	MP4GetSampleSync (MP4FileHandle hFile, MP4TrackId trackId, MP4SampleId sampleId)
	Get sync/random access state of sample. More...

Detailed Description

Typedef Documentation

◆ MP4SampleDependencyType

typedef enum MP4SampleDependencyType_e MP4SampleDependencyType

Sample dependency types.

Bit combinations 0x03, 0x30, 0xc0 are reserved.

Enumeration Type Documentation

◆ MP4SampleDependencyType_e

enum MP4SampleDependencyType_e

Sample dependency types.

Bit combinations 0x03, 0x30, 0xc0 are reserved.

Enumerator
MP4_SDT_UNKNOWN	unknown
MP4_SDT_HAS_REDUNDANT_CODING	contains redundant coding
MP4_SDT_HAS_NO_REDUNDANT_CODING	does not contain redundant coding
MP4_SDT_HAS_DEPENDENTS	referenced by other samples
MP4_SDT_HAS_NO_DEPENDENTS	not referenced by other samples
MP4_SDT_IS_DEPENDENT	references other samples
MP4_SDT_IS_INDEPENDENT	does not reference other samples
MP4_SDT_EARLIER_DISPLAY_TIMES_ALLOWED	subequent samples in GOP may display earlier
_MP4_SDT_RESERVED	reserved

Function Documentation

◆ MP4CopySample()

bool MP4CopySample	(	MP4FileHandle	srcFile,
		MP4TrackId	srcTrackId,
		MP4SampleId	srcSampleId,
		MP4FileHandle	dstFile = `MP4_INVALID_FILE_HANDLE`,
		MP4TrackId	dstTrackId = `MP4_INVALID_TRACK_ID`,
		MP4Duration	dstSampleDuration = `MP4_INVALID_DURATION`
	)

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.

Parameters

srcFile	source sample file handle.
srcTrackId	source sample track id.
srcSampleId	source sample id.
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 srcFile.
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 srcTrackId.
dstSampleDuration	duration in track timescale for new sample. If the value is MP4_INVALID_DURATION, then the duration of the source sample is used.

Returns: On success, thew id of the new sample. On error, MP4_INVALID_SAMPLE_ID.

See also: MP4ReadSample(); MP4WriteSample()

◆ MP4EncAndCopySample()

bool MP4EncAndCopySample	(	MP4FileHandle	srcFile,
		MP4TrackId	srcTrackId,
		MP4SampleId	srcSampleId,
		encryptFunc_t	encfcnp,
		uint32_t	encfcnparam1,
		MP4FileHandle	dstFile = `MP4_INVALID_FILE_HANDLE`,
		MP4TrackId	dstTrackId = `MP4_INVALID_TRACK_ID`,
		MP4Duration	dstSampleDuration = `MP4_INVALID_DURATION`
	)

Make a copy of a sample.

MP4EncAndCopySample is similar to MP4CopySample() except that it offers an encryption hook to the caller.

Parameters

srcFile	source sample file handle.
srcTrackId	source sample track id.
srcSampleId	source sample id.
encfcnp	undocumented.
encfcnparam1	undocumented.
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 srcFile.
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 srcTrackId.
dstSampleDuration	duration in track timescale for new sample. If the value is MP4_INVALID_DURATION, then the duration of the source sample is used.

Returns: On success, thew id of the new sample. On error, MP4_INVALID_SAMPLE_ID.

See also: MP4CopySample()

◆ MP4GetSampleDuration()

MP4Duration MP4GetSampleDuration	(	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.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
sampleId	id of sample for operation. Caveat: the first sample has id 1, not 0.

Returns: On success, the sample duration in track timescale units. On error, MP4_INVALID_DURATION.

See also: MP4ConvertFromTrackDuration()

◆ MP4GetSampleIdFromTime()

MP4SampleId MP4GetSampleIdFromTime	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		MP4Timestamp	when,
		bool	wantSyncSample = `false`
	)

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

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
when	time in track timescale.
wantSyncSample	specifies if the result sample id must correspond to a sample whose sync/random access flag is true.

Returns: On success, the sample id that occurs at the specified time. On error, MP4_INVALID_SAMPLE_ID.

See also: MP4ConvertToTrackTimestamp()

◆ MP4GetSampleRenderingOffset()

MP4Duration MP4GetSampleRenderingOffset	(	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.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
sampleId	id of sample for operation. Caveat: the first sample has id 1, not 0.

Returns: On success, the rendering offset in track timescale units. On error, MP4_INVALID_DURATION.

See also: MP4ConvertFromTrackDuration()

◆ MP4GetSampleSize()

uint32_t MP4GetSampleSize	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		MP4SampleId	sampleId
	)

Get size of a track sample.

MP4GetSampleSize returns the size in bytes of the specified sample from the the specified track.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
sampleId	id of sample for operation. Caveat: the first sample has id 1, not 0.

Returns: On success the sample size in bytes. On error, 0.

◆ MP4GetSampleSync()

int8_t MP4GetSampleSync	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		MP4SampleId	sampleId
	)

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.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
sampleId	id of sample for operation. Caveat: the first sample has id 1, not 0.

Returns: 1 when true, 0 when false. On error, -1.

◆ MP4GetSampleTime()

MP4Timestamp MP4GetSampleTime	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		MP4SampleId	sampleId
	)

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.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
sampleId	id of sample for operation. Caveat: the first sample has id 1, not 0.

Returns: On success, sample start time in track timescale units. On error, MP4_INVALID_TIMESTAMP.

See also: MP4ConvertFromTrackTimestamp()

◆ MP4GetTrackMaxSampleSize()

uint32_t MP4GetTrackMaxSampleSize	(	MP4FileHandle	hFile,
		MP4TrackId	trackId
	)

Get the maximum sample size of a track.

MP4GetTrackMaxSampleSize returns the maximum size in bytes of all the samples in the specified track.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.

Returns: On success, the maximum sample size in bytes. On error, 0.

See also: MP4GetSampleSize()

◆ MP4ReadSample()

bool MP4ReadSample	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		MP4SampleId	sampleId,
		uint8_t **	ppBytes,
		uint32_t *	pNumBytes,
		MP4Timestamp *	pStartTime = `NULL`,
		MP4Duration *	pDuration = `NULL`,
		MP4Duration *	pRenderingOffset = `NULL`,
		bool *	pIsSyncSample = `NULL`
	)

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

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
sampleId	specifies which sample is to be read. Caveat: the first sample has id 1 not 0.
ppBytes	pointer to the pointer to the sample data.
pNumBytes	pointer to variable that will be hold the size in bytes of the sample.
pStartTime	if non-NULL, pointer to variable that will receive the starting timestamp for this sample. Caveat: The timestamp is in trackId's timescale.
pDuration	if non-NULL, pointer to variable that will receive the duration for this sample. Caveat: The duration is in trackId's timescale.
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 trackId's timescale.
pIsSyncSample	if non-NULL, pointer to variable that will receive the state of the sync/random access flag for this sample.

Returns: true on success, false on failure.

See also: MP4GetSampleSize(); MP4GetTrackMaxSampleSize()

◆ MP4ReadSampleFromTime()

bool MP4ReadSampleFromTime	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		MP4Timestamp	when,
		uint8_t **	ppBytes,
		uint32_t *	pNumBytes,
		MP4Timestamp *	pStartTime = `NULL`,
		MP4Duration *	pDuration = `NULL`,
		MP4Duration *	pRenderingOffset = `NULL`,
		bool *	pIsSyncSample = `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 ppBytes 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.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
when	specifies which sample is to be read based on a time in the track timeline. See MP4GetSampleIdFromTime() for details.
ppBytes	pointer to the pointer to the sample data.
pNumBytes	pointer to variable that will be hold the size in bytes of the sample.
pStartTime	if non-NULL, pointer to variable that will receive the starting timestamp for this sample. Caveat: The timestamp is in trackId's timescale.
pDuration	if non-NULL, pointer to variable that will receive the duration for this sample. Caveat: The duration is in trackId's timescale.
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 trackId's timescale.
pIsSyncSample	if non-NULL, pointer to variable that will receive the state of the sync/random access flag for this sample.

Returns: true on success, false on failure.

See also: MP4ReadSample(); MP4GetSampleIdFromTime(); MP4GetSampleSize(); MP4GetTrackMaxSampleSize()

◆ MP4SetSampleRenderingOffset()

bool MP4SetSampleRenderingOffset	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		MP4SampleId	sampleId,
		MP4Duration	renderingOffset
	)

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.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
sampleId	id of sample for operation. Caveat: the first sample has id 1, not 0.
renderingOffset	new offset value in timescale units.

Returns: true on success, false on failure.

See also: MP4ConvertToTrackDuration(); MP4GetSampleRenderingOffset()

◆ MP4WriteSample()

bool MP4WriteSample	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		const uint8_t *	pBytes,
		uint32_t	numBytes,
		MP4Duration	duration = `MP4_INVALID_DURATION`,
		MP4Duration	renderingOffset = `0`,
		bool	isSyncSample = `true`
	)

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.

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
pBytes	pointer to sample data.
numBytes	length of sample data in bytes.
duration	sample duration. Caveat: should be in track timescale.
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.
isSyncSample	the sync/random access flag for this sample.

Returns: true on success, false on failure.

See also: MP4AddTrack()

◆ MP4WriteSampleDependency()

bool MP4WriteSampleDependency	(	MP4FileHandle	hFile,
		MP4TrackId	trackId,
		const uint8_t *	pBytes,
		uint32_t	numBytes,
		MP4Duration	duration,
		MP4Duration	renderingOffset,
		bool	isSyncSample,
		uint32_t	dependencyFlags
	)

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

Parameters

hFile	handle of file for operation.
trackId	id of track for operation.
pBytes	pointer to sample data.
numBytes	length of sample data in bytes.
duration	sample duration. Caveat: should be in track timescale.
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.
isSyncSample	the sync/random access flag for this sample.
dependencyFlags	bitmask specifying sample dependency characteristics. See MP4SampleDependencyType for bit constants.

Returns: true on success, false on failure.

See also: MP4AddTrack()

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MP4SampleDependencyType

Enumeration Type Documentation

◆ MP4SampleDependencyType_e

Function Documentation

◆ MP4CopySample()

◆ MP4EncAndCopySample()

◆ MP4GetSampleDuration()

◆ MP4GetSampleIdFromTime()

◆ MP4GetSampleRenderingOffset()

◆ MP4GetSampleSize()

◆ MP4GetSampleSync()

◆ MP4GetSampleTime()

◆ MP4GetTrackMaxSampleSize()

◆ MP4ReadSample()

◆ MP4ReadSampleFromTime()

◆ MP4SetSampleRenderingOffset()

◆ MP4WriteSample()

◆ MP4WriteSampleDependency()