1 :mod:`winsound` --- Sound-playing interface for Windows 2 ======================================================= 3 4 .. module:: winsound 5 :platform: Windows 6 :synopsis: Access to the sound-playing machinery for Windows. 7 8 .. moduleauthor:: Toby Dickenson <htrd90 (a] zepler.org> 9 .. sectionauthor:: Fred L. Drake, Jr. <fdrake (a] acm.org> 10 11 -------------- 12 13 The :mod:`winsound` module provides access to the basic sound-playing machinery 14 provided by Windows platforms. It includes functions and several constants. 15 16 17 .. function:: Beep(frequency, duration) 18 19 Beep the PC's speaker. The *frequency* parameter specifies frequency, in hertz, 20 of the sound, and must be in the range 37 through 32,767. The *duration* 21 parameter specifies the number of milliseconds the sound should last. If the 22 system is not able to beep the speaker, :exc:`RuntimeError` is raised. 23 24 25 .. function:: PlaySound(sound, flags) 26 27 Call the underlying :c:func:`PlaySound` function from the Platform API. The 28 *sound* parameter may be a filename, a system sound alias, audio data as a 29 :term:`bytes-like object`, or ``None``. Its 30 interpretation depends on the value of *flags*, which can be a bitwise ORed 31 combination of the constants described below. If the *sound* parameter is 32 ``None``, any currently playing waveform sound is stopped. If the system 33 indicates an error, :exc:`RuntimeError` is raised. 34 35 36 .. function:: MessageBeep(type=MB_OK) 37 38 Call the underlying :c:func:`MessageBeep` function from the Platform API. This 39 plays a sound as specified in the registry. The *type* argument specifies which 40 sound to play; possible values are ``-1``, ``MB_ICONASTERISK``, 41 ``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all 42 described below. The value ``-1`` produces a "simple beep"; this is the final 43 fallback if a sound cannot be played otherwise. If the system indicates an 44 error, :exc:`RuntimeError` is raised. 45 46 47 .. data:: SND_FILENAME 48 49 The *sound* parameter is the name of a WAV file. Do not use with 50 :const:`SND_ALIAS`. 51 52 53 .. data:: SND_ALIAS 54 55 The *sound* parameter is a sound association name from the registry. If the 56 registry contains no such name, play the system default sound unless 57 :const:`SND_NODEFAULT` is also specified. If no default sound is registered, 58 raise :exc:`RuntimeError`. Do not use with :const:`SND_FILENAME`. 59 60 All Win32 systems support at least the following; most systems support many 61 more: 62 63 +--------------------------+----------------------------------------+ 64 | :func:`PlaySound` *name* | Corresponding Control Panel Sound name | 65 +==========================+========================================+ 66 | ``'SystemAsterisk'`` | Asterisk | 67 +--------------------------+----------------------------------------+ 68 | ``'SystemExclamation'`` | Exclamation | 69 +--------------------------+----------------------------------------+ 70 | ``'SystemExit'`` | Exit Windows | 71 +--------------------------+----------------------------------------+ 72 | ``'SystemHand'`` | Critical Stop | 73 +--------------------------+----------------------------------------+ 74 | ``'SystemQuestion'`` | Question | 75 +--------------------------+----------------------------------------+ 76 77 For example:: 78 79 import winsound 80 # Play Windows exit sound. 81 winsound.PlaySound("SystemExit", winsound.SND_ALIAS) 82 83 # Probably play Windows default sound, if any is registered (because 84 # "*" probably isn't the registered name of any sound). 85 winsound.PlaySound("*", winsound.SND_ALIAS) 86 87 88 .. data:: SND_LOOP 89 90 Play the sound repeatedly. The :const:`SND_ASYNC` flag must also be used to 91 avoid blocking. Cannot be used with :const:`SND_MEMORY`. 92 93 94 .. data:: SND_MEMORY 95 96 The *sound* parameter to :func:`PlaySound` is a memory image of a WAV file, as a 97 :term:`bytes-like object`. 98 99 .. note:: 100 101 This module does not support playing from a memory image asynchronously, so a 102 combination of this flag and :const:`SND_ASYNC` will raise :exc:`RuntimeError`. 103 104 105 .. data:: SND_PURGE 106 107 Stop playing all instances of the specified sound. 108 109 .. note:: 110 111 This flag is not supported on modern Windows platforms. 112 113 114 .. data:: SND_ASYNC 115 116 Return immediately, allowing sounds to play asynchronously. 117 118 119 .. data:: SND_NODEFAULT 120 121 If the specified sound cannot be found, do not play the system default sound. 122 123 124 .. data:: SND_NOSTOP 125 126 Do not interrupt sounds currently playing. 127 128 129 .. data:: SND_NOWAIT 130 131 Return immediately if the sound driver is busy. 132 133 .. note:: 134 135 This flag is not supported on modern Windows platforms. 136 137 138 .. data:: MB_ICONASTERISK 139 140 Play the ``SystemDefault`` sound. 141 142 143 .. data:: MB_ICONEXCLAMATION 144 145 Play the ``SystemExclamation`` sound. 146 147 148 .. data:: MB_ICONHAND 149 150 Play the ``SystemHand`` sound. 151 152 153 .. data:: MB_ICONQUESTION 154 155 Play the ``SystemQuestion`` sound. 156 157 158 .. data:: MB_OK 159 160 Play the ``SystemDefault`` sound. 161 162
