# `winsound` --- Windows 的音效播放介面

Source code: PC/winsound.c

The `winsound` module provides access to the basic sound-playing machinery provided by Windows platforms. It includes functions and several constants.

可用性: 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 版被加入.