path: root/devdocs/python~3.12/library%2Fwave.html

 <span id="wave-read-and-write-wav-files"></span><h1>wave — Read and write WAV files</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/wave.py">Lib/wave.py</a></p>  <p>The <a class="reference internal" href="#module-wave" title="wave: Provide an interface to the WAV sound format."><code>wave</code></a> module provides a convenient interface to the Waveform Audio “WAVE” (or “WAV”) file format. Only uncompressed PCM encoded wave files are supported.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Support for <code>WAVE_FORMAT_EXTENSIBLE</code> headers was added, provided that the extended format is <code>KSDATAFORMAT_SUBTYPE_PCM</code>.</p> </div> <p>The <a class="reference internal" href="#module-wave" title="wave: Provide an interface to the WAV sound format."><code>wave</code></a> module defines the following function and exception:</p> <dl class="py function"> <dt class="sig sig-object py" id="wave.open">
<code>wave.open(file, mode=None)</code> </dt> <dd>
<p>If <em>file</em> is a string, open the file by that name, otherwise treat it as a file-like object. <em>mode</em> can be:</p> <dl class="simple"> <dt>
<code>'rb'</code> </dt>
<dd>
<p>Read only mode.</p> </dd> <dt>
<code>'wb'</code> </dt>
<dd>
<p>Write only mode.</p> </dd> </dl> <p>Note that it does not allow read/write WAV files.</p> <p>A <em>mode</em> of <code>'rb'</code> returns a <a class="reference internal" href="#wave.Wave_read" title="wave.Wave_read"><code>Wave_read</code></a> object, while a <em>mode</em> of <code>'wb'</code> returns a <a class="reference internal" href="#wave.Wave_write" title="wave.Wave_write"><code>Wave_write</code></a> object. If <em>mode</em> is omitted and a file-like object is passed as <em>file</em>, <code>file.mode</code> is used as the default value for <em>mode</em>.</p> <p>If you pass in a file-like object, the wave object will not close it when its <code>close()</code> method is called; it is the caller’s responsibility to close the file object.</p> <p>The <a class="reference internal" href="#wave.open" title="wave.open"><code>open()</code></a> function may be used in a <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement. When the <code>with</code> block completes, the <a class="reference internal" href="#wave.Wave_read.close" title="wave.Wave_read.close"><code>Wave_read.close()</code></a> or <a class="reference internal" href="#wave.Wave_write.close" title="wave.Wave_write.close"><code>Wave_write.close()</code></a> method is called.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Added support for unseekable files.</p> </div> </dd>
</dl> <dl class="py exception"> <dt class="sig sig-object py" id="wave.Error">
<code>exception wave.Error</code> </dt> <dd>
<p>An error raised when something is impossible because it violates the WAV specification or hits an implementation deficiency.</p> </dd>
</dl> <section id="wave-read-objects"> <span id="id1"></span><h2>Wave_read Objects</h2> <dl class="py class"> <dt class="sig sig-object py" id="wave.Wave_read">
<code>class wave.Wave_read</code> </dt> <dd>
<p>Read a WAV file.</p> <p>Wave_read objects, as returned by <a class="reference internal" href="#wave.open" title="wave.open"><code>open()</code></a>, have the following methods:</p> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.close">
<code>close()</code> </dt> <dd>
<p>Close the stream if it was opened by <a class="reference internal" href="#module-wave" title="wave: Provide an interface to the WAV sound format."><code>wave</code></a>, and make the instance unusable. This is called automatically on object collection.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getnchannels">
<code>getnchannels()</code> </dt> <dd>
<p>Returns number of audio channels (<code>1</code> for mono, <code>2</code> for stereo).</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getsampwidth">
<code>getsampwidth()</code> </dt> <dd>
<p>Returns sample width in bytes.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getframerate">
<code>getframerate()</code> </dt> <dd>
<p>Returns sampling frequency.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getnframes">
<code>getnframes()</code> </dt> <dd>
<p>Returns number of audio frames.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getcomptype">
<code>getcomptype()</code> </dt> <dd>
<p>Returns compression type (<code>'NONE'</code> is the only supported type).</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getcompname">
<code>getcompname()</code> </dt> <dd>
<p>Human-readable version of <a class="reference internal" href="#wave.Wave_read.getcomptype" title="wave.Wave_read.getcomptype"><code>getcomptype()</code></a>. Usually <code>'not compressed'</code> parallels <code>'NONE'</code>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getparams">
<code>getparams()</code> </dt> <dd>
<p>Returns a <a class="reference internal" href="collections#collections.namedtuple" title="collections.namedtuple"><code>namedtuple()</code></a> <code>(nchannels, sampwidth,
framerate, nframes, comptype, compname)</code>, equivalent to output of the <code>get*()</code> methods.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.readframes">
<code>readframes(n)</code> </dt> <dd>
<p>Reads and returns at most <em>n</em> frames of audio, as a <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a> object.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.rewind">
<code>rewind()</code> </dt> <dd>
<p>Rewind the file pointer to the beginning of the audio stream.</p> </dd>
</dl> <p>The following two methods are defined for compatibility with the <a class="reference internal" href="aifc#module-aifc" title="aifc: Read and write audio files in AIFF or AIFC format. (deprecated)"><code>aifc</code></a> module, and don’t do anything interesting.</p> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getmarkers">
<code>getmarkers()</code> </dt> <dd>
<p>Returns <code>None</code>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.getmark">
<code>getmark(id)</code> </dt> <dd>
<p>Raise an error.</p> </dd>
</dl> <p>The following two methods define a term “position” which is compatible between them, and is otherwise implementation dependent.</p> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.setpos">
<code>setpos(pos)</code> </dt> <dd>
<p>Set the file pointer to the specified position.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_read.tell">
<code>tell()</code> </dt> <dd>
<p>Return current file pointer position.</p> </dd>
</dl> </dd>
</dl> </section> <section id="wave-write-objects"> <span id="id2"></span><h2>Wave_write Objects</h2> <dl class="py class"> <dt class="sig sig-object py" id="wave.Wave_write">
<code>class wave.Wave_write</code> </dt> <dd>
<p>Write a WAV file.</p> <p>Wave_write objects, as returned by <a class="reference internal" href="#wave.open" title="wave.open"><code>open()</code></a>.</p> <p>For seekable output streams, the <code>wave</code> header will automatically be updated to reflect the number of frames actually written. For unseekable streams, the <em>nframes</em> value must be accurate when the first frame data is written. An accurate <em>nframes</em> value can be achieved either by calling <a class="reference internal" href="#wave.Wave_write.setnframes" title="wave.Wave_write.setnframes"><code>setnframes()</code></a> or <a class="reference internal" href="#wave.Wave_write.setparams" title="wave.Wave_write.setparams"><code>setparams()</code></a> with the number of frames that will be written before <a class="reference internal" href="#wave.Wave_write.close" title="wave.Wave_write.close"><code>close()</code></a> is called and then using <a class="reference internal" href="#wave.Wave_write.writeframesraw" title="wave.Wave_write.writeframesraw"><code>writeframesraw()</code></a> to write the frame data, or by calling <a class="reference internal" href="#wave.Wave_write.writeframes" title="wave.Wave_write.writeframes"><code>writeframes()</code></a> with all of the frame data to be written. In the latter case <a class="reference internal" href="#wave.Wave_write.writeframes" title="wave.Wave_write.writeframes"><code>writeframes()</code></a> will calculate the number of frames in the data and set <em>nframes</em> accordingly before writing the frame data.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Added support for unseekable files.</p> </div> <p>Wave_write objects have the following methods:</p> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.close">
<code>close()</code> </dt> <dd>
<p>Make sure <em>nframes</em> is correct, and close the file if it was opened by <a class="reference internal" href="#module-wave" title="wave: Provide an interface to the WAV sound format."><code>wave</code></a>. This method is called upon object collection. It will raise an exception if the output stream is not seekable and <em>nframes</em> does not match the number of frames actually written.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.setnchannels">
<code>setnchannels(n)</code> </dt> <dd>
<p>Set the number of channels.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.setsampwidth">
<code>setsampwidth(n)</code> </dt> <dd>
<p>Set the sample width to <em>n</em> bytes.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.setframerate">
<code>setframerate(n)</code> </dt> <dd>
<p>Set the frame rate to <em>n</em>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>A non-integral input to this method is rounded to the nearest integer.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.setnframes">
<code>setnframes(n)</code> </dt> <dd>
<p>Set the number of frames to <em>n</em>. This will be changed later if the number of frames actually written is different (this update attempt will raise an error if the output stream is not seekable).</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.setcomptype">
<code>setcomptype(type, name)</code> </dt> <dd>
<p>Set the compression type and description. At the moment, only compression type <code>NONE</code> is supported, meaning no compression.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.setparams">
<code>setparams(tuple)</code> </dt> <dd>
<p>The <em>tuple</em> should be <code>(nchannels, sampwidth, framerate, nframes, comptype,
compname)</code>, with values valid for the <code>set*()</code> methods. Sets all parameters.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.tell">
<code>tell()</code> </dt> <dd>
<p>Return current position in the file, with the same disclaimer for the <a class="reference internal" href="#wave.Wave_read.tell" title="wave.Wave_read.tell"><code>Wave_read.tell()</code></a> and <a class="reference internal" href="#wave.Wave_read.setpos" title="wave.Wave_read.setpos"><code>Wave_read.setpos()</code></a> methods.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.writeframesraw">
<code>writeframesraw(data)</code> </dt> <dd>
<p>Write audio frames, without correcting <em>nframes</em>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Any <a class="reference internal" href="../glossary#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> is now accepted.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="wave.Wave_write.writeframes">
<code>writeframes(data)</code> </dt> <dd>
<p>Write audio frames and make sure <em>nframes</em> is correct. It will raise an error if the output stream is not seekable and the total number of frames that have been written after <em>data</em> has been written does not match the previously set value for <em>nframes</em>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Any <a class="reference internal" href="../glossary#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> is now accepted.</p> </div> <p>Note that it is invalid to set any parameters after calling <a class="reference internal" href="#wave.Wave_write.writeframes" title="wave.Wave_write.writeframes"><code>writeframes()</code></a> or <a class="reference internal" href="#wave.Wave_write.writeframesraw" title="wave.Wave_write.writeframesraw"><code>writeframesraw()</code></a>, and any attempt to do so will raise <a class="reference internal" href="#wave.Error" title="wave.Error"><code>wave.Error</code></a>.</p> </dd>
</dl> </dd>
</dl> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/wave.html" class="_attribution-link">https://docs.python.org/3.12/library/wave.html</a>
  </p>
</div>