chrome.audio

refresh date: 2026-09-25 robots: noindex

說明

chrome.audio API 可讓使用者取得系統連接的音訊裝置相關資訊，並控制這些裝置。這個 API 目前僅適用於 ChromeOS 的 Kiosk 模式。

權限

audio

可用性

Chrome 59 以上版本 僅適用於 ChromeOS

類型

AudioDeviceInfo

屬性

  • deviceName

    字串

    裝置名稱。

  • deviceType

    DeviceType

    裝置的類型。

  • displayName

    字串

    容易使用的名稱 (例如「USB 麥克風」)。

  • id

    字串

    音訊裝置的專屬 ID。

  • isActive

    布林值

    如果這是目前使用中的裝置，則為 True。

  • 等級

    數字

    裝置的音量、輸出音量、輸入增益。

  • stableDeviceId

    字串 選填

    穩定的/永久的裝置 ID 字串 (如有)。

  • streamType

    StreamType

    與這部裝置相關聯的串流類型。

DeviceFilter

屬性

  • isActive

    布林值 選填

    如果設定，只有啟用狀態與這個值相符的音訊裝置，才符合篩選條件。

  • streamTypes

    StreamType[] 選用

    如果設定這項屬性，只有串流類型包含在這份清單中的音訊裝置，才符合篩選條件。

DeviceIdLists

屬性

  • 輸入

    string[] 選填

    依 ID 指定的輸入裝置清單。

    如要表示輸入裝置不應受到影響，請勿設定這個屬性。

  • 輸出

    string[] 選填

    輸出裝置清單 (依 ID 指定)。

    如要表示輸出裝置不應受到影響，請勿設定這個屬性。

DeviceProperties

屬性

  • 等級

    數字 選填

    音訊裝置的目標音量。預設為裝置目前的音量。

    如果與音訊輸入裝置搭配使用，則代表音訊裝置增益。

    如果與音訊輸出裝置搭配使用，則代表音訊裝置音量。

DeviceType

可用的音訊裝置類型。

列舉

"HEADPHONE"

"MIC"

「USB」

「藍牙」

「HDMI」

"INTERNAL_SPEAKER"

"INTERNAL_MIC"

"FRONT_MIC"

"REAR_MIC"

"KEYBOARD_MIC"

"HOTWORD"

"LINEOUT"

"POST_MIX_LOOPBACK"

"POST_DSP_LOOPBACK"

"ALSA_LOOPBACK"

"OTHER"

LevelChangedEvent

屬性

  • deviceId

    字串

    音量已變更的裝置 ID。

  • 等級

    數字

    裝置的新音量。

MuteChangedEvent

屬性

  • isMuted

    布林值

    串流是否已靜音。

  • streamType

    StreamType

    靜音值變更的串流類型。更新後的靜音值會套用至所有使用此串流類型的裝置。

StreamType

音訊裝置提供的串流類型。

列舉

"INPUT"

"OUTPUT"

方法

getDevices()

Promise 
chrome.audio.getDevices(
  filter?: DeviceFilter,
  callback?: function,
): Promise<AudioDeviceInfo[]>

取得根據 filter 篩選的音訊裝置清單。

參數

  • 篩選器

    DeviceFilter 選填

    用於篩選傳回音訊裝置清單的裝置屬性。如果未設定篩選器或設為 {}，傳回的裝置清單會包含所有可用的音訊裝置。

  • callback

    函式 選填

    callback 參數如下： 

    (devices: AudioDeviceInfo[]) => void

傳回

  • Promise<AudioDeviceInfo[]>

    Chrome 116 以上版本

    回報要求的音訊裝置清單。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getMute()

Promise 
chrome.audio.getMute(
  streamType: StreamType,
  callback?: function,
): Promise<boolean>

取得指定串流類型的全系統靜音狀態。

參數

  • streamType

    StreamType

    要擷取靜音狀態的串流類型。

  • callback

    函式 選填

    callback 參數如下： 

    (value: boolean) => void

    • 值

      布林值

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    Promise 會解析為布林值，指出是否已為指定串流類型設定靜音。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setActiveDevices()

Promise 
chrome.audio.setActiveDevices(
  ids: DeviceIdLists,
  callback?: function,
): Promise<void>

設定使用中的輸入和/或輸出裝置清單。

參數

  • 指定應啟用的裝置 ID。如果未設定輸入或輸出清單，該類別中的裝置就不會受到影響。

    如果傳入不存在的裝置 ID，系統會顯示錯誤。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setMute()

Promise 
chrome.audio.setMute(
  streamType: StreamType,
  isMuted: boolean,
  callback?: function,
): Promise<void>

設定串流類型的靜音狀態。靜音狀態會套用至所有具有指定音訊串流類型的音訊裝置。

參數

  • streamType

    StreamType

    要設定靜音狀態的串流類型。

  • isMuted

    布林值

    新的靜音值。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setProperties()

Promise 
chrome.audio.setProperties(
  id: string,
  properties: DeviceProperties,
  callback?: function,
): Promise<void>

設定輸入或輸出裝置的屬性。

參數

  • id

    字串

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

事件

onDeviceListChanged

chrome.audio.onDeviceListChanged.addListener(
  callback: function,
)

音訊裝置變更時 (新增裝置或移除現有裝置) 觸發。

參數

onLevelChanged

chrome.audio.onLevelChanged.addListener(
  callback: function,
)

當使用中音訊裝置的音量變更時，系統會觸發這個事件。

參數

onMuteChanged

chrome.audio.onMuteChanged.addListener(
  callback: function,
)

音訊輸入或輸出靜音狀態變更時觸發。請注意，靜音狀態會套用至整個系統，新值會套用至具有指定串流類型的每個音訊裝置。

參數