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_Ls, /* Rear Surround Left (7.1 systems) */
192  LQT_CHANNEL_Rs, /* Rear Surround Right (7.1 systems) */
193  LQT_CHANNEL_MONO,
194  LQT_CHANNEL_Lt, /* Prologic (matrixed) Left Total */
195  LQT_CHANNEL_Rt /* Prologic (matrixed) Right Total */
196  } lqt_channel_t;
197 
198 
262 typedef enum
263  {
268 
278 typedef enum
279  {
284 
294 typedef enum
295  {
304 
313 typedef struct quicktime_s quicktime_t;
314 
315 /* This is the reference for all your library entry points. */
316 
317 /* ===== compression formats for which codecs exist ====== */
318 
338 #define QUICKTIME_DIVX "DIVX"
339 
346 #define QUICKTIME_DIV3 "DIV3"
347 
354 #define QUICKTIME_DV "dvc "
355 /* AVID DV codec can be processed with libdv as well */
356 
363 #define QUICKTIME_DV_AVID "AVdv"
364 
371 #define QUICKTIME_DV_AVID_A "dvcp"
372 
380 /* RGB uncompressed. Allows alpha */
381 #define QUICKTIME_RAW "raw "
382 
389 /* Jpeg Photo */
390 #define QUICKTIME_JPEG "jpeg"
391 
392 /* Concatenated png images. Allows alpha */
393 
401 #define QUICKTIME_PNG "png "
402 
410 #define QUICKTIME_MJPA "mjpa"
411 
418 #define QUICKTIME_YUV2 "yuv2"
419 
426 #define QUICKTIME_YUV4 "yuv4"
427 
435 #define QUICKTIME_YUV420 "yv12"
436 
443 #define QUICKTIME_2VUY "2vuy"
444 
451 #define QUICKTIME_YUVS "yuvs"
452 
453 
460 #define QUICKTIME_V308 "v308"
461 
468 #define QUICKTIME_V408 "v408"
469 
476 #define QUICKTIME_V210 "v210"
477 
484 #define QUICKTIME_V410 "v410"
485 
486 /* =================== Audio formats ======================= */
487 
507 #define QUICKTIME_RAWAUDIO "raw "
508 
515 #define QUICKTIME_IMA4 "ima4"
516 
523 #define QUICKTIME_TWOS "twos"
524 
531 #define QUICKTIME_ULAW "ulaw"
532 
541 #define QUICKTIME_VORBIS "OggS"
542 
550 #define QUICKTIME_MP3 ".mp3"
551 
552 /* =========================== public interface ========================= // */
553 
562  /* Get version information */
564 
573 
583 
595 int quicktime_check_sig(char *path);
596 
607 quicktime_t* quicktime_open(const char *filename, int rd, int wr);
608 
621 int quicktime_make_streamable(char *in_path, char *out_path);
622 
636 void quicktime_set_copyright(quicktime_t *file, char *string);
637 
644 void quicktime_set_name(quicktime_t *file, char *string);
645 
652 void quicktime_set_info(quicktime_t *file, char *string);
653 
662 
671 
679 
680 
697  int channels,
698  long sample_rate,
699  int bits,
700  char *compressor);
701 
712 void quicktime_set_framerate(quicktime_t *file, double framerate);
713 
730  int tracks,
731  int frame_w,
732  int frame_h,
733  double frame_rate,
734  char *compressor);
735 
749 void quicktime_set_jpeg(quicktime_t *file, int quality, int use_float);
750 
765 void quicktime_set_parameter(quicktime_t *file, char *key, void *value);
766 
778  int depth,
779  int track);
780 
790 void quicktime_set_cmodel(quicktime_t *file, int colormodel);
791 
802 void quicktime_set_row_span(quicktime_t *file, int row_span);
803 
810 
811 /* get length information */
812 /* channel numbers start on 1 for audio and video */
813 
822 long quicktime_audio_length(quicktime_t *file, int track);
823 
835 long quicktime_video_length(quicktime_t *file, int track);
836 
844  /* get position information */
845 long quicktime_audio_position(quicktime_t *file, int track);
846 
856 long quicktime_video_position(quicktime_t *file, int track);
857 
864 /* get file information */
866 
874 
882 
890 long quicktime_sample_rate(quicktime_t *file, int track);
891 
906 int quicktime_audio_bits(quicktime_t *file, int track);
907 
915 int quicktime_track_channels(quicktime_t *file, int track);
916 
929 char* quicktime_audio_compressor(quicktime_t *file, int track);
930 
938 
946 int quicktime_video_width(quicktime_t *file, int track);
947 
955 int quicktime_video_height(quicktime_t *file, int track);
956 
971 int quicktime_video_depth(quicktime_t *file, int track);
972 
987 double quicktime_frame_rate(quicktime_t *file, int track);
988 
999 char* quicktime_video_compressor(quicktime_t *file, int track);
1000 
1001 /* number of bytes of raw data in this frame */
1002 
1014 long quicktime_frame_size(quicktime_t *file, long frame, int track);
1015 
1025 int quicktime_channel_location(quicktime_t *file, int *quicktime_track, int *quicktime_channel, int channel);
1026 
1027 /* file positioning */
1028 /* Remove these and see what happens :) */
1029 
1030 // int quicktime_seek_end(quicktime_t *file);
1031 
1041 
1042 /* set position of file descriptor relative to a track */
1043 
1052 int quicktime_set_audio_position(quicktime_t *file, int64_t sample, int track);
1053 
1064 int quicktime_set_video_position(quicktime_t *file, int64_t frame, int track);
1065 
1066 /* ========================== Access to raw data follows. */
1067 /* write data for one quicktime track */
1068 /* the user must handle conversion to the channels in this track */
1069 int quicktime_write_audio(quicktime_t *file, uint8_t *audio_buffer, long samples, int track);
1070 
1086 int quicktime_write_frame(quicktime_t *file, uint8_t *video_buffer, int64_t bytes, int track);
1087 
1103 long quicktime_read_frame(quicktime_t *file, unsigned char *video_buffer, int track);
1104 
1105 /* for reading frame using a library that needs a file descriptor */
1106 /* Frame caching doesn't work here. */
1107 int quicktime_read_frame_init(quicktime_t *file, int track);
1108 int quicktime_read_frame_end(quicktime_t *file, int track);
1109 
1110 /* One keyframe table for each track */
1111 long quicktime_get_keyframe_before(quicktime_t *file, long frame, int track);
1112 long quicktime_get_partial_keyframe_before(quicktime_t *file, long frame, int track);
1113 void quicktime_insert_keyframe(quicktime_t *file, long frame, int track);
1114 void quicktime_insert_partial_keyframe(quicktime_t *file, long frame, int track);
1115 /* Track has keyframes */
1116 int quicktime_has_keyframes(quicktime_t *file, int track);
1117 
1118 /* Sample dependencies for long-GOP formats. */
1119 void quicktime_insert_sdtp_entry(quicktime_t *file, long frame, int track, uint8_t flags);
1120 
1121 /* ===================== Access to built in codecs follows. */
1122 
1123 /* If the codec for this track is supported in the library return 1. */
1124 
1133 
1142 
1155  int colormodel,
1156  int track);
1157 
1170  int colormodel,
1171  int track);
1172 
1173 
1174 /* Hacks for temporal codec */
1175 int quicktime_divx_is_key(unsigned char *data, long size);
1176 int quicktime_divx_write_vol(unsigned char *data_start,
1177  int vol_width,
1178  int vol_height,
1179  int time_increment_resolution,
1180  double frame_rate);
1181 int quicktime_divx_has_vol(unsigned char *data);
1182 
1183 int quicktime_div3_is_key(unsigned char *data, long size);
1184 
1196  unsigned char **row_pointers,
1197  int track);
1198 
1210  unsigned char **row_pointers,
1211  int track);
1212 
1234  int in_x, /* Location of input frame to take picture */
1235  int in_y,
1236  int in_w,
1237  int in_h,
1238  int out_w, /* Dimensions of output frame */
1239  int out_h,
1240  int color_model, /* One of the color models defined above */
1241  unsigned char **row_pointers,
1242  int track);
1243 
1244 /* Decode or encode audio for a single channel into the buffer. */
1245 /* Pass a buffer for the _i or the _f argument if you want int16 or float data. */
1246 /* Notice that encoding requires an array of pointers to each channel. */
1247 
1265 int quicktime_decode_audio(quicktime_t *file, int16_t *output_i, float *output_f, long samples, int channel);
1266 
1279 int quicktime_encode_audio(quicktime_t *file, int16_t **input_i, float **input_f, long samples);
1280 
1289 
1290 /* Specify the number of cpus to utilize. */
1291 
1302 int quicktime_set_cpus(quicktime_t *file, int cpus);
1303 
1304 /* Specify whether to read contiguously or not. */
1305 /* preload is the number of bytes to read ahead. */
1306 /* This is no longer functional to the end user but is used to accelerate */
1307 /* reading the header internally. */
1308 void quicktime_set_preload(quicktime_t *file, int64_t preload);
1309 
1310 int64_t quicktime_byte_position(quicktime_t *file);
1311 
1320 void quicktime_set_avi(quicktime_t *file, int value);
1321 
1322 #ifdef __GNUC__
1323 #pragma GCC visibility pop
1324 #endif
1325 
1326 
1327 #ifdef __cplusplus
1328 }
1329 #endif
1330 
1331 #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:142
LQT_INTERLACE_TOP_FIRST
@ LQT_INTERLACE_TOP_FIRST
Definition: quicktime.h:265
LQT_FILE_M4A
@ LQT_FILE_M4A
Definition: quicktime.h:162
LQT_SAMPLE_FLOAT
@ LQT_SAMPLE_FLOAT
Definition: quicktime.h:301
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:298
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:160
LQT_FILE_3GP
@ LQT_FILE_3GP
Definition: quicktime.h:163
lqt_file_type_t
lqt_file_type_t
File types.
Definition: quicktime.h:155
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:295
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:157
LQT_FILE_MP4
@ LQT_FILE_MP4
Definition: quicktime.h:161
lqt_channel_t
lqt_channel_t
Channel definitions.
Definition: quicktime.h:178
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:263
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:264
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:159
LQT_SAMPLE_DOUBLE
@ LQT_SAMPLE_DOUBLE
Definition: quicktime.h:302
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:279
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:299
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:297
LQT_INTERLACE_BOTTOM_FIRST
@ LQT_INTERLACE_BOTTOM_FIRST
Definition: quicktime.h:266
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:158
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:280
LQT_FILE_NONE
@ LQT_FILE_NONE
Definition: quicktime.h:156
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:190
lqt_log_level_t
lqt_log_level_t
Log level.
Definition: quicktime.h:127
LQT_SAMPLE_UNDEFINED
@ LQT_SAMPLE_UNDEFINED
Definition: quicktime.h:296
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:313
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:281
LQT_CHROMA_PLACEMENT_DVPAL
@ LQT_CHROMA_PLACEMENT_DVPAL
Definition: quicktime.h:282
LQT_SAMPLE_INT32
@ LQT_SAMPLE_INT32
Definition: quicktime.h:300
quicktime_encode_video
int quicktime_encode_video(quicktime_t *file, unsigned char **row_pointers, int track)
Encode a video frame.