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