libquicktime: Video decoding

# 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_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.
void | lqt_seek_video (quicktime_t *file, int track, int64_t time)
| Seek to a specific video time.

## 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_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.

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