1 :mod:`chunk` --- Read IFF chunked data 2 ====================================== 3 4 .. module:: chunk 5 :synopsis: Module to read IFF chunks. 6 7 .. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org> 8 .. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org> 9 10 **Source code:** :source:`Lib/chunk.py` 11 12 .. index:: 13 single: Audio Interchange File Format 14 single: AIFF 15 single: AIFF-C 16 single: Real Media File Format 17 single: RMFF 18 19 -------------- 20 21 This module provides an interface for reading files that use EA IFF 85 chunks. 22 [#]_ This format is used in at least the Audio Interchange File Format 23 (AIFF/AIFF-C) and the Real Media File Format (RMFF). The WAVE audio file format 24 is closely related and can also be read using this module. 25 26 A chunk has the following structure: 27 28 +---------+--------+-------------------------------+ 29 | Offset | Length | Contents | 30 +=========+========+===============================+ 31 | 0 | 4 | Chunk ID | 32 +---------+--------+-------------------------------+ 33 | 4 | 4 | Size of chunk in big-endian | 34 | | | byte order, not including the | 35 | | | header | 36 +---------+--------+-------------------------------+ 37 | 8 | *n* | Data bytes, where *n* is the | 38 | | | size given in the preceding | 39 | | | field | 40 +---------+--------+-------------------------------+ 41 | 8 + *n* | 0 or 1 | Pad byte needed if *n* is odd | 42 | | | and chunk alignment is used | 43 +---------+--------+-------------------------------+ 44 45 The ID is a 4-byte string which identifies the type of chunk. 46 47 The size field (a 32-bit value, encoded using big-endian byte order) gives the 48 size of the chunk data, not including the 8-byte header. 49 50 Usually an IFF-type file consists of one or more chunks. The proposed usage of 51 the :class:`Chunk` class defined here is to instantiate an instance at the start 52 of each chunk and read from the instance until it reaches the end, after which a 53 new instance can be instantiated. At the end of the file, creating a new 54 instance will fail with an :exc:`EOFError` exception. 55 56 57 .. class:: Chunk(file, align=True, bigendian=True, inclheader=False) 58 59 Class which represents a chunk. The *file* argument is expected to be a 60 file-like object. An instance of this class is specifically allowed. The 61 only method that is needed is :meth:`~io.IOBase.read`. If the methods 62 :meth:`~io.IOBase.seek` and :meth:`~io.IOBase.tell` are present and don't 63 raise an exception, they are also used. 64 If these methods are present and raise an exception, they are expected to not 65 have altered the object. If the optional argument *align* is true, chunks 66 are assumed to be aligned on 2-byte boundaries. If *align* is false, no 67 alignment is assumed. The default value is true. If the optional argument 68 *bigendian* is false, the chunk size is assumed to be in little-endian order. 69 This is needed for WAVE audio files. The default value is true. If the 70 optional argument *inclheader* is true, the size given in the chunk header 71 includes the size of the header. The default value is false. 72 73 A :class:`Chunk` object supports the following methods: 74 75 76 .. method:: getname() 77 78 Returns the name (ID) of the chunk. This is the first 4 bytes of the 79 chunk. 80 81 82 .. method:: getsize() 83 84 Returns the size of the chunk. 85 86 87 .. method:: close() 88 89 Close and skip to the end of the chunk. This does not close the 90 underlying file. 91 92 The remaining methods will raise :exc:`OSError` if called after the 93 :meth:`close` method has been called. Before Python 3.3, they used to 94 raise :exc:`IOError`, now an alias of :exc:`OSError`. 95 96 97 .. method:: isatty() 98 99 Returns ``False``. 100 101 102 .. method:: seek(pos, whence=0) 103 104 Set the chunk's current position. The *whence* argument is optional and 105 defaults to ``0`` (absolute file positioning); other values are ``1`` 106 (seek relative to the current position) and ``2`` (seek relative to the 107 file's end). There is no return value. If the underlying file does not 108 allow seek, only forward seeks are allowed. 109 110 111 .. method:: tell() 112 113 Return the current position into the chunk. 114 115 116 .. method:: read(size=-1) 117 118 Read at most *size* bytes from the chunk (less if the read hits the end of 119 the chunk before obtaining *size* bytes). If the *size* argument is 120 negative or omitted, read all data until the end of the chunk. An empty 121 bytes object is returned when the end of the chunk is encountered 122 immediately. 123 124 125 .. method:: skip() 126 127 Skip to the end of the chunk. All further calls to :meth:`read` for the 128 chunk will return ``b''``. If you are not interested in the contents of 129 the chunk, this method should be called so that the file points to the 130 start of the next chunk. 131 132 133 .. rubric:: Footnotes 134 135 .. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic 136 Arts, January 1985. 137 138