22

✏️ Editing: winsound.rst.txt

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

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.

MR SKB