AVI File Format

AVI File Format 1 Last change: December 14, 2006 Contents 1 Introduction 3 1.1 Why another AVI file format documentation? . . . . . . . . . . . . . . . . . 3 1.2 Basic data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2.1 Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2.2 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3 AVI file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2 Layout of an AVI file 6 2.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.1 MainAVIHeader (avih) . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.2 The Stream header list - general . . . . . . . . . . . . . . . . . . . . 9 2.1.3 The stream header list element: strh . . . . . . . . . . . . . . . . . . 10 2.1.4 The stream header list element: strf . . . . . . . . . . . . . . . . . . 11 2.1.5 The stream header list element: indx . . . . . . . . . . . . . . . . . . 11 2.1.6 The stream header list element: strn . . . . . . . . . . . . . . . . . . 11 3 AVI Indexes 12 3.1 old style index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2 Open-DML Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2.1 Upper Level Index ('Super Index') . . . . . . . . . . . . . . . . . . . 14 3.2.2 The Standard Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.3 Using the Open-DML Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4 The movi - Lists 18 5 Audio types requiring special attention 19 5.1 MP3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.2 AC3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.3 DTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.4 VBR audio - general . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.5 MPx VBR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.6 AAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.7 VFR Audio - Storing Vorbis in AVI . . . . . . . . . . . . . . . . . . . . . . . 21 6 Subtitles in AVI files 22 7 Garbage in AVI files 24 7.1 Constant Bitrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 7.2 Variable Bitrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2 8 Overhead of AVI files 25 8.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 8.2 Getting number of CHUNKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 8.2.1 Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 8.2.2 Audio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 8.2.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3 1 Introduction 1.1 Why another AVI file format documentation? Even though the AVI file format has been around for more than 10 years, there is no docu- mentation available which does not only describe the format itself, but which also informs about issues that come from flawed demuxers and flawed decoders, and how to circumvent them. The goal of this document is not only to explain the AVI format, as it is defined on the paper, but rather how to use it, when working with flawed muxers, flawed demuxers, and flawed decompressors. 4 1.2 Basic data structures There are 2 types of atoms in AVI files: 1.2.1 Chunks typedef struct { DWORD dwFourCC DWORD dwSize BYTE data[dwSize] // contains headers or video/audio data } CHUNK; 1.2.2 Lists typedef struct { DWORD dwList DWORD dwSize DWORD dwFourCC BYTE data[dwSize-4] // contains Lists and Chunks } LIST; A chunk containing video, audio or subtitle data uses a dwFourCC containing 2 hexadecimal digits specifying the stream number and 2 letters specifying the data type (dc = video, wb = audio, tx = text). The values dwFourCC and dwSize have the same meaning in both of the structures: dwFourCC describes the type of the chunk (for example 'hdrl' for 'header list'), and dwSize contains the size of the chunk or list, including the first byte after the dwSize value. In the case of Lists, this includes the 4 bytes taken by dwFourCC! The value of dwList can be 'RIFF' ('RIFF-List') or 'LIST' ('List'). 5 1.3 AVI file types Basicly, there are 3 types of AVI files: • AVI 1.0 The original, old AVI file. • Open-DML An extension to the AVI file format. Version 1.02 has been specified by 28/02/1996. The most important improvements are: � almost unlimited filesize (much more than what NTFS allows, for example) � overhead reduced by 33% • Hybride-Files: Open-DML files that contain an additional Legacy Index for compat- ibility reasons. This is not an "official" word for those files, but it is describing that file type pretty well. Hybride files containing only one RIFF List can be treated as either file type. This document describes the subset of Open-DML 1.02 file format features, as well as some additions ('hacks'), which work in common players if the proper (freely available) filters are installed. Features that work in Open-DML, but not in AVI 1.0, will be indicated to be Open-DML only. 6 2 Layout of an AVI file A RIFF-List where dwFourCC = 'AVI ' shall be called a 'RIFF-AVI-List', a RIFF-List where dwFourCC = 'AVIX' shall be called a 'RIFF-AVIX-List'. Every AVI file has the following layout: RIFF AVI // mandatory { RIFF AVIX } // only for Open-DML files Unlike what a uint32 suggests, the limit for the size of those lists is not 4 GB, but • for AVI 1.0: size(RIFF-AVI) < 2 GB • for Open-DML: � size(RIFF-AVI) < 1 GB (!!) (assumed to be 2 GB by some muxing applications, like VirtualDub!) � size(RIFF-AVIX) < 2 GB As Windows XP insists on reading the entire first RIFF AVI list if no Legacy Index (see page 12) is found, and as that Legacy Index causes overhead, it is recommended to create RIFF-AVI-Lists as small as possible. 7 2.1 Headers The header section of an AVI file looks like this: The following sections describe the meaning of these lists and chunks. 2.1.1 MainAVIHeader (avih) This structure is defined as follows: typedef struct { DWORD dwMicroSecPerFrame; // frame display rate (or 0) DWORD dwMaxBytesPerSec; // max. transfer rate DWORD dwPaddingGranularity; // pad to multiples of this // size; DWORD dwFlags; // the ever-present flags DWORD dwTotalFrames; // # frames in file DWORD dwInitialFrames; DWORD dwStreams; DWORD dwSuggestedBufferSize; DWORD dwWidth; DWORD dwHeight; DWORD dwReserved[4]; } MainAVIHeader; 8 Unfortunately, those values do NOT have the meaning they seem to have when looking at their names. • dwMicroSecPerFrame Contains the duration of one video frame in microseconds. This value can be ignored (see stream header), but shall be written correctly by any AVI writer. Important: Some broken programs, like AVIFrate, write the framerate value in the stream header, but not dwMicroSecPerFrame. Thus, dwMicroSecPerFrame should not be considered reliable! • dwMaxBytesPerSec Highest occuring data rate within the file. That value is of no importance either. Its reliability should not be overrated. • dwPaddingGranularity File is padded to a multiple of this • dwFlags See below • dwTotalFrames Contains the number of video frames in the RIFF-AVI list (it should NOT contain the total number of frames in the entire file if there are RIFF-AVIX-Lists. Some tools claiming to handle AVI files even assume this, but it definitely violates the Open-DML file format specification. Such applications are broken.) As some AVI file muxers write bad values here, this value should not be considered reliable. • dwInitialFrames Ignore that • dwStreams Number of streams in the file • dwSuggestedBufferSize Size of buffer required to hold chunks of the file. The reliability of this value should not be overrated. • dwWidth Width of video stream • dwHeight Height of video stream Available Flags for MainAVIHeader::dwFlags • AVIF_HASINDEX The file has an index 9 • AVIF_MUSTUSEINDEX The order in which the video and audio chunks must be replayed is determined by the index and may differ from the order in which those chunks occur in the file. • AVIF_ISINTERLEAVED The streams are properly interleaved into each other • AVIF_WASCAPTUREFILE The file was captured. The interleave might be weird. • AVIF_COPYRIGHTED Ignore it • AVIF_TRUSTCKTYPE (Open-DML only!) This flag indicates that the keyframe flags in the index are reliable. If this flag is not set in an Open-DML file, the keyframe flags could be defective without technically rendering the file invalid. 2.1.2 The Stream header list - general There is one strl - List for each stream. If the number of strl - Lists inside the hdrl - List is different from MainAVIHeader::dwStreams, a fatal error should be reported. 10 2.1.3 The stream header list element: strh typedef struct { FOURCC fccType; FOURCC fccHandler; DWORD dwFlags; WORD wPriority; WORD wLanguage; DWORD dwInitialFrames; DWORD dwScale; DWORD dwRate; /* dwRate / dwScale == samples/second */ DWORD dwStart; DWORD dwLength; /* In units above... */ DWORD dwSuggestedBufferSize; DWORD dwQuality; DWORD dwSampleSize; RECT rcFrame; } AVIStreamHeader; Again, the meaning is not always obvious. • fccType Can be � 'vids' - video � 'auds' - audio � 'txts' - subtitle • fccHandler FourCC of codec to be used. • dwFlags The following flags are defined: � AVISF_DISABLED - Stream should not be activated by default � AVISF_VIDEO_PALCHANGES - Stream is a video stream using palettes where the palette is changing during playback. • dwInitialFrames Number of the first block of the stream that is present in the file. • dwRate / dwScale = samples / second (audio) or frames / second (video). dwScale and dwRate should be mutually prime. Tests have shown that for example 10,000,000/400,000 instead of 25/1 results in files that don't work on some hardware MPEG4 players. 11 • dwStart Start time of stream. In the case of VBR audio, this value indicates the number of silent frames to be played before the stream starts. • dwLength size of stream in units as defined in dwRate and dwScale • dwSuggestedBufferSize Size of buffer necessary to store blocks of that stream. Can be 0 (in that case the application has to guess), but should not be 0, as Microsoft's AVI splitter does not handle this case properly in some cases (e.g. MP3-CBR in Open-DML files) • dwQuality should indicate the quality of the stream. Not important • dwSampleSize number of bytes of one stream atom (that should not be split any further). 2.1.4 The stream header list element: strf The structure of the strf chunk depends on the media type. Video streams use the BITMAPINFOHEADER structure, whereas audio streams use the WAVEFORMATEX structure. 2.1.5 The stream header list element: indx This chunk contains the upper level index for the stream. See page 13. 2.1.6 The stream header list element: strn This element contains a name for the stream. That stream name should only use plain ASCII, especially not UTF-8. 12 3 AVI Indexes 3.1 old style index The index as described is the index you will find in AVI 1.0 files. It is placed after the movi List in the RIFF AVI List. The data section of the idx1 chunk has the following layout: AVIINDEXENTRY index_entry[n] typedef struct { DWORD ckid; DWORD dwFlags; DWORD dwChunkOffset; DWORD dwChunkLength; } AVIINDEXENTRY; Those values have the following meaning: • ckid Specifies a four-character code corresponding to the chunk ID of a data chunk in the file. • dwFlags The following flags are defined: � AVIIF_KEYFRAME: The chunk the entry refers to is a keyframe. � AVIIF_LIST: The entry points to a list, not to a chunk. � AVIIF_FIRSTPART: Indicates this chunk needs the frames following it to be used; it cannot stand alone. � AVIIF_LASTPART: Indicates this chunk needs the frames preceding it to be used; it cannot stand alone. � AVIIF_NOTIME: The duration which is applied to the corresponding chunk is 0. If neither AVIIF_FIRSTPART nor AVIIF_LASTPART is set, the chunk can be used alone, in other words, it is at least one packet of the corresponding stream. This is important for storing VBR audio streams in AVI files (see chapter 5.4) • dwChunkOffset Contains the position of the header of the corresponding Chunk. Warning: This can be either the absolute position in the file, or the position relatively to the first byte of the 'movi' identificator. An AVI File parser must be able to handle both versions. • dwChunkLength Contains the size of the corresponding chunk in bytes. 13 3.2 Open-DML Index The general structure of an Open-DML-Index-Chunk is the following: typedef struct _aviindex_chunk { FOURCC fcc; DWORD cb; WORD wLongsPerEntry; BYTE bIndexSubType; BYTE bIndexType; DWORD nEntriesInUse; DWORD dwChunkId; DWORD dwReserved[3]; struct _aviindex_entry { DWORD adw[wLongsPerEntry]; } aIndex [ ]; } AVIINDEXCHUNK; Every subtype of Open-DML index structures is compatible to this one. The elements have the following meaning: • fcc, cb: Chunk header, same as dwFourCC and dwSize in the CHUNK structure • wLongsPerEntry: every aIndex[i] has a size of 4*wLongsPerEntry bytes. (the struc- ture of each aIndex[i] depends on the special type of index) • bIndexType, bIndexSubType: defines the type of the index • nEntriesInUse: aIndex[0]..aIndex[nEntriesInUse-1] are valid • dwChunkId: ID of the stream the index points into, for example '00dc'. Consequently, one such index chunk can only point to data of one and the same stream. 14 3.2.1 Upper Level Index ('Super Index') The upper level index ('super index') points to other index chunks and has the following structure: typedef struct _avisuperindex_chunk { FOURCC fcc; DWORD cb; WORD wLongsPerEntry; BYTE bIndexSubType; BYTE bIndexType; DWORD nEntriesInUse; DWORD dwChunkId; DWORD dwReserved[3]; struct _avisuperindex_entry { __int64 qwOffset; DWORD dwSize; DWORD dwDuration; } aIndex[ ]; } AVISUPERINDEX; The following values are now defined more specifically: • bIndexType = AVI_INDEX_OF_INDEXES • bIndexSubType = [ AVI_INDEX_2FIELD | 0 ] • wLongsPerEntry = 4 As you can see, the aIndex array now consists of 4 DWORDs per entry. The values have the following meaning: • qwOffset: Position of the index chunk this entry points to in the file • dwSize: The size of the standard or field index chunk the entry is pointing to • dwDuration: The duration, measured in stream ticks as indicated in the AVI stream header. In case of video or VBR audio, that usually refers to the number of frames. Important: VirtualDub 1.4.10 and earlier versions wrote b0rked values for this member in the audio stream. Thus, an AVI parser should be able to handle files without using this value! 15 3.2.2 The Standard Index This index type contains pointers to video, audio or subtitle chunks. It also is a special form of the general Open-DML Index and looks like this: typedef struct _avistdindex_chunk { FOURCC fcc; DWORD cb; WORD wLongsPerEntry; BYTE bIndexSubType; BYTE bIndexType; DWORD nEntriesInUse; DWORD dwChunkId; __int64 qwBaseOffset; DWORD dwReserved3; struct _avistdindex_entry { DWORD dwOffset; DWORD dwSize; } aIndex[ ]; } AVISTDINDEX; • wLongsPerEnrty: As you can see easily, each aIndex[i] takes 8 bytes, so wLongsPerEntry = 2 • bIndexSubType: = 0 • bIndexType:= AVI_INDEX_OF_CHUNKS • qwBaseOffset: This value is added to each dwOffset value of the AVISTDINDEX. • dwOffset, dwSize: These elements define the position (qwBaseOffset + dwOffset) of the data section of the corresponding CHUNK (NOT the chunk header!) and its length. There are nEntriesInUse such pairs, each one describing one video/audio frame. Note that Bit 31 of dwSize indicates the frametype: If this bit is set, this frame is not a keyframe. 16 Low-overhead mode The Open-DML specification does not explicitly require that each "data section" the index contains an entry to be preceded by a chunk header. Thus, several frames can be put into one chunk, while having one index entry per frame. This way, only few frames have a chunk header, reducing the overhead by 50% compared to normal Open-DML files. This means, of course, that the AVIF_MUSTUSEINDEX flag in the main AVI header must be set, to force any parser to use the index. Files created this way will be called "low overhead AVI files". This is not an AVI file type on its own. Any parser handling that flag, as well as the Open- DML index correctly, should be compatible to such files. Microsoft's AVI splitter, as well as VirtualDub(Mod) can handle such files without problems, without having been updated to do so. 17 3.3 Using the Open-DML Index The preceding section described what the Open-DML Index looks like. This section will deal with using it. Each stream contains an 'indx' chunk in its stream header list ('strl'). This chunk is a Super Index chunk. As each Standard Index contains one 64 bit offset and then a list of 32 bit offsets relatively to the 64 bit offset, one Standard Index chunk can only point to data within one 4 GB segment. Thus you need one Standard Index per 4 GB file size per stream. Unfortunately, it seems that Microsoft did not read the specification properly: If a file contains more than 3 audio streams, then the Microsoft AVI Splitter will not recognize files using such large Standard Index chunks. It is required to use smaller pieces. Tests have shown that pieces with 15000 entries each are small enough to be processed correctly by Microsoft's AVI splitter. 18 4 The movi - Lists The Movi - Lists contain Video, Audio, Subtitle and (secondary) index data. Those can be grouped into rec - Lists. Example: LIST movi LIST rec 01wb 01wb 02wb 03wb 03wb 03wb 00dc 00dc LIST rec 01wb 02wb LIST rec ... ... ix01 ix02 ix03 .... .... The following chunk header IDs are defined: • ..wb: audio chunk • ..dc: video chunk • ..tx: subtitle chunk • ix..: standard index block Grouping chunks into rec - Lists prevents excessive seeking when using the Microsoft AVI splitter for replay, but does not allow playback on some standalone replay devices. The maximum size of a chunk of a stream should be smaller than the corresponding dwSuggestedBufferSize value. Otherwise, some players, especially the Microsoft AVI splitter, could malfunction. 19 5 Audio types requiring special attention 5.1 MP3 wFormatTag = 0x0055 An MP3 audio stream consists of inseparable frames. MP3 decoders should be able to handle partial frames, but it is nevertheless recommended to store entire MP3 frames in the AVI chunks. The strf chunk is an MPEGLAYER3WAVEFORMAT structure, which is an extention to the WAVEFORMATEX structure: typedef struct mpeglayer3waveformat_tag { WAVEFORMATEX wfx; WORD wID; DWORD fdwFlags; WORD nBlockSize; WORD nFramesPerBlock; WORD nCodecDelay; } MPEGLAYER3WAVEFORMAT; Important: This is only valid for MP3 ('MPEG Layer 3'), not for MP1 or MP2 ('MPEG Layer 1 / 2'). If the MP3 stream has a variable bitrate, then you need to convince DirectShow to seek properly. See section 5.4 (page 20) for more details on VBR audio streams in AVI files. Unfortunately, whoever came up with the idea didn't think enough about it: It is possible to create MP3 audio frames larger than 1152 bytes if the sample rate is 32 khz or less. After reading and understanding section 5.4, you'll see why such audio frames render an MP3 stream unplayable if nBlockSize is set to 1152, which is usually done for MP3. Using a larger value would resolve this issue. However, some programs read an MP3 stream as VBR if and only if this value is exactly 1152. In other words, lo