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