Libquicktime API usage
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:
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);