Debian Codegraph @

Doc/library/winsound.rst

raw
1 :mod:`!winsound` --- Sound-playing interface for Windows
2 ========================================================
3
4 .. module:: winsound
5 :synopsis: Access to the sound-playing machinery for Windows.
6
7 .. moduleauthor:: Toby Dickenson <[email protected]>
8 .. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
9
10 --------------
11
12 The :mod:`!winsound` module provides access to the basic sound-playing machinery
13 provided by Windows platforms. It includes functions and several constants.
14
15 .. availability:: Windows.
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
26 .. function:: PlaySound(sound, flags)
27
28 Call the underlying :c:func:`!PlaySound` function from the Platform API. The
29 *sound* parameter may be a filename, a system sound alias, audio data as a
30 :term:`bytes-like object`, or ``None``. Its
31 interpretation depends on the value of *flags*, which can be a bitwise ORed
32 combination of the constants described below. If the *sound* parameter is
33 ``None``, any currently playing waveform sound is stopped. If the system
34 indicates an error, :exc:`RuntimeError` is raised.
35
36
37 .. function:: MessageBeep(type=MB_OK)
38
39 Call the underlying :c:func:`!MessageBeep` function from the Platform API. This
40 plays a sound as specified in the registry. The *type* argument specifies which
41 sound to play; possible values are ``-1``, ``MB_ICONASTERISK``,
42 ``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all
43 described below. The value ``-1`` produces a "simple beep"; this is the final
44 fallback if a sound cannot be played otherwise. If the system indicates an
45 error, :exc:`RuntimeError` is raised.
46
47
48 .. data:: SND_FILENAME
49
50 The *sound* parameter is the name of a WAV file. Do not use with
51 :const:`SND_ALIAS`.
52
53
54 .. data:: SND_ALIAS
55
56 The *sound* parameter is a sound association name from the registry. If the
57 registry contains no such name, play the system default sound unless
58 :const:`SND_NODEFAULT` is also specified. If no default sound is registered,
59 raise :exc:`RuntimeError`. Do not use with :const:`SND_FILENAME`.
60
61 All Win32 systems support at least the following; most systems support many
62 more:
63
64 +--------------------------+----------------------------------------+
65 | :func:`PlaySound` *name* | Corresponding Control Panel Sound name |
66 +==========================+========================================+
67 | ``'SystemAsterisk'`` | Asterisk |
68 +--------------------------+----------------------------------------+
69 | ``'SystemExclamation'`` | Exclamation |
70 +--------------------------+----------------------------------------+
71 | ``'SystemExit'`` | Exit Windows |
72 +--------------------------+----------------------------------------+
73 | ``'SystemHand'`` | Critical Stop |
74 +--------------------------+----------------------------------------+
75 | ``'SystemQuestion'`` | Question |
76 +--------------------------+----------------------------------------+
77
78 For example::
79
80 import winsound
81 # Play Windows exit sound.
82 winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
83
84 # Probably play Windows default sound, if any is registered (because
85 # "*" probably isn't the registered name of any sound).
86 winsound.PlaySound("*", winsound.SND_ALIAS)
87
88
89 .. data:: SND_LOOP
90
91 Play the sound repeatedly. The :const:`SND_ASYNC` flag must also be used to
92 avoid blocking. Cannot be used with :const:`SND_MEMORY`.
93
94
95 .. data:: SND_MEMORY
96
97 The *sound* parameter to :func:`PlaySound` is a memory image of a WAV file, as a
98 :term:`bytes-like object`.
99
100 .. note::
101
102 This module does not support playing from a memory image asynchronously, so a
103 combination of this flag and :const:`SND_ASYNC` will raise :exc:`RuntimeError`.
104
105
106 .. data:: SND_PURGE
107
108 Stop playing all instances of the specified sound.
109
110 .. note::
111
112 This flag is not supported on modern Windows platforms.
113
114
115 .. data:: SND_ASYNC
116
117 Return immediately, allowing sounds to play asynchronously.
118
119
120 .. data:: SND_NODEFAULT
121
122 If the specified sound cannot be found, do not play the system default sound.
123
124
125 .. data:: SND_NOSTOP
126
127 Do not interrupt sounds currently playing.
128
129
130 .. data:: SND_NOWAIT
131
132 Return immediately if the sound driver is busy.
133
134 .. note::
135
136 This flag is not supported on modern Windows platforms.
137
138
139 .. data:: SND_APPLICATION
140
141 The *sound* parameter is an application-specific alias in the registry.
142 This flag can be combined with the :const:`SND_ALIAS` flag
143 to specify an application-defined sound alias.
144
145
146 .. data:: SND_SENTRY
147
148 Triggers a SoundSentry event when the sound is played.
149
150 .. versionadded:: 3.14
151
152
153 .. data:: SND_SYNC
154
155 The sound is played synchronously. This is the default behavior.
156
157 .. versionadded:: 3.14
158
159
160 .. data:: SND_SYSTEM
161
162 Assign the sound to the audio session for system notification sounds.
163
164 .. versionadded:: 3.14
165
166
167 .. data:: MB_ICONASTERISK
168
169 Play the ``SystemDefault`` sound.
170
171
172 .. data:: MB_ICONEXCLAMATION
173
174 Play the ``SystemExclamation`` sound.
175
176
177 .. data:: MB_ICONHAND
178
179 Play the ``SystemHand`` sound.
180
181
182 .. data:: MB_ICONQUESTION
183
184 Play the ``SystemQuestion`` sound.
185
186
187 .. data:: MB_OK
188
189 Play the ``SystemDefault`` sound.
190
191
192 .. data:: MB_ICONERROR
193
194 Play the ``SystemHand`` sound.
195
196 .. versionadded:: 3.14
197
198
199 .. data:: MB_ICONINFORMATION
200
201 Play the ``SystemDefault`` sound.
202
203 .. versionadded:: 3.14
204
205
206 .. data:: MB_ICONSTOP
207
208 Play the ``SystemHand`` sound.
209
210 .. versionadded:: 3.14
211
212
213 .. data:: MB_ICONWARNING
214
215 Play the ``SystemExclamation`` sound.
216
217 .. versionadded:: 3.14