Video decoding

Video related definitions and functions (reading) More...

Functions
long	quicktime_video_length (quicktime_t *file, int track)
	Get the video length. More...
long	quicktime_video_position (quicktime_t *file, int track)
	Get the video position. More...
int	quicktime_video_tracks (quicktime_t *file)
	Get the number of video tracks. More...
int	quicktime_has_video (quicktime_t *file)
	Check if a file has at least one video track. More...
int	quicktime_video_width (quicktime_t *file, int track)
	Get the width of a video track. More...
int	quicktime_video_height (quicktime_t *file, int track)
	Get the height of a video track. More...
int	quicktime_video_depth (quicktime_t *file, int track)
	Get the depth of a video track. More...
double	quicktime_frame_rate (quicktime_t *file, int track)
	Get the framerate of a video track. More...
char *	quicktime_video_compressor (quicktime_t *file, int track)
	Get the four character code of a video track. More...
long	quicktime_frame_size (quicktime_t *file, long frame, int track)
	Get the compressed size of frame in a video track. More...
int	quicktime_set_video_position (quicktime_t *file, int64_t frame, int track)
	Seek to a specific video frame. More...
long	quicktime_read_frame (quicktime_t *file, unsigned char *video_buffer, int track)
	Read a compressed video frame. More...
int	quicktime_supported_video (quicktime_t *file, int track)
	Check if a video track is supported by libquicktime. More...
int	quicktime_reads_cmodel (quicktime_t *file, int colormodel, int track)
	Check if a colormodel is supported for decoding. More...
int	quicktime_decode_video (quicktime_t *file, unsigned char **row_pointers, int track)
	Decode a video frame in BC_RGB888. More...
long	quicktime_decode_scaled (quicktime_t *file, int in_x, int in_y, int in_w, int in_h, int out_w, int out_h, int color_model, unsigned char **row_pointers, int track)
	Decode aand optionally scale a video frame. More...
int	lqt_get_pixel_aspect (quicktime_t *file, int track, int *pixel_width, int *pixel_height)
	Get the pixel aspect ratio of a video track. More...
lqt_interlace_mode_t	lqt_get_interlace_mode (quicktime_t *file, int track)
	Get the interlace mode. More...
lqt_chroma_placement_t	lqt_get_chroma_placement (quicktime_t *file, int track)
	Get the chroma placement. More...
int	lqt_get_decoder_colormodel (quicktime_t *file, int track)
	Get the native colormodel of the decoder. More...
int64_t	lqt_get_frame_time (quicktime_t *file, int track, int frame)
	Get the timestamp of a given frame. More...
int64_t	lqt_frame_time (quicktime_t *file, int track)
	Get the timestamp of the next frame to be decoded. More...
int	lqt_decode_video (quicktime_t *file, unsigned char **row_pointers, int track)
	Decode one video frame. More...
int	lqt_read_video_frame (quicktime_t *file, uint8_t **buffer, int *buffer_alloc, int64_t frame, int64_t *time, int track)
	Read a compressed video frame. More...
int	lqt_frame_duration (quicktime_t *file, int track, int *constant)
	Get the duration of the NEXT frame to be decoded. More...
int	lqt_video_time_scale (quicktime_t *file, int track)
	Get the timescale of the track. More...
int64_t	lqt_video_duration (quicktime_t *file, int track)
	Get the duration of a video track. More...
long	lqt_video_edit_list_total_entries (quicktime_t *file, int track)
	Get the number of video track edit segments. More...
long	lqt_video_edit_duration (quicktime_t *file, int track, int entry_index)
	Get the duration of a video track edit segment. More...
long	lqt_video_edit_time (quicktime_t *file, int track, int entry_index)
	Get the time offset of a video track edit segment. More...
float	lqt_video_edit_rate (quicktime_t *file, int track, int entry_index)
	Get the rate of a video track edit segment. More...
void	lqt_seek_video (quicktime_t *file, int track, int64_t time)
	Seek to a specific video time. More...
int64_t	lqt_get_video_pts_offset (quicktime_t *file, int track)
	Get an video pts offset. More...

Detailed Description

Video related definitions and functions (reading)

