/Doc/library/winsound.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 160 lines · 92 code · 68 blank · 0 comment · 0 complexity · 39ef0c5b4591edca9879368d901304c4 MD5 · raw file
- :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>
- .. 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 :cfunc:`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 :cfunc:`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.
- .. 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.