blob: c1ba497b2b29a5abcab9db63aeaf4327c77ca54b [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`chunk` --- Read IFF chunked data
2======================================
3
4.. module:: chunk
5 :synopsis: Module to read IFF chunks.
6.. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>
7.. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>
8
9
10.. index::
11 single: Audio Interchange File Format
12 single: AIFF
13 single: AIFF-C
14 single: Real Media File Format
15 single: RMFF
16
17This module provides an interface for reading files that use EA IFF 85 chunks.
18[#]_ This format is used in at least the Audio Interchange File Format
19(AIFF/AIFF-C) and the Real Media File Format (RMFF). The WAVE audio file format
20is closely related and can also be read using this module.
21
22A chunk has the following structure:
23
24+---------+--------+-------------------------------+
25| Offset | Length | Contents |
26+=========+========+===============================+
27| 0 | 4 | Chunk ID |
28+---------+--------+-------------------------------+
29| 4 | 4 | Size of chunk in big-endian |
30| | | byte order, not including the |
31| | | header |
32+---------+--------+-------------------------------+
33| 8 | *n* | Data bytes, where *n* is the |
34| | | size given in the preceding |
35| | | field |
36+---------+--------+-------------------------------+
37| 8 + *n* | 0 or 1 | Pad byte needed if *n* is odd |
38| | | and chunk alignment is used |
39+---------+--------+-------------------------------+
40
41The ID is a 4-byte string which identifies the type of chunk.
42
43The size field (a 32-bit value, encoded using big-endian byte order) gives the
44size of the chunk data, not including the 8-byte header.
45
46Usually an IFF-type file consists of one or more chunks. The proposed usage of
47the :class:`Chunk` class defined here is to instantiate an instance at the start
48of each chunk and read from the instance until it reaches the end, after which a
49new instance can be instantiated. At the end of the file, creating a new
50instance will fail with a :exc:`EOFError` exception.
51
52
Georg Brandl0d8f0732009-04-05 22:20:44 +000053.. class:: Chunk(file, align=True, bigendian=True, inclheader=False)
Georg Brandl116aa622007-08-15 14:28:22 +000054
55 Class which represents a chunk. The *file* argument is expected to be a
56 file-like object. An instance of this class is specifically allowed. The
57 only method that is needed is :meth:`read`. If the methods :meth:`seek` and
58 :meth:`tell` are present and don't raise an exception, they are also used.
59 If these methods are present and raise an exception, they are expected to not
60 have altered the object. If the optional argument *align* is true, chunks
61 are assumed to be aligned on 2-byte boundaries. If *align* is false, no
62 alignment is assumed. The default value is true. If the optional argument
63 *bigendian* is false, the chunk size is assumed to be in little-endian order.
64 This is needed for WAVE audio files. The default value is true. If the
65 optional argument *inclheader* is true, the size given in the chunk header
66 includes the size of the header. The default value is false.
67
Benjamin Petersone41251e2008-04-25 01:59:09 +000068 A :class:`Chunk` object supports the following methods:
Georg Brandl116aa622007-08-15 14:28:22 +000069
70
Benjamin Petersone41251e2008-04-25 01:59:09 +000071 .. method:: getname()
Georg Brandl116aa622007-08-15 14:28:22 +000072
Benjamin Petersone41251e2008-04-25 01:59:09 +000073 Returns the name (ID) of the chunk. This is the first 4 bytes of the
74 chunk.
Georg Brandl116aa622007-08-15 14:28:22 +000075
76
Benjamin Petersone41251e2008-04-25 01:59:09 +000077 .. method:: getsize()
Georg Brandl116aa622007-08-15 14:28:22 +000078
Benjamin Petersone41251e2008-04-25 01:59:09 +000079 Returns the size of the chunk.
Georg Brandl116aa622007-08-15 14:28:22 +000080
81
Benjamin Petersone41251e2008-04-25 01:59:09 +000082 .. method:: close()
Georg Brandl116aa622007-08-15 14:28:22 +000083
Benjamin Petersone41251e2008-04-25 01:59:09 +000084 Close and skip to the end of the chunk. This does not close the
85 underlying file.
Georg Brandl116aa622007-08-15 14:28:22 +000086
Antoine Pitrou4272d6a2011-10-12 19:10:10 +020087 The remaining methods will raise :exc:`OSError` if called after the
88 :meth:`close` method has been called. Before Python 3.3, they used to
89 raise :exc:`IOError`, now an alias of :exc:`OSError`.
Georg Brandl116aa622007-08-15 14:28:22 +000090
91
Benjamin Petersone41251e2008-04-25 01:59:09 +000092 .. method:: isatty()
Georg Brandl116aa622007-08-15 14:28:22 +000093
Benjamin Petersone41251e2008-04-25 01:59:09 +000094 Returns ``False``.
Georg Brandl116aa622007-08-15 14:28:22 +000095
96
Georg Brandl0d8f0732009-04-05 22:20:44 +000097 .. method:: seek(pos, whence=0)
Georg Brandl116aa622007-08-15 14:28:22 +000098
Benjamin Petersone41251e2008-04-25 01:59:09 +000099 Set the chunk's current position. The *whence* argument is optional and
100 defaults to ``0`` (absolute file positioning); other values are ``1``
101 (seek relative to the current position) and ``2`` (seek relative to the
102 file's end). There is no return value. If the underlying file does not
103 allow seek, only forward seeks are allowed.
Georg Brandl116aa622007-08-15 14:28:22 +0000104
105
Benjamin Petersone41251e2008-04-25 01:59:09 +0000106 .. method:: tell()
Georg Brandl116aa622007-08-15 14:28:22 +0000107
Benjamin Petersone41251e2008-04-25 01:59:09 +0000108 Return the current position into the chunk.
Georg Brandl116aa622007-08-15 14:28:22 +0000109
110
Georg Brandl0d8f0732009-04-05 22:20:44 +0000111 .. method:: read(size=-1)
Georg Brandl116aa622007-08-15 14:28:22 +0000112
Benjamin Petersone41251e2008-04-25 01:59:09 +0000113 Read at most *size* bytes from the chunk (less if the read hits the end of
114 the chunk before obtaining *size* bytes). If the *size* argument is
115 negative or omitted, read all data until the end of the chunk. The bytes
116 are returned as a string object. An empty string is returned when the end
117 of the chunk is encountered immediately.
Georg Brandl116aa622007-08-15 14:28:22 +0000118
119
Benjamin Petersone41251e2008-04-25 01:59:09 +0000120 .. method:: skip()
Georg Brandl116aa622007-08-15 14:28:22 +0000121
Benjamin Petersone41251e2008-04-25 01:59:09 +0000122 Skip to the end of the chunk. All further calls to :meth:`read` for the
123 chunk will return ``''``. If you are not interested in the contents of
124 the chunk, this method should be called so that the file points to the
125 start of the next chunk.
126
Georg Brandl116aa622007-08-15 14:28:22 +0000127
128.. rubric:: Footnotes
129
130.. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic
131 Arts, January 1985.
132