Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`chunk` --- Read IFF chunked data |
| 2 | ====================================== |
| 3 | |
| 4 | .. module:: chunk |
| 5 | :synopsis: Module to read IFF chunks. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org> |
| 8 | .. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org> |
| 9 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 10 | **Source code:** :source:`Lib/chunk.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 19 | -------------- |
| 20 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 54 | instance will fail with an :exc:`EOFError` exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
| 56 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 57 | .. class:: Chunk(file, align=True, bigendian=True, inclheader=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Serhiy Storchaka | bfdcd43 | 2013-10-13 23:09:14 +0300 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 73 | A :class:`Chunk` object supports the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
| 75 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 76 | .. method:: getname() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 78 | Returns the name (ID) of the chunk. This is the first 4 bytes of the |
| 79 | chunk. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
| 81 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 82 | .. method:: getsize() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 84 | Returns the size of the chunk. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 87 | .. method:: close() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 89 | Close and skip to the end of the chunk. This does not close the |
| 90 | underlying file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
Antoine Pitrou | 4272d6a | 2011-10-12 19:10:10 +0200 | [diff] [blame] | 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`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
| 96 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 97 | .. method:: isatty() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 99 | Returns ``False``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
| 101 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 102 | .. method:: seek(pos, whence=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
| 110 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 111 | .. method:: tell() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 113 | Return the current position into the chunk. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
| 115 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 116 | .. method:: read(size=-1) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 117 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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 |
Serhiy Storchaka | 5e028ae | 2014-02-06 21:10:41 +0200 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 123 | |
| 124 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 125 | .. method:: skip() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 127 | Skip to the end of the chunk. All further calls to :meth:`read` for the |
Serhiy Storchaka | 5e028ae | 2014-02-06 21:10:41 +0200 | [diff] [blame] | 128 | chunk will return ``b''``. If you are not interested in the contents of |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 129 | the chunk, this method should be called so that the file points to the |
| 130 | start of the next chunk. |
| 131 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
| 133 | .. rubric:: Footnotes |
| 134 | |
| 135 | .. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic |
| 136 | Arts, January 1985. |
| 137 | |