1 

     2 :mod:`chunk` --- Read IFF chunked data

     3 ======================================

     4 

     5 .. module:: chunk

     6    :synopsis: Module to read IFF chunks.

     7 .. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>

     8 .. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>

     9 

    10 

    11 .. index::

    12    single: Audio Interchange File Format

    13    single: AIFF

    14    single: AIFF-C

    15    single: Real Media File Format

    16    single: RMFF

    17 

    18 This module provides an interface for reading files that use EA IFF 85 chunks.

    19 [#]_  This format is used in at least the Audio Interchange File Format

    20 (AIFF/AIFF-C) and the Real Media File Format (RMFF).  The WAVE audio file format

    21 is closely related and can also be read using this module.

    22 

    23 A chunk has the following structure:

    24 

    25 +---------+--------+-------------------------------+

    26 | Offset  | Length | Contents                      |

    27 +=========+========+===============================+

    28 | 0       | 4      | Chunk ID                      |

    29 +---------+--------+-------------------------------+

    30 | 4       | 4      | Size of chunk in big-endian   |

    31 |         |        | byte order, not including the |

    32 |         |        | header                        |

    33 +---------+--------+-------------------------------+

    34 | 8       | *n*    | Data bytes, where *n* is the  |

    35 |         |        | size given in the preceding   |

    36 |         |        | field                         |

    37 +---------+--------+-------------------------------+

    38 | 8 + *n* | 0 or 1 | Pad byte needed if *n* is odd |

    39 |         |        | and chunk alignment is used   |

    40 +---------+--------+-------------------------------+

    41 

    42 The ID is a 4-byte string which identifies the type of chunk.

    43 

    44 The size field (a 32-bit value, encoded using big-endian byte order) gives the

    45 size of the chunk data, not including the 8-byte header.

    46 

    47 Usually an IFF-type file consists of one or more chunks.  The proposed usage of

    48 the :class:`Chunk` class defined here is to instantiate an instance at the start

    49 of each chunk and read from the instance until it reaches the end, after which a

    50 new instance can be instantiated. At the end of the file, creating a new

    51 instance will fail with a :exc:`EOFError` exception.

    52 

    53 

    54 .. class:: Chunk(file[, align, bigendian, inclheader])

    55 

    56    Class which represents a chunk.  The *file* argument is expected to be a

    57    file-like object.  An instance of this class is specifically allowed.  The

    58    only method that is needed is :meth:`read`.  If the methods :meth:`seek` and

    59    :meth:`tell` are present and don't raise an exception, they are also used.

    60    If these methods are present and raise an exception, they are expected to not

    61    have altered the object.  If the optional argument *align* is true, chunks

    62    are assumed to be aligned on 2-byte boundaries.  If *align* is false, no

    63    alignment is assumed.  The default value is true.  If the optional argument

    64    *bigendian* is false, the chunk size is assumed to be in little-endian order.

    65    This is needed for WAVE audio files. The default value is true.  If the

    66    optional argument *inclheader* is true, the size given in the chunk header

    67    includes the size of the header.  The default value is false.

    68 

    69    A :class:`Chunk` object supports the following methods:

    70 

    71 

    72    .. method:: getname()

    73 

    74       Returns the name (ID) of the chunk.  This is the first 4 bytes of the

    75       chunk.

    76 

    77 

    78    .. method:: getsize()

    79 

    80       Returns the size of the chunk.

    81 

    82 

    83    .. method:: close()

    84 

    85       Close and skip to the end of the chunk.  This does not close the

    86       underlying file.

    87 

    88    The remaining methods will raise :exc:`IOError` if called after the

    89    :meth:`close` method has been called.

    90 

    91 

    92    .. method:: isatty()

    93 

    94       Returns ``False``.

    95 

    96 

    97    .. method:: seek(pos[, whence])

    98 

    99       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.

   104 

   105 

   106    .. method:: tell()

   107 

   108       Return the current position into the chunk.

   109 

   110 

   111    .. method:: read([size])

   112 

   113       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.

   118 

   119 

   120    .. method:: skip()

   121 

   122       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 

   127 

   128 .. rubric:: Footnotes

   129 

   130 .. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic

   131    Arts, January 1985.

   132