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