143 lines
4.8 KiB
TeX
143 lines
4.8 KiB
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}{htrd90@zepler.org}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
|
|
\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}
|