chrome.audio

說明

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

權限

audio

可用性

Chrome 59 以上版本 (僅限 ChromeOS)

類型

AudioDeviceInfo

屬性

  • deviceName

    字串

    裝置名稱。

  • deviceType

    DeviceType

    裝置的類型。

  • displayName

    字串

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

  • id

    字串

    音訊裝置的專屬 ID。

  • isActive

    布林值

    如果是目前的活動裝置，則為「是」。

  • level

    數字

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

  • stableDeviceId

    string 選填

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

  • streamType

    StreamType

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

DeviceFilter

屬性

  • isActive

    boolean 選填

    如果已設值，則只有活動狀態符合此值的音訊裝置才會符合篩選器。

  • streamTypes

    StreamType[] 選填

    如果已設，只有串流類型列在此清單中的音訊裝置才符合篩選條件。

DeviceIdLists

屬性

  • 輸入

    string[] 選填

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

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

  • output

    string[] 選填

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

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

DeviceProperties

屬性

  • level

    號碼 選填

    音訊裝置的理想音量。預設為裝置目前的音量等級。

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

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

DeviceType

可用的音訊裝置類型。

列舉

"HEADPHONE"

"MIC"

"USB"

"BLUETOOTH"

"HDMI"

"INTERNAL_SPEAKER"

"INTERNAL_MIC"

"FRONT_MIC"

"REAR_MIC"

"KEYBOARD_MIC"

"HOTWORD"

"LINEOUT"

"POST_MIX_LOOPBACK"

"POST_DSP_LOOPBACK"

"ALSA_LOOPBACK"

「其他」

LevelChangedEvent

屬性

  • deviceId

    字串

    音量層級已變更的裝置 ID。

  • level

    數字

    裝置的新音量。

MuteChangedEvent

屬性

  • isMuted

    布林值

    直播目前是否已設為靜音。

  • streamType

    StreamType

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

StreamType

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

列舉

"INPUT"

"OUTPUT"

方法

getDevices()

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

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

參數

  • 篩選器

    DeviceFilter 選填

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (devices: AudioDeviceInfo[]) => void

傳回

  • Promise<AudioDeviceInfo[]>

    Chrome 116 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getMute()

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

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

參數

  • streamType

    StreamType

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (value: boolean) => void

    • 值

      布林值

傳回

  • Promise<boolean>

    Chrome 116 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setActiveDevices()

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

設定有效輸入和/或輸出裝置的清單。

參數

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

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 116 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setMute()

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

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

參數

  • streamType

    StreamType

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

  • isMuted

    布林值

    新的靜音值。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 116 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setProperties()

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

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

參數

  • id

    字串

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 116 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onDeviceListChanged

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

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

參數

onLevelChanged

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

當音量變化時，系統會觸發此事件，以便在使用中的音訊裝置上播放音訊。

參數

onMuteChanged

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

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

參數