|
1 :mod:`wave` --- Read and write WAV files |
|
2 ======================================== |
|
3 |
|
4 .. module:: wave |
|
5 :synopsis: Provide an interface to the WAV sound format. |
|
6 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
|
7 .. Documentations stolen from comments in file. |
|
8 |
|
9 The :mod:`wave` module provides a convenient interface to the WAV sound format. |
|
10 It does not support compression/decompression, but it does support mono/stereo. |
|
11 |
|
12 The :mod:`wave` module defines the following function and exception: |
|
13 |
|
14 |
|
15 .. function:: open(file[, mode]) |
|
16 |
|
17 If *file* is a string, open the file by that name, other treat it as a seekable |
|
18 file-like object. *mode* can be any of |
|
19 |
|
20 ``'r'``, ``'rb'`` |
|
21 Read only mode. |
|
22 |
|
23 ``'w'``, ``'wb'`` |
|
24 Write only mode. |
|
25 |
|
26 Note that it does not allow read/write WAV files. |
|
27 |
|
28 A *mode* of ``'r'`` or ``'rb'`` returns a :class:`Wave_read` object, while a |
|
29 *mode* of ``'w'`` or ``'wb'`` returns a :class:`Wave_write` object. If *mode* |
|
30 is omitted and a file-like object is passed as *file*, ``file.mode`` is used as |
|
31 the default value for *mode* (the ``'b'`` flag is still added if necessary). |
|
32 |
|
33 |
|
34 .. function:: openfp(file, mode) |
|
35 |
|
36 A synonym for :func:`open`, maintained for backwards compatibility. |
|
37 |
|
38 |
|
39 .. exception:: Error |
|
40 |
|
41 An error raised when something is impossible because it violates the WAV |
|
42 specification or hits an implementation deficiency. |
|
43 |
|
44 |
|
45 .. _wave-read-objects: |
|
46 |
|
47 Wave_read Objects |
|
48 ----------------- |
|
49 |
|
50 Wave_read objects, as returned by :func:`open`, have the following methods: |
|
51 |
|
52 |
|
53 .. method:: Wave_read.close() |
|
54 |
|
55 Close the stream, and make the instance unusable. This is called automatically |
|
56 on object collection. |
|
57 |
|
58 |
|
59 .. method:: Wave_read.getnchannels() |
|
60 |
|
61 Returns number of audio channels (``1`` for mono, ``2`` for stereo). |
|
62 |
|
63 |
|
64 .. method:: Wave_read.getsampwidth() |
|
65 |
|
66 Returns sample width in bytes. |
|
67 |
|
68 |
|
69 .. method:: Wave_read.getframerate() |
|
70 |
|
71 Returns sampling frequency. |
|
72 |
|
73 |
|
74 .. method:: Wave_read.getnframes() |
|
75 |
|
76 Returns number of audio frames. |
|
77 |
|
78 |
|
79 .. method:: Wave_read.getcomptype() |
|
80 |
|
81 Returns compression type (``'NONE'`` is the only supported type). |
|
82 |
|
83 |
|
84 .. method:: Wave_read.getcompname() |
|
85 |
|
86 Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'`` |
|
87 parallels ``'NONE'``. |
|
88 |
|
89 |
|
90 .. method:: Wave_read.getparams() |
|
91 |
|
92 Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype, |
|
93 compname)``, equivalent to output of the :meth:`get\*` methods. |
|
94 |
|
95 |
|
96 .. method:: Wave_read.readframes(n) |
|
97 |
|
98 Reads and returns at most *n* frames of audio, as a string of bytes. |
|
99 |
|
100 |
|
101 .. method:: Wave_read.rewind() |
|
102 |
|
103 Rewind the file pointer to the beginning of the audio stream. |
|
104 |
|
105 The following two methods are defined for compatibility with the :mod:`aifc` |
|
106 module, and don't do anything interesting. |
|
107 |
|
108 |
|
109 .. method:: Wave_read.getmarkers() |
|
110 |
|
111 Returns ``None``. |
|
112 |
|
113 |
|
114 .. method:: Wave_read.getmark(id) |
|
115 |
|
116 Raise an error. |
|
117 |
|
118 The following two methods define a term "position" which is compatible between |
|
119 them, and is otherwise implementation dependent. |
|
120 |
|
121 |
|
122 .. method:: Wave_read.setpos(pos) |
|
123 |
|
124 Set the file pointer to the specified position. |
|
125 |
|
126 |
|
127 .. method:: Wave_read.tell() |
|
128 |
|
129 Return current file pointer position. |
|
130 |
|
131 |
|
132 .. _wave-write-objects: |
|
133 |
|
134 Wave_write Objects |
|
135 ------------------ |
|
136 |
|
137 Wave_write objects, as returned by :func:`open`, have the following methods: |
|
138 |
|
139 |
|
140 .. method:: Wave_write.close() |
|
141 |
|
142 Make sure *nframes* is correct, and close the file. This method is called upon |
|
143 deletion. |
|
144 |
|
145 |
|
146 .. method:: Wave_write.setnchannels(n) |
|
147 |
|
148 Set the number of channels. |
|
149 |
|
150 |
|
151 .. method:: Wave_write.setsampwidth(n) |
|
152 |
|
153 Set the sample width to *n* bytes. |
|
154 |
|
155 |
|
156 .. method:: Wave_write.setframerate(n) |
|
157 |
|
158 Set the frame rate to *n*. |
|
159 |
|
160 |
|
161 .. method:: Wave_write.setnframes(n) |
|
162 |
|
163 Set the number of frames to *n*. This will be changed later if more frames are |
|
164 written. |
|
165 |
|
166 |
|
167 .. method:: Wave_write.setcomptype(type, name) |
|
168 |
|
169 Set the compression type and description. At the moment, only compression type |
|
170 ``NONE`` is supported, meaning no compression. |
|
171 |
|
172 |
|
173 .. method:: Wave_write.setparams(tuple) |
|
174 |
|
175 The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype, |
|
176 compname)``, with values valid for the :meth:`set\*` methods. Sets all |
|
177 parameters. |
|
178 |
|
179 |
|
180 .. method:: Wave_write.tell() |
|
181 |
|
182 Return current position in the file, with the same disclaimer for the |
|
183 :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods. |
|
184 |
|
185 |
|
186 .. method:: Wave_write.writeframesraw(data) |
|
187 |
|
188 Write audio frames, without correcting *nframes*. |
|
189 |
|
190 |
|
191 .. method:: Wave_write.writeframes(data) |
|
192 |
|
193 Write audio frames and make sure *nframes* is correct. |
|
194 |
|
195 Note that it is invalid to set any parameters after calling :meth:`writeframes` |
|
196 or :meth:`writeframesraw`, and any attempt to do so will raise |
|
197 :exc:`wave.Error`. |
|
198 |