chrome.audio

Description: The chrome.audio API is provided to allow users to get information about and control the audio devices attached to the system. This API is currently only implemented for ChromeOS.
Availability: Since Chrome 59.
Permissions: "audio"

Summary

Types
StreamType
AudioDeviceInfo
DeviceIdLists
Methods
getDevices − chrome.audio.getDevices(object filter, function callback)
setActiveDevices − chrome.audio.setActiveDevices( DeviceIdLists or array of string ids, function callback)
setProperties − chrome.audio.setProperties(string id, object properties, function callback)
getMute − chrome.audio.getMute( StreamType streamType, function callback)
setMute − chrome.audio.setMute( StreamType streamType, boolean isMuted, function callback)
Events
onLevelChanged
onMuteChanged
onDeviceListChanged

Types

StreamType

Type of stream an audio device provides.
Enum
"INPUT", or "OUTPUT"

AudioDeviceInfo

properties
string id

The unique identifier of the audio device.

StreamType streamType

Stream type associated with this device.

enum of "HEADPHONE", "MIC", "USB", "BLUETOOTH", "HDMI", "INTERNAL_SPEAKER", "INTERNAL_MIC", "FRONT_MIC", "REAR_MIC", "KEYBOARD_MIC", "HOTWORD", "LINEOUT", "POST_MIX_LOOPBACK", "POST_DSP_LOOPBACK", or "OTHER" deviceType

Type of the device.

string displayName

The user-friendly name (e.g. "USB Microphone").

string deviceName

Device name.

boolean isActive

True if this is the current active device.

integer level

The sound level of the device, volume for output, gain for input.

string (optional) stableDeviceId

The stable/persisted device id string when available.

DeviceIdLists

properties
array of string (optional) input

List of input devices specified by their ID.

To indicate input devices should be unaffected, leave this property unset.
array of string (optional) output

List of output devices specified by their ID.

To indicate output devices should be unaffected, leave this property unset.

Methods

getDevices

chrome.audio.getDevices(object filter, function callback)

Gets a list of audio devices filtered based on |filter|.

Parameters
object (optional) filter

Device properties by which to filter the list of returned audio devices. If the filter is not set or set to {}, returned device list will contain all available audio devices.

array of StreamType (optional) streamTypes

If set, only audio devices whose stream type is included in this list will satisfy the filter.

boolean (optional) isActive

If set, only audio devices whose active state matches this value will satisfy the filter.

function callback

Reports the requested list of audio devices.

The callback parameter should be a function that looks like this:

function(array of AudioDeviceInfo devices) {...};
array of AudioDeviceInfo devices

setActiveDevices

chrome.audio.setActiveDevices( DeviceIdLists or array of string ids, function callback)

Sets lists of active input and/or output devices.

Parameters
DeviceIdLists or array of string ids

Specifies IDs of devices that should be active. If either the input or output list is not set, devices in that category are unaffected.

It is an error to pass in a non-existent device ID.

NOTE: While the method signature allows device IDs to be passed as a list of strings, this method of setting active devices is deprecated and should not be relied upon to work. Please use DeviceIdLists instead.

function callback

The callback parameter should be a function that looks like this:

function() {...};

setProperties

chrome.audio.setProperties(string id, object properties, function callback)

Sets the properties for the input or output device.

Parameters
string id
object properties
integer (optional) level

The audio device's desired sound level. Defaults to the device's current sound level.

If used with audio input device, represents audio device gain.

If used with audio output device, represents audio device volume.
function callback

The callback parameter should be a function that looks like this:

function() {...};

getMute

chrome.audio.getMute( StreamType streamType, function callback)

Gets the system-wide mute state for the specified stream type.

Parameters
StreamType streamType

Stream type for which mute state should be fetched.

function callback

Callback reporting whether mute is set or not for specified stream type.

The callback parameter should be a function that looks like this:

function(boolean value) {...};
boolean value

setMute

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

Sets mute state for a stream type. The mute state will apply to all audio devices with the specified audio stream type.

Parameters
StreamType streamType

Stream type for which mute state should be set.

boolean isMuted

New mute value.

function (optional) callback

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

Events

onLevelChanged

Fired when sound level changes for an active audio device.

addListener

chrome.audio.onLevelChanged.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(object event) {...};
object event
string deviceId

ID of device whose sound level has changed.

integer level

The device's new sound level.

onMuteChanged

Fired when the mute state of the audio input or output changes. Note that mute state is system-wide and the new value applies to every audio device with specified stream type.

addListener

chrome.audio.onMuteChanged.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(object event) {...};
object event
StreamType streamType

The type of the stream for which the mute value changed. The updated mute value applies to all devices with this stream type.

boolean isMuted

Whether or not the stream is now muted.

onDeviceListChanged

Fired when audio devices change, either new devices being added, or existing devices being removed.

addListener

chrome.audio.onDeviceListChanged.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function(array of AudioDeviceInfo devices) {...};
array of AudioDeviceInfo devices

List of all present audio devices after the change.