MP4v2

Typedefs | Enumerations | Functions
MP4v2 Sample

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