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    .. note::
  26
  27       Under Windows 95 and 98, the Windows :cfunc:`Beep` function exists but is
  28       useless (it ignores its arguments).  In that case Python simulates it via direct
  29       port manipulation (added in version 2.1).  It's unknown whether that will work
  30       on all systems.
  31
  32    .. versionadded:: 1.6
  33
  34
  35 .. function:: PlaySound(sound, flags)
  36
  37    Call the underlying :cfunc:`PlaySound` function from the Platform API.  The
  38    *sound* parameter may be a filename, audio data as a string, or ``None``.  Its
  39    interpretation depends on the value of *flags*, which can be a bitwise ORed
  40    combination of the constants described below.  If the system indicates an error,
  41    :exc:`RuntimeError` is raised.
  42
  43
  44 .. function:: MessageBeep([type=MB_OK])
  45
  46    Call the underlying :cfunc:`MessageBeep` function from the Platform API.  This
  47    plays a sound as specified in the registry.  The *type* argument specifies which
  48    sound to play; possible values are ``-1``, ``MB_ICONASTERISK``,
  49    ``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all
  50    described below.  The value ``-1`` produces a "simple beep"; this is the final
  51    fallback if a sound cannot be played otherwise.
  52
  53    .. versionadded:: 2.3
  54
  55
  56 .. data:: SND_FILENAME
  57
  58    The *sound* parameter is the name of a WAV file. Do not use with
  59    :const:`SND_ALIAS`.
  60
  61
  62 .. data:: SND_ALIAS
  63
  64    The *sound* parameter is a sound association name from the registry.  If the
  65    registry contains no such name, play the system default sound unless
  66    :const:`SND_NODEFAULT` is also specified. If no default sound is registered,
  67    raise :exc:`RuntimeError`. Do not use with :const:`SND_FILENAME`.
  68
  69    All Win32 systems support at least the following; most systems support many
  70    more:
  71
  72    +--------------------------+----------------------------------------+
  73    | :func:`PlaySound` *name* | Corresponding Control Panel Sound name |
  74    +==========================+========================================+
  75    | ``'SystemAsterisk'``     | Asterisk                               |
  76    +--------------------------+----------------------------------------+
  77    | ``'SystemExclamation'``  | Exclamation                            |
  78    +--------------------------+----------------------------------------+
  79    | ``'SystemExit'``         | Exit Windows                           |
  80    +--------------------------+----------------------------------------+
  81    | ``'SystemHand'``         | Critical Stop                          |
  82    +--------------------------+----------------------------------------+
  83    | ``'SystemQuestion'``     | Question                               |
  84    +--------------------------+----------------------------------------+
  85
  86    For example::
  87
  88       import winsound
  89       # Play Windows exit sound.
  90       winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
  91
  92       # Probably play Windows default sound, if any is registered (because
  93       # "*" probably isn't the registered name of any sound).
  94       winsound.PlaySound("*", winsound.SND_ALIAS)
  95
  96
  97 .. data:: SND_LOOP
  98
  99    Play the sound repeatedly.  The :const:`SND_ASYNC` flag must also be used to
 100    avoid blocking.  Cannot be used with :const:`SND_MEMORY`.
 101
 102
 103 .. data:: SND_MEMORY
 104
 105    The *sound* parameter to :func:`PlaySound` is a memory image of a WAV file, as a
 106    string.
 107
 108    .. note::
 109
 110       This module does not support playing from a memory image asynchronously, so a
 111       combination of this flag and :const:`SND_ASYNC` will raise :exc:`RuntimeError`.
 112
 113
 114 .. data:: SND_PURGE
 115
 116    Stop playing all instances of the specified sound.
 117
 118
 119 .. data:: SND_ASYNC
 120
 121    Return immediately, allowing sounds to play asynchronously.
 122
 123
 124 .. data:: SND_NODEFAULT
 125
 126    If the specified sound cannot be found, do not play the system default sound.
 127
 128
 129 .. data:: SND_NOSTOP
 130
 131    Do not interrupt sounds currently playing.
 132
 133
 134 .. data:: SND_NOWAIT
 135
 136    Return immediately if the sound driver is busy.
 137
 138
 139 .. data:: MB_ICONASTERISK
 140
 141    Play the ``SystemDefault`` sound.
 142
 143
 144 .. data:: MB_ICONEXCLAMATION
 145
 146    Play the ``SystemExclamation`` sound.
 147
 148
 149 .. data:: MB_ICONHAND
 150
 151    Play the ``SystemHand`` sound.
 152
 153
 154 .. data:: MB_ICONQUESTION
 155
 156    Play the ``SystemQuestion`` sound.
 157
 158
 159 .. data:: MB_OK
 160
 161    Play the ``SystemDefault`` sound.
 162