Libquicktime API usage

1. API conventions
2. Opening/Closing
3. Reading
    3.1 Getting audio information
    3.2 Decoding audio
    3.3 Audio seeking
    3.4 Getting video information
    3.5 Decoding video
    3.6 Video seeking
    3.7 Global information
4. Writing
    4.1 Setting metadata
    4.2 Setting up tracks
    4.3 Setting codec parameters
    4.4 Making an AVI
    4.5 Encoding audio
    4.6 Encoding video
    4.7 Making streamable quicktime
5. Colormodels
6. Codec registry interface

1. API Conventions

The libquicktime API is kept quite similar to the quicktime4linux API. All libquicktime specific extensions are prefixed with lqt_ or LQT_. Libquicktime makes however, a bit more use of enums. In this file, some not recommended functions are not documented. Brave people might consult the files <quicktime/quicktime.h> and <quicktime/lqt.h> for the whole truth.

2. Opening/Closing

To open a Quicktime or sufficiently compatible AVI file, use:

quicktime_t* quicktime_open(const char *filename, int rd, int wr);

This returns an opaque pointer type quicktime_t* or NULL if the file could not be opened. The returned handle is the first argument for most libquicktime functions. The arguments rd and wr specify if the file will be opened for reading or writing. Only one of both can be TRUE. After you are done with it, close the handle with

int quicktime_close(quicktime_t *file);

3. Reading quicktime files

3.1 Getting audio information

First, get the number of audio streams with:

int quicktime_audio_tracks(quicktime_t *file);

Then, for each track, call:

int quicktime_track_channels(quicktime_t *file, int track);
long quicktime_sample_rate(quicktime_t *file, int track);
long quicktime_audio_length(quicktime_t *file, int track);
int quicktime_audio_bits(quicktime_t *file, int track);

to get channel count, the samplerate, length (in samples) and bits per sample. The last value is for information purposes only. While the audio format is always available from the quicktime container, it can happen, that the codec isn't supported by libquicktime. To make sure, that an audio track can be decoded, check if the return value of

int quicktime_supported_audio(quicktime_t *file, int track);

is nonzero. Then, before you decode the first samples, you can set some codec parameters. This works exactly the same way as for encoding (see Setting codec parameters).

3.2 Decoding audio

There are 3 functions for decoding audio. The most recommended one is:

int lqt_decode_audio_track(quicktime_t *file, int16_t **output_i, float **output_f, long samples, int track);

output_i and output_f are pointers to arrays where the samples for the channels will be copied. Either of both arrays can be NULL. Single channel arrays can also be NULL if some channels are not of interest.
The quicktime4linux API (unlike ours) hides the concept of an audio track from the user. To resemble this behaviour, there is a function:

int lqt_decode_audio(quicktime_t *file, int16_t **output_i, float **output_f, long samples);

It decodes all channels of all tracks at once. Finally, there is the quicktime4linux approach (for compatibility reasons):

int quicktime_decode_audio(quicktime_t *file, int16_t *output_i, float *output_f, long samples, int channel);

It's not recommended, because if you need more than one channel, you must seek backwards between the decode calls.
After decoding, you can use

int64_t lqt_last_audio_position(quicktime_t * file, int track);

It returns the REAL sample position of the stream. You can use this to check, if you decoded fewer samples than you wanted. In this case, EOF is reached.

3.3 Audio seeking

To set an audio stream to a specified position, use:

int quicktime_set_audio_position(quicktime_t *file, int64_t sample, int track);

Subsequent decode calls will then start from the specified sample position. Seeking is sample-accurate except for AVI files with compressed audio due to file format weaknesses.

3.4 Getting video information

First, get the number of video tracks with:

int quicktime_video_tracks(quicktime_t *file);

For each track, get the video format with:

int quicktime_video_width(quicktime_t *file, int track);
int quicktime_video_height(quicktime_t *file, int track);
int lqt_video_time_scale(quicktime_t * file, int track);
double quicktime_frame_rate(quicktime_t *file, int track);
long quicktime_video_length(quicktime_t *file, int track);
int64_t lqt_video_duration(quicktime_t * file, int track);
int quicktime_video_depth(quicktime_t *file, int track);

The last function is for information only. You can either use the framerate (and quicktime_video_length) for your synchronization or the timescale (and lqt_video_duration). The timescale method has the advantage, that you make no rounding errors and can synchronize tracks with nonconstant framerates. While the video format is always available from the quicktime container, it can happen, that the codec isn't supported by libquicktime. To make sure, that a video track can be decoded, check if the return value of

int quicktime_supported_video(quicktime_t *file, int track);

is nonzero. Then, before you decode the first frame, you can set some codec parameters. This works exactly the same way as for encoding (see Setting codec parameters).

3.5 Decoding video

After you figured out the proper colormodel (see colormodels) and before decoding the first frame, call:

