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