← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-2.7.11-docs-html/_sources/library/winsound.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-2.7.11-docs-html/_sources/library/winsound.txt
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
 
 
14
 
The :mod:`winsound` module provides access to the basic sound-playing machinery
15
 
provided 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 :c:func:`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 :c:func:`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
 
   .. note::
137
 
 
138
 
      This flag is not supported on modern Windows platforms.
139
 
 
140
 
 
141
 
.. data:: MB_ICONASTERISK
142
 
 
143
 
   Play the ``SystemDefault`` sound.
144
 
 
145
 
 
146
 
.. data:: MB_ICONEXCLAMATION
147
 
 
148
 
   Play the ``SystemExclamation`` sound.
149
 
 
150
 
 
151
 
.. data:: MB_ICONHAND
152
 
 
153
 
   Play the ``SystemHand`` sound.
154
 
 
155
 
 
156
 
.. data:: MB_ICONQUESTION
157
 
 
158
 
   Play the ``SystemQuestion`` sound.
159
 
 
160
 
 
161
 
.. data:: MB_OK
162
 
 
163
 
   Play the ``SystemDefault`` sound.
164