libquicktime: Video encoding

# Video encoding
[Video]

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

## Functions
void | quicktime_set_framerate (quicktime_t *file, double framerate)
| Set the framerate for encoding.
int | quicktime_set_video (quicktime_t *file, int tracks, int frame_w, int frame_h, double frame_rate, char *compressor)
| Set up video tracks for encoding.
void | quicktime_set_jpeg (quicktime_t *file, int quality, int use_float)
| Set jpeg encoding quality.
void | quicktime_set_parameter (quicktime_t *file, char *key, void *value)
| Set a codec parameter.
void | quicktime_set_depth (quicktime_t *file, int depth, int track)
| Set the depth of a video track.
int | quicktime_write_frame (quicktime_t *file, uint8_t *video_buffer, int64_t bytes, int track)
| Write a compressed video frame.
int | quicktime_writes_cmodel (quicktime_t *file, int colormodel, int track)
| Check if a colormodel is supported for encoding.
int | quicktime_encode_video (quicktime_t *file, unsigned char **row_pointers, int track)
| Encode a video frame.
int | lqt_set_pixel_aspect (quicktime_t *file, int track, int pixel_width, int pixel_height)
| Set the pixel aspect ratio of a video track.
int | lqt_set_interlace_mode (quicktime_t *file, int track, lqt_interlace_mode_t mode)
| Set the interlace mode.
int | lqt_set_video (quicktime_t *file, int tracks, int frame_w, int frame_h, int frame_duration, int timescale, lqt_codec_info_t *codec_info)
| Set up video tracks for encoding.
int | lqt_add_video_track (quicktime_t *file, int frame_w, int frame_h, int frame_duration, int timescale, lqt_codec_info_t *codec_info)
| Add a video track for encoding.
int | lqt_set_video_pass (quicktime_t *file, int pass, int total_passes, const char *stats_file, int track)
| Enable multipass encoding.
int | lqt_encode_video (quicktime_t *file, unsigned char **row_pointers, int track, int64_t time)
| Encode one video frame.
int | lqt_encode_video_d (quicktime_t *file, unsigned char **row_pointers, int track, int64_t time, int duration)
| Encode one video frame.

## Detailed Description

Video related definitions and functions (writing).

The video API changed a lot during the last years (causing lot of confusion), so here is the preferred way: Use the Codec registry functions to get all supported video encoders. Once you found a codec (i.e. a lqt_codec_info_t ), call lqt_add_video_track to add the track to the file. You can repeat this procedure to add as many tracks as you like with different formats and/or codecs. You can pass further format parameters with lqt_set_pixel_aspect.

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.

Next you might want to set some compression parameters. This is done by calling lqt_set_video_parameter. Supported parameters and valid ranges are in the lqt_codec_info_t.

Actual encoding should happen with lqt_encode_video.

## Function Documentation

void quicktime_set_framerate | ( | quicktime_t * | file,
|  | double | framerate |
| ) |  |  |

Set the framerate for encoding.

Parameters:

  | file | A quicktime handle
  | framerate | framerate

Sets the framerate for encoding.

This function is depracated and should not be used in newly written code.

int quicktime_set_video | ( | quicktime_t * | file,
|  | int | tracks,
|  | int | frame_w,
|  | int | frame_h,
|  | double | frame_rate,
|  | char * | compressor |
| ) |  |  |

Set up video tracks for encoding.

Parameters:

  | file | A quicktime handle
  | tracks | Number of tracks
  | frame_w | Frame width
  | frame_h | Frame height
  | frame_rate | Frame rate (in frames per second)
  | compressor | Four character code of the compressor

This function is depracated and should not be used in newly written code. It won't allow you to set multiple video streams with different formats, and passing a double framerate causes rounding errors. Use lqt_add_video_track instead.

void quicktime_set_jpeg | ( | quicktime_t * | file,
|  | int | quality,
|  | int | use_float |
| ) |  |  |

Set jpeg encoding quality.

Parameters:

  | file | A quicktime handle
  | quality | Quality (0..100)
  | use_float | Use floating point routines

Set the jpeg encoding quality and whether to use floating point routines. This should be called after creating the video track(s).

This function is depracated and should not be used in newly written code. Use lqt_set_video_parameter instead.

void quicktime_set_parameter | ( | quicktime_t * | file,
|  | char * | key,
|  | void * | value |
| ) |  |  |

Set a codec parameter.

Parameters:

  | file | A quicktime handle
  | key | Short name of the parameter
  | value | Parameter value.

For integer parameters, value must be of the type int*. For string parameters, use char*.

This function sets the same parameter for all video AND audio streams, which is quite idiotic. Use lqt_set_audio_parameter and lqt_set_video_parameter to set codec parameters on a per stream basis.

void quicktime_set_depth | ( | quicktime_t * | file,
|  | int | depth,
|  | int | track |
| ) |  |  |

Set the depth of a video track.

Parameters:

  | file | A quicktime handle
  | depth | The depth (bits per pixel)
  | track | index (starting with 0)

This function is deprecated and should never be called. The depth is set by the codecs and there is no reason to change this.

int quicktime_write_frame | ( | quicktime_t * | file,
|  | uint8_t * | video_buffer,
|  | int64_t | bytes,
|  | int | track |
| ) |  |  |

Write a compressed video frame.

