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