chrome.audio

說明

使用者可以利用 chrome.audio API 取得及控制系統連接的音訊裝置相關資訊。這個 API 目前只能在 ChromeOS 的 Kiosk 模式中使用。

權限

audio

可用性

Chrome 59 以上版本 僅適用於 ChromeOS

類型

AudioDeviceInfo

屬性

  • deviceName

    字串

    裝置名稱。

  • deviceType

    DeviceType

    裝置的類型。

  • displayName

    字串

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

  • id

    字串

    音訊裝置的專屬 ID。

  • isActive

    布林值

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

  • level

    數字

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

  • stableDeviceId

    string optional

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

  • streamType

    StreamType

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

DeviceFilter

屬性

  • isActive

    布林值 選填

    如果設定這項政策，只有使用中狀態與這個值相符的音訊裝置符合篩選器條件。

  • streamTypes

    StreamType[] 選用

    如果設定這項政策，這份清單中僅包含串流類型的音訊裝置會符合篩選器條件。

DeviceIdLists

屬性

  • 輸入

    string[] 選填

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

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

  • output

    string[] 選填

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

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

DeviceProperties

屬性

  • level

    編號 選填

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

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

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

DeviceType

可用的音訊裝置類型。

列舉

"HEADPHONE"

「MIC」

「USB」

「藍牙」

「HDMI」

「INTERNAL_SPEAKER」

「INTERNAL_MIC」

"FRONT_MIC"

「REAR_MIC」

"KEYBOARD_MIC"

「HOTWORD」

「首選頻道」

「POST_MIX_LOOPBACK」

"POST_DSP_LOOPBACK"

"ALSA_LOOPBACK"

「OTHER」

LevelChangedEvent

屬性

  • deviceId

    字串

    音量改變的裝置 ID。

  • level

    數字

    裝置的新音量大小。

MuteChangedEvent

屬性

  • isMuted

    布林值

    是否將直播設為靜音。

  • streamType

    StreamType

    靜音值變更的串流類型。新的靜音值會套用至所有具備這個串流類型的裝置。

StreamType

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

列舉

"INPUT"

「輸出內容」

方法

getDevices()

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

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

參數

  • 篩選器

    DeviceFilter 選用

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (devices: AudioDeviceInfo[]) => void

傳回

  • Promise<AudioDeviceInfo[]>

    Chrome 116 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getMute()

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

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

參數

  • streamType

    StreamType

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (value: boolean) => void

    • 值

      布林值

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setActiveDevices()

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

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

參數

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

    如果傳入不存在的裝置 ID，會發生錯誤。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setMute()

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

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

參數

  • streamType

    StreamType

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

  • isMuted

    布林值

    新的靜音值。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 116 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setProperties()

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

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

參數

  • id

    字串

  • 資源

    裝置屬性

  • 回呼

    函式 選用

    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,
)

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

參數