Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Twilio.Device.audio


When using the The Voice JavaScript SDK, a Device instance has access to a device.audio property containing an AudioHelper(link takes you to an external page) object. This allows you to control the way a Device instance interacts with speaker and microphone resources.

The AudioHelper(link takes you to an external page) is an EventEmitter(link takes you to an external page), so it provides a variety of event-related methods and properties. That functionality will not be covered here. For more information on EventEmitter functionality, see the Node.js Events documentation(link takes you to an external page) or click on the method/property below.

addListener(link takes you to an external page)

emit(link takes you to an external page)

eventNames(link takes you to an external page) getMaxListeners(link takes you to an external page)

listenerCount(link takes you to an external page)

listeners(link takes you to an external page)

off(link takes you to an external page)

on(link takes you to an external page)
once(link takes you to an external page)

prependListener(link takes you to an external page)

prependOnceListener(link takes you to an external page)

rawListeners(link takes you to an external page)

removeAllListeners(link takes you to an external page)

removeListener(link takes you to an external page)

listenerCount (static method)(link takes you to an external page)

defaultMaxListeners (static property)(link takes you to an external page)

Browser Support

browser-support page anchor
(warning)

Warning

Many device.audio features are browser-dependent.

Currently Chrome 49+ is the only browser that fully supports device.audio.

Audio output selection requires support for setSinkId(link takes you to an external page).

Audio input selection requires support for AudioContext(link takes you to an external page).

If these features are used in a browser that does not support them, the get method will return an empty Set, whereas the set and test methods will return a rejected Promise.


Below are explanations of the audio-related methods on the AudioHelper object provided by device.audio.

device.audio.addProcessor(processor)

deviceaudioaddprocessorprocessor page anchor

Adds an AudioProcessor object and returns a Promise representing the result. Once added, the AudioHelper will route the input audio stream through the processor before sending the audio stream to Twilio. Only one AudioProcessor can be added at this time.

See the AudioProcessor interface for an example.

device.audio.disconnect(doEnable)

deviceaudiodisconnectdoenable page anchor

Enable or disable the disconnect sound. Passing true will enable the sound and false will disable the sound. Not passing this parameter will not alter the enable-status of the sound.

Returns a boolean value that represents the enable-status of the sound.

device.audio.incoming(doEnable)

deviceaudioincomingdoenable page anchor

Enable or disable the incoming sound. Passing true will enable the sound and false will disable the sound. Not passing this parameter will not alter the enable-status of the sound.

Returns a boolean value that represents the enable-status of the sound.

device.audio.outgoing(doEnable)

deviceaudiooutgoingdoenable page anchor

Enable or disable the outgoing sound. Passing true will enable the sound and false will disable the sound. Not passing this parameter will not alter the enable-status of the sound.

Returns a boolean value that represents the enable-status of the sound.

device.audio.removeProcessor(processor)

deviceaudioremoveprocessorprocessor page anchor

Removes an AudioProcessor and returns a Promise representing the result. Once removed, the AudioHelper will start using the audio stream from the selected input device for existing or future calls.

device.audio.setAudioConstraints(audioConstraints)

deviceaudiosetaudioconstraintsaudioconstraints page anchor

Set the MediaTrackConstraints(link takes you to an external page) to be applied on every getUserMedia(link takes you to an external page) call for new input device audio. Any deviceId specified here will be ignored. Instead, device IDs should be specified using device.audio.setInputDevice(). The returned Promise resolves when the media is successfully reacquired, or immediately if no input device is set.

Example:


_20
const device = new Device(token);
_20
_20
device.audio.setAudioConstraints({ echoCancellation: true })
_20
.then(()=> {
_20
device.audio.setInputDevice('default');
_20
});
_20
_20
// Now we have a live input audio track, opened with echoCancellation:true
_20
device.audio.setAudioConstraints({
_20
autoGainControl: false,
_20
echoCancellation: false,
_20
noiseSuppression: false,
_20
}).then(() => {
_20
// We successfully applied the new constraints and should automatically hear the difference.
_20
// Future calls to setInputDevice will also use these constraints until they're cleared.
_20
}, err => {
_20
// Something went wrong, most likely err is an OverconstrainedError. Let's roll back.
_20
await device.audio.unsetAudioConstraints();
_20
// We should now have a working input audio track again
_20
});

