libquicktime
quicktime.h
Go to the documentation of this file.
1 /*******************************************************************************
2  quicktime.h
3 
4  libquicktime - A library for reading and writing quicktime/avi/mp4 files.
5  http://libquicktime.sourceforge.net
6 
7  Copyright (C) 2002 Heroine Virtual Ltd.
8  Copyright (C) 2002-2011 Members of the libquicktime project.
9 
10  This library is free software; you can redistribute it and/or modify it under
11  the terms of the GNU Lesser General Public License as published by the Free
12  Software Foundation; either version 2.1 of the License, or (at your option)
13  any later version.
14 
15  This library is distributed in the hope that it will be useful, but WITHOUT
16  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17  FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
18  details.
19 
20  You should have received a copy of the GNU Lesser General Public License along
21  with this library; if not, write to the Free Software Foundation, Inc., 51
22  Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
23 *******************************************************************************/
24 
25 #ifndef QUICKTIME_H
26 #define QUICKTIME_H
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 #include <inttypes.h>
33 #include <stddef.h>
34 
35 #pragma GCC visibility push(default)
36 
37 /* Some public enums needed by most subsequent headers */
38 
39 typedef struct lqt_codec_info_s lqt_codec_info_t;
40 
41 
124 typedef enum
125  {
126  LQT_LOG_ERROR = (1<<0),
127  LQT_LOG_WARNING = (1<<1),
128  LQT_LOG_INFO = (1<<2),
129  LQT_LOG_DEBUG = (1<<3),
130  } lqt_log_level_t;
131 
140 typedef void (*lqt_log_callback_t)(lqt_log_level_t level,
141  const char * domain,
142  const char * message,
143  void * data);
144 
145 
152 typedef enum
153  {
155  LQT_FILE_QT_OLD = (1<<0),
156  LQT_FILE_QT = (1<<1),
157  LQT_FILE_AVI = (1<<2),
158  LQT_FILE_AVI_ODML = (1<<3),
159  LQT_FILE_MP4 = (1<<4),
160  LQT_FILE_M4A = (1<<5),
161  LQT_FILE_3GP = (1<<6),
162  } lqt_file_type_t;
163 
164 
175 typedef enum
176  {
177  LQT_CHANNEL_UNKNOWN,
178  LQT_CHANNEL_FRONT_LEFT,
179  LQT_CHANNEL_FRONT_RIGHT,
180  LQT_CHANNEL_FRONT_CENTER,
181  LQT_CHANNEL_FRONT_CENTER_LEFT,
182  LQT_CHANNEL_FRONT_CENTER_RIGHT,
183  LQT_CHANNEL_BACK_CENTER,
184  LQT_CHANNEL_BACK_LEFT,
185  LQT_CHANNEL_BACK_RIGHT,
186  LQT_CHANNEL_SIDE_LEFT,
187  LQT_CHANNEL_SIDE_RIGHT,
188  LQT_CHANNEL_LFE,
189  } lqt_channel_t;
190 
191 
255 typedef enum
256  {
261 
271 typedef enum
272  {
277 
287 typedef enum
288  {
297 
306 typedef struct quicktime_s quicktime_t;
307 
308 /* This is the reference for all your library entry points. */
309 
310 /* ===== compression formats for which codecs exist ====== */
311 
331 #define QUICKTIME_DIVX "DIVX"
332 
339 #define QUICKTIME_DIV3 "DIV3"
340 
347 #define QUICKTIME_DV "dvc "
348 /* AVID DV codec can be processed with libdv as well */
349 
356 #define QUICKTIME_DV_AVID "AVdv"
357 
364 #define QUICKTIME_DV_AVID_A "dvcp"
365 
373 /* RGB uncompressed. Allows alpha */
374 #define QUICKTIME_RAW "raw "
375 
382 /* Jpeg Photo */
383 #define QUICKTIME_JPEG "jpeg"
384 
385 /* Concatenated png images. Allows alpha */
386 
394 #define QUICKTIME_PNG "png "
395 
403 #define QUICKTIME_MJPA "mjpa"
404 
411 #define QUICKTIME_YUV2 "yuv2"
412 
419 #define QUICKTIME_YUV4 "yuv4"
420 
428 #define QUICKTIME_YUV420 "yv12"
429 
436 #define QUICKTIME_2VUY "2vuy"
437 
444 #define QUICKTIME_YUVS "yuvs"
445 
446 
453 #define QUICKTIME_V308 "v308"
454 
461 #define QUICKTIME_V408 "v408"
462 
469 #define QUICKTIME_V210 "v210"
470 
477 #define QUICKTIME_V410 "v410"
478 
479 /* =================== Audio formats ======================= */
480 
500 #define QUICKTIME_RAWAUDIO "raw "
501 
508 #define QUICKTIME_IMA4 "ima4"
509 
516 #define QUICKTIME_TWOS "twos"
517 
524 #define QUICKTIME_ULAW "ulaw"
525 
534 #define QUICKTIME_VORBIS "OggS"
535 
543 #define QUICKTIME_MP3 ".mp3"
544 
545 /* =========================== public interface ========================= // */
546 
555  /* Get version information */
557 
566 
576 
588 int quicktime_check_sig(char *path);
589 
600 quicktime_t* quicktime_open(const char *filename, int rd, int wr);
601 
614 int quicktime_make_streamable(char *in_path, char *out_path);
615 
629 void quicktime_set_copyright(quicktime_t *file, char *string);
630 
637 void quicktime_set_name(quicktime_t *file, char *string);
638 
645 void quicktime_set_info(quicktime_t *file, char *string);
646 
655 
664 
672 
673 
690  int channels,
691  long sample_rate,
692  int bits,
693  char *compressor);
694 
705 void quicktime_set_framerate(quicktime_t *file, double framerate);
706 
723  int tracks,
724  int frame_w,
725  int frame_h,
726  double frame_rate,
727  char *compressor);
728 
742 void quicktime_set_jpeg(quicktime_t *file, int quality, int use_float);
743 
758 void quicktime_set_parameter(quicktime_t *file, char *key, void *value);
759 
771  int depth,
772  int track);
773 
783 void quicktime_set_cmodel(quicktime_t *file, int colormodel);
784 
795 void quicktime_set_row_span(quicktime_t *file, int row_span);
796 
803 
804 /* get length information */
805 /* channel numbers start on 1 for audio and video */
806 
815 long quicktime_audio_length(quicktime_t *file, int track);
816 
828 long quicktime_video_length(quicktime_t *file, int track);
829 
837  /* get position information */
838 long quicktime_audio_position(quicktime_t *file, int track);
839 
849 long quicktime_video_position(quicktime_t *file, int track);
850 
857 /* get file information */
859 
867 
875 
883 long quicktime_sample_rate(quicktime_t *file, int track);
884 
899 int quicktime_audio_bits(quicktime_t *file, int track);
900 
908 int quicktime_track_channels(quicktime_t *file, int track);
909 
922 char* quicktime_audio_compressor(quicktime_t *file, int track);
923 
931 
939 int quicktime_video_width(quicktime_t *file, int track);
940 
948 int quicktime_video_height(quicktime_t *file, int track);
949 
964 int quicktime_video_depth(quicktime_t *file, int track);
965 
980 double quicktime_frame_rate(quicktime_t *file, int track);
981 
992 char* quicktime_video_compressor(quicktime_t *file, int track);
993 
994 /* number of bytes of raw data in this frame */
995 
1007 long quicktime_frame_size(quicktime_t *file, long frame, int track);
1008 
1018 int quicktime_channel_location(quicktime_t *file, int *quicktime_track, int *quicktime_channel, int channel);
1019 
1020 /* file positioning */
1021 /* Remove these and see what happens :) */
1022 
1023 // int quicktime_seek_end(quicktime_t *file);
1024 
1034 
1035 /* set position of file descriptor relative to a track */
1036 
1045 int quicktime_set_audio_position(quicktime_t *file, int64_t sample, int track);
1046 
1057 int quicktime_set_video_position(quicktime_t *file, int64_t frame, int track);
1058 
1059 /* ========================== Access to raw data follows. */
1060 /* write data for one quicktime track */
1061 /* the user must handle conversion to the channels in this track */
1062 int quicktime_write_audio(quicktime_t *file, uint8_t *audio_buffer, long samples, int track);
1063 
1078 int quicktime_write_frame(quicktime_t *file, uint8_t *video_buffer, int64_t bytes, int track);
1079 
1092 long quicktime_read_frame(quicktime_t *file, unsigned char *video_buffer, int track);
1093 
1094 /* for reading frame using a library that needs a file descriptor */
1095 /* Frame caching doesn't work here. */
1096 int quicktime_read_frame_init(quicktime_t *file, int track);
1097 int quicktime_read_frame_end(quicktime_t *file, int track);
1098 
1099 /* One keyframe table for each track */
1100 long quicktime_get_keyframe_before(quicktime_t *file, long frame, int track);
1101 void quicktime_insert_keyframe(quicktime_t *file, long frame, int track);
1102 /* Track has keyframes */
1103 int quicktime_has_keyframes(quicktime_t *file, int track);
1104 
1105 /* ===================== Access to built in codecs follows. */
1106 
1107 /* If the codec for this track is supported in the library return 1. */
1108 
1117 
1126 
1139  int colormodel,
1140  int track);
1141 
1154  int colormodel,
1155  int track);
1156 
1157 
1158 /* Hacks for temporal codec */
1159 int quicktime_divx_is_key(unsigned char *data, long size);
1160 int quicktime_divx_write_vol(unsigned char *data_start,
1161  int vol_width,
1162  int vol_height,
1163  int time_increment_resolution,
1164  double frame_rate);
1165 int quicktime_divx_has_vol(unsigned char *data);
1166 
1167 int quicktime_div3_is_key(unsigned char *data, long size);
1168 
1180  unsigned char **row_pointers,
1181  int track);
1182 
1194  unsigned char **row_pointers,
1195  int track);
1196 
1218  int in_x, /* Location of input frame to take picture */
1219  int in_y,
1220  int in_w,
1221  int in_h,
1222  int out_w, /* Dimensions of output frame */
1223  int out_h,
1224  int color_model, /* One of the color models defined above */
1225  unsigned char **row_pointers,
1226  int track);
1227 
1228 /* Decode or encode audio for a single channel into the buffer. */
1229 /* Pass a buffer for the _i or the _f argument if you want int16 or float data. */
1230 /* Notice that encoding requires an array of pointers to each channel. */
1231 
1249 int quicktime_decode_audio(quicktime_t *file, int16_t *output_i, float *output_f, long samples, int channel);
1250 
1263 int quicktime_encode_audio(quicktime_t *file, int16_t **input_i, float **input_f, long samples);
1264 
1273 
1274 /* Specify the number of cpus to utilize. */
1275 
1286 int quicktime_set_cpus(quicktime_t *file, int cpus);
1287 
1288 /* Specify whether to read contiguously or not. */
1289 /* preload is the number of bytes to read ahead. */
1290 /* This is no longer functional to the end user but is used to accelerate */
1291 /* reading the header internally. */
1292 void quicktime_set_preload(quicktime_t *file, int64_t preload);
1293 
1294 int64_t quicktime_byte_position(quicktime_t *file);
1295 
1304 void quicktime_set_avi(quicktime_t *file, int value);
1305 
1306 #pragma GCC visibility pop
1307 
1308 
1309 #ifdef __cplusplus
1310 }
1311 #endif
1312 
1313 #endif
quicktime_set_name
void quicktime_set_name(quicktime_t *file, char *string)
Set the name for the file.
quicktime_video_length
long quicktime_video_length(quicktime_t *file, int track)
Get the video length.
quicktime_audio_tracks
int quicktime_audio_tracks(quicktime_t *file)
Get the number of audio tracks.
lqt_log_callback_t
void(* lqt_log_callback_t)(lqt_log_level_t level, const char *domain, const char *message, void *data)
Log callback.
Definition: quicktime.h:140
LQT_INTERLACE_TOP_FIRST
@ LQT_INTERLACE_TOP_FIRST
Definition: quicktime.h:258
LQT_FILE_M4A
@ LQT_FILE_M4A
Definition: quicktime.h:160
LQT_SAMPLE_FLOAT
@ LQT_SAMPLE_FLOAT
Definition: quicktime.h:294
quicktime_set_video_position
int quicktime_set_video_position(quicktime_t *file, int64_t frame, int track)
Seek to a specific video frame.
quicktime_video_height
int quicktime_video_height(quicktime_t *file, int track)
Get the height of a video track.
LQT_SAMPLE_UINT8
@ LQT_SAMPLE_UINT8
Definition: quicktime.h:291
quicktime_audio_position
long quicktime_audio_position(quicktime_t *file, int track)
Get the audio position.
quicktime_decode_audio
int quicktime_decode_audio(quicktime_t *file, int16_t *output_i, float *output_f, long samples, int channel)
Decode a number of audio samples of a single channel.
quicktime_release
int quicktime_release()
Get the quicktime4linux release number.
LQT_FILE_AVI_ODML
@ LQT_FILE_AVI_ODML
Definition: quicktime.h:158
LQT_FILE_3GP
@ LQT_FILE_3GP
Definition: quicktime.h:161
lqt_file_type_t
lqt_file_type_t
File types.
Definition: quicktime.h:153
quicktime_check_sig
int quicktime_check_sig(char *path)
Test file compatibility.
lqt_sample_format_t
lqt_sample_format_t
Sample format definitions for audio.
Definition: quicktime.h:288
quicktime_video_position
long quicktime_video_position(quicktime_t *file, int track)
Get the video position.
quicktime_encode_audio
int quicktime_encode_audio(quicktime_t *file, int16_t **input_i, float **input_f, long samples)
Encode a number of audio samples for the first track.
quicktime_make_streamable
int quicktime_make_streamable(char *in_path, char *out_path)
Make a file streamable.
quicktime_audio_compressor
char * quicktime_audio_compressor(quicktime_t *file, int track)
Get the four character code of an audio track.
quicktime_has_audio
int quicktime_has_audio(quicktime_t *file)
Check if a file has at least one audio track.
quicktime_channel_location
int quicktime_channel_location(quicktime_t *file, int *quicktime_track, int *quicktime_channel, int channel)
quicktime_set_audio_position
int quicktime_set_audio_position(quicktime_t *file, int64_t sample, int track)
Seek to a specific audio position.
quicktime_close
int quicktime_close(quicktime_t *file)
Close a quicktime handle and free all associated memory.
quicktime_set_cpus
int quicktime_set_cpus(quicktime_t *file, int cpus)
Set the number of CPUs.
LQT_FILE_QT_OLD
@ LQT_FILE_QT_OLD
Definition: quicktime.h:155
LQT_FILE_MP4
@ LQT_FILE_MP4
Definition: quicktime.h:159
lqt_channel_t
lqt_channel_t
Channel definitions.
Definition: quicktime.h:176
quicktime_decode_video
int quicktime_decode_video(quicktime_t *file, unsigned char **row_pointers, int track)
Decode a video frame in BC_RGB888.
quicktime_video_tracks
int quicktime_video_tracks(quicktime_t *file)
Get the number of video tracks.
quicktime_seek_start
int quicktime_seek_start(quicktime_t *file)
Reposition all tracks to the very beginning.
lqt_interlace_mode_t
lqt_interlace_mode_t
interlace modes
Definition: quicktime.h:256
quicktime_set_parameter
void quicktime_set_parameter(quicktime_t *file, char *key, void *value)
Set a codec parameter.
quicktime_set_depth
void quicktime_set_depth(quicktime_t *file, int depth, int track)
Set the depth of a video track.
quicktime_has_video
int quicktime_has_video(quicktime_t *file)
Check if a file has at least one video track.
quicktime_audio_bits
int quicktime_audio_bits(quicktime_t *file, int track)
Get the bits per sample of an audio track.
LQT_INTERLACE_NONE
@ LQT_INTERLACE_NONE
Definition: quicktime.h:257
quicktime_set_avi
void quicktime_set_avi(quicktime_t *file, int value)
Write an AVI file instead of quicktime.
LQT_FILE_AVI
@ LQT_FILE_AVI
Definition: quicktime.h:157
LQT_SAMPLE_DOUBLE
@ LQT_SAMPLE_DOUBLE
Definition: quicktime.h:295
quicktime_track_channels
int quicktime_track_channels(quicktime_t *file, int track)
Get the number of channels of an audio track.
quicktime_reads_cmodel
int quicktime_reads_cmodel(quicktime_t *file, int colormodel, int track)
Check if a colormodel is supported for decoding.
lqt_chroma_placement_t
lqt_chroma_placement_t
Chroma placement.
Definition: quicktime.h:272
quicktime_set_framerate
void quicktime_set_framerate(quicktime_t *file, double framerate)
Set the framerate for encoding.
quicktime_supported_audio
int quicktime_supported_audio(quicktime_t *file, int track)
Check if an audio track is supported by libquicktime.
LQT_SAMPLE_INT16
@ LQT_SAMPLE_INT16
Definition: quicktime.h:292
quicktime_decode_scaled
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.
quicktime_open
quicktime_t * quicktime_open(const char *filename, int rd, int wr)
Open a file.
quicktime_read_frame
long quicktime_read_frame(quicktime_t *file, unsigned char *video_buffer, int track)
Read a compressed video frame.
LQT_SAMPLE_INT8
@ LQT_SAMPLE_INT8
Definition: quicktime.h:290
LQT_INTERLACE_BOTTOM_FIRST
@ LQT_INTERLACE_BOTTOM_FIRST
Definition: quicktime.h:259
quicktime_frame_size
long quicktime_frame_size(quicktime_t *file, long frame, int track)
Get the compressed size of frame in a video track.
LQT_FILE_QT
@ LQT_FILE_QT
Definition: quicktime.h:156
quicktime_sample_rate
long quicktime_sample_rate(quicktime_t *file, int track)
Get the samplerate of an audio track.
quicktime_set_info
void quicktime_set_info(quicktime_t *file, char *string)
Set info for the file.
quicktime_video_width
int quicktime_video_width(quicktime_t *file, int track)
Get the width of a video track.
quicktime_set_cmodel
void quicktime_set_cmodel(quicktime_t *file, int colormodel)
Set the colormodel for en-/decoding.
quicktime_set_row_span
void quicktime_set_row_span(quicktime_t *file, int row_span)
Set the row_span for en-/decoding.
quicktime_dump
int quicktime_dump(quicktime_t *file)
Dump the file structures to stdout.
LQT_CHROMA_PLACEMENT_DEFAULT
@ LQT_CHROMA_PLACEMENT_DEFAULT
Definition: quicktime.h:273
LQT_FILE_NONE
@ LQT_FILE_NONE
Definition: quicktime.h:154
quicktime_set_video
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.
quicktime_major
int quicktime_major()
Get the quicktime4linux major version.
quicktime_set_copyright
void quicktime_set_copyright(quicktime_t *file, char *string)
Set the copyright info for the file.
lqt_codec_info_s
Structure describing a codec.
Definition: lqt_codecinfo.h:188
lqt_log_level_t
lqt_log_level_t
Log level.
Definition: quicktime.h:125
LQT_SAMPLE_UNDEFINED
@ LQT_SAMPLE_UNDEFINED
Definition: quicktime.h:289
quicktime_frame_rate
double quicktime_frame_rate(quicktime_t *file, int track)
Get the framerate of a video track.
quicktime_set_audio
int quicktime_set_audio(quicktime_t *file, int channels, long sample_rate, int bits, char *compressor)
Set up tracks in a new file after opening and before writing.
quicktime_get_copyright
char * quicktime_get_copyright(quicktime_t *file)
Get the copyright info from the file.
quicktime_get_name
char * quicktime_get_name(quicktime_t *file)
Get the name from the file.
quicktime_minor
int quicktime_minor()
Get the quicktime4linux minor version.
quicktime_video_compressor
char * quicktime_video_compressor(quicktime_t *file, int track)
Get the four character code of a video track.
quicktime_writes_cmodel
int quicktime_writes_cmodel(quicktime_t *file, int colormodel, int track)
Check if a colormodel is supported for encoding.
quicktime_write_frame
int quicktime_write_frame(quicktime_t *file, uint8_t *video_buffer, int64_t bytes, int track)
Write a compressed video frame.
quicktime_t
struct quicktime_s quicktime_t
Quicktime handle.
Definition: quicktime.h:306
quicktime_video_depth
int quicktime_video_depth(quicktime_t *file, int track)
Get the depth of a video track.
quicktime_audio_length
long quicktime_audio_length(quicktime_t *file, int track)
Get the audio length.
quicktime_get_info
char * quicktime_get_info(quicktime_t *file)
Get the info string from the file.
quicktime_set_jpeg
void quicktime_set_jpeg(quicktime_t *file, int quality, int use_float)
Set jpeg encoding quality.
quicktime_supported_video
int quicktime_supported_video(quicktime_t *file, int track)
Check if a video track is supported by libquicktime.
LQT_CHROMA_PLACEMENT_MPEG2
@ LQT_CHROMA_PLACEMENT_MPEG2
Definition: quicktime.h:274
LQT_CHROMA_PLACEMENT_DVPAL
@ LQT_CHROMA_PLACEMENT_DVPAL
Definition: quicktime.h:275
LQT_SAMPLE_INT32
@ LQT_SAMPLE_INT32
Definition: quicktime.h:293
quicktime_encode_video
int quicktime_encode_video(quicktime_t *file, unsigned char **row_pointers, int track)
Encode a video frame.