lqt_set_cmodel(quicktime_t *file, int track, int colormodel);

Furthermore, you might have planar video frames (e.g. XVideo images) which have padded scanlines. To tell this to the library, use:

void lqt_set_row_span(quicktime_t *file, int track, int row_span);
void lqt_set_row_span_uv(quicktime_t *file, int track, int row_span_uv);

The first one sets the byte offsets between the scane lines for the luminance plane, the second one is for the chrominance planes. Then, you can get the timestamp and duration of the NEXT frame to be decoded with:

int64_t lqt_frame_time(quicktime_t * file, int track);

The unit are timescale tics. Finally, decode the frame with:

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

row_pointers points to the scanline beginnings for packed formats and to the planes for planar formats. Alternatively, you can use:

long quicktime_decode_scaled(quicktime_t *file,
        int in_x, /* Location of input frame to take picture */
        int in_y,
        int in_w,
        int in_h,
        int out_w, /* Dimensions of output frame */
        int out_h,
        int color_model,
        unsigned char **row_pointers,
        int track);

It lets you take a rectangular area from the file and writes it into the buffer at a specified location. If input size and output size are different, the image will be scaled. Finally, there is a legacy version, which will only work for BC_RGB888:

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

3.6 Video seeking

There are different approaches depending on your timing method.

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

seeks to the specified time given in timescale tics. Since the timestamp of the next frame might be slightly different from
the time you seeked to, use lqt_frame_time to get the timestamp of the next frame. If you trust the framerate and just count frames, you can use:

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

3.7 Global information

These are for information only. They play no role in the decoding process. To find out, if the file is an AVI, use

int lqt_is_avi(quicktime_t *file);

Then, you can get the metadata as strings:

char* quicktime_get_copyright(quicktime_t *file);
char* quicktime_get_name(quicktime_t *file);
char* quicktime_get_info(quicktime_t *file);
char * lqt_get_album(quicktime_t * file);
char * lqt_get_artist(quicktime_t * file);
char * lqt_get_genre(quicktime_t * file);
char * lqt_get_track(quicktime_t * file);
char * lqt_get_comment(quicktime_t *file);
char * lqt_get_author(quicktime_t *file);

Treat the return values as if they were const. No, libquicktime isn't really const friendly ;-(

4. Writing Quicktime files

4.1 Setting metadata

First, you might want to insert some information strings into your file. Do this with:

void quicktime_set_copyright(quicktime_t *file, char *string);
void quicktime_set_name(quicktime_t *file, char *string);
void quicktime_set_info(quicktime_t *file, char *string);
void lqt_set_album(quicktime_t *file, char *string);
void lqt_set_artist(quicktime_t *file, char *string);
void lqt_set_genre(quicktime_t *file, char *string);
void lqt_set_track(quicktime_t *file, char *string);
void lqt_set_comment(quicktime_t *file, char *string);
void lqt_set_author(quicktime_t *file, char *string);

4.2 Setting up tracks

To add an audio track, call:

int lqt_add_audio_track(quicktime_t *file,
            int channels, long sample_rate, int bits, lqt_codec_info_t * info);

The bits argument is only relevant for the twos and sowt codecs. It should be set to 16 by default. To add a video track, use:

int lqt_add_video_track(quicktime_t *file,
                        int frame_w, int frame_h,
                        int frame_duration, int timescale,
                        lqt_codec_info_t * info);

The frame_duration should is only important, if you use quicktime_encode_video (see below).

4.3 Setting codec parameters

To set a parameter of audio and video codecs, call

void lqt_set_audio_parameter(quicktime_t *file,int stream, char *key,void *value);
void lqt_set_video_parameter(quicktime_t *file,int stream, char *key,void *value);

value must be of type char* for string parameters and int* for integer parameters. See Codec registry interface for methods to find out the encoding parameters.

4.4 Making an AVI

After you configured all codecs, you can tell the library to make an AVI instead of a Quicktime file. It's done with:

void quicktime_set_avi(quicktime_t *file, 1);

Please note, that not all codecs are supported with AVI files. Some are only supported in AVIs. See Codec registry interface for more informtation about this.

4.5 Encoding audio

To encode a buffer full of samples, use

int lqt_encode_audio_track(quicktime_t *file,
                           int16_t **channels_i,
                           float **channels_f,
                           long samples,
                           int track);

Either channels_i or channels_f must be NULL.

4.6 Encoding video

Before you encode the first frame, you must decide which colormodel you use (see Colormodels). You tell the library about the colormodel with:

void lqt_set_cmodel(quicktime_t *file, int track, int colormodel);

Then, if you will use a planar format, and your memory had padded scanlines, tell the byte offsets between the scanlines of the luminance and chrominance planes:

void lqt_set_row_span(quicktime_t *file, int track, int row_span);
void lqt_set_row_span_uv(quicktime_t *file, int track, int row_span_uv);