The video API changed a lot during the last years (causing lot of confusion), so here is the preferred way: First get the number of video tracks with quicktime_video_tracks. Then for each track you want to decode, use quicktime_supported_video to verify that a codec is available. Then for each track, get the frame size with quicktime_video_width and quicktime_video_height . The framerate is only exact when handled as a rational number. Thus, you'll need 2 functions lqt_video_time_scale and lqt_frame_duration . The framerate in frames/sec becomes time_scale/frame_duration. Further format information can be obtained with lqt_get_pixel_aspect, lqt_get_interlace_mode and lqt_get_chroma_placement.

A very important thing is the colormodel (see Color handling): First obtain the colormodel used natively by the codec with lqt_get_cmodel. Your application might or might not support all colormodels, which exist in libquicktime. The more colormodels you can handle yourself, the better, since libquicktimes built in colormodel converter is not the best. Thus, it's the best idea to pack all colormodels you can handle yourself into an array, and call lqt_get_best_colormodel to get the best colormodel. After you figured out, which colormodel you use, tell this to libquicktime with lqt_set_cmodel.

When decoding frames, libquicktime by default assumes, that the frames you pass to it have no padding bytes between the scanlines. Some APIs however padd scanlines to certain boundaries. If this is the case, you must tell this to libquicktime by calling lqt_set_row_span and lqt_set_row_span_uv (for planar formats).

Then, for each frame, it's wise to get the timestamp with lqt_frame_time before decoding it. This will make sure, that you'll support tracks with nonconstant framerates. The actual decoding then should happen with lqt_decode_video.

Function Documentation

long quicktime_video_length	(	quicktime_t *	file,
		int	track
	)

Get the video length.

Parameters

file	A quicktime handle
track	index (starting with 0)

Returns

The total number of video frames in the track

Note that for tracks with nonconstant framerate, you won't be able to obtain the track duration from the number of frame. If you are interested in the total playing time, use lqt_video_duration

long quicktime_video_position	(	quicktime_t *	file,
		int	track
	)

Get the video position.

Parameters

file	A quicktime handle
track	index (starting with 0)

Returns

The number (starting with 0) of the next frame to be decoded.

To get timestamps for tracks with nonconstant framerate, use lqt_frame_time

int quicktime_video_tracks

(

quicktime_t *

file

)

Get the number of video tracks.

Parameters

file	A quicktime handle

Returns

The number of video tracks

int quicktime_has_video

(

quicktime_t *

file

)

Check if a file has at least one video track.

Parameters

file	A quicktime handle

Returns

1 if the file has video tracks, 0 else

int quicktime_video_width	(	quicktime_t *	file,
		int	track
	)

Get the width of a video track.

Parameters

file	A quicktime handle
track	index (starting with 0)

Returns

The image width in pixels

int quicktime_video_height	(	quicktime_t *	file,
		int	track
	)

Get the height of a video track.

Parameters

file	A quicktime handle
track	index (starting with 0)

Returns

The image height in pixels

int quicktime_video_depth	(	quicktime_t *	file,
		int	track
	)

Get the depth of a video track.

Parameters

file	A quicktime handle
track	index (starting with 0)

Returns

The image depth in pixels

Don't use this function for anything else than for informational purposes. Depth is meaningless for compressed codecs and sometimes plain wrong even for uncompressed ones.

To get some better informations about the pixel format, a codec will deliver, use lqt_get_cmodel or (better) lqt_get_decoder_colormodel .

double quicktime_frame_rate	(	quicktime_t *	file,
		int	track
	)

Get the framerate of a video track.

Parameters

file	A quicktime handle
track	index (starting with 0)

Returns

The framerate in frames per second.

Don't use this unless A/V sync is nor important. The return value is practically random for tracks with nonconstant framerate. Even for constant framerate, the return value can never correctly resemble e.g. the NTSC framerate (30000/1001).

