cpython/Doc/library/winsound.rst

154 lines
4.8 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
:mod:`winsound` --- Sound-playing interface for Windows
=======================================================
.. module:: winsound
:platform: Windows
:synopsis: Access to the sound-playing machinery for Windows.
.. moduleauthor:: Toby Dickenson <htrd90@zepler.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The :mod:`winsound` module provides access to the basic sound-playing machinery
provided by Windows platforms. It includes functions and several constants.
.. function:: Beep(frequency, duration)
Beep the PC's speaker. The *frequency* parameter specifies frequency, in hertz,
of the sound, and must be in the range 37 through 32,767. The *duration*
parameter specifies the number of milliseconds the sound should last. If the
system is not able to beep the speaker, :exc:`RuntimeError` is raised.
.. function:: PlaySound(sound, flags)
Call the underlying :c:func:`PlaySound` function from the Platform API. The
2007-08-15 11:28:22 -03:00
*sound* parameter may be a filename, audio data as a string, or ``None``. Its
Merged revisions 59703-59773 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59704 | christian.heimes | 2008-01-04 04:15:05 +0100 (Fri, 04 Jan 2008) | 1 line Moved include "Python.h" in front of other imports to silence a warning. ........ r59706 | raymond.hettinger | 2008-01-04 04:22:53 +0100 (Fri, 04 Jan 2008) | 10 lines Minor fix-ups to named tuples: * Make the _replace() method respect subclassing. * Using property() to make _fields read-only wasn't a good idea. It caused len(Point._fields) to fail. * Add note to _cast() about length checking and alternative with the star-operator. ........ r59707 | jeffrey.yasskin | 2008-01-04 09:01:23 +0100 (Fri, 04 Jan 2008) | 3 lines Make math.{floor,ceil}({int,long}) return float again for backwards compatibility after r59671 made them return integral types. ........ r59709 | christian.heimes | 2008-01-04 14:21:07 +0100 (Fri, 04 Jan 2008) | 1 line Bug #1713: posixpath.ismount() claims symlink to a mountpoint is a mountpoint. ........ r59712 | lars.gustaebel | 2008-01-04 15:00:33 +0100 (Fri, 04 Jan 2008) | 5 lines Issue #1735: TarFile.extractall() now correctly sets directory permissions and times. (will backport to 2.5) ........ r59714 | andrew.kuchling | 2008-01-04 15:47:17 +0100 (Fri, 04 Jan 2008) | 1 line Update links to bug/patch tracker ........ r59716 | christian.heimes | 2008-01-04 16:23:30 +0100 (Fri, 04 Jan 2008) | 1 line Added interface to Windows' WSAIoctl and a simple example for a network sniffer. ........ r59717 | christian.heimes | 2008-01-04 16:29:00 +0100 (Fri, 04 Jan 2008) | 1 line And here is the rest of Hirokazu Yamamoto's patch for VS6.0 support. Thanks Hiro! ........ r59719 | christian.heimes | 2008-01-04 16:34:06 +0100 (Fri, 04 Jan 2008) | 1 line Reverted last transaction. It's the wrong branch. ........ r59721 | christian.heimes | 2008-01-04 16:48:06 +0100 (Fri, 04 Jan 2008) | 1 line socket.ioctl is only available on Windows ........ r59722 | andrew.kuchling | 2008-01-04 19:24:41 +0100 (Fri, 04 Jan 2008) | 1 line Fix markup ........ r59723 | andrew.kuchling | 2008-01-04 19:25:05 +0100 (Fri, 04 Jan 2008) | 1 line Fix markup ........ r59725 | guido.van.rossum | 2008-01-05 01:59:59 +0100 (Sat, 05 Jan 2008) | 3 lines Patch #1725 by Mark Dickinson, fixes incorrect conversion of -1e1000 and adds errors for -0x. ........ r59726 | guido.van.rossum | 2008-01-05 02:21:57 +0100 (Sat, 05 Jan 2008) | 2 lines Patch #1698 by Senthil: allow '@' in username when parsed by urlparse.py. ........ r59727 | raymond.hettinger | 2008-01-05 02:35:43 +0100 (Sat, 05 Jan 2008) | 1 line Improve namedtuple's _cast() method with a docstring, new name, and error-checking. ........ r59728 | raymond.hettinger | 2008-01-05 03:17:24 +0100 (Sat, 05 Jan 2008) | 1 line Add error-checking to namedtuple's _replace() method. ........ r59730 | fred.drake | 2008-01-05 05:38:38 +0100 (Sat, 05 Jan 2008) | 2 lines clean up a comment ........ r59731 | jeffrey.yasskin | 2008-01-05 09:47:13 +0100 (Sat, 05 Jan 2008) | 11 lines Continue rolling back pep-3141 changes that changed behavior from 2.5. This round included: * Revert round to its 2.6 behavior (half away from 0). * Because round, floor, and ceil always return float again, it's no longer necessary to have them delegate to __xxx___, so I've ripped that out of their implementations and the Real ABC. This also helps in implementing types that work in both 2.6 and 3.0: you return int from the __xxx__ methods, and let it get enabled by the version upgrade. * Make pow(-1, .5) raise a ValueError again. ........ r59736 | andrew.kuchling | 2008-01-05 16:13:49 +0100 (Sat, 05 Jan 2008) | 1 line Fix comment typo ........ r59738 | thomas.heller | 2008-01-05 18:15:44 +0100 (Sat, 05 Jan 2008) | 1 line Add myself. ........ r59739 | georg.brandl | 2008-01-05 18:49:17 +0100 (Sat, 05 Jan 2008) | 2 lines Fix C++-style comment. ........ r59742 | georg.brandl | 2008-01-05 20:28:16 +0100 (Sat, 05 Jan 2008) | 2 lines Remove with_statement future imports from 2.6 docs. ........ r59743 | georg.brandl | 2008-01-05 20:29:45 +0100 (Sat, 05 Jan 2008) | 2 lines Simplify index entries; fix #1712. ........ r59744 | georg.brandl | 2008-01-05 20:44:22 +0100 (Sat, 05 Jan 2008) | 2 lines Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. ........ r59749 | georg.brandl | 2008-01-05 21:29:13 +0100 (Sat, 05 Jan 2008) | 2 lines Revert socket.rst to unix-eol. ........ r59750 | georg.brandl | 2008-01-05 21:33:46 +0100 (Sat, 05 Jan 2008) | 2 lines Set native svn:eol-style property for text files. ........ r59752 | georg.brandl | 2008-01-05 21:46:29 +0100 (Sat, 05 Jan 2008) | 2 lines #1719: capitalization error in "UuidCreate". ........ r59753 | georg.brandl | 2008-01-05 22:02:25 +0100 (Sat, 05 Jan 2008) | 2 lines Repair markup. ........ r59754 | georg.brandl | 2008-01-05 22:10:50 +0100 (Sat, 05 Jan 2008) | 2 lines Use markup. ........ r59757 | christian.heimes | 2008-01-05 22:35:52 +0100 (Sat, 05 Jan 2008) | 1 line Final adjustments for #1601 ........ r59758 | guido.van.rossum | 2008-01-05 23:19:06 +0100 (Sat, 05 Jan 2008) | 3 lines Patch #1637: fix urlparse for URLs like 'http://x.com?arg=/foo'. Fix by John Nagle. ........ r59759 | guido.van.rossum | 2008-01-05 23:20:01 +0100 (Sat, 05 Jan 2008) | 2 lines Add John Nagle (of issue #1637). ........ r59765 | raymond.hettinger | 2008-01-06 10:02:24 +0100 (Sun, 06 Jan 2008) | 1 line Small code simplification. Forgot that classmethods can be called from intances. ........ r59766 | martin.v.loewis | 2008-01-06 11:09:48 +0100 (Sun, 06 Jan 2008) | 2 lines Use vcbuild for VS 2009. ........ r59767 | martin.v.loewis | 2008-01-06 12:03:43 +0100 (Sun, 06 Jan 2008) | 2 lines Package using VS 2008. ........ r59768 | martin.v.loewis | 2008-01-06 12:13:16 +0100 (Sun, 06 Jan 2008) | 2 lines Don't try to package msvcr90 for the moment. ........ r59769 | georg.brandl | 2008-01-06 15:17:36 +0100 (Sun, 06 Jan 2008) | 4 lines #1696393: don't check for '.' and '..' in ntpath.walk since they aren't returned from os.listdir anymore. Reported by Michael Haggerty. ........ r59770 | georg.brandl | 2008-01-06 15:27:15 +0100 (Sun, 06 Jan 2008) | 3 lines #1742: don't raise exception on os.path.relpath("a", "a"), but return os.curdir. Reported by Jesse Towner. ........ r59771 | georg.brandl | 2008-01-06 15:33:52 +0100 (Sun, 06 Jan 2008) | 2 lines #1591: Clarify docstring of Popen3. ........ r59772 | georg.brandl | 2008-01-06 16:30:34 +0100 (Sun, 06 Jan 2008) | 2 lines #1680: fix context manager example function name. ........ r59773 | georg.brandl | 2008-01-06 16:34:57 +0100 (Sun, 06 Jan 2008) | 2 lines #1755097: document default values for [].sort() and sorted(). ........
2008-01-06 12:59:19 -04:00
interpretation depends on the value of *flags*, which can be a bitwise ORed
Merged revisions 67952,67957-67958,67960-67961,67963,67973,67978,67995,68030,68057,68061 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67952 | georg.brandl | 2008-12-27 11:42:40 -0600 (Sat, 27 Dec 2008) | 2 lines #4752: actually use custom handler in example. ........ r67957 | georg.brandl | 2008-12-27 12:49:19 -0600 (Sat, 27 Dec 2008) | 2 lines #4754: improve winsound documentation. ........ r67958 | georg.brandl | 2008-12-27 13:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines #4682: 'b' is actually unsigned char. ........ r67960 | georg.brandl | 2008-12-27 13:04:44 -0600 (Sat, 27 Dec 2008) | 2 lines #4695: fix backslashery. ........ r67961 | georg.brandl | 2008-12-27 13:06:04 -0600 (Sat, 27 Dec 2008) | 2 lines Use :samp: role. ........ r67963 | georg.brandl | 2008-12-27 13:11:15 -0600 (Sat, 27 Dec 2008) | 2 lines #4671: document that pydoc imports modules. ........ r67973 | alexandre.vassalotti | 2008-12-27 20:58:22 -0600 (Sat, 27 Dec 2008) | 2 lines Document Py_VaBuildValue. ........ r67978 | georg.brandl | 2008-12-28 05:58:49 -0600 (Sun, 28 Dec 2008) | 2 lines #4731: clarify message about missing module prerequisites. ........ r67995 | benjamin.peterson | 2008-12-28 15:16:07 -0600 (Sun, 28 Dec 2008) | 1 line #4763 PyErr_ExceptionMatches won't blow up with NULL arguments ........ r68030 | benjamin.peterson | 2008-12-29 15:38:14 -0600 (Mon, 29 Dec 2008) | 1 line fix French ........ r68057 | vinay.sajip | 2008-12-30 01:01:25 -0600 (Tue, 30 Dec 2008) | 1 line Minor documentation change relating to NullHandler. ........ r68061 | georg.brandl | 2008-12-30 04:15:49 -0600 (Tue, 30 Dec 2008) | 2 lines #4778: attributes can't be called. ........
2008-12-31 20:23:30 -04:00
combination of the constants described below. If the *sound* parameter is
``None``, any currently playing waveform sound is stopped. If the system
indicates an error, :exc:`RuntimeError` is raised.
2007-08-15 11:28:22 -03:00
.. function:: MessageBeep(type=MB_OK)
2007-08-15 11:28:22 -03:00
Call the underlying :c:func:`MessageBeep` function from the Platform API. This
2007-08-15 11:28:22 -03:00
plays a sound as specified in the registry. The *type* argument specifies which
sound to play; possible values are ``-1``, ``MB_ICONASTERISK``,
``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all
described below. The value ``-1`` produces a "simple beep"; this is the final
fallback if a sound cannot be played otherwise.
.. data:: SND_FILENAME
The *sound* parameter is the name of a WAV file. Do not use with
:const:`SND_ALIAS`.
.. data:: SND_ALIAS
The *sound* parameter is a sound association name from the registry. If the
registry contains no such name, play the system default sound unless
:const:`SND_NODEFAULT` is also specified. If no default sound is registered,
raise :exc:`RuntimeError`. Do not use with :const:`SND_FILENAME`.
All Win32 systems support at least the following; most systems support many
more:
+--------------------------+----------------------------------------+
| :func:`PlaySound` *name* | Corresponding Control Panel Sound name |
+==========================+========================================+
| ``'SystemAsterisk'`` | Asterisk |
+--------------------------+----------------------------------------+
| ``'SystemExclamation'`` | Exclamation |
+--------------------------+----------------------------------------+
| ``'SystemExit'`` | Exit Windows |
+--------------------------+----------------------------------------+
| ``'SystemHand'`` | Critical Stop |
+--------------------------+----------------------------------------+
| ``'SystemQuestion'`` | Question |
+--------------------------+----------------------------------------+
For example::
import winsound
# Play Windows exit sound.
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
# Probably play Windows default sound, if any is registered (because
# "*" probably isn't the registered name of any sound).
winsound.PlaySound("*", winsound.SND_ALIAS)
.. data:: SND_LOOP
Play the sound repeatedly. The :const:`SND_ASYNC` flag must also be used to
avoid blocking. Cannot be used with :const:`SND_MEMORY`.
.. data:: SND_MEMORY
The *sound* parameter to :func:`PlaySound` is a memory image of a WAV file, as a
string.
.. note::
This module does not support playing from a memory image asynchronously, so a
combination of this flag and :const:`SND_ASYNC` will raise :exc:`RuntimeError`.
.. data:: SND_PURGE
Stop playing all instances of the specified sound.
Merged revisions 67952,67957-67958,67960-67961,67963,67973,67978,67995,68030,68057,68061 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67952 | georg.brandl | 2008-12-27 11:42:40 -0600 (Sat, 27 Dec 2008) | 2 lines #4752: actually use custom handler in example. ........ r67957 | georg.brandl | 2008-12-27 12:49:19 -0600 (Sat, 27 Dec 2008) | 2 lines #4754: improve winsound documentation. ........ r67958 | georg.brandl | 2008-12-27 13:02:59 -0600 (Sat, 27 Dec 2008) | 2 lines #4682: 'b' is actually unsigned char. ........ r67960 | georg.brandl | 2008-12-27 13:04:44 -0600 (Sat, 27 Dec 2008) | 2 lines #4695: fix backslashery. ........ r67961 | georg.brandl | 2008-12-27 13:06:04 -0600 (Sat, 27 Dec 2008) | 2 lines Use :samp: role. ........ r67963 | georg.brandl | 2008-12-27 13:11:15 -0600 (Sat, 27 Dec 2008) | 2 lines #4671: document that pydoc imports modules. ........ r67973 | alexandre.vassalotti | 2008-12-27 20:58:22 -0600 (Sat, 27 Dec 2008) | 2 lines Document Py_VaBuildValue. ........ r67978 | georg.brandl | 2008-12-28 05:58:49 -0600 (Sun, 28 Dec 2008) | 2 lines #4731: clarify message about missing module prerequisites. ........ r67995 | benjamin.peterson | 2008-12-28 15:16:07 -0600 (Sun, 28 Dec 2008) | 1 line #4763 PyErr_ExceptionMatches won't blow up with NULL arguments ........ r68030 | benjamin.peterson | 2008-12-29 15:38:14 -0600 (Mon, 29 Dec 2008) | 1 line fix French ........ r68057 | vinay.sajip | 2008-12-30 01:01:25 -0600 (Tue, 30 Dec 2008) | 1 line Minor documentation change relating to NullHandler. ........ r68061 | georg.brandl | 2008-12-30 04:15:49 -0600 (Tue, 30 Dec 2008) | 2 lines #4778: attributes can't be called. ........
2008-12-31 20:23:30 -04:00
.. note::
This flag is not supported on modern Windows platforms.
2007-08-15 11:28:22 -03:00
.. data:: SND_ASYNC
Return immediately, allowing sounds to play asynchronously.
.. data:: SND_NODEFAULT
If the specified sound cannot be found, do not play the system default sound.
.. data:: SND_NOSTOP
Do not interrupt sounds currently playing.
.. data:: SND_NOWAIT
Return immediately if the sound driver is busy.
.. data:: MB_ICONASTERISK
Play the ``SystemDefault`` sound.
.. data:: MB_ICONEXCLAMATION
Play the ``SystemExclamation`` sound.
.. data:: MB_ICONHAND
Play the ``SystemHand`` sound.
.. data:: MB_ICONQUESTION
Play the ``SystemQuestion`` sound.
.. data:: MB_OK
Play the ``SystemDefault`` sound.