Device management
Updated
Video SDK provides APIs for managing input and output devices. Use these APIs to switch devices dynamically during Interactive Live Streaming and implement hot-swap logic when devices are added or removed.
Understand the tech
Managing audio and video devices involves selecting, switching, and handling changes in media input and output devices. The Video SDK provides APIs to:
- Change the default audio output route to a selected device.
- List available devices, including microphones and cameras.
- Dynamically switch devices during Interactive Live Streaming.
- Detect device changes (added or removed) and enable hot-swapping.
Change the default audio route
To change the audio output device, retrieve a list of available media devices, filter for audio output devices, and select the desired deviceId.
// Request a list of media devices and filter audio output devices.
const devices = await navigator.mediaDevices.enumerateDevices();
const audioOutputs = devices.filter(device => device.kind == "audiooutput");
const audioContext = new AudioContext();
// Pick the first available audio output.
const deviceId = audioOutputs[0].deviceId;
await audioContext.setSinkId(deviceId)For further details on changing the default audio route, see Change the destination output device in Web Audio.
Change audio or video capture devices
To set an audio or video capture device, retrieve available microphones and cameras using AgoraRTC.getMicrophones() and AgoraRTC.getCameras(). Then, call setDevice(deviceId) with the desired deviceId to use the selected capture device.
// Get available microphones and cameras
const microphones = await AgoraRTC.getMicrophones();
const cameras = await AgoraRTC.getCameras();
if (!microphones.length || !cameras.length) {
console.error("No microphone or camera found");
return;
}
// Switch to the first available microphone
localAudioTrack.setDevice(microphones[0].deviceId );
// Switch to the first available camera
localVideoTrack.setDevice(cameras[0].deviceId);Where localVideoTrack and localAudioTrack refer to the tracks you created using AgoraRTC.createCameraVideoTrack and AgoraRTC.createMicrophoneAudioTrack.
You can call setDevice to change the capture device even after publishing a track. However, on certain mobile devices, this operation may fail due to hardware or browser limitations.
Hot-swap capture devices
Video SDK provides the onMicrophoneChanged and onCameraChanged callbacks to detect changes in the plug-in status of audio and video devices. Implement listeners for these callbacks and call setDevice() to switch to a newly connected device automatically.
AgoraRTC.onMicrophoneChanged = async (changedDevice) => {
// When a new device is detected, switch to the new device
if (changedDevice.state === "ACTIVE") {
microphoneTrack.setDevice(changedDevice.device.deviceId);
} else if (changedDevice.device.label === microphoneTrack.getTrackLabel()) {
// Switch to an existing device when the unplugged device is the current device
const oldMicrophones = await AgoraRTC.getMicrophones();
oldMicrophones[0] && microphoneTrack.setDevice(oldMicrophones[0].deviceId);
}
};
AgoraRTC.onCameraChanged = async (changedDevice) => {
// When a new device is detected, switch to the new device
if (changedDevice.state === "ACTIVE") {
cameraTrack.setDevice(changedDevice.device.deviceId);
} else if (changedDevice.device.label === cameraTrack.getTrackLabel()) {
// Switch to an existing device when the unplugged device is the current device
const oldCameras = await AgoraRTC.getCameras();
oldCameras[0] && cameraTrack.setDevice(oldCameras[0].deviceId);
}
};If the user adds a virtual or a faulty device, hot-swap routing logic may result in no picture or no sound when the device is plugged-in or unplugged.
Reference
This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.