The AVI file read/write object provides methods to access, read, write, and parse files in the AVI format. In this section, the term track refers to what the AVI format calls a stream.
When writing to a file, this object adds index entries if the file has an index. When creating a new file, the AVIF_HASINDEX bit in the dwFlags field of the MainAVIHeader structure can be set to tell this object to create an index. If this bit is not set, this object does not create an index.
If an index is present in the file, it is always used by this object. If the file does not have an index, seek operations are still possible but with reduced performance. The object goes to frame 0 and steps through the frames until it reaches the target frame.
When writing to a file, this object always creates rec chunks to hold the data. When reading from a file, this object accepts data with or without rec chunks.
The frame numbering starts at 0. If there are 60 frames in the file, they are numbered from 0 to 59. The rec chunks are considered one frame; all the subchunks of a rec chunk are considered to be in the same frame.
If each rec chunk (R) has one audio (A) subchunks and one video (V) subchunk, the frame numbering is as follows:
R{A V} R{A V} R{A V} R{A V} R{A V} R{A V} ...
|0 |1 |2 |3 |4 |5 |...
If each rec chunk (R) has two audio (A) and one video (V) subchunk, the frame numbering is as follows:
R{A A V} R{A A V} R{A A V} R{A A V} R{A A V} R{A A V} ...
|0 |1 |2 |3 |4 |5 |...
If one track has initial frames, the numbering is as follows (dwInitialFrames is equal to 2, dwTotalFrames is equal to 8):
R{A} R{A} R{A V} R{A V} R{A V} R{A V} R{A V} R{A V} R{V} R{V}
|0 |1 |2 |3 |4 |5 |6 |7 |8 |9
If no rec chunks are used, the frame numbering is as follows:
A V A V A V A V A V A V ...
|0 |1 |2 |3 |4 |5 |...
If no rec chunks are used and one track has initial frames, the numbering is as follows: (dwInitialFrames is equal to 2, dwTotalFrames is equal to 8)
A A A V A V A V A V A V A V V V
|0 |1 |2 |3 |4 |5 |6 |7 |8 |9
If no rec chunks are used and there are two audio chunks for every video chunk, the frame numbering is as follows:
A A V A A V A A V A A V A A V
|0 |1 |2 |3 |4 |5 |6 |7 |8 |9
To learn more about the UMSAVIReadWrite object, see:
For introductory information, see Formatted File Access Objects.
The AVI file format is built on top of the RIFF file format. The following is a description of the AVI file format.
RIFF ( 'AVI'
LIST ( 'hdrl'
'avih' ( <Main AVI Header> )
LIST ( 'strl'
'strh' ( <Stream 1 Header> )
'strf' ( <Stream 1 Format> )
['strd' ( <Stream 1 optional codec data> )]
)
LIST ( 'strl'
'strh' ( <Stream 2 Header> )
'strf' ( <Stream 2 Format> )
['strd' ( <Stream 2 optional codec data> )]
)
...
)
LIST ( 'movi'
{
'##dc' ( <compressed DIB> )
|
LIST ( 'rec '
'##dc' ( <compressed DIB> )
'##db' ( <uncompressed DIB> )
'##wb' ( <audio data> )
'##pc' ( <palette change> )
...
)
}
...
)
[ 'idx1' ( <AVI Index> ) ] )
Where ## is the track number. For example, if video was track 0 and audio was track 1, the video chunks would be '00dc' and the audio chunks would be '01wb'.
The object defines the following data types in the avistructs.h file in the:
typedef signed char sint1; typedef unsigned char uint1; typedef signed short sint2; typedef unsigned short uint2; typedef signed long sint4; typedef unsigned long uint4;
Additionally the following AVI file structures are defined:
typedef struct {
uint4 dwMicroSecPerFrame;
uint4 dwMaxBytesPerSec;
uint4 dwReserved1;
uint4 dwFlags;
uint4 dwTotalFrames;
uint4 dwInitialFrames;
uint4 dwStreams;
uint4 dwSuggestedBufferSize;
uint4 dwWidth;
uint4 dwHeight;
uint4 dwScale;
uint4 dwRate;
uint4 dwStart;
uint4 dwLength;
} MainAVIHeader;
typedef struct {
uint4 fccType;
uint4 fccHandler;
uint4 dwFlags;
uint4 dwReserved1;
uint4 dwInitialFrames;
uint4 dwScale;
uint4 dwRate;
uint4 dwStart;
uint4 dwLength;
uint4 dwSuggestedBufferSize;
uint4 dwQuality;
uint4 dwSampleSize;
} AVIStreamHeader;
typedef struct {
uint1 bFirstEntry;
uint1 bNumEntries;
uint2 wFlags;
} AVIPALCHANGE;
typedef struct {
uint4 ckid;
uint4 dwFlags;
uint4 dwChunkOffset;
uint4 dwChunkLength;
} AVIINDEXENTRY;
To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list can vary with the application. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object are:
enum ReturnCode {
Success,
Failure,
FileNotOpen,
InvalidTrack,
StorageAllocationFailure,
InvalidArgument,
NotAnAVIFile,
RiffFailure,
EndOfFile
};
This function flushes buffers and closes the file. This can be called by the destructor if needed.
Success Failure
This method flushes data held in the object to the file.
Success Failure RiffFailure
This returns the next audio chunk from the AVI file. The chunks are returned in the order they exist in the file. If track selection is used, only the selected tracks are returned. The default is that all tracks are selected. This function skips past any video chunks to get the next audio chunk.
This method identifies an audio chunk by checking the stream header field fccType to see if it is equal to FOURCC_auds. This method does not recognize an audio chunk if it is not marked as type auds.
| in void *v | This returns the next audio chunk from the AVI file. The caller should supply enough space for the chunk. |
Success Failure FileNotOpen InvalidArgument EndOfFile
This returns the size of the next audio chunk from the AVI file. The sizes of the chunks are returned in the order they exist in the file. If track selection is used, only the sizes of chunks from the selected tracks are returned. The default is that all tracks are selected. This function skips past any video chunks to get at the next audio chunk.
This method identifies an audio chunk by checking the stream header field fccType to see if it is equal to FOURCC_auds. This method does not recognize an audio chunk if it is not marked as type auds.
After this method is called, the get_chunk_fourcc, get_chunk_track, and get_chunk_flags methods apply to the next audio chunk to be read from the file with the get_audio_chunk method. Before this method is called, those three methods can return information about some previous chunk.
The return value is the size in bytes of the next audio chunk. A size of 0 indicates end of file. A size of -1 indicates an error.
This returns the MainAVIHeader structure from the AVI file. All byte-order swapping has been done.
| in void *headerp | This should be a pointer to a MainAVIHeader structure. |
Success Failure FileNotOpen InvalidArgument
This method returns the next video or audio chunk from the AVI file. The type of the chunk can be determined from the track number. The tracks are returned in the order they exist in the file. If track selection is used, only the selected tracks are returned. The default is that all tracks are selected.
| in void *v | This returns the next video or audio chunk from the AVI file. The caller must supply enough space to hold the chunk. |
Success Failure FileNotOpen InvalidArgument EndOfFile
This method returns the value of the dwFlags field in the AVIINDEXENTRY structure for the chunk. This method applies to the next chunk to be read from the file.
Possible values are -1 in case of an error, 0 in case there is no index in the file, or the value of the dwFlags field.
This method returns the RIFF FOURCC value of the chunk containing the audio or video data. This method applies to the next chunk to be read from the file.
Possible values are 0 if not successful or the RIFF FOURCC value of the chunk containing the current chunk.
This method gets the size of the next video or audio chunk in the AVI file. Unselected tracks are bypassed by this method. This method applies to the next chunk to be read from the file. After this method is called, the get_chunk_fourcc, get_chunk_track, and get_chunk_flags methods apply to the next chunk to be read from the file.
If successful, returns the size in bytes of the next chunk. A 0 is returned if at the end of file. A -1 is returned if unsuccessful.
This method returns the track number for the chunk. This method applies to the next chunk to be read from the file.
Possible return values are -1 if not successful or the track number for the current chunk.
This function returns the frame number for the next frame to be read. Frame numbers start at 0. A file with 10 frames has frame numbers 0 to 9. This method applies to the next chunk to be read from the file.
| in long *frame_number | This is a pointer to a long integer for the next frame to be read. |
Success Failure InvalidArgument FileNotOpen
This method gets a copy of the index from the file (if it exists). The caller must supply enough space to hold all the AVIINDEXENTRY structures in the index. The caller can use get_index_size to find out how many structures are needed.
| in void *v | This is a pointer to an array of AVIINDEXENTRY structures. |
Success Failure FileNotOpen InvalidArgument
This method returns the number of AVIINDEXENTRY structures in the file.
The return value is 0 if there is no index in the file or if there are no chunks in the file. Otherwise, it returns the number of AVIINDEXENTRY structures in the file.
This function returns the strd data chunks from the AVI file. This data chunk is optional. There may be one for each track. If the size that is returned by the get_strd_sizes method is 0, that track does not have a strd chunk. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure. To find the sizes of each strd chunk, use the get_strd_sizes method. Byte-order swapping has not been done.
| in long count | This is the number of buffers pointed to by datap. |
| in void *datap | This is a pointer to an array of count pointers to buffers to hold the strd data. |
Success Failure FileNotOpen InvalidArgument
This method returns the sizes of each strd data chunk from the AVI file. This data chunk is optional. There may be one for each track. If the size that is returned is 0, that track does not have a strd chunk. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure.
| in long count | This is the number of long integers pointed to by sizep. |
| in long *sizep | This should be a pointer to count long integers. |
Success Failure FileNotOpen InvalidArgument
This returns the AVIStreamHeader structures from the AVI file. There should be one for each track. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure. All byte-order swapping has been done.
| in long count | This is the number of AVIStreamHeader structures pointed to by headerp. |
| in void *headerp | This should be a pointer to count AVIStreamHeader structures. |
Success Failure FileNotOpen InvalidArgument
This function returns the strf data chunks from the AVI file. There should be one for each track. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure. To find the sizes of each strf chunk, use the get_strf_sizes method. Byte-order swapping has not been done.
| in long count | This is the number of buffers pointed to by datap. |
| in void *datap | This is a pointer to an array of count pointers to buffers to hold the strf data. |
Success Failure FileNotOpen InvalidArgument
This method returns the sizes of each strf data chunk from the AVI file. There should be one for each track. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure.
| in long count | This is the number of long integers pointed to by sizep. |
| in long *sizep | This should be a pointer to count long integers. |
Success Failure FileNotOpen InvalidArgument
This returns the number of tracks in the file.
This returns the number of tracks in the file. A 0 is returned in case of an error.
This returns the next video chunk from the AVI file. The chunks are returned in the order they exist in the file. If track selection is used, only the selected tracks are returned. The default is that all tracks are selected. This function skips past any audio chunks to get at the next video chunk.
This method identifies a video chunk by checking the stream header field fccType to see if it is equal to FOURCC_vids. This method does not recognize a video chunk if it is not marked as type vids.
| in void *v | This returns the next video chunk from the AVI file. The caller should supply enough space to hold the chunk. |
Success Failure FileNotOpen InvalidArgument EndOfFile
This returns the size of the next video chunk from the AVI file. The sizes of the chunks are returned in the order they exist in the file. If track selection is used, only the sizes of chunks from the selected tracks are returned. The default is that all tracks are selected. This function skips past any audio chunks to get at the next video chunk.
This method identifies a video chunk by checking the stream header field fccType to see if it is equal to FOURCC_vids. This method does not recognize a video chunk if it is not marked as type vids.
After this method is called, the get_chunk_fourcc, get_chunk_track, and get_chunk_flags methods apply to the next video chunk to be read from the file with the get_video_chunk method. Before this method is called, those three methods can return information about some previous chunk.
The return value is the size in bytes of the next video chunk. A size of 0 indicates end of file. A size of -1 indicates an error.
This function opens an AVI file for reading or writing.
Success Failure InvalidArgument NotAnAVIFile RiffFailure
This method writes the MainAVIHeader to the file. Most of the fields in the structure should be filled by the caller. The rest are calculated or overridden by this method. Some consistency checks are applied to the values filled by the caller. This header can be rewritten at any time. The object gets better performance and uses less temporary space if the header is written before writing frames.
Set the following field values in the structure:
dwMicroSecPerFrame dwMaxBytesPerSec dwReserved1 (set to zero) dwFlags dwInitialFrames dwStreams dwSuggestedBufferSize dwWidth dwHeight dwScale dwRate dwStart dwLength
The dwStreams value is checked and AVIStreamHeader stream headers are deleted or created to match.
If the dwFlags value has the AVIF_HASINDEX bit set but there is no index in the file, an index is created. If the dwFlags value has the AVIF_MUSTUSEINDEX bit set but does not have the AVIF_HASINDEX bit set, the method returns an error.
The dwTotalFrames value in the structure is ignored and is overwritten with the real number of frames in the file.
| in void *headerp | This is a pointer to the MainAVIHeader being written. |
Success Failure FileNotOpen StorageAllocationFailure InvalidArgument
This method inserts (writes) a chunk into the file at the current position. No byte-swapping is done on the data. The FOURCC value is edited to add the track number. For example, if the caller supplies 00wb as the FOURCC value and 1 as the track value, the RIFF chunk is created as 01wb. The flags value is ignored if the file does not have an index. The file header is updated to reflect the real number of frames written to the file. This method is not affected by the select_track and un_select_track methods.
Success Failure FileNotOpen StorageAllocationFailure InvalidTrack InvalidArgument
This method puts AVIStreamHeader stream headers into the file. This header can be rewritten at any time. The object gets better performance and uses less temporary space if the header is written before writing frames.
| in long count | This is the number of AVIStreamHeader structures pointed to by headerp. |
| in void *headerp | This points to count AVIStreamHeader structures that are to be written. |
Success Failure FileNotOpen InvalidArgument StorageAllocationFailure
This method puts strd chunks into the file.
Success Failure FileNotOpen InvalidArgument StorageAllocationFailure
This method puts strf chunks into the file.
Success Failure FileNotOpen StorageAllocationFailure InvalidArgument
This function attempts to seek to the frame number specified as an argument. If unsuccessful, the file position is unmodified. Frame numbers start at 0. A file with 10 frames has frame numbers 0 to 9. If the file does not have an index, seek operations are still possible but with reduced performance. The object goes to frame 0 and steps through the frames until it reaches the target frame.
| in long frame_number | This is the frame number desired. |
Success Failure InvalidArgument FileNotOpen RiffFailure
This function is used to select which tracks are returned by the get_*chunk functions. All tracks are selected by default when the file is opened. Multiple tracks can be selected by multiple use of this call. This method only applies when reading chunks from the file.
| in long track | This is the number of the track to be selected. A -1 value means to select all tracks. |
Success Failure InvalidTrack FileNotOpen StorageAllocationFailure
This function checks the status of the object. If the file is not open, this function returns an error.
Success Failure FileNotOpen
This function is used to select which tracks are returned by the get_*chunk functions. All tracks are selected by default when the file is opened. Multiple tracks can be unselected by multiple use of this method. This method only applies when reading chunks from the file.
| in long track | This is the number of the track to be unselected. A -1 value means to deselect all tracks. |
Success Failure InvalidTrack FileNotOpen StorageAllocationFailure
For introductory information, see Formatted File Access Objects.