Finally, if you source has individual tinestamps for all frames, call

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

The timestamp is given in timescale tics. row_pointers contains the scanlines for packet formats and the planes
for planar formats. If you have a constant frame duration and passed it to lqt_add_video_track, you might also use:

int quicktime_encode_video(quicktime_t *file,
        unsigned char **row_pointers,
        int track);

4.7 Making streamable Quicktime

By default, libquicktime will put the header (the moov atom) at the end of the file. This means, that it won't be playable from a non-seekable source (i.e. a http connection). To reorder the file to have the header at the start, call:

int quicktime_make_streamable(char *in_path, char *out_path);

This function must be called after you closed the file with quicktime_close. Note that you need twice the disk space for this function.

5. Colormodels

The supported colormodels are defined in colormodels.h. Libquicktime adds another value LQT_COLORMODEL_NONE, which specifies an uninitialized or unknown colormodel. Informations about the supported colormodels can be obtained with:

const char * lqt_colormodel_to_string(int colormodel);
int lqt_string_to_colormodel(const char * str);
int lqt_colormodel_is_planar(int colormodel);
int lqt_colormodel_has_alpha(int colormodel);
int lqt_colormodel_is_rgb(int colormodel);
int lqt_colormodel_is_yuv(int colormodel);

int lqt_num_colormodels();
const char * lqt_get_colormodel_string(int index);
int lqt_get_colormodel(int index);

The best idea is to decide, which colormodels you want to support in your application. BC_RGB888 and BC_YUV420P should always be supported. Please note, that libquicktimes internal colorspace converter is not the fastest out there. The more colorspaces you can handle yourself, the fewer time consuming internal conversions will be used. A nice library, which converts many libquicktime colormodels, is gavl. Then call for each video track:

int lqt_get_best_colormodel(quicktime_t * file, int track, int * supported);

supported is an array of the colorspaces, you can handle terminated with LQT_COLORMODEL_NONE. The function works for both en- and decoding and tries to minimize conversion overhead and information loss.

6. Codec registry interface

This allows you to access the codecs, which are installed on the system along with information about them. To query the registry about the installed codecs, use:

lqt_codec_info_t ** lqt_query_registry(int audio, int video,
                                       int encode, int decode);

The return value is a NULL terminated array of lqt_codec_info_t pointers. The codec info is defined in lqt_codecinfo.h:

typedef struct lqt_codec_info_s lqt_codec_info_t;

struct lqt_codec_info_s
{
int compatibility_flags; /* Compatibility flags (See defines above) */
char * name;               /* Name of the codec              */
char * long_name;          /* Long name of the codec         */
char * description;        /* Description                    */
lqt_codec_type type;
lqt_codec_direction direction;
int num_fourccs;           /* Fourccs, this codec can handle */
char ** fourccs;
int num_wav_ids;
int * wav_ids;
int num_encoding_parameters;
lqt_parameter_info_t * encoding_parameters;
int num_decoding_parameters;
lqt_parameter_info_t * decoding_parameters;
/* Colormodels this codec can handle */
int num_encoding_colormodels;
int * encoding_colormodels;

int decoding_colormodel;
/* The following members are set by libquicktime      */
char * module_filename;    /* Filename of the module */
int module_index;          /* Index inside the module */
uint32_t file_time;        /* File modification time */
struct lqt_codec_info_s * next;   /* For chaining */
};

Most interesting are the name, long name and description. The encoding_parameters and decoding_parameters arrays contain informations about the parameters you can pass to lqt_set_[audio|video]_parameter. The parameter infos are defined like this:

typedef enum
{
    LQT_PARAMETER_INT,
    LQT_PARAMETER_STRING,
    LQT_PARAMETER_STRINGLIST, /* String with options */
    /* This dummy type is used to separate sections (real_name will be on tab-label) */
    LQT_PARAMETER_SECTION
} lqt_parameter_type_t;

typedef union
{
int val_int;
char * val_string;
} lqt_parameter_value_t;

typedef struct
{
/* Parameter name (to be passed to quicktime_set_parameter() ) */
char * name;
char * real_name; /* Other name (for making dialogs) */
lqt_parameter_type_t type;
lqt_parameter_value_t val_default;
/*
   *   Minimum and maximum values:
   *   These are only valid for numeric types and if val_min < val_max
   */
int val_min;
int val_max;
/*
   * Possible options (only valid for LQT_STRINGLIST)
   */
int num_stringlist_options;
char ** stringlist_options;
} lqt_parameter_info_t;

You can also get the codec infos, when you read a file:

lqt_codec_info_t ** lqt_audio_codec_from_file(quicktime_t *, int track);
lqt_codec_info_t ** lqt_video_codec_from_file(quicktime_t *, int track);

Codec infos are returned as a local copy, so you must free them. This is done with:

void lqt_destroy_codec_info(lqt_codec_info_t ** info);