device.audio.setInputDevice(deviceId)

deviceaudiosetinputdevicedeviceid page anchor

Set the current input device by deviceId. Once this is set, the input device will be used in the current call, if any, and used by default for any subsequent calls. In addition, whenever an input device is set, the device.audio's inputVolume event will fire on every animation frame(link takes you to an external page).

Returns a Promise that resolves if the input device was set successfully.

Note: This is not supported in Firefox (as recent as 51) due to its lack of support for multiple input devices.

Example:


_10
const device = new Device(token);
_10
_10
device.audio.setInputDevice('default').then(() => {
_10
console.info('Success!');
_10
});

device.audio.unsetAudioConstraints()

deviceaudiounsetaudioconstraints page anchor

Unset the MediaTrackConstraints(link takes you to an external page) to be applied on every getUserMedia(link takes you to an external page) call for new input device audio. The returned Promise resolves when the media is successfully reacquired, or immediately if no input device is set.

device.audio.unsetInputDevice(deviceId)

deviceaudiounsetinputdevicedeviceid page anchor

Unset the active input device. This will stop the device.audio's inputVolumeEvent polling and stop the input stream.

Example:


_10
const device = new Device(token);
_10
_10
// ...
_10
_10
device.audio.unsetInputDevice().then(()=> {
_10
console.info('Success!');
_10
});


device.audio.availableInputDevices

deviceaudioavailableinputdevices page anchor

A Map(link takes you to an external page) containing the MediaDeviceInfo(link takes you to an external page) object of all available input devices (hardware devices capable of providing an input audio stream), indexed by deviceId.

(warning)

Warning

Due to browser-imposed security restrictions, MediaDeviceInfos available in availableInDevices may contain auto-generated labels (e.g. "Unknown Audio Input Device 1"), or an incomplete / empty list of devices, until the user grants the application access to these resources in response to a call to the browser's getUserMedia()(link takes you to an external page) API.

In an effort to reduce device fingerprinting, all major browsers are getting more strict in this regard. We strongly recommend your application calls getUserMedia()(link takes you to an external page) before rendering your input / output device selection UI for the cleanest user experience.

After the user accepts the getUserMedia() prompt, the AudioHelper's deviceChange event will be fired to indicate that the application UI should be updated.

device.audio.availableOutputDevices

deviceaudioavailableoutputdevices page anchor

A Map(link takes you to an external page) containing the MediaDeviceInfo(link takes you to an external page) object of all available output devices (hardware devices capable of outputting audio), indexed by deviceId.

(warning)

Warning

Due to browser-imposed security restrictions, MediaDeviceInfos available in availableOutputDevices may contain auto-generated labels (e.g. "Unknown Audio Output Device 1"), or an incomplete / empty list of devices, until the user grants the application access to these resources in response to a call to the browser's getUserMedia()(link takes you to an external page) API.

In an effort to reduce device fingerprinting, all major browsers are getting more strict in this regard. We strongly recommend your application calls getUserMedia()(link takes you to an external page) before rendering your input / output device selection UI for the cleanest user experience.

After the user accepts the getUserMedia() prompt, the AudioHelper's deviceChange event will be fired to indicate that the application UI should be updated.

(warning)

Warning

Firefox (as recent as 51) does not list any audiooutput devices, and Edge (as recent as 38) does not label its audiooutput devices even after user permission is granted.

Example:


_10
const device = new Device(token);
_10
_10
device.audio.availableOutputDevices.forEach((device, id) => {
_10
console.info('Available device:', id, '(labeled', device.label, ')');
_10
});

device.audio.isOutputSelectionSupported

deviceaudioisoutputselectionsupported page anchor

Returns a Boolean. Returns false if the browser does not support HTMLAudioElement.setSinkId()(link takes you to an external page) or MediaDevices.enumerateDevices()(link takes you to an external page) and Twilio cannot facilitate output selection functionality.

device.audio.isVolumeSupported

deviceaudioisvolumesupported page anchor

Returns a Boolean. Returns false if the browser does not support AudioContext(link takes you to an external page) and Twilio can not analyze the volume in real-time.

device.audio.ringtoneDevices

