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 (a] zepler.org> 9 .. sectionauthor:: Fred L. Drake, Jr. <fdrake (a] 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 165
