ref: 688c1f15cdaa5fcad19d9fddb30e1c555bfc59e0
dir: /sys/src/cmd/python/Doc/lib/libwinsound.tex/
\section{\module{winsound} ---
Sound-playing interface for Windows}
\declaremodule{builtin}{winsound}
\platform{Windows}
\modulesynopsis{Access to the sound-playing machinery for Windows.}
\moduleauthor{Toby Dickenson}{[email protected]}
\sectionauthor{Fred L. Drake, Jr.}{[email protected]}
\versionadded{1.5.2}
The \module{winsound} module provides access to the basic
sound-playing machinery provided by Windows platforms. It includes
functions and several constants.
\begin{funcdesc}{Beep}{frequency, duration}
Beep the PC's speaker.
The \var{frequency} parameter specifies frequency, in hertz, of the
sound, and must be in the range 37 through 32,767.
The \var{duration} parameter specifies the number of milliseconds the
sound should last. If the system is not
able to beep the speaker, \exception{RuntimeError} is raised.
\note{Under Windows 95 and 98, the Windows \cfunction{Beep()}
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.}
\versionadded{1.6}
\end{funcdesc}
\begin{funcdesc}{PlaySound}{sound, flags}
Call the underlying \cfunction{PlaySound()} function from the
Platform API. The \var{sound} parameter may be a filename, audio
data as a string, or \code{None}. Its interpretation depends on the
value of \var{flags}, which can be a bit-wise ORed combination of
the constants described below. If the system indicates an error,
\exception{RuntimeError} is raised.
\end{funcdesc}
\begin{funcdesc}{MessageBeep}{\optional{type=\code{MB_OK}}}
Call the underlying \cfunction{MessageBeep()} function from the
Platform API. This plays a sound as specified in the registry. The
\var{type} argument specifies which sound to play; possible values
are \code{-1}, \code{MB_ICONASTERISK}, \code{MB_ICONEXCLAMATION},
\code{MB_ICONHAND}, \code{MB_ICONQUESTION}, and \code{MB_OK}, all
described below. The value \code{-1} produces a ``simple beep'';
this is the final fallback if a sound cannot be played otherwise.
\versionadded{2.3}
\end{funcdesc}
\begin{datadesc}{SND_FILENAME}
The \var{sound} parameter is the name of a WAV file.
Do not use with \constant{SND_ALIAS}.
\end{datadesc}
\begin{datadesc}{SND_ALIAS}
The \var{sound} parameter is a sound association name from the
registry. If the registry contains no such name, play the system
default sound unless \constant{SND_NODEFAULT} is also specified.
If no default sound is registered, raise \exception{RuntimeError}.
Do not use with \constant{SND_FILENAME}.
All Win32 systems support at least the following; most systems support
many more:
\begin{tableii}{l|l}{code}
{\function{PlaySound()} \var{name}}
{Corresponding Control Panel Sound name}
\lineii{'SystemAsterisk'} {Asterisk}
\lineii{'SystemExclamation'}{Exclamation}
\lineii{'SystemExit'} {Exit Windows}
\lineii{'SystemHand'} {Critical Stop}
\lineii{'SystemQuestion'} {Question}
\end{tableii}
For example:
\begin{verbatim}
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)
\end{verbatim}
\end{datadesc}
\begin{datadesc}{SND_LOOP}
Play the sound repeatedly. The \constant{SND_ASYNC} flag must also
be used to avoid blocking. Cannot be used with \constant{SND_MEMORY}.
\end{datadesc}
\begin{datadesc}{SND_MEMORY}
The \var{sound} parameter to \function{PlaySound()} is a memory
image of a WAV file, as a string.
\note{This module does not support playing from a memory
image asynchronously, so a combination of this flag and
\constant{SND_ASYNC} will raise \exception{RuntimeError}.}
\end{datadesc}
\begin{datadesc}{SND_PURGE}
Stop playing all instances of the specified sound.
\end{datadesc}
\begin{datadesc}{SND_ASYNC}
Return immediately, allowing sounds to play asynchronously.
\end{datadesc}
\begin{datadesc}{SND_NODEFAULT}
If the specified sound cannot be found, do not play the system default
sound.
\end{datadesc}
\begin{datadesc}{SND_NOSTOP}
Do not interrupt sounds currently playing.
\end{datadesc}
\begin{datadesc}{SND_NOWAIT}
Return immediately if the sound driver is busy.
\end{datadesc}
\begin{datadesc}{MB_ICONASTERISK}
Play the \code{SystemDefault} sound.
\end{datadesc}
\begin{datadesc}{MB_ICONEXCLAMATION}
Play the \code{SystemExclamation} sound.
\end{datadesc}
\begin{datadesc}{MB_ICONHAND}
Play the \code{SystemHand} sound.
\end{datadesc}
\begin{datadesc}{MB_ICONQUESTION}
Play the \code{SystemQuestion} sound.
\end{datadesc}
\begin{datadesc}{MB_OK}
Play the \code{SystemDefault} sound.
\end{datadesc}