summaryrefslogtreecommitdiff
path: root/Doc/library/winsound.rst
blob: 372f792a0f938e17961fdee1a3ab72619f2e403a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
: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>

--------------

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.


.. function:: PlaySound(sound, flags)

   Call the underlying :c:func:`PlaySound` function from the Platform API.  The
   *sound* parameter may be a filename, a system sound alias, audio data as a
   :term:`bytes-like object`, or ``None``.  Its
   interpretation depends on the value of *flags*, which can be a bitwise ORed
   combination of the constants described below. If the *sound* parameter is
   ``None``, any currently playing waveform sound is stopped. If the system
   indicates an error, :exc:`RuntimeError` is raised.


.. function:: MessageBeep(type=MB_OK)

   Call the underlying :c:func:`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.  If the system indicates an
   error, :exc:`RuntimeError` is raised.


.. 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
   :term:`bytes-like object`.

   .. 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.

   .. note::

      This flag is not supported on modern Windows platforms.


.. 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.

   .. note::

      This flag is not supported on modern Windows platforms.


.. 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.