1avilib: Reading and writing avi files
2=====================================
3
4Copyright (C) 1999 Rainer Johanni <Rainer@Johanni.de>
5
6avilib is a open source library for dealing with AVI
7files under Linux or other UNIX operating systems.
8
9It provides a framework for extracting or adding raw
10audio and single raw (=compressed) frames from/to AVI Files.
11
12It does not deal with any compression issues which have to be
13handled on a higher level by the user of avilib.
14
15AVI files may have several video and audiotracks.
16
17avilib writes only one video track and (optionally) one
18audio track and also extracts only the first video and audio
19track (but input files may contain more than one track, the others
20just being ingored).
21
22The interface to avilib is kept similar to the quicktime4linux interface
23(by Adam Williams) with the following important differences:
24
25- since only the first track of video and audio is considered,
26  there is no track argument in any of the routines.
27
28- audio is generally considered as a byte stream and therefore
29  all size arguments used in reading/writing audio are in bytes
30  and not in samples.
31
32- as mentioned above, there are no routines dealing with compression issues.
33
34
35Compiling:
36==========
37
38Since the library consists only of one c source file, I have not provided
39a Makefile or similar, just compile with
40
41cc -c <your favorite options> avilib.c
42
43
44Portability:
45============
46
47AVI-Files use little endian numbers throughout the file, I have tried
48to read/write these numbers in a way which doesn't depent on endianness.
49This library should therefore also be useable on big endian machines.
50This feature is not so heavily tested, however.
51
52
53Usage:
54======
55
56Basics, opening, closing
57------------------------
58
59Include "avilib.h" in your source and declare a pointer:
60
61   avi_t *avifile;
62
63Open the AVI file with:
64
65   avifile = AVI_open_input_file("xxx.avi",1);
66
67or
68
69   avifile = AVI_open_output_file("xxx.avi");
70
71You may either only read from the input file (leaving it unchanged)
72or create a completly new AVI file. There is no editing or append
73mode available.
74
75Both routines will either return a pointer to avi_t or a zero pointer
76in the case of an error.
77
78For closing the file, use:
79
80   int  AVI_close(avi_t *AVI);
81
82Files you have written MUST be closed (the header is written at close time),
83else they will not be readable by any other software.
84
85Files opened for reading should be closed to free the file descriptor
86and some data (unless your program is finishing anyway).
87
88
89Error handling:
90---------------
91
92Most routines (besides open/close) will return 0 or a useful number if successfull
93and a -1 in the case of an error. If an error occured, the external variable
94AVI_errno is set. See avilib.h for the meaning of the error codes in AVI_errno.
95
96There is also a routine (which acts like strerror) to retrieve a string
97description of the last error (which can then be logged or printed):
98
99AVI_strerror(char *str)
100
101
102Reading from an AVI file:
103-------------------------
104
105After opening the file, you can obtain the parameters of the AVI
106with the following routines:
107
108long AVI_video_frames(avi_t *AVI);
109   number of video frames in the file
110
111int  AVI_video_width(avi_t *AVI);
112int  AVI_video_height(avi_t *AVI);
113   width and height of the video in pixels
114
115double AVI_frame_rate(avi_t *AVI);
116   frame rate in frames per second, notice that this is a double value!
117
118char* AVI_video_compressor(avi_t *AVI);
119   string describing the compressor
120
121int  AVI_audio_channels(avi_t *AVI);
122   number of audio channels, 1 for mono, 2 for stereo, 0 if no audio present
123
124int  AVI_audio_bits(avi_t *AVI);
125   audio bits, usually 8 or 16
126
127int  AVI_audio_format(avi_t *AVI);
128   audio format, most common is 1 for raw PCM, look into avilib.h for others
129
130long AVI_audio_rate(avi_t *AVI);
131   audio rate in samples/second
132
133long AVI_audio_bytes(avi_t *AVI);
134   total number of audio bytes in the file
135
136
137In order to read the video frame by frame, use
138(frame numbers are starting from 0 !!!!!)
139
140long AVI_frame_size(avi_t *AVI, long frame);
141   to get the size of frame with number "frame"
142
143long AVI_read_frame(avi_t *AVI, char *vidbuf);
144   to read the next  frame (frame posittion is advanced by 1 after the read)
145
146int  AVI_seek_start(avi_t *AVI);
147int  AVI_set_video_position(avi_t *AVI, long frame);
148   to position in the AVI file
149   (for reading the frames out of order)
150
151
152Read audio with
153
154int  AVI_set_audio_position(avi_t *AVI, long byte);
155   to position to an arbitrary byte position within the audio stream
156
157long AVI_read_audio(avi_t *AVI, char *audbuf, long bytes);
158   to actually read "bytes" number of audio bytes.
159   the audio position is advanced by "bytes", so there is no
160   need to reposition before every call when reading in order.
161
162
163Avoiding lengthy index searches:
164--------------------------------
165
166When opening the AVI file, avilib looks if the file has an index attached
167and if this is not the case, it creates one by reading through the whole file.
168
169If you want to read through the file only once, creation of an index is
170not necessary in that case. You may use AVI_open_input_file with the second
171argument set to 0 and then use AVI_read_data for readin through the file.
172
173Look to the source for the arguments of AVI_read_data.
174
175
176Writing to an AVI file:
177-----------------------
178
179After you have opened the file, use the following routines to set
180the properties of the AVI file:
181
182void AVI_set_video(avi_t *AVI, int width, int height, double fps, char *compressor);
183void AVI_set_audio(avi_t *AVI, int channels, long rate, int bits, int format);
184
185with:
186
187width, height   width and height of the video in pixels
188
189fps             frame rate in frames per second, notice that this is a double value!
190
191compressor      string describing the compressor
192
193channels        number of audio channels, 1 for mono, 2 for stereo, 0 if no audio present
194
195rate            audio rate in samples/second
196
197bits            audio bits, usually 8 or 16, 0 if no audio present
198
199format          audio format, most common is 1 for raw PCM, look into avilib.h for others
200
201
202to write video frames or audio, use:
203
204int  AVI_write_frame(avi_t *AVI, char *data, long bytes);
205int  AVI_write_audio(avi_t *AVI, char *data, long bytes);
206
207there is also a feature to duplicate the index entry of the last
208frame without writing the data again to the file, this should
209used with care since I don't know if all AVI players can handle
210the resulting file (xanim can do it!):
211
212int  AVI_dup_frame(avi_t *AVI);
213
214AVI files have a 2 GB limit (as has the Linux ext2 file system),
215avilib will return an error if you try to add more data to the file
216(and it cares that the file still can be correctly closed).
217If you want to check yourself how far you are away from that limit
218(for example to synchronize the amount of audio and video data) use:
219
220long AVI_bytes_remain(avi_t *AVI);
221