: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>

--------------

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.


.. function:: PlaySound(sound, flags)

   Call the underlying :c:func:`PlaySound` function from the Platform API.  The
   *sound* parameter may be a filename, a system sound alias, audio data as a
   :term:`bytes-like object`, or ``None``.  Its
   interpretation depends on the value of *flags*, which can be a bitwise ORed
   combination of the constants described below. If the *sound* parameter is
   ``None``, any currently playing waveform sound is stopped. If the system
   indicates an error, :exc:`RuntimeError` is raised.


.. function:: MessageBeep(type=MB_OK)

   Call the underlying :c:func:`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.  If the system indicates an
   error, :exc:`RuntimeError` is raised.


.. 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
   :term:`bytes-like object`.

   .. 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.

   .. note::

      This flag is not supported on modern Windows platforms.


.. 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.

   .. note::

      This flag is not supported on modern Windows platforms.


.. 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.