diff --git a/avilib-0.6.10/README.avilib b/avilib-0.6.10/README.avilib new file mode 100644 index 000000000..495c2960a --- /dev/null +++ b/avilib-0.6.10/README.avilib @@ -0,0 +1,221 @@ +avilib: Reading and writing avi files +===================================== + +Copyright (C) 1999 Rainer Johanni + +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 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);