Doc/lib/libwinsound.tex

   1 \section{\module{winsound} ---
   2          Sound-playing interface for Windows}
   3
   4 \declaremodule{builtin}{winsound}
   5   \platform{Windows}
   6 \modulesynopsis{Access to the sound-playing machinery for Windows.}
   7 \moduleauthor{Toby Dickenson}{htrd90@zepler.org}
   8 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   9
  10 \versionadded{1.5.2}
  11
  12 The \module{winsound} module provides access to the basic
  13 sound-playing machinery provided by Windows platforms.  It includes
  14 functions and several constants.
  15
  16
  17 \begin{funcdesc}{Beep}{frequency, duration}
  18   Beep the PC's speaker.
  19   The \var{frequency} parameter specifies frequency, in hertz, of the
  20   sound, and must be in the range 37 through 32,767.
  21   The \var{duration} parameter specifies the number of milliseconds the
  22   sound should last.  If the system is not
  23   able to beep the speaker, \exception{RuntimeError} is raised.
  24   \note{Under Windows 95 and 98, the Windows \cfunction{Beep()}
  25   function exists but is useless (it ignores its arguments).  In that
  26   case Python simulates it via direct port manipulation (added in version
  27   2.1).  It's unknown whether that will work on all systems.}
  28   \versionadded{1.6}
  29 \end{funcdesc}
  30
  31 \begin{funcdesc}{PlaySound}{sound, flags}
  32   Call the underlying \cfunction{PlaySound()} function from the
  33   Platform API.  The \var{sound} parameter may be a filename, audio
  34   data as a string, or \code{None}.  Its interpretation depends on the
  35   value of \var{flags}, which can be a bit-wise ORed combination of
  36   the constants described below.  If the system indicates an error,
  37   \exception{RuntimeError} is raised.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{MessageBeep}{\optional{type=\code{MB_OK}}}
  41   Call the underlying \cfunction{MessageBeep()} function from the
  42   Platform API.  This plays a sound as specified in the registry.  The
  43   \var{type} argument specifies which sound to play; possible values
  44   are \code{-1}, \code{MB_ICONASTERISK}, \code{MB_ICONEXCLAMATION},
  45   \code{MB_ICONHAND}, \code{MB_ICONQUESTION}, and \code{MB_OK}, all
  46   described below.  The value \code{-1} produces a ``simple beep'';
  47   this is the final fallback if a sound cannot be played otherwise.
  48   \versionadded{2.3}
  49 \end{funcdesc}
  50
  51 \begin{datadesc}{SND_FILENAME}
  52   The \var{sound} parameter is the name of a WAV file.
  53   Do not use with \constant{SND_ALIAS}.
  54 \end{datadesc}
  55
  56 \begin{datadesc}{SND_ALIAS}
  57   The \var{sound} parameter is a sound association name from the
  58   registry.  If the registry contains no such name, play the system
  59   default sound unless \constant{SND_NODEFAULT} is also specified.
  60   If no default sound is registered, raise \exception{RuntimeError}.
  61   Do not use with \constant{SND_FILENAME}.
  62
  63   All Win32 systems support at least the following; most systems support
  64   many more:
  65
  66 \begin{tableii}{l|l}{code}
  67                {\function{PlaySound()} \var{name}}
  68                {Corresponding Control Panel Sound name}
  69   \lineii{'SystemAsterisk'}   {Asterisk}
  70   \lineii{'SystemExclamation'}{Exclamation}
  71   \lineii{'SystemExit'}       {Exit Windows}
  72   \lineii{'SystemHand'}       {Critical Stop}
  73   \lineii{'SystemQuestion'}   {Question}
  74 \end{tableii}
  75
  76   For example:
  77
  78 \begin{verbatim}
  79 import winsound
  80 # Play Windows exit sound.
  81 winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
  82
  83 # Probably play Windows default sound, if any is registered (because
  84 # "*" probably isn't the registered name of any sound).
  85 winsound.PlaySound("*", winsound.SND_ALIAS)
  86 \end{verbatim}
  87 \end{datadesc}
  88
  89 \begin{datadesc}{SND_LOOP}
  90   Play the sound repeatedly.  The \constant{SND_ASYNC} flag must also
  91   be used to avoid blocking.  Cannot be used with \constant{SND_MEMORY}.
  92 \end{datadesc}
  93
  94 \begin{datadesc}{SND_MEMORY}
  95   The \var{sound} parameter to \function{PlaySound()} is a memory
  96   image of a WAV file, as a string.
  97
  98   \note{This module does not support playing from a memory
  99   image asynchronously, so a combination of this flag and
 100   \constant{SND_ASYNC} will raise \exception{RuntimeError}.}
 101 \end{datadesc}
 102
 103 \begin{datadesc}{SND_PURGE}
 104   Stop playing all instances of the specified sound.
 105 \end{datadesc}
 106
 107 \begin{datadesc}{SND_ASYNC}
 108   Return immediately, allowing sounds to play asynchronously.
 109 \end{datadesc}
 110
 111 \begin{datadesc}{SND_NODEFAULT}
 112   If the specified sound cannot be found, do not play the system default
 113   sound.
 114 \end{datadesc}
 115
 116 \begin{datadesc}{SND_NOSTOP}
 117   Do not interrupt sounds currently playing.
 118 \end{datadesc}
 119
 120 \begin{datadesc}{SND_NOWAIT}
 121   Return immediately if the sound driver is busy.
 122 \end{datadesc}
 123
 124 \begin{datadesc}{MB_ICONASTERISK}
 125   Play the \code{SystemDefault} sound.
 126 \end{datadesc}
 127
 128 \begin{datadesc}{MB_ICONEXCLAMATION}
 129   Play the \code{SystemExclamation} sound.
 130 \end{datadesc}
 131
 132 \begin{datadesc}{MB_ICONHAND}
 133   Play the \code{SystemHand} sound.
 134 \end{datadesc}
 135
 136 \begin{datadesc}{MB_ICONQUESTION}
 137   Play the \code{SystemQuestion} sound.
 138 \end{datadesc}
 139
 140 \begin{datadesc}{MB_OK}
 141   Play the \code{SystemDefault} sound.
 142 \end{datadesc}