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

 <span id="winsound-sound-playing-interface-for-windows"></span><h1>winsound — Sound-playing interface for Windows</h1>  <p>The <a class="reference internal" href="#module-winsound" title="winsound: Access to the sound-playing machinery for Windows. (Windows)"><code>winsound</code></a> module provides access to the basic sound-playing machinery provided by Windows platforms. It includes functions and several constants.</p> <dl class="py function"> <dt class="sig sig-object py" id="winsound.Beep">
<code>winsound.Beep(frequency, duration)</code> </dt> <dd>
<p>Beep the PC’s speaker. The <em>frequency</em> parameter specifies frequency, in hertz, of the sound, and must be in the range 37 through 32,767. The <em>duration</em> parameter specifies the number of milliseconds the sound should last. If the system is not able to beep the speaker, <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a> is raised.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="winsound.PlaySound">
<code>winsound.PlaySound(sound, flags)</code> </dt> <dd>
<p>Call the underlying <code>PlaySound()</code> function from the Platform API. The <em>sound</em> parameter may be a filename, a system sound alias, audio data as a <a class="reference internal" href="../glossary#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>, or <code>None</code>. Its interpretation depends on the value of <em>flags</em>, which can be a bitwise ORed combination of the constants described below. If the <em>sound</em> parameter is <code>None</code>, any currently playing waveform sound is stopped. If the system indicates an error, <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a> is raised.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="winsound.MessageBeep">
<code>winsound.MessageBeep(type=MB_OK)</code> </dt> <dd>
<p>Call the underlying <code>MessageBeep()</code> function from the Platform API. This plays a sound as specified in the registry. The <em>type</em> argument specifies which sound to play; possible values are <code>-1</code>, <code>MB_ICONASTERISK</code>, <code>MB_ICONEXCLAMATION</code>, <code>MB_ICONHAND</code>, <code>MB_ICONQUESTION</code>, and <code>MB_OK</code>, all described below. The value <code>-1</code> produces a “simple beep”; this is the final fallback if a sound cannot be played otherwise. If the system indicates an error, <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a> is raised.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_FILENAME">
<code>winsound.SND_FILENAME</code> </dt> <dd>
<p>The <em>sound</em> parameter is the name of a WAV file. Do not use with <a class="reference internal" href="#winsound.SND_ALIAS" title="winsound.SND_ALIAS"><code>SND_ALIAS</code></a>.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_ALIAS">
<code>winsound.SND_ALIAS</code> </dt> <dd>
<p>The <em>sound</em> parameter is a sound association name from the registry. If the registry contains no such name, play the system default sound unless <a class="reference internal" href="#winsound.SND_NODEFAULT" title="winsound.SND_NODEFAULT"><code>SND_NODEFAULT</code></a> is also specified. If no default sound is registered, raise <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a>. Do not use with <a class="reference internal" href="#winsound.SND_FILENAME" title="winsound.SND_FILENAME"><code>SND_FILENAME</code></a>.</p> <p>All Win32 systems support at least the following; most systems support many more:</p> <table class="docutils align-default">  <thead> <tr>
<th class="head"><p><a class="reference internal" href="#winsound.PlaySound" title="winsound.PlaySound"><code>PlaySound()</code></a> <em>name</em></p></th> <th class="head"><p>Corresponding Control Panel Sound name</p></th> </tr> </thead>  <tr>
<td><p><code>'SystemAsterisk'</code></p></td> <td><p>Asterisk</p></td> </tr> <tr>
<td><p><code>'SystemExclamation'</code></p></td> <td><p>Exclamation</p></td> </tr> <tr>
<td><p><code>'SystemExit'</code></p></td> <td><p>Exit Windows</p></td> </tr> <tr>
<td><p><code>'SystemHand'</code></p></td> <td><p>Critical Stop</p></td> </tr> <tr>
<td><p><code>'SystemQuestion'</code></p></td> <td><p>Question</p></td> </tr>  </table> <p>For example:</p> <pre data-language="python">import winsound
# Play Windows exit sound.
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)

# Probably play Windows default sound, if any is registered (because
# "*" probably isn't the registered name of any sound).
winsound.PlaySound("*", winsound.SND_ALIAS)
</pre> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_LOOP">
<code>winsound.SND_LOOP</code> </dt> <dd>
<p>Play the sound repeatedly. The <a class="reference internal" href="#winsound.SND_ASYNC" title="winsound.SND_ASYNC"><code>SND_ASYNC</code></a> flag must also be used to avoid blocking. Cannot be used with <a class="reference internal" href="#winsound.SND_MEMORY" title="winsound.SND_MEMORY"><code>SND_MEMORY</code></a>.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_MEMORY">
<code>winsound.SND_MEMORY</code> </dt> <dd>
<p>The <em>sound</em> parameter to <a class="reference internal" href="#winsound.PlaySound" title="winsound.PlaySound"><code>PlaySound()</code></a> is a memory image of a WAV file, as a <a class="reference internal" href="../glossary#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This module does not support playing from a memory image asynchronously, so a combination of this flag and <a class="reference internal" href="#winsound.SND_ASYNC" title="winsound.SND_ASYNC"><code>SND_ASYNC</code></a> will raise <a class="reference internal" href="exceptions#RuntimeError" title="RuntimeError"><code>RuntimeError</code></a>.</p> </div> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_PURGE">
<code>winsound.SND_PURGE</code> </dt> <dd>
<p>Stop playing all instances of the specified sound.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This flag is not supported on modern Windows platforms.</p> </div> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_ASYNC">
<code>winsound.SND_ASYNC</code> </dt> <dd>
<p>Return immediately, allowing sounds to play asynchronously.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_NODEFAULT">
<code>winsound.SND_NODEFAULT</code> </dt> <dd>
<p>If the specified sound cannot be found, do not play the system default sound.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_NOSTOP">
<code>winsound.SND_NOSTOP</code> </dt> <dd>
<p>Do not interrupt sounds currently playing.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.SND_NOWAIT">
<code>winsound.SND_NOWAIT</code> </dt> <dd>
<p>Return immediately if the sound driver is busy.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This flag is not supported on modern Windows platforms.</p> </div> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.MB_ICONASTERISK">
<code>winsound.MB_ICONASTERISK</code> </dt> <dd>
<p>Play the <code>SystemDefault</code> sound.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.MB_ICONEXCLAMATION">
<code>winsound.MB_ICONEXCLAMATION</code> </dt> <dd>
<p>Play the <code>SystemExclamation</code> sound.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.MB_ICONHAND">
<code>winsound.MB_ICONHAND</code> </dt> <dd>
<p>Play the <code>SystemHand</code> sound.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.MB_ICONQUESTION">
<code>winsound.MB_ICONQUESTION</code> </dt> <dd>
<p>Play the <code>SystemQuestion</code> sound.</p> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="winsound.MB_OK">
<code>winsound.MB_OK</code> </dt> <dd>
<p>Play the <code>SystemDefault</code> sound.</p> </dd>
</dl> <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/winsound.html" class="_attribution-link">https://docs.python.org/3.12/library/winsound.html</a>
  </p>
</div>