Doc/library/sunau.rst

   1
   2 :mod:`sunau` --- Read and write Sun AU files
   3 ============================================
   4
   5 .. module:: sunau
   6    :synopsis: Provide an interface to the Sun AU sound format.
   7 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
   8
   9
  10 The :mod:`sunau` module provides a convenient interface to the Sun AU sound
  11 format.  Note that this module is interface-compatible with the modules
  12 :mod:`aifc` and :mod:`wave`.
  13
  14 An audio file consists of a header followed by the data.  The fields of the
  15 header are:
  16
  17 +---------------+-----------------------------------------------+
  18 | Field         | Contents                                      |
  19 +===============+===============================================+
  20 | magic word    | The four bytes ``.snd``.                      |
  21 +---------------+-----------------------------------------------+
  22 | header size   | Size of the header, including info, in bytes. |
  23 +---------------+-----------------------------------------------+
  24 | data size     | Physical size of the data, in bytes.          |
  25 +---------------+-----------------------------------------------+
  26 | encoding      | Indicates how the audio samples are encoded.  |
  27 +---------------+-----------------------------------------------+
  28 | sample rate   | The sampling rate.                            |
  29 +---------------+-----------------------------------------------+
  30 | # of channels | The number of channels in the samples.        |
  31 +---------------+-----------------------------------------------+
  32 | info          | ASCII string giving a description of the      |
  33 |               | audio file (padded with null bytes).          |
  34 +---------------+-----------------------------------------------+
  35
  36 Apart from the info field, all header fields are 4 bytes in size. They are all
  37 32-bit unsigned integers encoded in big-endian byte order.
  38
  39 The :mod:`sunau` module defines the following functions:
  40
  41
  42 .. function:: open(file, mode)
  43
  44    If *file* is a string, open the file by that name, otherwise treat it as a
  45    seekable file-like object. *mode* can be any of
  46
  47    ``'r'``
  48       Read only mode.
  49
  50    ``'w'``
  51       Write only mode.
  52
  53    Note that it does not allow read/write files.
  54
  55    A *mode* of ``'r'`` returns a :class:`AU_read` object, while a *mode* of ``'w'``
  56    or ``'wb'`` returns a :class:`AU_write` object.
  57
  58
  59 .. function:: openfp(file, mode)
  60
  61    A synonym for :func:`.open`, maintained for backwards compatibility.
  62
  63
  64 The :mod:`sunau` module defines the following exception:
  65
  66 .. exception:: Error
  67
  68    An error raised when something is impossible because of Sun AU specs or
  69    implementation deficiency.
  70
  71
  72 The :mod:`sunau` module defines the following data items:
  73
  74 .. data:: AUDIO_FILE_MAGIC
  75
  76    An integer every valid Sun AU file begins with, stored in big-endian form.  This
  77    is the string ``.snd`` interpreted as an integer.
  78
  79
  80 .. data:: AUDIO_FILE_ENCODING_MULAW_8
  81           AUDIO_FILE_ENCODING_LINEAR_8
  82           AUDIO_FILE_ENCODING_LINEAR_16
  83           AUDIO_FILE_ENCODING_LINEAR_24
  84           AUDIO_FILE_ENCODING_LINEAR_32
  85           AUDIO_FILE_ENCODING_ALAW_8
  86
  87    Values of the encoding field from the AU header which are supported by this
  88    module.
  89
  90
  91 .. data:: AUDIO_FILE_ENCODING_FLOAT
  92           AUDIO_FILE_ENCODING_DOUBLE
  93           AUDIO_FILE_ENCODING_ADPCM_G721
  94           AUDIO_FILE_ENCODING_ADPCM_G722
  95           AUDIO_FILE_ENCODING_ADPCM_G723_3
  96           AUDIO_FILE_ENCODING_ADPCM_G723_5
  97
  98    Additional known values of the encoding field from the AU header, but which are
  99    not supported by this module.
 100
 101
 102 .. _au-read-objects:
 103
 104 AU_read Objects
 105 ---------------
 106
 107 AU_read objects, as returned by :func:`.open` above, have the following methods:
 108
 109
 110 .. method:: AU_read.close()
 111
 112    Close the stream, and make the instance unusable. (This is  called automatically
 113    on deletion.)
 114
 115
 116 .. method:: AU_read.getnchannels()
 117
 118    Returns number of audio channels (1 for mone, 2 for stereo).
 119
 120
 121 .. method:: AU_read.getsampwidth()
 122
 123    Returns sample width in bytes.
 124
 125
 126 .. method:: AU_read.getframerate()
 127
 128    Returns sampling frequency.
 129
 130
 131 .. method:: AU_read.getnframes()
 132
 133    Returns number of audio frames.
 134
 135
 136 .. method:: AU_read.getcomptype()
 137
 138    Returns compression type. Supported compression types are ``'ULAW'``, ``'ALAW'``
 139    and ``'NONE'``.
 140
 141
 142 .. method:: AU_read.getcompname()
 143
 144    Human-readable version of :meth:`getcomptype`.  The supported types have the
 145    respective names ``'CCITT G.711 u-law'``, ``'CCITT G.711 A-law'`` and ``'not
 146    compressed'``.
 147
 148
 149 .. method:: AU_read.getparams()
 150
 151    Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype,
 152    compname)``, equivalent to output of the :meth:`get\*` methods.
 153
 154
 155 .. method:: AU_read.readframes(n)
 156
 157    Reads and returns at most *n* frames of audio, as a string of bytes.  The data
 158    will be returned in linear format.  If the original data is in u-LAW format, it
 159    will be converted.
 160
 161
 162 .. method:: AU_read.rewind()
 163
 164    Rewind the file pointer to the beginning of the audio stream.
 165
 166 The following two methods define a term "position" which is compatible between
 167 them, and is otherwise implementation dependent.
 168
 169
 170 .. method:: AU_read.setpos(pos)
 171
 172    Set the file pointer to the specified position.  Only values returned from
 173    :meth:`tell` should be used for *pos*.
 174
 175
 176 .. method:: AU_read.tell()
 177
 178    Return current file pointer position.  Note that the returned value has nothing
 179    to do with the actual position in the file.
 180
 181 The following two functions are defined for compatibility with the  :mod:`aifc`,
 182 and don't do anything interesting.
 183
 184
 185 .. method:: AU_read.getmarkers()
 186
 187    Returns ``None``.
 188
 189
 190 .. method:: AU_read.getmark(id)
 191
 192    Raise an error.
 193
 194
 195 .. _au-write-objects:
 196
 197 AU_write Objects
 198 ----------------
 199
 200 AU_write objects, as returned by :func:`.open` above, have the following methods:
 201
 202
 203 .. method:: AU_write.setnchannels(n)
 204
 205    Set the number of channels.
 206
 207
 208 .. method:: AU_write.setsampwidth(n)
 209
 210    Set the sample width (in bytes.)
 211
 212
 213 .. method:: AU_write.setframerate(n)
 214
 215    Set the frame rate.
 216
 217
 218 .. method:: AU_write.setnframes(n)
 219
 220    Set the number of frames. This can be later changed, when and if more  frames
 221    are written.
 222
 223
 224 .. method:: AU_write.setcomptype(type, name)
 225
 226    Set the compression type and description. Only ``'NONE'`` and ``'ULAW'`` are
 227    supported on output.
 228
 229
 230 .. method:: AU_write.setparams(tuple)
 231
 232    The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
 233    compname)``, with values valid for the :meth:`set\*` methods.  Set all
 234    parameters.
 235
 236
 237 .. method:: AU_write.tell()
 238
 239    Return current position in the file, with the same disclaimer for the
 240    :meth:`AU_read.tell` and :meth:`AU_read.setpos` methods.
 241
 242
 243 .. method:: AU_write.writeframesraw(data)
 244
 245    Write audio frames, without correcting *nframes*.
 246
 247
 248 .. method:: AU_write.writeframes(data)
 249
 250    Write audio frames and make sure *nframes* is correct.
 251
 252
 253 .. method:: AU_write.close()
 254
 255    Make sure *nframes* is correct, and close the file.
 256
 257    This method is called upon deletion.
 258
 259 Note that it is invalid to set any parameters after calling  :meth:`writeframes`
 260 or :meth:`writeframesraw`.
 261