deviceaudioringtonedevices page anchor

ringtoneDevices is an OutputDeviceCollection(link takes you to an external page) that controls which output devices are used to play the ringing sound when receiving an incoming call. Changing this set of devices will switch the devices used for the incoming call sound.

Note: This is not supported in Firefox (as recent as 51) or Edge (as recent as 38) due to their lack of support for HTMLAudioElement.setSinkId().

device.audio.ringtoneDevices.delete(device)

Delete a device from the collection. If no devices remain, the default device will be added as the sole device. If no default device exists, the first available device will be used.

The device parameter is a MediaDeviceInfo(link takes you to an external page) object.

This method returns a Boolean for whether the device was present before it was deleted.

device.audio.ringtoneDevices.get()

Returns the current set of devices (as MediaDeviceInfo(link takes you to an external page) objects).


_10
const device = new Device(token);
_10
_10
device.audio.ringtoneDevices.get(); // Returns a Set<MediaDeviceInfo>

device.audio.ringtoneDevices.set(deviceIdOrIds).

Replace the current device/set of devices with a new device or set of devices.

The deviceIdOrIds parameter can be either a single deviceId (as a string) or an array of deviceIds (as an array of strings).

Returns an empty Promise. Rejects if this feature is not supported, or if any of the supplied deviceIds are not found, or if no deviceIds are passed.


_10
const device = new Device(token);
_10
_10
device.audio.ringtoneDevices.set('default'); // Set active device
_10
device.audio.ringtoneDevices.set(['default', 'ABC123']); // Set active devices

device.audio.ringtoneDevices.test(soundUrl?)

Test the devices by playing audio through them.

The optional soundUrl parameter is a URL string for a test sound. If no soundUrl is passed, the test will be run with the 'outgoing' sound.

Returns a Promise. It will resolve with the result of the underlying HTMLAudioElement's play() calls.


_10
const device = new Device(token);
_10
_10
device.audio.ringtoneDevices.test(); // Test with 'outgoing' sound
_10
device.audio.ringtoneDevices.test('cowbell.mp3'); // Test with custom sound

device.audio.speakerDevices

deviceaudiospeakerdevices page anchor

speakerDevices is an OutputDeviceCollection(link takes you to an external page) that controls which output devices are used to play standard speaker sounds: the ringtone you hear when initiating a call, the disconnect sound, DTMF tones the user might press and the audio received from the remote participant.

Changing this set of devices will switch the device(s) used for these sounds. If you change these during an active call, the remote participant's audio will immediately be played through the new set of outputs.

Note: This is not supported in Firefox (as recent as 51) or Edge (as recent as 38) due to their lack of support for HTMLAudioElement.setSinkId().

device.audio.speakerDevices.delete(device)

Delete a device from the collection. If no devices remain, the default device will be added as the sole device. If no default device exists, the first available device will be used.

The device parameter is a MediaDeviceInfo(link takes you to an external page) object.

This method returns a Boolean for whether the device was present before it was deleted.

device.audio.speakerDevices.get()

Returns the current set of devices (as MediaDeviceInfo(link takes you to an external page) objects).


_10
const device = new Device(token);
_10
_10
device.audio.speakerDevices.get(); // Returns a Set<MediaDeviceInfo>

device.audio.speakerDevices.set(deviceIdOrIds).

Replace the current device/set of devices with a new device or set of devices.

The deviceIdOrIds parameter can be either a single deviceId (as a string) or an array of deviceIds (as an array of strings).

Returns an empty Promise. Rejects if this feature is not supported, or if any of the supplied deviceIds are not found, or if no deviceIds are passed.


_10
const device = new Device(token);
_10
_10
device.audio.speakerDevices.set('default'); // Set active device
_10
device.audio.speakerDevices.set(['default', 'ABC123']); // Set active devices

device.audio.speakerDevices.test(soundUrl?)

Test the devices by playing audio through them.

The optional soundUrl parameter is a URL string for a test sound. If no soundUrl is passed, the test will be run with the 'outgoing' sound.

Returns a Promise. It will resolve with the result of the underlying HTMLAudioElement's play() calls.


_10
const device = new Device(token);
_10
_10
device.audio.speakerDevices.test(); // Test with 'outgoing' sound
_10
device.audio.speakerDevices.test('cowbell.mp3'); // Test with custom sound


