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 #ifdef __GNUC__
36 #pragma GCC visibility push(default)
37 #endif
38 
39 /* Some public enums needed by most subsequent headers */
40 
41 typedef struct lqt_codec_info_s lqt_codec_info_t;
42 
43 
126 typedef enum
127  {
128  LQT_LOG_ERROR = (1<<0),
129  LQT_LOG_WARNING = (1<<1),
130  LQT_LOG_INFO = (1<<2),
131  LQT_LOG_DEBUG = (1<<3),
132  } lqt_log_level_t;
133 
142 typedef void (*lqt_log_callback_t)(lqt_log_level_t level,
143  const char * domain,
144  const char * message,
145  void * data);
146 
147 
154 typedef enum
155  {
157  LQT_FILE_QT_OLD = (1<<0),
158  LQT_FILE_QT = (1<<1),
159  LQT_FILE_AVI = (1<<2),
160  LQT_FILE_AVI_ODML = (1<<3),
161  LQT_FILE_MP4 = (1<<4),
162  LQT_FILE_M4A = (1<<5),
163  LQT_FILE_3GP = (1<<6),
164  } lqt_file_type_t;
165 
166 
177 typedef enum
178  {
179  LQT_CHANNEL_UNKNOWN,
180  LQT_CHANNEL_FRONT_LEFT,
181  LQT_CHANNEL_FRONT_RIGHT,
182  LQT_CHANNEL_FRONT_CENTER,
183  LQT_CHANNEL_FRONT_CENTER_LEFT,
184  LQT_CHANNEL_FRONT_CENTER_RIGHT,
185  LQT_CHANNEL_BACK_CENTER,
186  LQT_CHANNEL_BACK_LEFT,
187  LQT_CHANNEL_BACK_RIGHT,
188  LQT_CHANNEL_SIDE_LEFT,
189  LQT_CHANNEL_SIDE_RIGHT,
190  LQT_CHANNEL_LFE,
191  } lqt_channel_t;
192 
193 
257 typedef enum
258  {
263 
273 typedef enum
274  {
279 
289 typedef enum
290  {
299 
308 typedef struct quicktime_s quicktime_t;
309 
310 /* This is the reference for all your library entry points. */
311 
312 /* ===== compression formats for which codecs exist ====== */
313 
333 #define QUICKTIME_DIVX "DIVX"
334 
341 #define QUICKTIME_DIV3 "DIV3"
342 
349 #define QUICKTIME_DV "dvc "
350 /* AVID DV codec can be processed with libdv as well */
351 
358 #define QUICKTIME_DV_AVID "AVdv"
359 
366 #define QUICKTIME_DV_AVID_A "dvcp"
367 
375 /* RGB uncompressed. Allows alpha */
376 #define QUICKTIME_RAW "raw "
377 
384 /* Jpeg Photo */
385 #define QUICKTIME_JPEG "jpeg"
386 
387 /* Concatenated png images. Allows alpha */
388 
396 #define QUICKTIME_PNG "png "
397 
405 #define QUICKTIME_MJPA "mjpa"
406 
413 #define QUICKTIME_YUV2 "yuv2"
414 
421 #define QUICKTIME_YUV4 "yuv4"
422 
430 #define QUICKTIME_YUV420 "yv12"
431 
438 #define QUICKTIME_2VUY "2vuy"
439 
446 #define QUICKTIME_YUVS "yuvs"
447 
448 
455 #define QUICKTIME_V308 "v308"
456 
463 #define QUICKTIME_V408 "v408"
464 
471 #define QUICKTIME_V210 "v210"
472 
479 #define QUICKTIME_V410 "v410"
480 
481 /* =================== Audio formats ======================= */
482 
502 #define QUICKTIME_RAWAUDIO "raw "
503 
510 #define QUICKTIME_IMA4 "ima4"
511 
518 #define QUICKTIME_TWOS "twos"
519 
526 #define QUICKTIME_ULAW "ulaw"
527 
536 #define QUICKTIME_VORBIS "OggS"
537 
545 #define QUICKTIME_MP3 ".mp3"
546 
547 /* =========================== public interface ========================= // */
548 
557  /* Get version information */
558 int quicktime_major();
559 
567 int quicktime_minor();
568 
577 int quicktime_release();
578 
590 int quicktime_check_sig(char *path);
591 
602 quicktime_t* quicktime_open(const char *filename, int rd, int wr);
603 
616 int quicktime_make_streamable(char *in_path, char *out_path);
617 
631 void quicktime_set_copyright(quicktime_t *file, char *string);
632 
639 void quicktime_set_name(quicktime_t *file, char *string);
640 
647 void quicktime_set_info(quicktime_t *file, char *string);
648 
657 
665 char* quicktime_get_name(quicktime_t *file);
666 
673 char* quicktime_get_info(quicktime_t *file);
674 
675 
692  int channels,
693  long sample_rate,
694  int bits,
695  char *compressor);
696 
707 void quicktime_set_framerate(quicktime_t *file, double framerate);
708 
725  int tracks,
726  int frame_w,
727  int frame_h,
728  double frame_rate,
729  char *compressor);
730 
744 void quicktime_set_jpeg(quicktime_t *file, int quality, int use_float);
745 
760 void quicktime_set_parameter(quicktime_t *file, char *key, void *value);
761 
772 void quicktime_set_depth(quicktime_t *file,
773  int depth,
774  int track);
775 
785 void quicktime_set_cmodel(quicktime_t *file, int colormodel);
786 
797 void quicktime_set_row_span(quicktime_t *file, int row_span);
798 
804 int quicktime_close(quicktime_t *file);
805 
806 /* get length information */
807 /* channel numbers start on 1 for audio and video */
808 
817 long quicktime_audio_length(quicktime_t *file, int track);
818 
830 long quicktime_video_length(quicktime_t *file, int track);
831 
839  /* get position information */
840 long quicktime_audio_position(quicktime_t *file, int track);
841 
851 long quicktime_video_position(quicktime_t *file, int track);
852 
859 /* get file information */
861 
869 
877 
885 long quicktime_sample_rate(quicktime_t *file, int track);
886 
901 int quicktime_audio_bits(quicktime_t *file, int track);
902 
910 int quicktime_track_channels(quicktime_t *file, int track);
911 
924 char* quicktime_audio_compressor(quicktime_t *file, int track);
925 
933 
941 int quicktime_video_width(quicktime_t *file, int track);
942 
950 int quicktime_video_height(quicktime_t *file, int track);
951 
966 int quicktime_video_depth(quicktime_t *file, int track);
967 
982 double quicktime_frame_rate(quicktime_t *file, int track);
983 
994 char* quicktime_video_compressor(quicktime_t *file, int track);
995 
996 /* number of bytes of raw data in this frame */
997 
1009 long quicktime_frame_size(quicktime_t *file, long frame, int track);
1010 
1020 int quicktime_channel_location(quicktime_t *file, int *quicktime_track, int *quicktime_channel, int channel);
1021 
1022 /* file positioning */
1023 /* Remove these and see what happens :) */
1024 
1025 // int quicktime_seek_end(quicktime_t *file);
1026 
1036 
1037 /* set position of file descriptor relative to a track */
1038 
1047 int quicktime_set_audio_position(quicktime_t *file, int64_t sample, int track);
1048 
1059 int quicktime_set_video_position(quicktime_t *file, int64_t frame, int track);
1060 
1061 /* ========================== Access to raw data follows. */
1062 /* write data for one quicktime track */
1063 /* the user must handle conversion to the channels in this track */
1064 int quicktime_write_audio(quicktime_t *file, uint8_t *audio_buffer, long samples, int track);
1065 
1081 int quicktime_write_frame(quicktime_t *file, uint8_t *video_buffer, int64_t bytes, int track);
1082 
1098 long quicktime_read_frame(quicktime_t *file, unsigned char *video_buffer, int track);
1099 
1100 /* for reading frame using a library that needs a file descriptor */
1101 /* Frame caching doesn't work here. */
1102 int quicktime_read_frame_init(quicktime_t *file, int track);
1103 int quicktime_read_frame_end(quicktime_t *file, int track);
1104 
1105 /* One keyframe table for each track */
1106 long quicktime_get_keyframe_before(quicktime_t *file, long frame, int track);
1107 long quicktime_get_partial_keyframe_before(quicktime_t *file, long frame, int track);
1108 void quicktime_insert_keyframe(quicktime_t *file, long frame, int track);
1109 void quicktime_insert_partial_keyframe(quicktime_t *file, long frame, int track);
1110 /* Track has keyframes */
1111 int quicktime_has_keyframes(quicktime_t *file, int track);
1112 
1113 /* Sample dependencies for long-GOP formats. */
1114 void quicktime_insert_sdtp_entry(quicktime_t *file, long frame, int track, uint8_t flags);
1115 
1116 /* ===================== Access to built in codecs follows. */
1117 
1118 /* If the codec for this track is supported in the library return 1. */
1119 
1127 int quicktime_supported_video(quicktime_t *file, int track);
1128 
1136 int quicktime_supported_audio(quicktime_t *file, int track);
1137 
1150  int colormodel,
1151  int track);
1152 
1165  int colormodel,
1166  int track);
1167 
1168 
1169 /* Hacks for temporal codec */
1170 int quicktime_divx_is_key(unsigned char *data, long size);
1171 int quicktime_divx_write_vol(unsigned char *data_start,
1172  int vol_width,
1173  int vol_height,
1174  int time_increment_resolution,
1175  double frame_rate);
1176 int quicktime_divx_has_vol(unsigned char *data);
1177 
1178 int quicktime_div3_is_key(unsigned char *data, long size);
1179 
1191  unsigned char **row_pointers,
1192  int track);
1193 
1205  unsigned char **row_pointers,
1206  int track);
1207 
1229  int in_x, /* Location of input frame to take picture */
1230  int in_y,
1231  int in_w,
1232  int in_h,
1233  int out_w, /* Dimensions of output frame */
1234  int out_h,
1235  int color_model, /* One of the color models defined above */
1236  unsigned char **row_pointers,
1237  int track);
1238 
1239 /* Decode or encode audio for a single channel into the buffer. */
1240 /* Pass a buffer for the _i or the _f argument if you want int16 or float data. */
1241 /* Notice that encoding requires an array of pointers to each channel. */
1242 
1260 int quicktime_decode_audio(quicktime_t *file, int16_t *output_i, float *output_f, long samples, int channel);
1261 
1274 int quicktime_encode_audio(quicktime_t *file, int16_t **input_i, float **input_f, long samples);
1275 
1283 int quicktime_dump(quicktime_t *file);
1284 
1285 /* Specify the number of cpus to utilize. */
1286 
1297 int quicktime_set_cpus(quicktime_t *file, int cpus);
1298 
1299 /* Specify whether to read contiguously or not. */
1300 /* preload is the number of bytes to read ahead. */
1301 /* This is no longer functional to the end user but is used to accelerate */
1302 /* reading the header internally. */
1303 void quicktime_set_preload(quicktime_t *file, int64_t preload);
1304 
1305 int64_t quicktime_byte_position(quicktime_t *file);
1306 
1315 void quicktime_set_avi(quicktime_t *file, int value);
1316 
1317 #ifdef __GNUC__
1318 #pragma GCC visibility pop
1319 #endif
1320 
1321 
1322 #ifdef __cplusplus
1323 }
1324 #endif
1325 
1326 #endif
Definition: quicktime.h:161
Definition: quicktime.h:277
int quicktime_set_video_position(quicktime_t *file, int64_t frame, int track)
Seek to a specific video frame.
Definition: quicktime.h:294
int quicktime_release()
Get the quicktime4linux release number.
lqt_log_level_t
Log level.
Definition: quicktime.h:126
Definition: quicktime.h:276
int quicktime_check_sig(char *path)
Test file compatibility.
void quicktime_set_framerate(quicktime_t *file, double framerate)
Set the framerate for encoding.
lqt_file_type_t
File types.
Definition: quicktime.h:154
Definition: quicktime.h:159
int quicktime_reads_cmodel(quicktime_t *file, int colormodel, int track)
Check if a colormodel is supported for decoding.
void(* lqt_log_callback_t)(lqt_log_level_t level, const char *domain, const char *message, void *data)
Log callback.
Definition: quicktime.h:142
int quicktime_set_audio_position(quicktime_t *file, int64_t sample, int track)
Seek to a specific audio position.
Definition: quicktime.h:293
char * quicktime_video_compressor(quicktime_t *file, int track)
Get the four character code of a video track.
int quicktime_channel_location(quicktime_t *file, int *quicktime_track, int *quicktime_channel, int channel)
lqt_channel_t
Channel definitions.
Definition: quicktime.h:177
void quicktime_set_row_span(quicktime_t *file, int row_span)
Set the row_span for en-/decoding.
Definition: quicktime.h:158
int quicktime_writes_cmodel(quicktime_t *file, int colormodel, int track)
Check if a colormodel is supported for encoding.
int quicktime_audio_bits(quicktime_t *file, int track)
Get the bits per sample of an audio track.
int quicktime_track_channels(quicktime_t *file, int track)
Get the number of channels of an audio track.
long quicktime_video_length(quicktime_t *file, int track)
Get the video length.
double quicktime_frame_rate(quicktime_t *file, int track)
Get the framerate of a video track.
Definition: quicktime.h:259
Definition: quicktime.h:156
lqt_chroma_placement_t
Chroma placement.
Definition: quicktime.h:273
long quicktime_audio_length(quicktime_t *file, int track)
Get the audio length.
void quicktime_set_cmodel(quicktime_t *file, int colormodel)
Set the colormodel for en-/decoding.
void quicktime_set_parameter(quicktime_t *file, char *key, void *value)
Set a codec parameter.
int quicktime_encode_video(quicktime_t *file, unsigned char **row_pointers, int track)
Encode a video frame.
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.
int quicktime_supported_audio(quicktime_t *file, int track)
Check if an audio track is supported by libquicktime.
Definition: quicktime.h:291
long quicktime_frame_size(quicktime_t *file, long frame, int track)
Get the compressed size of frame in a video track.
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.
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.
Structure describing a codec.
Definition: lqt_codecinfo.h:189
long quicktime_video_position(quicktime_t *file, int track)
Get the video position.
int quicktime_supported_video(quicktime_t *file, int track)
Check if a video track is supported by libquicktime.
int quicktime_close(quicktime_t *file)
Close a quicktime handle and free all associated memory.
int quicktime_set_cpus(quicktime_t *file, int cpus)
Set the number of CPUs.
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.
int quicktime_make_streamable(char *in_path, char *out_path)
Make a file streamable.
quicktime_t * quicktime_open(const char *filename, int rd, int wr)
Open a file.
int quicktime_seek_start(quicktime_t *file)
Reposition all tracks to the very beginning.
Definition: quicktime.h:260
Definition: quicktime.h:297
int quicktime_major()
Get the quicktime4linux major version.
int quicktime_write_frame(quicktime_t *file, uint8_t *video_buffer, int64_t bytes, int track)
Write a compressed video frame.
void quicktime_set_info(quicktime_t *file, char *string)
Set info for the file.
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.
Definition: quicktime.h:292
Definition: quicktime.h:160
void quicktime_set_jpeg(quicktime_t *file, int quality, int use_float)
Set jpeg encoding quality.
int quicktime_has_audio(quicktime_t *file)
Check if a file has at least one audio track.
Definition: quicktime.h:162
int quicktime_audio_tracks(quicktime_t *file)
Get the number of audio tracks.
void quicktime_set_avi(quicktime_t *file, int value)
Write an AVI file instead of quicktime.
int quicktime_video_tracks(quicktime_t *file)
Get the number of video tracks.
Definition: quicktime.h:261
int quicktime_video_depth(quicktime_t *file, int track)
Get the depth of a video track.
char * quicktime_audio_compressor(quicktime_t *file, int track)
Get the four character code of an audio track.
int quicktime_video_height(quicktime_t *file, int track)
Get the height of a video track.
Definition: quicktime.h:275
lqt_sample_format_t
Sample format definitions for audio.
Definition: quicktime.h:289
char * quicktime_get_name(quicktime_t *file)
Get the name from the file.
int quicktime_has_video(quicktime_t *file)
Check if a file has at least one video track.
int quicktime_minor()
Get the quicktime4linux minor version.
Definition: quicktime.h:163
Definition: quicktime.h:296
int quicktime_decode_video(quicktime_t *file, unsigned char **row_pointers, int track)
Decode a video frame in BC_RGB888.
struct quicktime_s quicktime_t
Quicktime handle.
Definition: quicktime.h:308
void quicktime_set_copyright(quicktime_t *file, char *string)
Set the copyright info for the file.
void quicktime_set_depth(quicktime_t *file, int depth, int track)
Set the depth of a video track.
int quicktime_dump(quicktime_t *file)
Dump the file structures to stdout.
int quicktime_video_width(quicktime_t *file, int track)
Get the width of a video track.
char * quicktime_get_copyright(quicktime_t *file)
Get the copyright info from the file.
Definition: quicktime.h:157
long quicktime_sample_rate(quicktime_t *file, int track)
Get the samplerate of an audio track.
long quicktime_read_frame(quicktime_t *file, unsigned char *video_buffer, int track)
Read a compressed video frame.
long quicktime_audio_position(quicktime_t *file, int track)
Get the audio position.
Definition: quicktime.h:295
void quicktime_set_name(quicktime_t *file, char *string)
Set the name for the file.
char * quicktime_get_info(quicktime_t *file)
Get the info string from the file.
lqt_interlace_mode_t
interlace modes
Definition: quicktime.h:257