Merged 2448

avilib-0.6.10/README.avilib

@@ -0,0 +1,221 @@
+avilib: Reading and writing avi files
+=====================================
+
+Copyright (C) 1999 Rainer Johanni <Rainer@Johanni.de>
+
+avilib is a open source library for dealing with AVI
+files under Linux or other UNIX operating systems.
+
+It provides a framework for extracting or adding raw
+audio and single raw (=compressed) frames from/to AVI Files.
+
+It does not deal with any compression issues which have to be
+handled on a higher level by the user of avilib.
+
+AVI files may have several video and audiotracks.
+
+avilib writes only one video track and (optionally) one
+audio track and also extracts only the first video and audio
+track (but input files may contain more than one track, the others
+just being ingored).
+
+The interface to avilib is kept similar to the quicktime4linux interface
+(by Adam Williams) with the following important differences:
+
+- since only the first track of video and audio is considered,
+  there is no track argument in any of the routines.
+
+- audio is generally considered as a byte stream and therefore
+  all size arguments used in reading/writing audio are in bytes
+  and not in samples.
+
+- as mentioned above, there are no routines dealing with compression issues.
+
+
+Compiling:
+==========
+
+Since the library consists only of one c source file, I have not provided
+a Makefile or similar, just compile with
+
+cc -c <your favorite options> avilib.c
+
+
+Portability:
+============
+
+AVI-Files use little endian numbers throughout the file, I have tried
+to read/write these numbers in a way which doesn't depent on endianness.
+This library should therefore also be useable on big endian machines.
+This feature is not so heavily tested, however.
+
+
+Usage:
+======
+
+Basics, opening, closing
+------------------------
+
+Include "avilib.h" in your source and declare a pointer:
+
+   avi_t *avifile;
+
+Open the AVI file with:
+
+   avifile = AVI_open_input_file("xxx.avi",1);
+
+or
+
+   avifile = AVI_open_output_file("xxx.avi");
+
+You may either only read from the input file (leaving it unchanged)
+or create a completly new AVI file. There is no editing or append
+mode available.
+
+Both routines will either return a pointer to avi_t or a zero pointer
+in the case of an error.
+
+For closing the file, use:
+
+   int  AVI_close(avi_t *AVI);
+
+Files you have written MUST be closed (the header is written at close time),
+else they will not be readable by any other software.
+
+Files opened for reading should be closed to free the file descriptor
+and some data (unless your program is finishing anyway).
+
+
+Error handling:
+---------------
+
+Most routines (besides open/close) will return 0 or a usefull number if successfull
+and a -1 in the case of an error. If an error occured, the external variable
+AVI_errno is set. See avilib.h for the meaning of the error codes in AVI_errno.
+
+There is also a routine (which acts like perror) to output a description
+of the last error to stderr:
+
+AVI_print_error(char *str)
+
+
+
+Reading from an AVI file:
+-------------------------
+
+After opening the file, you can obtain the parameters of the AVI
+with the following routines:
+
+long AVI_video_frames(avi_t *AVI);
+   number of video frames in the file
+
+int  AVI_video_width(avi_t *AVI);
+int  AVI_video_height(avi_t *AVI);
+   width and height of the video in pixels
+
+double AVI_frame_rate(avi_t *AVI);
+   frame rate in frames per second, notice that this is a double value!
+
+char* AVI_video_compressor(avi_t *AVI);
+   string describing the compressor
+
+int  AVI_audio_channels(avi_t *AVI);
+   number of audio channels, 1 for mono, 2 for stereo, 0 if no audio present
+
+int  AVI_audio_bits(avi_t *AVI);
+   audio bits, usually 8 or 16
+
+int  AVI_audio_format(avi_t *AVI);
+   audio format, most common is 1 for raw PCM, look into avilib.h for others
+
+long AVI_audio_rate(avi_t *AVI);
+   audio rate in samples/second
+
+long AVI_audio_bytes(avi_t *AVI);
+   total number of audio bytes in the file
+
+
+In order to read the video frame by frame, use
+(frame numbers are starting from 0 !!!!!)
+
+long AVI_frame_size(avi_t *AVI, long frame);
+   to get the size of frame with number "frame"
+
+long AVI_read_frame(avi_t *AVI, char *vidbuf);
+   to read the next  frame (frame posittion is advanced by 1 after the read)
+
+int  AVI_seek_start(avi_t *AVI);
+int  AVI_set_video_position(avi_t *AVI, long frame);
+   to position in the AVI file
+   (for reading the frames out of order)
+
+
+Read audio with
+
+int  AVI_set_audio_position(avi_t *AVI, long byte);
+   to position to an arbitrary byte position within the audio stream
+
+long AVI_read_audio(avi_t *AVI, char *audbuf, long bytes);
+   to actually read "bytes" number of audio bytes.
+   the audio position is advanced by "bytes", so there is no
+   need to reposition before every call when reading in order.
+
+
+Avoiding lengthy index searches:
+--------------------------------
+
+When opening the AVI file, avilib looks if the file has an index attached
+and if this is not the case, it creates one by reading through the whole file.
+
+If you want to read through the file only once, creation of an index is
+not necessary in that case. You may use AVI_open_input_file with the second
+argument set to 0 and then use AVI_read_data for readin through the file.
+
+Look to the source for the arguments of AVI_read_data.
+
+
+Writing to an AVI file:
+-----------------------
+
+After you have opened the file, use the following routines to set
+the properties of the AVI file:
+
+void AVI_set_video(avi_t *AVI, int width, int height, double fps, char *compressor);
+void AVI_set_audio(avi_t *AVI, int channels, long rate, int bits, int format);
+
+with:
+
+width, height   width and height of the video in pixels
+
+fps             frame rate in frames per second, notice that this is a double value!
+
+compressor      string describing the compressor
+
+channels        number of audio channels, 1 for mono, 2 for stereo, 0 if no audio present
+
+rate            audio rate in samples/second
+
+bits            audio bits, usually 8 or 16, 0 if no audio present
+
+format          audio format, most common is 1 for raw PCM, look into avilib.h for others
+
+
+to write video frames or audio, use:
+
+int  AVI_write_frame(avi_t *AVI, char *data, long bytes);
+int  AVI_write_audio(avi_t *AVI, char *data, long bytes);
+
+there is also a feature to duplicate the index entry of the last
+frame without writing the data again to the file, this should
+used with care since I don't know if all AVI players can handle
+the resulting file (xanim can do it!):
+
+int  AVI_dup_frame(avi_t *AVI);
+
+AVI files have a 2 GB limit (as has the Linux ext2 file system),
+avilib will return an error if you try to add more data to the file
+(and it cares that the file still can be correctly closed).
+If you want to check yourself how far you are away from that limit
+(for example to synchronize the amount of audio and video data) use:
+
+long AVI_bytes_remain(avi_t *AVI);