"Fossies" - the Fresh Open Source Software Archive

Member "quicktime4linux-2.3/docs/reading.html" (9 Jan 2007, 9629 Bytes) of package /linux/privat/old/quicktime4linux-2.3-src.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <TITLE>Reading</TITLE>
    2 
    3 <H1>Reading a file</H1>
    4 
    5 Most users simply want read access for a player toy or something.  A
    6 good place to start is before opening the file, making sure it is
    7 Quicktime with quicktime_check_sig().<P>
    8 
    9 <CODE>
   10 quicktime_check_sig("path");<P>
   11 </CODE>
   12 
   13 This returns 1 if it looks like a Quicktime file or 0 if it doesn't. 
   14 Then you can open the file as described in <A
   15 HREF="opening.html">opening.html</A>.<P>
   16 
   17 Next get the number of tracks for each media type in the file:<P>
   18 
   19 <CODE>
   20 int quicktime_video_tracks(quicktime_t *file);<BR>
   21 int quicktime_audio_tracks(quicktime_t *file);
   22 </CODE>
   23 <P>
   24 
   25 
   26 While Quicktime can store multiple video tracks, the audio track count
   27 is a bit more complicated.  Usually you'll only encounter a single
   28 audio track.  Inside the audio track is a variable number of channels. 
   29 To get the channel count call:<P>
   30 
   31 <CODE>
   32 int quicktime_track_channels(quicktime_t *file, int track);
   33 </CODE>
   34 <P>
   35 
   36 With the track parameter set to track 0.  Many routines require a
   37 <B>track</B> parameter to specify the track to operate on.  Tracks are
   38 always numbered from 0 to the total number of tracks - 1 for the
   39 particular media type.<P>
   40 
   41 Audio tracks are numbered from 0 to the total number of audio tracks -
   42 1.  But like I said, you'll probably never encounter an audio track
   43 higher than 0.  Other routines you might find useful for getting audio
   44 information are:<P>
   45 
   46 <CODE>
   47 long quicktime_sample_rate(quicktime_t *file, int track);<BR>
   48 long quicktime_audio_length(quicktime_t *file, int track);<BR>
   49 </CODE>
   50 <P>
   51 
   52 quicktime_audio_length gives you the total number of samples.  The
   53 sample rate is samples per second.<P>
   54 
   55 Routines you'll never use unless you want to write a codec are:<P>
   56 
   57 <CODE>
   58 char* quicktime_audio_compressor(quicktime_t *file, int track);<BR>
   59 int quicktime_audio_bits(quicktime_t *file, int track);<BR>
   60 </CODE>
   61 <P>
   62 
   63 The audio compressor call returns a 4 byte array identifying the data
   64 compression of the track.  These identifiers are 4 alphanumeric
   65 characters which go along with one of the #defines in quicktime.h.  The
   66 bits function returns the number of bits in a sample, usually
   67 meaningless.<P>
   68 
   69 The most interesting contents of a Quicktime file are of course the
   70 video tracks.  Quicktime stores multiple video tracks.<P>
   71 
   72 The available queries for each video track are:<P>
   73 
   74 
   75 <CODE>
   76 long quicktime_video_length(quicktime_t *file, int track);<BR>
   77 int quicktime_video_width(quicktime_t *file, int track);<BR>
   78 int quicktime_video_height(quicktime_t *file, int track);<BR>
   79 float quicktime_frame_rate(quicktime_t *file, int track);<BR>
   80 long quicktime_frame_size(quicktime_t *file, long frame, int track);<BR>
   81 int quicktime_video_depth(quicktime_t *file, int track);<BR>
   82 quicktime_reads_cmodel(quicktime_t *file, 
   83         int colormodel, 
   84         int track);<BR>
   85 </CODE>
   86 <P>
   87 
   88 
   89 
   90 Tracks are numbered 0 to the total number of tracks - 1.  The video
   91 length is in frames.  The width and height are in pixels.  The frame
   92 rate is in frames per second.  Depth returns the total number of bits
   93 per pixel.  The only two values Quicktime for Linux returns are 24 and
   94 32 and the 32 bit depth is only returned when the format has an alpha
   95 channel.  There's no reason to use 16 or 8.<P>
   96 
   97 <CODE>quicktime_reads_cmodel</CODE> allows you to determine the optimum
   98 color model for decompression output.  It requires a colormodel #define
   99 from colormodels.h.  If the codec can generate the desired colormodel
  100 without downsampling it returns 1.  If downsampling is required it
  101 returns 0.  You can assume all colormodels in colormodels.h are
  102 supported, whether they require downsampling or not.<P>
  103 
  104 To get the four byte compressor type for the track issue:<P>
  105 
  106 <CODE>
  107 char* quicktime_video_compressor(quicktime_t *file, int track);<BR>
  108 </CODE>
  109 <P>
  110 
  111 Unless you get a really nihilistic file for reading, you can safely
  112 assume the encoding scheme for track 0 of audio or video is the same
  113 for all tracks.<P>
  114 
  115 <A NAME="Decodingvideo">
  116 <H1>Decoding video</H1>
  117 
  118 The library decodes compressed video frames into a buffer in whatever
  119 colormodel you desire but before then you should issue<P>
  120 
  121 <CODE>
  122 int quicktime_supported_video(quicktime_t *file, int track);<BR>
  123 </CODE>
  124 <P>
  125 
  126 to find out if the data for the track can be decoded by the library. 
  127 This returns 1 if it is and 0 if it isn't supported.<P>
  128 
  129 Then use<P>
  130 
  131 <CODE>
  132 <PRE>
  133 long quicktime_decode_video(quicktime_t *file, 
  134     unsigned char **row_pointers, 
  135     int track);<BR>
  136 </PRE>
  137 </CODE>
  138 <P>
  139 
  140 to decompress a frame at the current position of the track into
  141 <CODE>**row_pointers</CODE> and advance the current position.  The
  142 array of rows must have enough space allocated for the entire frame,
  143 depending on the colormodel.  Planar colormodels use only the first 3
  144 row pointers, each pointing to one of the planes.<P>
  145 
  146 Several parameters determine the decoder output.  They may be set
  147 before the call to <CODE>quicktime_decode_video</CODE>.<P>
  148 
  149 <CODE>
  150 <PRE>
  151 void quicktime_set_cmodel(quicktime_t *file, int colormodel);
  152 </PRE>
  153 </CODE>
  154 <P>
  155 
  156 Set the colormodel of the output frame to a value in colormodels.h. 
  157 The default is <CODE>BC_RGB888</CODE>.<P>
  158 
  159 <CODE>
  160 <PRE>
  161 void quicktime_set_row_span(quicktime_t *file, int row_span);
  162 </PRE>
  163 </CODE>
  164 <P>
  165 
  166 Set the number of bytes in a row.  The default is the row width * bytes
  167 per pixel.<P>
  168 
  169 <CODE>
  170 <PRE>
  171 void quicktime_set_window(quicktime_t *file,
  172     int in_x,                    /* Location of input frame to take picture */
  173     int in_y,
  174     int in_w,
  175     int in_h,
  176     int out_w,                   /* Dimensions of output frame */
  177     int out_h);
  178 </PRE>
  179 </CODE>
  180 <P>
  181 
  182 
  183 
  184 The decoder "sees" a region of the movie screen defined by <CODE>in_x,
  185 in_y, in_w, in_h</CODE> and transfers it to the frame buffer defined by
  186 <CODE>**row_pointers</CODE>.  The size of the frame buffer is defined
  187 by <CODE>out_w, out_h</CODE>.  The default is a 1:1 transfer from the
  188 codec to the output frame.<P>
  189 
  190 
  191 For more about the track's current position go to <A
  192 HREF="positioning.html">positioning</A><P>
  193 
  194 
  195 
  196 
  197 
  198 
  199 
  200 <H2>RAW ACCESS</H2><P>
  201 
  202 
  203 There are other routines for reading compressed data and chunks without
  204 a codec.  These allow you to perform direct copying of video data from
  205 one movie to the other after editing it, without recompressing it.<P>
  206 
  207 <A NAME="Decodingaudio">
  208 <H1>Decoding audio</H1>
  209 
  210 For reading audio, first use:<P>
  211 
  212 <CODE>
  213 int quicktime_supported_audio(quicktime_t *file, int track);<BR>
  214 </CODE>
  215 <P>
  216 
  217 To determine if the audio can be decompressed by the library.  This
  218 returns 1 if it is and 0 if it isn't supported.  Then use<P>
  219 
  220 <CODE>
  221 int quicktime_decode_audio(quicktime_t *file, int16_t *output_i, float *output_f, long samples, int channel);<BR>
  222 </CODE>
  223 <P>
  224 
  225 
  226 To read a buffer's worth of samples for a single channel starting at
  227 the current position in the track.  Notice this command takes a channel
  228 argument not a track argument.  The channel argument is automatically
  229 converted into a track and channel.  Positioning information is
  230 automatically taken from the appropriate track and advanced for all the
  231 channels in the track.<P>
  232 
  233 Notice the int16_t* and float* parameters.  This call can
  234 either return a buffer of int16 samples or float samples.  The argument
  235 for the data format you want should be passed a preallocated buffer big
  236 enough to contain the sample range while the undesired format should be
  237 passed NULL.  For a buffer of float samples you would say<P>
  238 
  239 <CODE>
  240 result = quicktime_decode_audio(file, NULL, output_f, samples, channel);<BR>
  241 </CODE>
  242 <P>
  243 
  244 For a buffer of signed int16 samples you would say<P>
  245 
  246 <CODE>
  247 result = quicktime_decode_audio(file, output_i, NULL, samples, channel);<BR>
  248 </CODE>
  249 <P>
  250 
  251 The data format you don't want should be passed a NULL.  The decoder
  252 automatically fills the appropriate buffer.  Floating point samples are
  253 from -1 to 0 to 1.<P>
  254 
  255 
  256 <A NAME="Readingrawvideo">
  257 <H1>Reading raw video</H1>
  258 
  259 <CODE>
  260 long quicktime_read_frame(quicktime_t *file, unsigned char *video_buffer, int track);
  261 </CODE>
  262 <P>
  263 
  264 <B>quicktime_read_frame</B> reads one frame worth of raw data from your
  265 current position on the specified video track and returns the number of
  266 bytes in the frame.  You have to make sure the buffer is big enough for
  267 the frame.   A return value of 0 means error.<P>
  268 
  269 <CODE>
  270 long quicktime_frame_size(quicktime_t *file, long frame, int track);
  271 </CODE>
  272 <P>
  273 
  274 gives up the number of bytes in the specified frame in the specified
  275 track even if you haven't read the frame yet.  Frame numbers start on
  276 0.<P>
  277 
  278 <A NAME="Readingkeyframes">
  279 <H1>Accessing Keyframes</H1>
  280 
  281 Quicktime offers very simple support for keyframes: a table of all the
  282 keyframe numbers in a track.  There are two things you can do with the
  283 keyframe table: insert keyframe numbers and retrieve keyframe
  284 numbers.<P>
  285 
  286 <CODE>
  287 long quicktime_get_keyframe_before(quicktime_t *file, long frame, int track)
  288 </CODE>
  289 <P>
  290 
  291 Gets the keyframe number before the <B>frame</B> argument.  The frames
  292 start on 0.<P>
  293 
  294 <CODE>
  295 long quicktime_get_keyframe_after(quicktime_t *file, long frame, int track);
  296 </CODE>
  297 <P>
  298 
  299 Gets the keyframe number after the <B>frame</B> argument.  The frames
  300 start on 0.<P>
  301 
  302 
  303 <CODE>
  304 void quicktime_insert_keyframe(quicktime_t *file, long frame, int track)
  305 </CODE>
  306 <P>
  307 
  308 Inserts a keyframe into the table.  The frame argument starts on 0.<P>
  309 
  310 <CODE>
  311 int quicktime_has_keyframes(quicktime_t *file, int track);
  312 </CODE>
  313 <P>
  314 
  315 Returns TRUE if the track has keyframes.  The track starts on 0.<P>
  316 
  317 
  318 <A NAME="Readingrawaudio">
  319 <H1>Reading raw audio</H1>
  320 
  321 There is no simple read or write access to raw audio.  Due to vagaries
  322 in the audio indexing and the lack of benefit in direct audio copying,
  323 you're better off using a codec.<P>