sam-t2/devtools/v9/html/python/lib/module-winsound.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="module--winreg.html" />
<link rel="parent" href="node822.html" />
<link rel="next" href="undoc.html" />
<meta name='aesop' content='information' />
<title>22.3 winsound -- Sound-playing interface for Windows</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="22.2.1 Registry Handle Objects"
  href="handle-object.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="22. MS Windows Specific"
  href="node822.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="A. Undocumented Modules"
  href="undoc.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="handle-object.html">22.2.1 Registry Handle Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="node822.html">22. MS Windows Specific</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="undoc.html">A. Undocumented Modules</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0024300000000000000000">
22.3 <tt class="module">winsound</tt> --
         Sound-playing interface for Windows</A>
</H1>

<P>
<A NAME="module-winsound"></A>
<p class="availability">Availability: <span
 class="platform">Windows</span>.</p>

<P>

<span class="versionnote">New in version 1.5.2.</span>

<P>
The <tt class="module">winsound</tt> module provides access to the basic
sound-playing machinery provided by Windows platforms.  It includes
functions and several constants.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5276' xml:id='l2h-5276' class="function">Beep</tt></b>(</nobr></td>
  <td><var>frequency, duration</var>)</td></tr></table></dt>
<dd>
  Beep the PC's speaker.
  The <var>frequency</var> parameter specifies frequency, in hertz, of the
  sound, and must be in the range 37 through 32,767.
  The <var>duration</var> parameter specifies the number of milliseconds the
  sound should last.  If the system is not
  able to beep the speaker, <tt class="exception">RuntimeError</tt> is raised.
  <span class="note"><b class="label">Note:</b>
Under Windows 95 and 98, the Windows <tt class="cfunction">Beep()</tt>
  function exists but is useless (it ignores its arguments).  In that
  case Python simulates it via direct port manipulation (added in version
  2.1).  It's unknown whether that will work on all systems.</span>

<span class="versionnote">New in version 1.6.</span>

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5277' xml:id='l2h-5277' class="function">PlaySound</tt></b>(</nobr></td>
  <td><var>sound, flags</var>)</td></tr></table></dt>
<dd>
  Call the underlying <tt class="cfunction">PlaySound()</tt> function from the
  Platform API.  The <var>sound</var> parameter may be a filename, audio
  data as a string, or <code>None</code>.  Its interpretation depends on the
  value of <var>flags</var>, which can be a bit-wise ORed combination of
  the constants described below.  If the system indicates an error,
  <tt class="exception">RuntimeError</tt> is raised.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5278' xml:id='l2h-5278' class="function">MessageBeep</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>type=<code>MB_OK</code></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Call the underlying <tt class="cfunction">MessageBeep()</tt> function from the
  Platform API.  This plays a sound as specified in the registry.  The
  <var>type</var> 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.

<span class="versionnote">New in version 2.3.</span>

</dl>

<P>
<dl><dt><b><tt id='l2h-5279' xml:id='l2h-5279'>SND_FILENAME</tt></b></dt>
<dd>
  The <var>sound</var> parameter is the name of a WAV file.
  Do not use with <tt class="constant">SND_ALIAS</tt>.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5280' xml:id='l2h-5280'>SND_ALIAS</tt></b></dt>
<dd>
  The <var>sound</var> parameter is a sound association name from the
  registry.  If the registry contains no such name, play the system
  default sound unless <tt class="constant">SND_NODEFAULT</tt> is also specified.
  If no default sound is registered, raise <tt class="exception">RuntimeError</tt>.
  Do not use with <tt class="constant">SND_FILENAME</tt>.

<P>
All Win32 systems support at least the following; most systems support
  many more:

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  ><tt class="function">PlaySound()</tt> <var>name</var></th>
      <th class="left"  >Corresponding Control Panel Sound name</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline"><code>'SystemAsterisk'</code></td>
        <td class="left"  >Asterisk</td></tr>
    <tr><td class="left"   valign="baseline"><code>'SystemExclamation'</code></td>
        <td class="left"  >Exclamation</td></tr>
    <tr><td class="left"   valign="baseline"><code>'SystemExit'</code></td>
        <td class="left"  >Exit Windows</td></tr>
    <tr><td class="left"   valign="baseline"><code>'SystemHand'</code></td>
        <td class="left"  >Critical Stop</td></tr>
    <tr><td class="left"   valign="baseline"><code>'SystemQuestion'</code></td>
        <td class="left"  >Question</td></tr></tbody>
</table></div>

<P>
For example:

<P>
<div class="verbatim"><pre>
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></div>
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5281' xml:id='l2h-5281'>SND_LOOP</tt></b></dt>
<dd>
  Play the sound repeatedly.  The <tt class="constant">SND_ASYNC</tt> flag must also
  be used to avoid blocking.  Cannot be used with <tt class="constant">SND_MEMORY</tt>.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5282' xml:id='l2h-5282'>SND_MEMORY</tt></b></dt>
<dd>
  The <var>sound</var> parameter to <tt class="function">PlaySound()</tt> is a memory
  image of a WAV file, as a string.

<P>
<span class="note"><b class="label">Note:</b>
This module does not support playing from a memory
  image asynchronously, so a combination of this flag and
  <tt class="constant">SND_ASYNC</tt> will raise <tt class="exception">RuntimeError</tt>.</span>
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5283' xml:id='l2h-5283'>SND_PURGE</tt></b></dt>
<dd>
  Stop playing all instances of the specified sound.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5284' xml:id='l2h-5284'>SND_ASYNC</tt></b></dt>
<dd>
  Return immediately, allowing sounds to play asynchronously.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5285' xml:id='l2h-5285'>SND_NODEFAULT</tt></b></dt>
<dd>
  If the specified sound cannot be found, do not play the system default
  sound.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5286' xml:id='l2h-5286'>SND_NOSTOP</tt></b></dt>
<dd>
  Do not interrupt sounds currently playing.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5287' xml:id='l2h-5287'>SND_NOWAIT</tt></b></dt>
<dd>
  Return immediately if the sound driver is busy.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5288' xml:id='l2h-5288'>MB_ICONASTERISK</tt></b></dt>
<dd>
  Play the <code>SystemDefault</code> sound.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5289' xml:id='l2h-5289'>MB_ICONEXCLAMATION</tt></b></dt>
<dd>
  Play the <code>SystemExclamation</code> sound.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5290' xml:id='l2h-5290'>MB_ICONHAND</tt></b></dt>
<dd>
  Play the <code>SystemHand</code> sound.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5291' xml:id='l2h-5291'>MB_ICONQUESTION</tt></b></dt>
<dd>
  Play the <code>SystemQuestion</code> sound.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-5292' xml:id='l2h-5292'>MB_OK</tt></b></dt>
<dd>
  Play the <code>SystemDefault</code> sound.
</dd></dl>

<P>


<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="22.2.1 Registry Handle Objects"
  href="handle-object.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="22. MS Windows Specific"
  href="node822.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="A. Undocumented Modules"
  href="undoc.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="handle-object.html">22.2.1 Registry Handle Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="node822.html">22. MS Windows Specific</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="undoc.html">A. Undocumented Modules</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>