"winsound" --- Windows 的音效播放介面
*************************************

**Source code:** PC/winsound.c

======================================================================

"winsound" 模組提供存取 Windows 平台所提供的基本音效播放機制。它包含數
個函式與常數。

可用性: Windows.


Functions
=========

winsound.Beep(frequency, duration)

   讓電腦的喇叭發出嗶聲。*frequency* 參數指定音效的頻率（以赫茲為單位
   ），範圍必須介於 37 到 32,767 之間。*duration* 參數指定音效持續的時
   間（以毫秒為單位）。若系統無法讓喇叭發出嗶聲，則會引發
   "RuntimeError"。

winsound.PlaySound(sound, flags)

   呼叫平台 API 中底層的 "PlaySound()" 函式。*sound* 參數可以是檔案名
   稱、系統音效別名、作為 *bytes-like object* 的音訊資料，或 "None"。
   其直譯方式取決於 *flags* 的值，該值可以是以下所述常數的位元 OR 組合
   。若 *sound* 為 "None"，則會停止任何正在播放的波形音效。若系統回報
   錯誤，則會引發 "RuntimeError"。

winsound.MessageBeep(type=MB_OK)

   呼叫平台 API 中底層的 "MessageBeep()" 函式。此函式會播放登錄檔中指
   定的音效。*type* 引數指定要播放的音效類型，可接受的值包括 "-1"、
   "MB_ICONASTERISK"、"MB_ICONEXCLAMATION"、"MB_ICONHAND"、
   "MB_ICONQUESTION" 與 "MB_OK"，這些皆會在下文中說明。數值 "-1" 會產
   生「簡單嗶聲」，當無法播放其他音效時即作為最終退路。若系統回報錯誤
   ，則會引發 "RuntimeError"。


Constants
=========

winsound.SND_FILENAME

   *sound* 參數為 WAV 檔案名稱。請勿與 "SND_ALIAS" 同時使用。

winsound.SND_ALIAS

   *sound* 參數為登錄檔中的音效關聯名稱。若登錄檔中找不到此名稱，則會
   播放系統預設音效，除非同時指定了 "SND_NODEFAULT"。若沒有註冊預設音
   效，則會引發 "RuntimeError"。請勿與 "SND_FILENAME" 同時使用。

   所有 Win32 系統至少支援以下項目；大多數系統支援更多：

   +----------------------------+------------------------------------------+
   | "PlaySound()" *name*       | 對應的控制台音效名稱                     |
   |============================|==========================================|
   | "'SystemAsterisk'"         | 星號                                     |
   +----------------------------+------------------------------------------+
   | "'SystemExclamation'"      | 驚嘆號                                   |
   +----------------------------+------------------------------------------+
   | "'SystemExit'"             | 離開 Windows                             |
   +----------------------------+------------------------------------------+
   | "'SystemHand'"             | 關鍵性停止                               |
   +----------------------------+------------------------------------------+
   | "'SystemQuestion'"         | 問題                                     |
   +----------------------------+------------------------------------------+

   例如說：

      import winsound
      # 播放 Windows 的離開音效。
      winsound.PlaySound("SystemExit", winsound.SND_ALIAS)

      # 若有註冊預設音效，可能會播放該音效
      # （因為 "*" 可能不是任何音效的註冊名稱）。
      winsound.PlaySound("*", winsound.SND_ALIAS)

winsound.SND_LOOP

   重複播放音效。必須同時使用 "SND_ASYNC" 旗標以避免阻塞。不能與
   "SND_MEMORY" 一同使用。

winsound.SND_MEMORY

   傳入 "PlaySound()" 的 *sound* 參數是 WAV 檔案的記憶體映像，型別為
   *bytes-like object*。

   備註:

     此模組不支援從記憶體映像非同步播放音效，因此若同時使用本旗標與
     "SND_ASYNC"，將引發 "RuntimeError"。

winsound.SND_PURGE

   停止播放指定音效的所有實例。

   備註:

     此旗標在現代 Windows 平台上不支援。

winsound.SND_ASYNC

   立即回傳，使音效可非同步播放。

winsound.SND_NODEFAULT

   若找不到指定的音效，則不播放系統預設音效。

winsound.SND_NOSTOP

   不中斷目前正在播放的音效。

winsound.SND_NOWAIT

   若音效驅動程式正在忙碌，則立即回傳此。

   備註:

     此旗標在現代 Windows 平台上不支援。

winsound.SND_APPLICATION

   *sound* 參數為登錄檔中的應用程式特定別名。此旗標可與 "SND_ALIAS" 一
   同使用，以指定應用程式自訂的音效別名。

winsound.SND_SENTRY

   當音效被播放時，會觸發 SoundSentry 事件。

   在 3.14 版被加入.

winsound.SND_SYNC

   音效會同步播放。這是預設行為。

   在 3.14 版被加入.

winsound.SND_SYSTEM

   將音效指派給系統通知音效的音訊工作階段 (audio session)。

   在 3.14 版被加入.

winsound.MB_ICONASTERISK

   播放 "SystemDefault" 音效。

winsound.MB_ICONEXCLAMATION

   播放 "SystemExclamation" 音效。

winsound.MB_ICONHAND

   播放 "SystemHand" 音效。

winsound.MB_ICONQUESTION

   播放 "SystemQuestion" 音效。

winsound.MB_OK

   播放 "SystemDefault" 音效。

winsound.MB_ICONERROR

   播放 "SystemHand" 音效。

   在 3.14 版被加入.

winsound.MB_ICONINFORMATION

   播放 "SystemDefault" 音效。

   在 3.14 版被加入.

winsound.MB_ICONSTOP

   播放 "SystemHand" 音效。

   在 3.14 版被加入.

winsound.MB_ICONWARNING

   播放 "SystemExclamation" 音效。

   在 3.14 版被加入.
