Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Device management

Updated

Voice SDK provides APIs for managing input and output devices. Use these APIs to switch devices dynamically during Voice Calling and implement hot-swap logic when devices are added or removed.

Understand the tech

Managing audio devices involves selecting, switching, and handling changes in media input and output devices. The Voice SDK provides APIs to:

  • Change the default audio output route to a selected device.
  • List available microphones.
  • Dynamically switch devices during Voice Calling.
  • 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 the audio capture device

To set an audio capture device, retrieve available microphones using AgoraRTC.getMicrophones(). Then, call setDevice(deviceId) with the desired deviceId to use the selected capture device.

// Get available microphones
const microphones = await AgoraRTC.getMicrophones();

if (!microphones.length) {
 console.error("No microphone found");
 return;
}

// Switch to the first available microphone
localAudioTrack.setDevice(microphones[0].deviceId );

Here localAudioTrack refers to the local audio track created using 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

Voice SDK provides the onMicrophoneChanged callback to detect changes in the plug-in status of audio device. To switch to a newly connected device automatically, implement a listener for this callback and call setDevice to use the new device

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);
 }
};

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.

API reference

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved