NAME
MP4ReadSample - Read a track sample
SYNTAX
#include <mp4.h>
bool MP4ReadSample(
MP4FileHandle hFile,
MP4TrackId trackId,
MP4SampleId sampleId,
u_int8_t** ppBytes,
u_int32_t* pNumBytes,
MP4Timestamp* pStartTime = NULL,
MP4Duration* pDuration = NULL,
MP4Duration* pRenderingOffset = NULL,
bool pIsSyncSample = NULL
);
ARGUMENTS
hFile Specifies the mp4 file to which the operation applies.
trackId
Specifies the track to which the operation applies.
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. See DESCRIPTION for
details on this argument.
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 the track
timescale.
pDuration
If non-NULL, pointer to variable that will receive the duration
for this sample. Caveat: The duration is in the track timescale
units.
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 the track
timescale units.
pIsSyncSample
If non-NULL, pointer to variable that will receive the state of
the sync/random access flag for this sample.
RETURN VALUES
Upon success, true (1). Upon an error, false (0).
DESCRIPTION
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 before-hand how large the
receiving buffer must be.
If the value of *ppBytes is NULL, then an appropriately sized buffer is
automatically malloc’ed for the sample data and *ppBytes set to this
pointer. The calling application is responsible for free’ing this
memory.
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.
SEE ALSO
MP4(3)