To get the framerate as a rational number (and check if it's constant), use lqt_frame_duration and lqt_video_time_scale .

char* quicktime_video_compressor	(	quicktime_t *	file,
		int	track
	)

Get the four character code of a video track.

Parameters

file	A quicktime handle
track	index (starting with 0)

Returns

The four character code (fourcc) of the track.

To get more save information about the codec responsible for the stream, use lqt_video_codec_from_file .

long quicktime_frame_size	(	quicktime_t *	file,
		long	frame,
		int	track
	)

Get the compressed size of frame in a video track.

Parameters

file	A quicktime handle
frame	Frame index (starting with 0)
track	index (starting with 0)

Returns

The size in bytes of the frame

Use this if you want to read compressed frames with quicktime_read_frame

int quicktime_set_video_position	(	quicktime_t *	file,
		int64_t	frame,
		int	track
	)

Seek to a specific video frame.

Parameters

file	A quicktime handle
frame	The frame position (starting with 0)
track	index (starting with 0)

Use this for seeking. During sequential decode calls, the position will be updated automatically. If you want to support tracks with nonconmstant framerate, you should use lqt_seek_video .

long quicktime_read_frame	(	quicktime_t *	file,
		unsigned char *	video_buffer,
		int	track
	)

Read a compressed video frame.

Parameters

file	A quicktime handle
video_buffer	The compressed frame
track	index (starting with 0)

Read a compressed video frame. The size of the frame can be obtained with quicktime_frame_size . This function increments all pointers in the track, so you can sequentially read all frames without setting the position in between.

int quicktime_supported_video	(	quicktime_t *	file,
		int	track
	)

Check if a video track is supported by libquicktime.

Parameters

file	A quicktime handle
track	index (starting with 0)

Returns

1 if a codec for this track is available, 0 else

int quicktime_reads_cmodel	(	quicktime_t *	file,
		int	colormodel,
		int	track
	)

Check if a colormodel is supported for decoding.

Parameters

file	A quicktime handle
colormodel	A colormodel (see Color handling)
track	index (starting with 0)

Returns

1 if the colormodel can be used for decoding calls, 0 if it can't.

To let libquicktime get the best colormodel out of a list of colormodels your application supports, use lqt_get_best_colormodel instead.

int quicktime_decode_video	(	quicktime_t *	file,
		unsigned char **	row_pointers,
		int	track
	)

Decode a video frame in BC_RGB888.

Parameters

file	A quicktime handle
row_pointers	Frame buffer (see lqt_rows_alloc )
track	index (starting with 0)

Decode one video frame. All colormodels are converted to BC_RGB888 automatically probably causing lots of overhead. To decode frames in other colormodels, use lqt_decode_video .

long quicktime_decode_scaled	(	quicktime_t *	file,
		int	in_x,
		int	in_y,
		int	in_w,
		int	in_h,
		int	out_w,
		int	out_h,
		int	color_model,
		unsigned char **	row_pointers,
		int	track
	)

Decode aand optionally scale a video frame.

Parameters

file	A quicktime handle
in_x	Horizontal offset of the image relative to the source image
in_y	Vertical offset of the image relative to the source image
in_w	Image width in the source image
in_h	Image height in the source image
out_w	Width of output frame
out_h	Height of output frame
color_model	Colormodel of the output frame
row_pointers	Frame buffer (see lqt_rows_alloc )
track	index (starting with 0)

This function takes a subwindow of the source image (specified by in_x, in_y, in_w, in_h) and scales it to the dimensions (out_w, out_h) of the output frame given by row_pointers. Colormodel conversion from the stream colormodel to the color_model you pass is also done. Scaling is done by a not very optimized nearest neighbor algorithm. To do high quality video scaling, you should use something else.

int lqt_get_pixel_aspect	(	quicktime_t *	file,
		int	track,
		int *	pixel_width,
		int *	pixel_height
	)

Get the pixel aspect ratio of a video track.

Parameters

file	A quicktime handle
track	Track index (starting with 0)
pixel_width	returns the pixel width
pixel_height	returns the pixel height

Returns

1 if the call was successful, 0 if there is no such track

lqt_interlace_mode_t lqt_get_interlace_mode	(	quicktime_t *	file,
		int	track
	)

Get the interlace mode.

Parameters

file	A quicktime handle
track	Track index (starting with 0)

Returns

The interlace mode.

The interlace mode is stored in the fiel atom, which is used by default. If there is no fiel atom and the interlace mode is not implied by the codec, LQT_INTERLACE_NONE is returned, which might be wrong.

lqt_chroma_placement_t lqt_get_chroma_placement	(	quicktime_t *	file,
		int	track
	)

Get the chroma placement.

Parameters

file	A quicktime handle
track	Track index (starting with 0)

Returns

The chroma placement

The chroma placement is implied by the codec and makes only sense for YUV420 formats.

int lqt_get_decoder_colormodel	(	quicktime_t *	file,
		int	track
	)

Get the native colormodel of the decoder.

Parameters

file	A quicktime handle
track	Track index (starting with 0)

This returns the colormodel, which is used by the stream natively. If your application can handle the colormodel, you can use lqt_decode_video for decoding in the native colormodel. This will bypass all internal colormodel conversions.

int64_t lqt_get_frame_time	(	quicktime_t *	file,
		int	track,
		int	frame
	)

Get the timestamp of a given frame.

Parameters

file	A quicktime handle
track	Track index (starting with 0)
frame	The frame

Returns

The timestamp of the frame

int64_t lqt_frame_time	(	quicktime_t *	file,
		int	track
	)

Get the timestamp of the next frame to be decoded.

Parameters

file	A quicktime handle
track	Track index (starting with 0)

Returns

The timestamp of the next frame to be decoded

Call this BEFORE one of the decoding functions to get the timestamp of the next frame

int lqt_decode_video	(	quicktime_t *	file,
		unsigned char **	row_pointers,
		int	track
	)

Decode one video frame.

Parameters

file	A quicktime handle
row_pointers	Frame (see lqt_rows_alloc)
track	Track index (starting with 0)

Decode one video frame and increment the interal frame pointer. To get the presentation timestamp for this frame, call lqt_frame_time before.

int lqt_read_video_frame	(	quicktime_t *	file,
		uint8_t **	buffer,
		int *	buffer_alloc,
		int64_t	frame,
		int64_t *	time,
		int	track
	)

Read a compressed video frame.

Parameters

file	A quicktime handle
buffer	Buffer where the frame will be read to
buffer_alloc	Number of bytes allocated for the buffer
frame	Number of the frame to be read (starting with 0)
time	If non NULL, returns the timestamp in timescale tics
track	Track index (starting with 0)

Returns

The number of bytes in the frame or 0 if no frame could be read.

Read one compressed video frame. This function calls realloc() to ensure, that the buffer will be large enough. To use this function, set buffer to NULL and buffer_alloc to zero before the first call. After the last call, free the buffer with free(). This function is mainly used by video codecs.

int lqt_frame_duration	(	quicktime_t *	file,
		int	track,
		int *	constant
	)

Get the duration of the NEXT frame to be decoded.

Parameters

file	A quicktime handle
track	Track index (starting with 0)
constant	If non NULL it will be set to 1 if the frame duration is constant throughout the whole track

Returns

The frame duration in timescale tics

int lqt_video_time_scale	(	quicktime_t *	file,
		int	track
	)

Get the timescale of the track.

Parameters

file	A quicktime handle
track	Track index (starting with 0)

Returns

The timescale of the track

int64_t lqt_video_duration	(	quicktime_t *	file,
		int	track
	)

Get the duration of a video track.

Parameters

file	A quicktime handle
track	Track index (starting with 0)

Returns

The total duration of the track in timescale tics

Use this function if you want to support nonconstant framerates.

long lqt_video_edit_list_total_entries	(	quicktime_t *	file,
		int	track
	)

Get the number of video track edit segments.

Parameters

file	A quicktime handle
track	Video track index (starting with 0)

long lqt_video_edit_duration	(	quicktime_t *	file,
		int	track,
		int	entry_index
	)

Get the duration of a video track edit segment.

Parameters

file	A quicktime handle
track	Video track index (starting with 0)
entry_index	Index into the edit segments

long lqt_video_edit_time	(	quicktime_t *	file,
		int	track,
		int	entry_index
	)

Get the time offset of a video track edit segment.

Parameters

file	A quicktime handle
track	Video track index (starting with 0)
entry_index	Index into the edit segments

float lqt_video_edit_rate	(	quicktime_t *	file,
		int	track,
		int	entry_index
	)

Get the rate of a video track edit segment.

Parameters

file	A quicktime handle
track	Video track index (starting with 0)
entry_index	Index into the edit segments

void lqt_seek_video	(	quicktime_t *	file,
		int	track,
		int64_t	time
	)

Seek to a specific video time.

Parameters

file	A quicktime handle
time	The desired time of the next frame in timescale tics (starting with 0)
track	index (starting with 0)

Use this for seeking. During sequential decode calls, the position will be updated automatically. Replacement of quicktime_set_video_position which also works for streams with nonconstant framerate

int64_t lqt_get_video_pts_offset	(	quicktime_t *	file,
		int	track
	)

Get an video pts offset.

Parameters

file	A quicktime handle
track	Track index (starting with 0)

Returns

PTS of the first video frame (in timescale units)