/Doc/library/winsound.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 160 lines · 92 code · 68 blank · 0 comment · 0 complexity · 39ef0c5b4591edca9879368d901304c4 MD5 · raw file

  1. :mod:`winsound` --- Sound-playing interface for Windows
  2. =======================================================
  3. .. module:: winsound
  4. :platform: Windows
  5. :synopsis: Access to the sound-playing machinery for Windows.
  6. .. moduleauthor:: Toby Dickenson <htrd90@zepler.org>
  7. .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
  8. .. versionadded:: 1.5.2
  9. The :mod:`winsound` module provides access to the basic sound-playing machinery
  10. provided by Windows platforms. It includes functions and several constants.
  11. .. function:: Beep(frequency, duration)
  12. Beep the PC's speaker. The *frequency* parameter specifies frequency, in hertz,
  13. of the sound, and must be in the range 37 through 32,767. The *duration*
  14. parameter specifies the number of milliseconds the sound should last. If the
  15. system is not able to beep the speaker, :exc:`RuntimeError` is raised.
  16. .. versionadded:: 1.6
  17. .. function:: PlaySound(sound, flags)
  18. Call the underlying :cfunc:`PlaySound` function from the Platform API. The
  19. *sound* parameter may be a filename, audio data as a string, or ``None``. Its
  20. interpretation depends on the value of *flags*, which can be a bitwise ORed
  21. combination of the constants described below. If the *sound* parameter is
  22. ``None``, any currently playing waveform sound is stopped. If the system
  23. indicates an error, :exc:`RuntimeError` is raised.
  24. .. function:: MessageBeep([type=MB_OK])
  25. Call the underlying :cfunc:`MessageBeep` function from the Platform API. This
  26. plays a sound as specified in the registry. The *type* argument specifies which
  27. sound to play; possible values are ``-1``, ``MB_ICONASTERISK``,
  28. ``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all
  29. described below. The value ``-1`` produces a "simple beep"; this is the final
  30. fallback if a sound cannot be played otherwise.
  31. .. versionadded:: 2.3
  32. .. data:: SND_FILENAME
  33. The *sound* parameter is the name of a WAV file. Do not use with
  34. :const:`SND_ALIAS`.
  35. .. data:: SND_ALIAS
  36. The *sound* parameter is a sound association name from the registry. If the
  37. registry contains no such name, play the system default sound unless
  38. :const:`SND_NODEFAULT` is also specified. If no default sound is registered,
  39. raise :exc:`RuntimeError`. Do not use with :const:`SND_FILENAME`.
  40. All Win32 systems support at least the following; most systems support many
  41. more:
  42. +--------------------------+----------------------------------------+
  43. | :func:`PlaySound` *name* | Corresponding Control Panel Sound name |
  44. +==========================+========================================+
  45. | ``'SystemAsterisk'`` | Asterisk |
  46. +--------------------------+----------------------------------------+
  47. | ``'SystemExclamation'`` | Exclamation |
  48. +--------------------------+----------------------------------------+
  49. | ``'SystemExit'`` | Exit Windows |
  50. +--------------------------+----------------------------------------+
  51. | ``'SystemHand'`` | Critical Stop |
  52. +--------------------------+----------------------------------------+
  53. | ``'SystemQuestion'`` | Question |
  54. +--------------------------+----------------------------------------+
  55. For example::
  56. import winsound
  57. # Play Windows exit sound.
  58. winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
  59. # Probably play Windows default sound, if any is registered (because
  60. # "*" probably isn't the registered name of any sound).
  61. winsound.PlaySound("*", winsound.SND_ALIAS)
  62. .. data:: SND_LOOP
  63. Play the sound repeatedly. The :const:`SND_ASYNC` flag must also be used to
  64. avoid blocking. Cannot be used with :const:`SND_MEMORY`.
  65. .. data:: SND_MEMORY
  66. The *sound* parameter to :func:`PlaySound` is a memory image of a WAV file, as a
  67. string.
  68. .. note::
  69. This module does not support playing from a memory image asynchronously, so a
  70. combination of this flag and :const:`SND_ASYNC` will raise :exc:`RuntimeError`.
  71. .. data:: SND_PURGE
  72. Stop playing all instances of the specified sound.
  73. .. note::
  74. This flag is not supported on modern Windows platforms.
  75. .. data:: SND_ASYNC
  76. Return immediately, allowing sounds to play asynchronously.
  77. .. data:: SND_NODEFAULT
  78. If the specified sound cannot be found, do not play the system default sound.
  79. .. data:: SND_NOSTOP
  80. Do not interrupt sounds currently playing.
  81. .. data:: SND_NOWAIT
  82. Return immediately if the sound driver is busy.
  83. .. data:: MB_ICONASTERISK
  84. Play the ``SystemDefault`` sound.
  85. .. data:: MB_ICONEXCLAMATION
  86. Play the ``SystemExclamation`` sound.
  87. .. data:: MB_ICONHAND
  88. Play the ``SystemHand`` sound.
  89. .. data:: MB_ICONQUESTION
  90. Play the ``SystemQuestion`` sound.
  91. .. data:: MB_OK
  92. Play the ``SystemDefault`` sound.