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