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 two 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 (\code{0x25}
  21   through \code{0x7fff}).  The \var{duration} parameter specifies the
  22   number of milliseconds the sound should last.  If the system is not
  23   able to beep the speaker, \exception{RuntimeError} is raised.
  24   \versionadded{1.5.3} % XXX fix this version number when release is scheduled!
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{PlaySound}{sound, flags}
  28   Call the underlying \cfunction{PlaySound()} function from the
  29   Platform API.  The \var{sound} parameter may be a filename, audio
  30   data as a string, or \code{None}.  Its interpretation depends on the
  31   value of \var{flags}, which can be a bit-wise ORed combination of
  32   the constants described below.  If the system indicates an error,
  33   \exception{RuntimeError} is raised.
  34 \end{funcdesc}
  35
  36
  37 \begin{datadesc}{SND_FILENAME}
  38   The \var{sound} parameter is the name of a WAV file.
  39 \end{datadesc}
  40
  41 \begin{datadesc}{SND_ALIAS}
  42   The \var{sound} parameter should be interpreted as a control panel
  43   sound association name.
  44 \end{datadesc}
  45
  46 \begin{datadesc}{SND_LOOP}
  47   Play the sound repeatedly.  The \constant{SND_ASYNC} flag must also
  48   be used to avoid blocking.
  49 \end{datadesc}
  50
  51 \begin{datadesc}{SND_MEMORY}
  52   The \var{sound} parameter to \function{PlaySound()} is a memory
  53   image of a WAV file.
  54
  55   \strong{Note:}  This module does not support playing from a memory
  56   image asynchonously, so a combination of this flag and
  57   \constant{SND_ASYNC} will raise a \exception{RuntimeError}.
  58 \end{datadesc}
  59
  60 \begin{datadesc}{SND_PURGE}
  61   Stop playing all instances of the specified sound.
  62 \end{datadesc}
  63
  64 \begin{datadesc}{SND_ASYNC}
  65   Return immediately, allowing sounds to play asynchronously.
  66 \end{datadesc}
  67
  68 \begin{datadesc}{SND_NODEFAULT}
  69   If the specified sound cannot be found, do not play a default beep.
  70 \end{datadesc}
  71
  72 \begin{datadesc}{SND_NOSTOP}
  73   Do not interrupt sounds currently playing.
  74 \end{datadesc}
  75
  76 \begin{datadesc}{SND_NOWAIT}
  77   Return immediately if the sound driver is busy.
  78 \end{datadesc}