Doc/library/winsound.rst

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