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:: MB_ICONASTERISK
147
148 Play the ``SystemDefault`` sound.
149
150
151 .. data:: MB_ICONEXCLAMATION
152
153 Play the ``SystemExclamation`` sound.
154
155
156 .. data:: MB_ICONHAND
157
158 Play the ``SystemHand`` sound.
159
160
161 .. data:: MB_ICONQUESTION
162
163 Play the ``SystemQuestion`` sound.
164
165
166 .. data:: MB_OK
167
168 Play the ``SystemDefault`` sound.
169