mirror of https://github.com/python/cpython
154 lines
4.8 KiB
ReStructuredText
154 lines
4.8 KiB
ReStructuredText
: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, 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.
|
|
|
|
|
|
.. 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.
|
|
|
|
|
|
.. 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.
|
|
|