|
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 The :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 |
|
71 The :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 |
|
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 |