Video decoding
[Video]

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

Functions

long quicktime_video_length (quicktime_t *file, int track)
 Get the video length.
long quicktime_video_position (quicktime_t *file, int track)
 Get the video position.
int quicktime_video_tracks (quicktime_t *file)
 Get the number of video tracks.
int quicktime_has_video (quicktime_t *file)
 Check if a file has at least one video track.
int quicktime_video_width (quicktime_t *file, int track)
 Get the width of a video track.
int quicktime_video_height (quicktime_t *file, int track)
 Get the height of a video track.
int quicktime_video_depth (quicktime_t *file, int track)
 Get the depth of a video track.
double quicktime_frame_rate (quicktime_t *file, int track)
 Get the framerate of a video track.
char * quicktime_video_compressor (quicktime_t *file, int track)
 Get the four character code of a video track.
long quicktime_frame_size (quicktime_t *file, long frame, int track)
 Get the compressed size of frame in a video track.
int quicktime_set_video_position (quicktime_t *file, int64_t frame, int track)
 Seek to a specific video frame.
long quicktime_read_frame (quicktime_t *file, unsigned char *video_buffer, int track)
 Read a compressed video frame.
int quicktime_supported_video (quicktime_t *file, int track)
 Check if a video track is supported by libquicktime.
int quicktime_reads_cmodel (quicktime_t *file, int colormodel, int track)
 Check if a colormodel is supported for decoding.
int quicktime_decode_video (quicktime_t *file, unsigned char **row_pointers, int track)
 Decode a video frame in BC_RGB888.
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.
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.
lqt_interlace_mode_t lqt_get_interlace_mode (quicktime_t *file, int track)
 Get the interlace mode.
lqt_chroma_placement_t lqt_get_chroma_placement (quicktime_t *file, int track)
 Get the chroma placement.
int lqt_get_decoder_colormodel (quicktime_t *file, int track)
 Get the native colormodel of the decoder.
int64_t lqt_get_frame_time (quicktime_t *file, int track, int frame)
 Get the timestamp of a given frame.
int64_t lqt_frame_time (quicktime_t *file, int track)
 Get the timestamp of the next frame to be decoded.
int lqt_decode_video (quicktime_t *file, unsigned char **row_pointers, int track)
 Decode one video frame.
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.
int lqt_frame_duration (quicktime_t *file, int track, int *constant)
 Get the duration of the NEXT frame to be decoded.
int lqt_video_time_scale (quicktime_t *file, int track)
 Get the timescale of the track.
int64_t lqt_video_duration (quicktime_t *file, int track)
 Get the duration of a video track.
long lqt_video_edit_list_total_entries (quicktime_t *file, int track)
 Get the number of video track edit segments.
long lqt_video_edit_duration (quicktime_t *file, int track, int entry_index)
 Get the duration of a video track edit segment.
long lqt_video_edit_time (quicktime_t *file, int track, int entry_index)
 Get the time offset of a video track edit segment.
float lqt_video_edit_rate (quicktime_t *file, int track, int entry_index)
 Get the rate of a video track edit segment.
void lqt_seek_video (quicktime_t *file, int track, int64_t time)
 Seek to a specific video time.
int64_t lqt_get_video_pts_offset (quicktime_t *file, int track)
 Get an video pts offset.

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)
Generated on Thu Mar 8 22:27:04 2012 for libquicktime by  doxygen 1.6.3