Doc/library/chunk.rst

   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:: Chunk.getname()
  73
  74    Returns the name (ID) of the chunk.  This is the first 4 bytes of the chunk.
  75
  76
  77 .. method:: Chunk.getsize()
  78
  79    Returns the size of the chunk.
  80
  81
  82 .. method:: Chunk.close()
  83
  84    Close and skip to the end of the chunk.  This does not close the underlying
  85    file.
  86
  87 The remaining methods will raise :exc:`IOError` if called after the
  88 :meth:`close` method has been called.
  89
  90
  91 .. method:: Chunk.isatty()
  92
  93    Returns ``False``.
  94
  95
  96 .. method:: Chunk.seek(pos[, whence])
  97
  98    Set the chunk's current position.  The *whence* argument is optional and
  99    defaults to ``0`` (absolute file positioning); other values are ``1`` (seek
 100    relative to the current position) and ``2`` (seek relative to the file's end).
 101    There is no return value. If the underlying file does not allow seek, only
 102    forward seeks are allowed.
 103
 104
 105 .. method:: Chunk.tell()
 106
 107    Return the current position into the chunk.
 108
 109
 110 .. method:: Chunk.read([size])
 111
 112    Read at most *size* bytes from the chunk (less if the read hits the end of the
 113    chunk before obtaining *size* bytes).  If the *size* argument is negative or
 114    omitted, read all data until the end of the chunk.  The bytes are returned as a
 115    string object.  An empty string is returned when the end of the chunk is
 116    encountered immediately.
 117
 118
 119 .. method:: Chunk.skip()
 120
 121    Skip to the end of the chunk.  All further calls to :meth:`read` for the chunk
 122    will return ``''``.  If you are not interested in the contents of the chunk,
 123    this method should be called so that the file points to the start of the next
 124    chunk.
 125
 126 .. rubric:: Footnotes
 127
 128 .. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic
 129    Arts, January 1985.
 130