Parameters:

  | file | A quicktime handle
  | video_buffer | The compressed frame
  | bytes | Bytes of the compressed frame
  | track | index (starting with 0)

If you get compressed video frames (e.g. from a firewire port), use this function to write them into a quicktime container. Before, you must set up the track with lqt_add_video_track or, if no software codec is present, with quicktime_set_video .

int quicktime_writes_cmodel | ( | quicktime_t * | file,
|  | int | colormodel,
|  | int | track |
| ) |  |  |

Check if a colormodel is supported for encoding.

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 encoding 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_encode_video | ( | quicktime_t * | file,
|  | unsigned char ** | row_pointers,
|  | int | track |
| ) |  |  |

Encode a video frame.

Parameters:

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

Encode one video frame. This works only for constant framerate streams. For nonconstant framerates, you'll want to use lqt_encode_video instead.

int lqt_set_pixel_aspect | ( | quicktime_t * | file,
|  | int | track,
|  | int | pixel_width,
|  | int | pixel_height |
| ) |  |  |

Set the pixel aspect ratio of a video track.

Parameters:

  | file | A quicktime handle
  | track | Track index (starting with 0)
  | pixel_width | Pixel width
  | pixel_height | Pixel height

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

int lqt_set_interlace_mode | ( | quicktime_t * | file,
|  | int | track,
|  | lqt_interlace_mode_t | mode |
| ) |  |  |

Set the interlace mode.

Parameters:

  | file | A quicktime handle
  | track | Track index (starting with 0)
  | mode | The interlace mode.

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

This will in most cases store the correct interlacing information in the file (e.g. in the fiel atom). For tweaking the fiel atom directly, advanced users might look at lqt_set_fiel.

int lqt_set_video | ( | quicktime_t * | file,
|  | int | tracks,
|  | int | frame_w,
|  | int | frame_h,
|  | int | frame_duration,
|  | int | timescale,
|  | lqt_codec_info_t * | codec_info |
| ) |  |  |

Set up video tracks for encoding.

Parameters:

  | file | A quicktime handle
  | tracks | Number of video tracks
  | frame_w | Image width
  | frame_h | Image height
  | frame_duration | Duration of one frame. This can later be overridden
  | timescale | Timescale of the track
  | codec_info | Codec to use (see Codec registry )

This sets one or more video tracks for encoding. The framerate is passed as a rational number (timescale/frame_duration). E.g. for an NTSC stream, you'll choose timescale = 30000 and frame_duration = 1001. To set up multiple video tracks with different formats and/or codecs, use lqt_add_video_track .

int lqt_add_video_track | ( | quicktime_t * | file,
|  | int | frame_w,
|  | int | frame_h,
|  | int | frame_duration,
|  | int | timescale,
|  | lqt_codec_info_t * | codec_info |
| ) |  |  |

Add a video track for encoding.

Parameters:

  | file | A quicktime handle
  | frame_w | Image width
  | frame_h | Image height
  | frame_duration | Duration of one frame. This can later be overridden
  | timescale | Timescale of the track
  | codec_info | Codec to use (see Codec registry )

This sets one or more video tracks for encoding. The framerate is passed as a rational number (timescale/frame_duration). E.g. for an NTSC stream, you'll choose timescale = 30000 and frame_duration = 1001. Call this function to subsequently to add as many tracks as you like.

int lqt_set_video_pass | ( | quicktime_t * | file,
|  | int | pass,
|  | int | total_passes,
|  | const char * | stats_file,
|  | int | track |
| ) |  |  |

Enable multipass encoding.

Parameters:

  | file | A quicktime handle
  | track | Track index (starting with 0)
  | pass | The number of this pass (starting with 1)
  | total_passes | The total number of passes
  | stats_file | Statistics file

This is a purely optional function, which enables multipass encoding. Multipass encoding is done by repeatedly opening a quicktime file, encoding video and and closing it again. The stats_file parameter must always be the same for all passes.

Having more than 2 passes is not always useful. Audio encoding can be skipped for all passes until the last one.

int lqt_encode_video | ( | quicktime_t * | file,
|  | unsigned char ** | row_pointers,
|  | int | track,
|  | int64_t | time |
| ) |  |  |

Encode one video frame.

Parameters:

  | file | A quicktime handle
  | row_pointers | Frame (see lqt_rows_alloc)
  | track | Track index (starting with 0)
  | time | Timestamp of the frame in timescale tics

Returns:
  0 if the frame was encoded, 1 else.

Encode one video frame. The presentation timestamp is in timescale tics with the timescale you passed to lqt_add_video_track or lqt_set_video . WARNING: AVI files don't support arbitrary timestamps. For AVI files time is ignored, instead it's frame_number * frame_duration,

int lqt_encode_video_d | ( | quicktime_t * | file,
|  | unsigned char ** | row_pointers,
|  | int | track,
|  | int64_t | time,
|  | int | duration |
| ) |  |  |

Encode one video frame.

Parameters:

  | file | A quicktime handle
  | row_pointers | Frame (see lqt_rows_alloc)
  | track | Track index (starting with 0)
  | time | Timestamp of the frame in timescale tics
  | duration | Duration of the frame

Returns:
  0 if the frame was encoded, 1 else.

This is the same as lqt_encode_video except that you can pass the duration along with the timestamp. This is really only important for the last picture, since all other durations are calculated from the timestamp differences.

Since 1.1.2