/Doc/library/winsound.rst

  1
  2:mod:`winsound` --- Sound-playing interface for Windows
  3=======================================================
  4
  5.. module:: winsound
  6   :platform: Windows
  7   :synopsis: Access to the sound-playing machinery for Windows.
  8.. moduleauthor:: Toby Dickenson <htrd90@zepler.org>
  9.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 10
 11
 12.. versionadded:: 1.5.2
 13
 14The :mod:`winsound` module provides access to the basic sound-playing machinery
 15provided by Windows platforms.  It includes functions and several constants.
 16
 17
 18.. function:: Beep(frequency, duration)
 19
 20   Beep the PC's speaker. The *frequency* parameter specifies frequency, in hertz,
 21   of the sound, and must be in the range 37 through 32,767. The *duration*
 22   parameter specifies the number of milliseconds the sound should last.  If the
 23   system is not able to beep the speaker, :exc:`RuntimeError` is raised.
 24
 25   .. versionadded:: 1.6
 26
 27
 28.. function:: PlaySound(sound, flags)
 29
 30   Call the underlying :cfunc:`PlaySound` function from the Platform API.  The
 31   *sound* parameter may be a filename, audio data as a string, or ``None``.  Its
 32   interpretation depends on the value of *flags*, which can be a bitwise ORed
 33   combination of the constants described below. If the *sound* parameter is
 34   ``None``, any currently playing waveform sound is stopped. If the system
 35   indicates an error, :exc:`RuntimeError` is raised.
 36
 37
 38.. function:: MessageBeep([type=MB_OK])
 39
 40   Call the underlying :cfunc:`MessageBeep` function from the Platform API.  This
 41   plays a sound as specified in the registry.  The *type* argument specifies which
 42   sound to play; possible values are ``-1``, ``MB_ICONASTERISK``,
 43   ``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all
 44   described below.  The value ``-1`` produces a "simple beep"; this is the final
 45   fallback if a sound cannot be played otherwise.
 46
 47   .. versionadded:: 2.3
 48
 49
 50.. data:: SND_FILENAME
 51
 52   The *sound* parameter is the name of a WAV file. Do not use with
 53   :const:`SND_ALIAS`.
 54
 55
 56.. data:: SND_ALIAS
 57
 58   The *sound* parameter is a sound association name from the registry.  If the
 59   registry contains no such name, play the system default sound unless
 60   :const:`SND_NODEFAULT` is also specified. If no default sound is registered,
 61   raise :exc:`RuntimeError`. Do not use with :const:`SND_FILENAME`.
 62
 63   All Win32 systems support at least the following; most systems support many
 64   more:
 65
 66   +--------------------------+----------------------------------------+
 67   | :func:`PlaySound` *name* | Corresponding Control Panel Sound name |
 68   +==========================+========================================+
 69   | ``'SystemAsterisk'``     | Asterisk                               |
 70   +--------------------------+----------------------------------------+
 71   | ``'SystemExclamation'``  | Exclamation                            |
 72   +--------------------------+----------------------------------------+
 73   | ``'SystemExit'``         | Exit Windows                           |
 74   +--------------------------+----------------------------------------+
 75   | ``'SystemHand'``         | Critical Stop                          |
 76   +--------------------------+----------------------------------------+
 77   | ``'SystemQuestion'``     | Question                               |
 78   +--------------------------+----------------------------------------+
 79
 80   For example::
 81
 82      import winsound
 83      # Play Windows exit sound.
 84      winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
 85
 86      # Probably play Windows default sound, if any is registered (because
 87      # "*" probably isn't the registered name of any sound).
 88      winsound.PlaySound("*", winsound.SND_ALIAS)
 89
 90
 91.. data:: SND_LOOP
 92
 93   Play the sound repeatedly.  The :const:`SND_ASYNC` flag must also be used to
 94   avoid blocking.  Cannot be used with :const:`SND_MEMORY`.
 95
 96
 97.. data:: SND_MEMORY
 98
 99   The *sound* parameter to :func:`PlaySound` is a memory image of a WAV file, as a
100   string.
101
102   .. note::
103
104      This module does not support playing from a memory image asynchronously, so a
105      combination of this flag and :const:`SND_ASYNC` will raise :exc:`RuntimeError`.
106
107
108.. data:: SND_PURGE
109
110   Stop playing all instances of the specified sound.
111
112   .. note::
113
114      This flag is not supported on modern Windows platforms.
115
116
117.. data:: SND_ASYNC
118
119   Return immediately, allowing sounds to play asynchronously.
120
121
122.. data:: SND_NODEFAULT
123
124   If the specified sound cannot be found, do not play the system default sound.
125
126
127.. data:: SND_NOSTOP
128
129   Do not interrupt sounds currently playing.
130
131
132.. data:: SND_NOWAIT
133
134   Return immediately if the sound driver is busy.
135
136
137.. data:: MB_ICONASTERISK
138
139   Play the ``SystemDefault`` sound.
140
141
142.. data:: MB_ICONEXCLAMATION
143
144   Play the ``SystemExclamation`` sound.
145
146
147.. data:: MB_ICONHAND
148
149   Play the ``SystemHand`` sound.
150
151
152.. data:: MB_ICONQUESTION
153
154   Play the ``SystemQuestion`` sound.
155
156
157.. data:: MB_OK
158
159   Play the ``SystemDefault`` sound.
160