chrome.audio

說明

使用者可利用 chrome.audio API，取得及控制連接至系統的音訊裝置。這個 API 目前僅適用於 ChromeOS 的 Kiosk 模式。

權限

audio

適用國家/地區

Chrome 59 以上版本 僅限 ChromeOS

類型

AudioDeviceInfo

屬性

  • deviceName

    字串

    裝置名稱。

  • deviceType

    DeviceType

    裝置的類型。

  • displayName

    字串

    易記的名稱 (例如「USB 麥克風」)。

  • id

    字串

    音訊裝置的專屬 ID。

  • isActive

    boolean

    如果這是目前使用的裝置，則為「是」。

  • level

    號碼

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

  • stableDeviceId

    字串 選用

    穩定版/持續性裝置 ID 字串 (如有)。

  • streamType

    StreamType

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

DeviceFilter

屬性

  • isActive

    布林值 (選用)

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

  • streamTypes

    StreamType[] 選用

    設定之後，只有列於這份清單類型的音訊裝置才符合篩選條件。

DeviceIdLists

屬性

  • 輸入

    string[] 選填

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

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

  • output

    string[] 選填

    按 ID 指定的輸出裝置清單。

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

DeviceProperties

屬性

  • level

    數字 選填

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

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

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

DeviceType

可用的音訊裝置類型。

列舉

"KEYBOARD_MIC"

"POST_DSP_LOOPBACK"

LevelChangedEvent

屬性

  • deviceId

    字串

    變更音效的裝置 ID。

  • level

    號碼

    裝置的新音量。

MuteChangedEvent

屬性

  • isMuted

    boolean

    串流目前是否設為靜音。

  • streamType

    StreamType

    忽略值變更的串流類型。更新後的忽略值會套用至這個串流類型的所有裝置。

StreamType

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

列舉

方法

getDevices()

Promise 
chrome.audio.getDevices(
  filter?: DeviceFilter,
  callback?: function,
)

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

參數

  • 過濾器

    DeviceFilter (選用)

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    (devices: AudioDeviceInfo[])=>void

傳回

  • Promise<AudioDeviceInfo[]>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getMute()

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

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

參數

  • streamType

    StreamType

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    (value: boolean)=>void

    • 值

      boolean

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setActiveDevices()

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

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

參數

  • 指定應使用的裝置 ID。如果未設定輸入或輸出清單，則屬於這個類別的裝置不會受到影響。

    必須傳遞不存在的裝置 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setMute()

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

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

參數

  • streamType

    StreamType

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

  • isMuted

    boolean

    新增忽略值。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setProperties()

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

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

參數

  • id

    字串

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 116 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onDeviceListChanged

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

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

參數

onLevelChanged

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

使用中音訊裝置的音量改變時觸發。

參數

onMuteChanged

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

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

參數