/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
 10The :mod:`sunau` module provides a convenient interface to the Sun AU sound
 11format.  Note that this module is interface-compatible with the modules
 12:mod:`aifc` and :mod:`wave`.
 13
 14An audio file consists of a header followed by the data.  The fields of the
 15header 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
 36Apart from the info field, all header fields are 4 bytes in size. They are all
 3732-bit unsigned integers encoded in big-endian byte order.
 38
 39The :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
 63The :mod:`sunau` module defines the following exception:
 64
 65
 66.. exception:: Error
 67
 68   An error raised when something is impossible because of Sun AU specs or
 69   implementation deficiency.
 70
 71The :mod:`sunau` module defines the following data items:
 72
 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
104AU_read Objects
105---------------
106
107AU_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
166The following two methods define a term "position" which is compatible between
167them, 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
181The following two functions are defined for compatibility with the  :mod:`aifc`,
182and 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
197AU_write Objects
198----------------
199
200AU_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
259Note that it is invalid to set any parameters after calling  :meth:`writeframes`
260or :meth:`writeframesraw`.
261