MP4DMXExecute

Syntax

#include <cafe/mp4dmx.h>

MP4DMXExecute(void *data, s32 control_flag, s32 track_id, s32 seek_direction, u64 end_time_stamp,
	      u64 *time_stamp, u64 *next_offset, s32 *next_size, void *handle);

Parameters

data Set to NULL (Input).
control_flag Flag specifying process (Input).
  • Set to 1 indicates to seek (get current position).
  • Set to other than 1 indicates to perform demultiplexing (get sample).
track_id Specifies the track to be output. Specify the value MP4DMX_UNASSIGNED_TRACK_ID to output all tracks in the MP4 file (Input).
seek_direction The direction in which to seek. This sets the direction in which to search for points to seek to from the specified point (Input).
  • MP4DMX_SEEK_NORMAL: Search for a seek point that is nearby. If you seek to a timestamp that is as far away as the duration of the previous or next sample, that sample (the closest one) is output first.
  • MP4DMX_SEEK_BACKWARD: Search before the specified point.
  • MP4DMX_SEEK_FORWARD: Search after the specified point.
NOTE:
If you have specified MP4MDX_SEEK_BACKWARD or MP4DMX_SEEK_FORWARD and there are no seek points in the specified direction, MP4DMX_SEEK_NORMAL is used to search for a seek point.
end_time_stamp The timestamp at which to stop. Data is output up to the specified timestamp (in milliseconds). Use a value of MP4DMX_UNASSIGNED_END_TIME_STAMP when you do not specify a final timestamp (when you output data up to the end of the MP4 file), but this only works when getting samples (control_flag is 0).
If you specify 0 as the final timestamp, the function returns MP4DMX_RET_SUCCESS without outputting anything (Input).
time_stamp Input
When getting the current position
The time (in milliseconds) to seek through the file. Use the time_stamp output by the header parsing function (MP4DMXReadHeader) to continue getting the current position after calling the header parsing function (MP4DMXReadHeader) due to MP4DMX_RET_READ_HEADER being returned when getting the current header.
When getting samples
Use the time_stamp that was output when getting the current position.

Output
When getting the current position
Time information for an accessible seek point.
NOTE:
If there are no samples (if the number of stts Box entries or stsz Box samples is zero), 0xffffffffffffffff (the maximum uint64 value) is set for this parameter.
(This does not depend on whether there is a seek point).
When getting samples
Time information for the next input chunk.
next_offset The next offset from the beginning of the MP4 data file to pass to the library (Output).
next_size The next data size to pass to the library (Output).
handle A pointer referencing an object handle (Input).

Return Values

MP4DMX_RET_SUCCESS Success. This is returned when data could be processed up to the timestamp specified by end_time_stamp.
NOTE:
This value is not returned if end_time_stamp is set to MP4DMX_UNASSIGNED_END_TIME_STAMP.
MP4DMX_RET_EXECUTE_NORMAL Success. When a seek operation has been specified (when control_flag is 1), get the samples at the specified timestamp. To get the samples, call this function with control_flag set to 0.
MP4DMX_RET_FIND_HEADER Success. This is returned when no more data is being processed or when a seek operation has been specified to a fragment other than the one currently being processed. You need to read the next data or the header for the seek position. The size and offset from the beginning of the MP4 data file are set in next_size and next_offset for finding the next header. Read the specified amount of data from the specified offset in the MP4 file and then get the header's position (call MP4DMXFindHeader).
MP4DMX_RET_READ_HEADER This is returned when moving to a moof header that has already been parsed, or to request input of data for the next block of a segmented Box. The offset from the beginning of the MP4 data file and size for the next header or to continue reading header data are output in the next_offset and next_size parameters. Read the specified amount of data from the specified offset in the MP4 file and call this function again.
NOTE:
This value is only returned if one of the following has been specified:
DMX_MP4_STTS_READ_BUFFER_SIZE,
DMX_MP4_STSZ_READ_BUFFER_SIZE, or
DMX_MP4_CTTS_READ_BUFFER_SIZE.
MP4DMX_RET_EXECUTE_WARNING Warning. This warning is returned if a timestamp could not be guaranteed to be synchronized for a track while processing.
MP4DMX_RET_ERROR_BAD_TIMESTAMP Failure. This error is returned when the input timestamp exceeds the stream's duration (the value of the mvhd atom's duration or-for a fragmented file-the value calculated from the mehd atom's fragment_duration).
MP4DMX_RET_INVALID_TRACK_ID Failure. This error is returned when you seek to a track that does not exist or is not configured to be output by the input parameters.
MP4DMX_RET_ERROR_INVALID_POINTER Failure. This error is returned when an argument is NULL.
MP4DMX_RET_ERROR_FATAL Failure. This error is returned when functions are not called in the correct order.

Description

Seeks and demultiplexes.

This function can only be called after parsing a header (MP4DMXReadHeader).

If the value input for end_time_stamp when calling this function is MP4DMX_UNASSIGNED_END_TIME_STAMP, processing continues until all data is completed, so this function will not return until processing has completed. However, the output data is divided by each header, so this function can only consider the range indicated by the headers that have been parsed as its range. It cannot tell whether the end is the end of the entire data file, or the end indicated by a particular header, so when MP4DMX_UNASSIGNED_END_TIME_STAMP is input, it returns MP4DMX_RET_FIND_HEADER rather than MP4DMX_RET_SUCCESS, even if the end of the MP4 data file has been reached. When using MP4DMX_UNASSIGNED_END_TIME_STAMP, the user application must determine whether the true end of the file has been reached.

When calling this function with seek specified (control_flag is 1, getting the current position), the sample maintained within the library is output, and the header data maintained by the library must be updated with the seek target header data. For this reason, this function should be called every time directly before starting (call to MP4DMXBegin) when performing continuous processing, restarting (call to MP4DMXBegin) immediately after ending the previous (call to MP4DMXEnd). (This is not necessary when demultiplexing/getting samples, control_flag is 0.)

The value passed into time_stamp when calling this function sets the time information used for seeking. However, if you called the header parsing function MP4DMXReadHeader because MP4DMX_RET_READ_HEADER was returned when this function was called with seek specified (to get the current header), you should use the time_stamp output by the header parsing function MP4DMXReadHeader to continue getting the current position.

Do Not Call From

Background Do not call this function from the background.
Multiple threads This function is not thread-safe.

See Also

MP4DMXOpen
MP4DMXBegin
MP4DMXFindHeader
MP4DMXReadHeader
MP4DMXEnd
MP4DMXClose

Revision History

2014/07/29 Initial version.


CONFIDENTIAL