:mod:`!winsound` --- Sound-playing interface for Windows
========================================================
.. module:: winsound
:platform: Windows
:synopsis: Access to the sound-playing machinery for Windows.
.. moduleauthor:: Toby Dickenson <[email protected]>
.. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
--------------
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.
Codebase Browser
cpython