There are also queries for the video components:

int mpeg3_has_video(mpeg3_t *file);
int mpeg3_total_vstreams(mpeg3_t *file);            // Number of multiplexed video streams
int mpeg3_video_width(mpeg3_t *file, int stream);
int mpeg3_video_height(mpeg3_t *file, int stream);
float mpeg3_frame_rate(mpeg3_t *file, int stream);  // Frames/sec
long mpeg3_video_frames(mpeg3_t *file, int stream); // Total length
int mpeg3_colormodel(mpeg3_t *file, int stream);

mpeg3_colormodel returns either MPEG3_YUV420P or MPEG3_YUV422P. MPEG3_YUV422P is only encountered in high quality video not available in any consumer distribution medium.

STEP 5: Seeking to a point in the file

Each audio stream and each video stream has a position in the file independant of each other stream. A variety of methods are available for specifying the position of a stream: byte offset, frame, sample. Which method you use depends on whether you're seeking audio or video and whether you have a table of contents for the stream.

The preferred seeking method if you're writing a player is:

int mpeg3_seek_byte(mpeg3_t *file, int64_t byte);
int64_t mpeg3_tell_byte(mpeg3_t *file);

mpeg3_get_bytes(mpeg3_t *file)

int mpeg3_set_sample(mpeg3_t *file, long sample, int stream);    // Seek
long mpeg3_get_sample(mpeg3_t *file, int stream);    // Tell current position

int mpeg3_set_frame(mpeg3_t *file, long frame, int stream); // Seek
long mpeg3_get_frame(mpeg3_t *file, int stream);            // Tell current position

If you're in byte seeking mode and you want the current time stamp in the file you can't use mpeg3_get_frame or mpeg3_get_sample because you don't know the total length in the desired units. The mpeg3_audio_samples and mpeg3_video_frames commands don't work in percentage seeking either. Instead use

double mpeg3_get_time(mpeg3_t *file);

Finally, there is a way to seek to the previous frame of video:

int mpeg3_previous_frame(mpeg3_t *file, int stream);

STEP 6: Read the data

To read audio data use:

int mpeg3_read_audio(mpeg3_t *file, 
		float *output_f,      // Pointer to pre-allocated buffer of floats
		short *output_i,      // Pointer to pre-allocated buffer if int16's
		int channel,          // Channel to decode
		long samples,         // Number of samples to decode
		int stream);          // Stream containing the channel

After reading an audio buffer, the current position in the one stream is advanced. Remember that if you're using percentage seeking you can't call mpeg3_set_sample to rewind and read every channel. How then, do you read more than one channel of audio data? Use

mpeg3_reread_audio(mpeg3_t *file, 
		float *output_f,      /* Pointer to pre-allocated buffer of floats */
		short *output_i,      /* Pointer to pre-allocated buffer of int16's */
		int channel,          /* Channel to decode */
		long samples,         /* Number of samples to decode */
		int stream);

To read video data there are two methods. RGB frames or YUV frames. To get an RGB frame use:

int mpeg3_read_frame(mpeg3_t *file, 
		unsigned char **output_rows, // Array of pointers to the start of each output row
		int in_x,                    // Location in input frame to take picture
		int in_y, 
		int in_w, 
		int in_h, 
		int out_w,                   // Dimensions of output_rows
		int out_h, 
		int color_model,             // One of the color model #defines given above.
		int stream);

color_model defines which RGB color model the picture should be decoded to and the possible values are given in libmpeg3.h. The frame buffer pointed to by output_rows must have enough memory allocated to store the color model you select.

You must allocate 4 extra bytes in the last output_row. This is scratch area for the MMX routines.

mpeg3_read_frame advances the position in the one stream by 1 frame.

To read YUV frames use one of two methods:

int mpeg3_read_yuvframe(mpeg3_t *file,
		char *y_output,
		char *u_output,
		char *v_output,
		int in_x,
		int in_y,
		int in_w,
		int in_h,
		int stream);

int mpeg3_read_yuvframe_ptr(mpeg3_t *file,
		char **y_output,
		char **u_output,
		char **v_output,
		int stream);

For professional use the library can decode YUV 4:2:2 video in addition to YUV 4:2:0. This variable is determined at encoding time, won't affect the usage of mpeg3_read_frame but you do need an extra function call in order to use mpeg3_read_yuvframe. To determine the encoding of the video stream use

mpeg3_colormodel(mpeg3_t *file, int stream)

Synchronizing video with audio

To synchronize video with audio in realtime you need to sometimes delay the video and sometimes drop frames. It's easy to calculate the number of frames to drop but if you're using percentage seeking you can't calculate the exact percentage to seek forward by. Instead call

mpeg3_drop_frames(mpeg3_t *file, long frames, int stream);

This skips frames frames from the current position whether in percentage seeking or absolute seeking.

STEP 7: Close the file