1 files changed, 162 insertions, 0 deletions
diff --git a/Doc/library/winsound.rst b/Doc/library/winsound.rst
new file mode 100644
index 0000000000..c4c04bd058
--- /dev/null
+++ b/Doc/library/winsound.rst
@@ -0,0 +1,162 @@
+
+: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.
+
+   .. note::
+
+      Under Windows 95 and 98, the Windows :cfunc:`Beep` function exists but is
+      useless (it ignores its arguments).  In that case Python simulates it via direct
+      port manipulation (added in version 2.1).  It's unknown whether that will work
+      on all systems.
+
+   .. 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 bit-wise ORed
+   combination of the constants described below.  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.
+
+
+.. 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.
+