:mod:`winsound` --- Sound-playing interface for Windows ======================================================= .. module:: winsound :platform: Windows :synopsis: Access to the sound-playing machinery for Windows. .. moduleauthor:: Toby Dickenson .. sectionauthor:: Fred L. Drake, Jr. .. 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 :c:func:`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 *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. .. 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. .. 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.