← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/library/wave.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

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