:mod:`winsound` --- Sound-playing interface for Windows

=======================================================

.. module:: winsound

   :platform: Windows

   :synopsis: Access to the sound-playing machinery for Windows.

.. moduleauthor:: Toby Dickenson <htrd90@zepler.org>

.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

.. versionadded:: 1.5.2

The :mod:`winsound` module provides access to the basic sound-playing machinery

provided by Windows platforms.  It includes functions and several constants.

.. function:: Beep(frequency, duration)

   Beep the PC's speaker. The *frequency* parameter specifies frequency, in hertz,

   of the sound, and must be in the range 37 through 32,767. The *duration*

   parameter specifies the number of milliseconds the sound should last.  If the

   system is not able to beep the speaker, :exc:`RuntimeError` is raised.

   .. versionadded:: 1.6

.. function:: PlaySound(sound, flags)

   Call the underlying :cfunc:`PlaySound` function from the Platform API.  The

   *sound* parameter may be a filename, audio data as a string, or ``None``.  Its

   interpretation depends on the value of *flags*, which can be a bitwise ORed

   combination of the constants described below.  If the system indicates an error,

   :exc:`RuntimeError` is raised.

.. function:: MessageBeep([type=MB_OK])

   Call the underlying :cfunc:`MessageBeep` function from the Platform API.  This

   plays a sound as specified in the registry.  The *type* argument specifies which

   sound to play; possible values are ``-1``, ``MB_ICONASTERISK``,

   ``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all

   described below.  The value ``-1`` produces a "simple beep"; this is the final

   fallback if a sound cannot be played otherwise.

   .. versionadded:: 2.3

.. data:: SND_FILENAME

   The *sound* parameter is the name of a WAV file. Do not use with

   :const:`SND_ALIAS`.

.. data:: SND_ALIAS

   The *sound* parameter is a sound association name from the registry.  If the

   registry contains no such name, play the system default sound unless

   :const:`SND_NODEFAULT` is also specified. If no default sound is registered,

   raise :exc:`RuntimeError`. Do not use with :const:`SND_FILENAME`.

   All Win32 systems support at least the following; most systems support many

   more:

   +--------------------------+----------------------------------------+

   | :func:`PlaySound` *name* | Corresponding Control Panel Sound name |

   +==========================+========================================+

   | ``'SystemAsterisk'``     | Asterisk                               |

   +--------------------------+----------------------------------------+

   | ``'SystemExclamation'``  | Exclamation                            |

   +--------------------------+----------------------------------------+

   | ``'SystemExit'``         | Exit Windows                           |

   +--------------------------+----------------------------------------+

   | ``'SystemHand'``         | Critical Stop                          |

   +--------------------------+----------------------------------------+

   | ``'SystemQuestion'``     | Question                               |

   +--------------------------+----------------------------------------+

   For example::

      import winsound

      # Play Windows exit sound.

      winsound.PlaySound("SystemExit", winsound.SND_ALIAS)

      # Probably play Windows default sound, if any is registered (because

      # "*" probably isn't the registered name of any sound).

      winsound.PlaySound("*", winsound.SND_ALIAS)

.. data:: SND_LOOP

   Play the sound repeatedly.  The :const:`SND_ASYNC` flag must also be used to

   avoid blocking.  Cannot be used with :const:`SND_MEMORY`.

.. data:: SND_MEMORY

   The *sound* parameter to :func:`PlaySound` is a memory image of a WAV file, as a

   string.

   .. note::

      This module does not support playing from a memory image asynchronously, so a

      combination of this flag and :const:`SND_ASYNC` will raise :exc:`RuntimeError`.

.. data:: SND_PURGE

   Stop playing all instances of the specified sound.

.. data:: SND_ASYNC

   Return immediately, allowing sounds to play asynchronously.

.. data:: SND_NODEFAULT

   If the specified sound cannot be found, do not play the system default sound.

.. data:: SND_NOSTOP

   Do not interrupt sounds currently playing.

.. data:: SND_NOWAIT

   Return immediately if the sound driver is busy.

.. data:: MB_ICONASTERISK

   Play the ``SystemDefault`` sound.

.. data:: MB_ICONEXCLAMATION

   Play the ``SystemExclamation`` sound.

.. data:: MB_ICONHAND

   Play the ``SystemHand`` sound.

.. data:: MB_ICONQUESTION

   Play the ``SystemQuestion`` sound.

.. data:: MB_OK

   Play the ``SystemDefault`` sound.