quicktime/docs/writing.html

   1 <TITLE>Quicktime for Linux</TITLE>
   2
   3 <H1>Writing a file</H1>
   4
   5
   6 The following commands are good for writing to a file.<P>
   7
   8 Immediately after opening the file, set up some tracks to write with
   9 these commands:<P>
  10
  11 <CODE>
  12         quicktime_set_audio(quicktime_t *file, int channels, long sample_rate, int bits, char *compressor);<BR>
  13         quicktime_set_video(quicktime_t *file, int tracks, int frame_w, int frame_h, float frame_rate, char *compressor);
  14 </CODE><P>
  15
  16 Don't call the audio command if you don't intend to store any audio
  17 data.  Likewise, don't call the video command if you're just going to
  18 save audio.<P>
  19
  20 Notice the channels argument for audio channels but there is no
  21 argument for total audio tracks. Currently the library only supports
  22 writing one audio track of any number of channels.<P>
  23
  24 If you intend to use the library's built-in compression routines
  25 specify a compressor #define from quicktime.h as the compressor
  26 argument.  If you want to write your own compression routine, specify
  27 any 4 byte identifier you want but don't expect the library to handle
  28 compression.  The compressor applies to all tracks of the same media
  29 type, for sanity reasons.<P>
  30
  31 Once these routines are called you can optionally call <P>
  32
  33
  34 <CODE>
  35 void quicktime_set_parameter(quicktime_t *file, char *key, void *value);<P>
  36 </CODE><P>
  37
  38 to set compression parameters for the codecs.  Each parameter for a
  39 codec consists of a unique string and a pointer to a value.  The string
  40 is unique to the codec and the parameter.  The value is in a specific
  41 data type recognized by the parameter.<P>
  42
  43 To set a jpeg compression quality of 80, for example, do the following:<P>
  44
  45 <CODE>
  46 int quality = 80;<BR>
  47 quicktime_set_parameter(file, "jpeg_quality", &quality);<BR>
  48 </CODE><P>
  49
  50 The data type of the value depends on the parameter.  Currently the
  51 best way to determine what parameters and value data types a particular
  52 codec supports is to look at the codec's source code.  A better way may
  53 become available in the future.<P>
  54
  55 If you don't call quicktime_set_parameter the codecs will use default
  56 parameters.<P>
  57
  58
  59 <H2>NOTE FOR AVI FILES</H2><P>
  60
  61 After the above sequence and only after it, call
  62 <CODE>quicktime_set_avi</CODE> to make the library generate an AVI
  63 file.<P>
  64
  65
  66
  67
  68
  69
  70 <A NAME="Encodingvideo">
  71 <H1>Encoding video</H1>
  72
  73 The library generates compressed video frames from a frame buffer of
  74 any colormodel in colormodels.h.  First use<P>
  75
  76 <CODE>
  77 int quicktime_supported_video(quicktime_t *file, int track);
  78 </CODE><P>
  79
  80 to find out if the codec for the track is in the library.  This returns
  81 1 if it is and 0 if it isn't supported.  Then use<P>
  82
  83 <CODE>
  84 int quicktime_writes_cmodel(quicktime_t *file,
  85                 int colormodel,
  86                 int track);
  87 </CODE><P>
  88
  89 To query the library for a colormodel which doesn't require
  90 downsampling to drive the codec.  <B>colormodels.h</B> contains a set
  91 of colormodel #defines which supply the colormodel argument.  The
  92 function returns True or False depending on whether the colormodel
  93 argument is optimum.  When a colormodel doesn't require downsampling it
  94 returns 1.  Then call<P>
  95
  96 <CODE>quicktime_set_cmodel(quicktime_t *file, int colormodel);</CODE><P>
  97
  98 to set the colormodel your frame buffer is in.  Finally call
  99
 100 <P><CODE>
 101         int quicktime_encode_video(quicktime_t *file, unsigned char **row_pointers, int track);
 102 </CODE><P>
 103
 104
 105 to compress the frame pointed to by **row_pointers, write it at the
 106 current position of the track and advance the current position.  The
 107 return value is always 1 for failure and 0 for success.  The row
 108 pointers must point to rows stored in the colormodel.  Planar
 109 colormodels use only the first 3 row pointers, each pointing to one of
 110 the planes.<P>
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120 <A NAME="Encodingaudio">
 121 <H1>Encoding audio</H1>
 122
 123 The library also supports encoding certain audio codecs.  Before
 124 writing a buffer of samples, try <P>
 125
 126 <CODE>
 127 int quicktime_supported_audio(quicktime_t *file, int track);
 128 </CODE>
 129 <P>
 130
 131 The track argument is really hypothetical here, since you should only
 132 pass 0 for it.  If you get a TRUE return value, you are free to use
 133
 134 <P><CODE>
 135 int quicktime_encode_audio(quicktime_t *file, int16_t **input_i, float **input_f, long samples);
 136 </CODE><P>
 137
 138 to encode the sample buffer.  Pass an array of buffers to either the
 139 int16_t** or the float** argument, depending on what format your data
 140 is in.  Pass a NULL to the undesired format.  The array of buffers is
 141 one buffer of samples for each channel.  This means all the channels
 142 have to be written simultaneously.  The return value is 0 on success.
 143 <P>
 144
 145
 146 <A NAME="Writingrawvideo">
 147 <H1>Writing raw video</H1>
 148
 149 For writing raw data, you need to supply a buffer of data exactly as
 150 you intend the read operations to see it, with the encoding done, then
 151 call one of these functions to write it.  For video, specify the number
 152 of bytes in the frame buffer and the track this frame belongs to.
 153 Video can only be written one frame at a time.
 154
 155 <P><CODE>
 156 int quicktime_write_frame(quicktime_t *file, unsigned char *video_buffer, long bytes, int track);
 157 </CODE><P>
 158
 159
 160
 161 Now some of you are going to want to write frames directly to a file
 162 descriptor using another library like libjpeg or something.  For every
 163 frame start by calling quicktime_write_frame_init to initialize the
 164 output.<P>
 165
 166 <CODE>
 167 int quicktime_write_frame_init(quicktime_t *file, int track);
 168 </CODE><P>
 169
 170 Then write your raw, compressed data to the file descriptor given by
 171 quicktime_get_fd.<P>
 172
 173 <CODE>
 174 FILE* quicktime_get_fd(quicktime_t *file);
 175 </CODE><P>
 176
 177 End the frame by calling quicktime_write_frame_end.<P>
 178
 179 <CODE>
 180 int quicktime_write_frame_end(quicktime_t *file, int track);
 181 </CODE><P>
 182
 183 Repeat starting at quicktime_write_frame_init for every frame.
 184
 185 <A NAME="Writingkeyframes">
 186 <H1>Writing Keyframes</H1>
 187
 188 Quicktime offers very simple support for keyframes: a table of all the
 189 keyframe numbers in a track.  Many students think there's a massive
 190 keyframe programming language in Quicktime.  Really all there is is a
 191 table.<P>
 192
 193 There are two things you can with the keyframe table: insert keyframe
 194 numbers and retrieve keyframe numbers.<P>
 195
 196 <CODE>
 197 void quicktime_insert_keyframe(quicktime_t *file, long frame, int track)
 198 </CODE>
 199 <P>
 200
 201 Inserts a keyframe number corresponding to the <B>frame</B> argument in
 202 the table.<P>
 203
 204 <A NAME="Encodingrawaudio">
 205 <H1>Writing raw audio data</H1>
 206
 207 This functionality is obsolete due to the idiosyncracies in compressed
 208 audio handling.  If you want to write uncompressed audio, use the
 209 <B>twos</B> codec.<P>
 210
 211 When you're done, call quicktime_close to close the file.<P>
 212
 213 <CODE>
 214 int quicktime_close(file);
 215 </CODE>