Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 1 | \section{\module{winsound} --- |
| 2 | Sound-playing interface for Windows} |
| 3 | |
| 4 | \declaremodule{builtin}{winsound} |
Fred Drake | f6863c1 | 1999-03-02 16:37:17 +0000 | [diff] [blame] | 5 | \platform{Windows} |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 6 | \modulesynopsis{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 | |
Fred Drake | f634634 | 1999-02-19 15:46:38 +0000 | [diff] [blame] | 10 | \versionadded{1.5.2} |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 11 | |
| 12 | The \module{winsound} module provides access to the basic |
Fred Drake | 714fd26 | 1999-10-22 21:08:56 +0000 | [diff] [blame] | 13 | sound-playing machinery provided by Windows platforms. It includes |
Fred Drake | ceeb191 | 2004-04-28 03:57:47 +0000 | [diff] [blame] | 14 | functions and several constants. |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 15 | |
| 16 | |
Fred Drake | 714fd26 | 1999-10-22 21:08:56 +0000 | [diff] [blame] | 17 | \begin{funcdesc}{Beep}{frequency, duration} |
| 18 | Beep the PC's speaker. |
| 19 | The \var{frequency} parameter specifies frequency, in hertz, of the |
Tim Peters | 25a9ce3 | 2001-02-19 07:06:36 +0000 | [diff] [blame] | 20 | sound, and must be in the range 37 through 32,767. |
| 21 | The \var{duration} parameter specifies the number of milliseconds the |
| 22 | sound should last. If the system is not |
Fred Drake | 714fd26 | 1999-10-22 21:08:56 +0000 | [diff] [blame] | 23 | able to beep the speaker, \exception{RuntimeError} is raised. |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 24 | \note{Under Windows 95 and 98, the Windows \cfunction{Beep()} |
Tim Peters | 373d151 | 2001-02-19 08:36:41 +0000 | [diff] [blame] | 25 | function exists but is useless (it ignores its arguments). In that |
Tim Peters | 25a9ce3 | 2001-02-19 07:06:36 +0000 | [diff] [blame] | 26 | case Python simulates it via direct port manipulation (added in version |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 27 | 2.1). It's unknown whether that will work on all systems.} |
Fred Drake | 2905248 | 2001-01-25 17:29:18 +0000 | [diff] [blame] | 28 | \versionadded{1.6} |
Fred Drake | 714fd26 | 1999-10-22 21:08:56 +0000 | [diff] [blame] | 29 | \end{funcdesc} |
| 30 | |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 31 | \begin{funcdesc}{PlaySound}{sound, flags} |
| 32 | Call the underlying \cfunction{PlaySound()} function from the |
| 33 | Platform API. The \var{sound} parameter may be a filename, audio |
| 34 | data as a string, or \code{None}. Its interpretation depends on the |
| 35 | value of \var{flags}, which can be a bit-wise ORed combination of |
| 36 | the constants described below. If the system indicates an error, |
| 37 | \exception{RuntimeError} is raised. |
| 38 | \end{funcdesc} |
| 39 | |
Guido van Rossum | 8f512a2 | 2003-05-16 01:42:22 +0000 | [diff] [blame] | 40 | \begin{funcdesc}{MessageBeep}{\optional{type=\code{MB_OK}}} |
| 41 | Call the underlying \cfunction{MessageBeep()} function from the |
| 42 | Platform API. This plays a sound as specified in the registry. The |
| 43 | \var{type} argument specifies which sound to play; possible values |
| 44 | are \code{-1}, \code{MB_ICONASTERISK}, \code{MB_ICONEXCLAMATION}, |
| 45 | \code{MB_ICONHAND}, \code{MB_ICONQUESTION}, and \code{MB_OK}, all |
| 46 | described below. The value \code{-1} produces a ``simple beep''; |
| 47 | this is the final fallback if a sound cannot be played otherwise. |
| 48 | \versionadded{2.3} |
| 49 | \end{funcdesc} |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 50 | |
| 51 | \begin{datadesc}{SND_FILENAME} |
| 52 | The \var{sound} parameter is the name of a WAV file. |
Tim Peters | e79af27 | 2001-02-20 10:02:21 +0000 | [diff] [blame] | 53 | Do not use with \constant{SND_ALIAS}. |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 54 | \end{datadesc} |
| 55 | |
| 56 | \begin{datadesc}{SND_ALIAS} |
Fred Drake | afdc8fc | 2001-02-23 19:10:41 +0000 | [diff] [blame] | 57 | The \var{sound} parameter is a sound association name from the |
| 58 | registry. If the registry contains no such name, play the system |
| 59 | default sound unless \constant{SND_NODEFAULT} is also specified. |
| 60 | If no default sound is registered, raise \exception{RuntimeError}. |
| 61 | Do not use with \constant{SND_FILENAME}. |
Tim Peters | e79af27 | 2001-02-20 10:02:21 +0000 | [diff] [blame] | 62 | |
| 63 | All Win32 systems support at least the following; most systems support |
| 64 | many more: |
| 65 | |
Fred Drake | afdc8fc | 2001-02-23 19:10:41 +0000 | [diff] [blame] | 66 | \begin{tableii}{l|l}{code} |
| 67 | {\function{PlaySound()} \var{name}} |
| 68 | {Corresponding Control Panel Sound name} |
| 69 | \lineii{'SystemAsterisk'} {Asterisk} |
| 70 | \lineii{'SystemExclamation'}{Exclamation} |
| 71 | \lineii{'SystemExit'} {Exit Windows} |
| 72 | \lineii{'SystemHand'} {Critical Stop} |
| 73 | \lineii{'SystemQuestion'} {Question} |
| 74 | \end{tableii} |
Tim Peters | e79af27 | 2001-02-20 10:02:21 +0000 | [diff] [blame] | 75 | |
Fred Drake | afdc8fc | 2001-02-23 19:10:41 +0000 | [diff] [blame] | 76 | For example: |
Tim Peters | e79af27 | 2001-02-20 10:02:21 +0000 | [diff] [blame] | 77 | |
Fred Drake | afdc8fc | 2001-02-23 19:10:41 +0000 | [diff] [blame] | 78 | \begin{verbatim} |
| 79 | import winsound |
| 80 | # Play Windows exit sound. |
| 81 | winsound.PlaySound("SystemExit", winsound.SND_ALIAS) |
Tim Peters | e79af27 | 2001-02-20 10:02:21 +0000 | [diff] [blame] | 82 | |
Fred Drake | afdc8fc | 2001-02-23 19:10:41 +0000 | [diff] [blame] | 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 | \end{verbatim} |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 87 | \end{datadesc} |
| 88 | |
| 89 | \begin{datadesc}{SND_LOOP} |
| 90 | Play the sound repeatedly. The \constant{SND_ASYNC} flag must also |
Tim Peters | e79af27 | 2001-02-20 10:02:21 +0000 | [diff] [blame] | 91 | be used to avoid blocking. Cannot be used with \constant{SND_MEMORY}. |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 92 | \end{datadesc} |
| 93 | |
| 94 | \begin{datadesc}{SND_MEMORY} |
| 95 | The \var{sound} parameter to \function{PlaySound()} is a memory |
Tim Peters | e79af27 | 2001-02-20 10:02:21 +0000 | [diff] [blame] | 96 | image of a WAV file, as a string. |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 97 | |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 98 | \note{This module does not support playing from a memory |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 99 | image asynchronously, so a combination of this flag and |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 100 | \constant{SND_ASYNC} will raise \exception{RuntimeError}.} |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 101 | \end{datadesc} |
| 102 | |
| 103 | \begin{datadesc}{SND_PURGE} |
| 104 | Stop playing all instances of the specified sound. |
| 105 | \end{datadesc} |
| 106 | |
| 107 | \begin{datadesc}{SND_ASYNC} |
| 108 | Return immediately, allowing sounds to play asynchronously. |
| 109 | \end{datadesc} |
| 110 | |
| 111 | \begin{datadesc}{SND_NODEFAULT} |
Tim Peters | e79af27 | 2001-02-20 10:02:21 +0000 | [diff] [blame] | 112 | If the specified sound cannot be found, do not play the system default |
| 113 | sound. |
Fred Drake | c7b72db | 1999-02-16 19:18:38 +0000 | [diff] [blame] | 114 | \end{datadesc} |
| 115 | |
| 116 | \begin{datadesc}{SND_NOSTOP} |
| 117 | Do not interrupt sounds currently playing. |
| 118 | \end{datadesc} |
| 119 | |
| 120 | \begin{datadesc}{SND_NOWAIT} |
| 121 | Return immediately if the sound driver is busy. |
| 122 | \end{datadesc} |
Guido van Rossum | 8f512a2 | 2003-05-16 01:42:22 +0000 | [diff] [blame] | 123 | |
| 124 | \begin{datadesc}{MB_ICONASTERISK} |
| 125 | Play the \code{SystemDefault} sound. |
| 126 | \end{datadesc} |
| 127 | |
| 128 | \begin{datadesc}{MB_ICONEXCLAMATION} |
| 129 | Play the \code{SystemExclamation} sound. |
| 130 | \end{datadesc} |
| 131 | |
| 132 | \begin{datadesc}{MB_ICONHAND} |
| 133 | Play the \code{SystemHand} sound. |
| 134 | \end{datadesc} |
| 135 | |
| 136 | \begin{datadesc}{MB_ICONQUESTION} |
| 137 | Play the \code{SystemQuestion} sound. |
| 138 | \end{datadesc} |
| 139 | |
| 140 | \begin{datadesc}{MB_OK} |
| 141 | Play the \code{SystemDefault} sound. |
| 142 | \end{datadesc} |