README
上传用户:luping1608
上传日期:2007-01-06
资源大小:38k
文件大小:18k
源码类别:

多媒体

开发平台:

Unix_Linux

  1. Quicktime for Linux
  2. Author: Adam Williams    quicktime@altavista.net
  3. Homepage: heroine.tampa.fl.us/quicktime
  4. Requires: libjpeg.so.62
  5. ------------------------------------------------------------------------
  6. ***** 
  7. This is a Quicktime library for UNIX in a freely redistributable,
  8. statically linkable library.  You can statically link it in a program
  9. and charge money for the program.  The only condition is that if you
  10. use it in a program, you must put the author's name and email
  11. somewhere.  If you improve the library itself or add a free codec to
  12. it, you should release your improvements.  If you redistribute the
  13. code, you must also redistribute the author information and
  14. documentation.  At this time it's very popular to license stuff under
  15. the GPL.  You are free to include this library in a derived work and
  16. license the derived work under GPL.
  17. *****
  18. Quicktime movies are first and foremost a very complicated, tedious,
  19. wrapper for 3rd party compression schemes.
  20. Quicktime for Linux hides the nightmare of accessing a Quicktime movie
  21. and gives the programmer a set of audio and video streams with some
  22. compression ability.  The audio tracks are sequential streams of PCM
  23. audio data and video tracks are a sequential streams of frames.
  24. Before you drop your classes and write up your dream program on this be
  25. aware of some limitations.  This library doesn't give you the official
  26. Quicktime API even remotely.  It uses it's own threadable, scalable
  27. ANSI C API.  This library doesn't include any commercial codecs nor
  28. does it include support for keyframes, which most of the expensive
  29. codecs require but the free codecs don't.  Also you may encounter
  30. Quicktime files containing compressed headers.  This library only reads
  31. uncompressed headers.
  32. What you can do is create and read any Quicktime movie that uses JPEG,
  33. RGB, or YUV2 compression and many sound formats.  JPEG, RGB, and YUV
  34. 4:2:2 encoding and decoding is currently built into the library.  For
  35. audio, IMA4, and ulaw encoding and decoding is in the library.  You can
  36. still get raw data if you want to write your own compression routines.
  37. Adding new codecs is hard, but if you read the section called The Story
  38. on Codecs and drop a few classes you can do it.
  39. /***************************************************
  40.  * Mandatory usage:
  41.  ************************************/
  42. For any operation, the first step is to #include <quicktime.h> and then
  43. create a pointer of type quicktime_t.
  44. quicktime_t *file;
  45. Open the movie with the quicktime_open function.  Argument 1 is the
  46. path to a file.  Argument 2 is a flag for read access.  Argument 3 is a
  47. flag for write access.  You can specify read, read/write or write
  48. access by setting these flags.  Don't specify read/write mode for files
  49. that already exist.  Read/write mode should only be used for creating
  50. new files.
  51. file = quicktime_open("test.mov", 1, 1));
  52. This returns a NULL if the file couldn't be opened or the format
  53. couldn't be recognized.  Now you can do all sorts of operations on the
  54. file.
  55. /*************************************************
  56.  * Reading a file:
  57.  **********************************/
  58. If you just want to read a file, a good place to start is before
  59. opening the file, making sure it is Quicktime with
  60. quicktime_check_sig().
  61. quicktime_check_sig("path");
  62. This returns 1 if it looks like a Quicktime file or 0 if it doesn't. 
  63. Then you can open the file as above.
  64. Next get the number of tracks for each media type in the file:
  65. int quicktime_video_tracks(quicktime_t *file);
  66. int quicktime_audio_tracks(quicktime_t *file);
  67. While Quicktime can store multiple video tracks, the audio track count
  68. is a bit more complicated.  In addition to the track count, Quicktime
  69. can store multiple audio channels for each audio track so you have to
  70. count those too, for each track.
  71. int quicktime_track_channels(quicktime_t *file, int track);
  72. Tracks are numbered from 0 to the total number of audio tracks - 1. 
  73. The library doesn't handle any extraction of channels from each track. 
  74. It just reads raw track data.  For each audio track, other routines you
  75. might find useful for getting information are:
  76. int quicktime_audio_bits(quicktime_t *file, int track);
  77. long quicktime_sample_rate(quicktime_t *file, int track);
  78. long quicktime_audio_length(quicktime_t *file, int track);
  79. char* quicktime_audio_compressor(quicktime_t *file, int track);
  80. quicktime_audio_length gives you the total number of samples in a given
  81. track regardless of the channels or bitrate.  The sample rate is
  82. samples per second.  The audio compressor routine returns a 4 byte
  83. array identifying the compression of the track.
  84. The available video information for each video track is:
  85. long quicktime_video_length(quicktime_t *file, int track);
  86. int quicktime_video_width(quicktime_t *file, int track);
  87. int quicktime_video_height(quicktime_t *file, int track);
  88. float quicktime_frame_rate(quicktime_t *file, int track);
  89. char* quicktime_video_compressor(quicktime_t *file, int track);
  90. long quicktime_frame_size(quicktime_t *file, long frame, int track);
  91. Tracks are numbered 0 to the total number of tracks - 1.  The video
  92. length is in frames.  The width and height are in pixels.  The frame
  93. rate is in frames per second.  The video compressor is a four byte
  94. array containing one of Quicktime's video data format types.  More on
  95. these later.
  96. Unless you get a really nihilistic file for reading, you can safely
  97. assume the encoding scheme for track 0 of audio or video is the same
  98. for all tracks of that media type.  That's what the encoders do.
  99. /********************************************
  100.  * Compressor types
  101.  **********************/
  102. The output of the compressor queries is a 4 byte array that matches one
  103. of the compressor #defines in quicktime.h.  The current audio
  104. compressor #defines are:
  105. QUICKTIME_RAW
  106. QUICKTIME_TWOS
  107. QUICKTIME_IMA4
  108. QUICKTIME_ULAW
  109. Several video codecs are built into the library.  The current video
  110. compressor #defines (which also indicate the codecs built into the
  111. library) are.
  112. QUICKTIME_RAW
  113. QUICKTIME_JPEG
  114. QUICKTIME_YUV2
  115. Once you have that information, you can begin reading data.
  116. /*************************************************
  117.  * Seeking around a file
  118.  *************************/
  119. The current position of each track is independant of each other track
  120. and advances automatically when you read from it.  Speaking of
  121. positions, you can also set each track's position arbitrarily with
  122. int quicktime_seek_end(quicktime_t *file);
  123. int quicktime_seek_start(quicktime_t *file);
  124. int quicktime_set_audio_position(quicktime_t *file, long sample, int track);
  125. int quicktime_set_video_position(quicktime_t *file, long frame, int track);
  126. The seek_end and seek_start seek all tracks to their ends or starts. 
  127. The set_position commands seek one track to the desired position.
  128. When seeking around audio tracks, be aware that Quicktime for Linux
  129. tries to guess the byte offset of the sample position by the codec
  130. type, so attempts to seek an unsupported nonlinear codec will fail.
  131. When you're done reading, call quicktime_close(quicktime_t *file);
  132. int quicktime_read_frame(quicktime_t *file, unsigned char *video_buffer, int track);
  133. int quicktime_read_audio(quicktime_t *file, char *audio_buffer, long samples, int track);
  134. /**************************************************
  135.  * Reading raw audio data
  136.  *************************/
  137. These commands are good for reading raw sample data.  They should only
  138. be used for codecs not supported in the library and only work for
  139. interleaved, linear PCM data.
  140. quicktime_read_audio requires a number of samples of raw audio data to
  141. read.  Then it reads that corresponding number of bytes on the
  142. specified track and returns the equivalent number of bytes read or 0 if
  143. error.  The data read is PCM audio data of interleaved channels
  144. depending on the format of the track.
  145. Be aware that Quicktime for Linux tries to guess the number of bytes by
  146. the codec type, so attempts to read most nonlinear codecs will crash.
  147. /***************************************************
  148.  * Reading raw video data
  149.  *************************/
  150. quicktime_read_frame reads one frame worth of raw data from your
  151. current position on the specified video track and returns the number of
  152. bytes in the frame.  You have to make sure the buffer is big enough for
  153. the frame.   A return value of 0 means error.
  154. long quicktime_frame_size(quicktime_t *file, long frame, int track);
  155. gives up the number of bytes in the specified frame in the specified
  156. track even if you haven't read the frame yet.  Frame numbers start on
  157. 0.
  158. Now some of you are going to want to read frames directly from a file
  159. descriptor using another library like libjpeg or something.  To read a
  160. frame directly start by calling quicktime_read_frame_init to initialize
  161. the input.
  162. int quicktime_read_frame_init(quicktime_t *file, int track);
  163. Then read your raw, compressed data from the file descriptor given by
  164. quicktime_get_fd.
  165. FILE* quicktime_get_fd(quicktime_t *file);
  166. End the frame by calling quicktime_read_frame_end.
  167. int quicktime_read_frame_end(quicktime_t *file, int track);
  168. You can get the file descriptor any time the file is opened, not just
  169. when reading or writing, but you must call the init and end routines to
  170. read a frame.
  171. /***************************************************
  172.  * Codec support for reading video:
  173.  ********************************/
  174. In addition to raw frame data, you can have the library decode
  175. compressed video frames into rows of unsigned RGB bytes.  First use
  176. int quicktime_supported_video(quicktime_t *file, int track);
  177. to find out if the codec for the track is in the library.  This returns
  178. 1 if it is and 0 if it isn't supported.
  179. Then use
  180. int quicktime_decode_video(quicktime_t *file, unsigned char **row_pointers, int track);
  181. to decompress a frame at the current position of the track into
  182. **row_pointers and advance the current position.
  183. /*************************************************
  184.  * Codec support for reading audio:
  185.  ********************************/
  186. For reading audio, first use:
  187. int quicktime_supported_audio(quicktime_t *file, int track);
  188. To determine if the codec can be read by the library.  This returns 1
  189. if it is and 0 if it isn't supported.
  190. Then use
  191. int quicktime_decode_audio(quicktime_t *file, QUICKTIME_INT16 *output_i, float *output_f, long samples, int channel);
  192. To read a buffer of samples for a single channel starting at the
  193. current position in the file.  Notice this command takes a channel
  194. argument not a track argument.  The channel is automatically resolved
  195. into a track # and a channel # in that track for reading.  Positioning
  196. information is automatically taken from the appropriate track.
  197. Notice the QUICKTIME_INT16* and float* parameters.  This call can
  198. either return int16 samples or float samples.  The data format you want
  199. should be passed a preallocated buffer big enough to contain the sample
  200. range.  For a buffer of float samples you would say
  201. result = quicktime_decode_audio(file, NULL, output_f, samples, channel);
  202. The data format you don't want should be passed a NULL.  The decoder
  203. automatically fills the appropriate buffer.  Floating point samples are
  204. from 0 to 1.
  205. /***************************************************
  206.  * Writing a file:
  207.  **********************************/
  208. The following commands are good for writing to a file.
  209. Immediately after opening the file, set up the tracks to write with
  210. these commands:
  211. quicktime_set_audio(quicktime_t *file, int channels, long sample_rate, int bits, char *compressor);
  212. quicktime_set_video(quicktime_t *file, int tracks, int frame_w, int frame_h, float frame_rate, char *compressor);
  213. Notice the channels argument for audio channels but there is no
  214. argument for total audio tracks. For sanity reasons, the library only
  215. supports writing one audio track of any number of channels.
  216. The compressor string can be one of the compressor #defines in
  217. quicktime.h or your own 4 byte array and applies to all tracks of the
  218. media type, for simplicity reasons.  Choose an audio compressor for the
  219. audio command and a video compressor for the video command.  The
  220. library doesn't check for conflicting media types or whether a
  221. compressor you make up is legitimate.
  222. Now you'll want to seek to any point in the file.  Seeking works
  223. exactly as in reading, using the same commands, except if you seek to
  224. the middle of a file and write out data, you're going to cause a glitch
  225. in the playback data.  It's virtually impossible to line up new frame
  226. boundaries with old frames since some codecs aren't linear and hardly
  227. anyone uses this library anyway.
  228. /****************************************************
  229.  * Writing raw data
  230.  ***********************/
  231. With that, you can now write data.  For writing raw frame data, you
  232. need to supply a buffer of data exactly as you intend
  233. quicktime_read_... to see it, with the encoding done, then call one of
  234. these functions to write it.  For video, specify the number of bytes in
  235. the frame buffer and the track this frame belongs to.  Video can only
  236. be written one frame at a time.
  237. int quicktime_write_frame(quicktime_t *file, unsigned char *video_buffer, long bytes, int track);
  238. Writing audio involves writing the raw audio data exactly the way
  239. quicktime_read_audio is going to see it, with channels interleaved and
  240. whatever else.
  241. int quicktime_write_audio(quicktime_t *file, char *audio_buffer, long samples, int track);
  242. The library automatically converts the sample count to the number of
  243. bytes of data in the buffer, based on channels and bits values you
  244. passed to quicktime_set_audio.
  245. Now some of you are going to want to write frames directly to a file
  246. descriptor using another library like libjpeg or something.  For every
  247. frame start by calling quicktime_write_frame_init to initialize the
  248. output.
  249. int quicktime_write_frame_init(quicktime_t *file, int track);
  250. Then write your raw, compressed data to the file descriptor given by
  251. quicktime_get_fd.
  252. FILE* quicktime_get_fd(quicktime_t *file);
  253. End the frame by calling quicktime_write_frame_end.
  254. int quicktime_write_frame_end(quicktime_t *file, int track);
  255. When you're done, call quicktime_close to close the file.
  256. int quicktime_close(file);
  257. Repeat starting at quicktime_write_frame_init for every frame.
  258. /*********************************************************
  259.  * Codec support for writing:
  260.  **********************************/
  261. In addition to raw frame data, you can have the library encode
  262. compressed video frames from rows of unsigned RGB bytes.  This depends
  263. on whether the compressor you passed to quicktime_set_video is
  264. supported in the library.  First use
  265. int quicktime_supported_video(quicktime_t *file, int track);
  266. to find out if the codec for the track is in the library.  This returns
  267. 1 if it is and 0 if it isn't supported.
  268. Then use
  269. int quicktime_encode_video(quicktime_t *file, unsigned char **row_pointers, int track);
  270. to compress the frame pointed to by **row_pointers, write it at the
  271. current position of the track and advance the current position.  There
  272. is no audio encoding currently.  The return value is always 1 for
  273. failure and 0 for success.
  274. The library also supports encoding certain audio codecs.  Before
  275. writing a buffer of samples, try 
  276. int quicktime_supported_audio(quicktime_t *file, int track);
  277. The track argument is really hypothetical here, since you should only
  278. pass 0 for it.  If the codec is supported, use 
  279. int quicktime_encode_audio(quicktime_t *file, QUICKTIME_INT16 **input_i, float **input_f, long samples);
  280. To encode the sample buffer.  Pass an array of buffers to either the
  281. QUICKTIME_INT16** or the float** argument, depending on what format
  282. your data is in.  Pass a NULL to the unused argument.  The array of
  283. buffers is one buffer of samples for each channel, all pointed to by an
  284. array.  This means all the channels have to be written simultaneously. 
  285. The return value is 0 on success.
  286. /*********************************************************
  287.  * Other functions:
  288.  **************************************/
  289. You can get some utilities by running make util in the source code
  290. directory.  The dump program merely reads the salient features of a
  291. header from a quicktime file and dumps it in english to the screen.  As
  292. you can see, there's a reason why no-one's written Quicktime libraries
  293. for Linux yet.  Eventually this library may allow you to access the
  294. extra information.
  295. Web authors might find a use for make_streamable.  This makes a
  296. Quicktime file readable before it's completely downloaded by relocating
  297. the header.  Only use it on files created by this library since it
  298. might clobber any other files.
  299. /*******************************************************
  300.  * Bugs:
  301.  ****************************************/
  302. Lots.
  303. /*******************************************************
  304.  * The story on codecs
  305.  ****************************************/
  306. Quicktime for Linux was originally intended as a back end to a higher
  307. level library which would contain all the codecs.  Later on some guy
  308. decided to move some codecs into the Quicktime library itself.
  309. Well we're now shooting for a compromise between building codecs
  310. directly in the library and using the library as a back end to a plugin
  311. architecture.  Unpatented, and freely redistributable codecs should be
  312. built into Quicktime for Linux while patented and expensive codecs
  313. should go into a higher level library.  A user application who wants to
  314. access a movie then queries Quicktime 4 Linux followed by whatever
  315. codec libraries are available until one rings positive.
  316. If you want to code into the Quicktime library itself, codecs have so
  317. far been implemented thus:
  318. 1) Add the #define for the codec ID to quicktime.h.
  319. 2) Go to codecs.c and edit the supported_**** to return the right value.
  320. 3) Go to codecs.h and add a codec structure to quicktime_codecs_t.
  321. 4) Include a .h file for the codec in codecs.h.
  322. 5) Create the .h file for your codec to define the codec structure.
  323. 6) Add switch conditions to codecs.c.
  324. 7) Define the init, delete, encode, and decode routines in a new .c
  325. file for the codec using one of the existing codecs as a template. 
  326. Codec .c files are currently named by the ID of the codec.
  327. 9) Add the new object file to Makefile
  328. /*******************************************************
  329.  * References:
  330.  *********************************/
  331. Apple's quicktime file format information:
  332. http://developer.apple.com/techpubs/quicktime/qtdevdocs/REF/refQTFileFormat.htm
  333. Color space conversions:
  334. http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html