device.audio.audioConstraints

deviceaudioaudioconstraints page anchor

The current audio constraints (as a MediaTrackConstraints(link takes you to an external page) object) set by device.audio.setAudioConstraints(). Starts as null.

device.audio.inputDevice

deviceaudioinputdevice page anchor

Returns the active input device (as a MediaDeviceInfo(link takes you to an external page) object).

Having no inputDevice specified by device.audio.setInputDevice() will disable functionality related to input selection.

device.audio.inputStream

deviceaudioinputstream page anchor

Returns the current input stream (as a MediaStream(link takes you to an external page) object).



_10
const device = new Device(token);
_10
_10
device.audio.on('deviceChange', handler(lostActiveDevices));

Register a handler that will be fired whenever a new audio device is found, an existing audio device is lost or the label of an existing device is changed. This typically happens when the user plugs in or unplugs an audio device, like a headset or a microphone.

This will also trigger after the customer has given access to user media via getUserMedia for the first time, as the labels will become populated. If you want to allow users to choose a specific audio device in your application's UI, attach a listener to this event.

(warning)

Warning

This does not detect a customer plugging in headphones or other speakers through the headphone jack, as the headphone jack only redirects audio from the internal audio device.

The parameter, lostActiveDevices, is an array of MediaDeviceInfo(link takes you to an external page) objects that represents all devices that were currently active in either .speakerDevices or .ringtoneDevices at the time they were lost, if any. A non-empty array is an indicator that the user's experience was likely affected by this event.


_10
const device = new Device(token);
_10
_10
device.audio.on('inputVolume', handler(volume))

Register a handler that will be fired every animation frame(link takes you to an external page) with the current volume of the selected input device, if one is set. The handler will be invoked up to 60 times per second, and will scale down dynamically on slower devices to preserve performance. The handler receives volume as a percentage of maximum volume represented by a floating point number between 0.0 and 1.0, inclusive. This value represents a range of relative decibel values between -100dB and -30dB.

Note: This will not work in Firefox (as recent as 51) as there is no supported way to set the input device.


Both device.audio.speakerDevices and device.audio.ringtoneDevices are instances of an OutputDeviceCollection. An OutputDeviceCollection represents active audio devices, and can be updated to redirect speaker and ringtone sounds to different devices in real time.

An OutputDeviceCollection provides delete, get, set, and test methods. Descriptions and examples for each of these methods can be found in the device.audio.ringtoneDevices and device.audio.speakerDevices sections above.

Below is an example on how one might work with an OutputDeviceCollection using a multi-select HTML element:


_37
const device = new Device(token);
_37
_37
var speakerDeviceSelect = document.getElementById('speaker-devices');
_37
_37
// When a device is found or lost, update a multi-select element with the
_37
// new set of available devices.
_37
device.audio.on('deviceChange', function updateAvailableDevices() {
_37
speakerDeviceSelect.innerHtml = '';
_37
_37
device.audio.availableOutputDevices.forEach((device, id) => {
_37
var deviceOption = document.createElement('option');
_37
deviceOption.label = device.label;
_37
deviceOption.setAttribute('data-id', id);
_37
_37
// If the device is present in device.audio.speakerDevices, then it is
_37
// currently active, and should be selected in the multi-select element.
_37
var speakerDevices = device.audio.speakerDevices.get();
_37
speakerDevices.forEach((speakerDevice) => {
_37
if (speakerDevice.deviceId === id) {
_37
deviceOption.setAttribute('selected', 'selected');
_37
}
_37
});
_37
_37
speakerDeviceSelect.appendChild(deviceOption);
_37
});
_37
});
_37
_37
// When a device is selected or unselected, update device.audio.speakerDevices
_37
// with the devices the user selected to immediately change where the audio
_37
// is playing from.
_37
speakerDeviceSelect.addEventListener('change',() => {
_37
var selectedDeviceIds = [].slice.call(speakerDevices.childNodes)
_37
.filter(function(node) { return node.selected; })
_37
.map(function(node) { return node.getAttribute('data-id'); });
_37
_37
device.audio.speakerDevices.set(selectedDeviceIds);
_37
});


Rate this page: