Audio core features

Enable audio in your Video SDK app to allow users to communicate with each other. Users can connect using their computer's audio (microphone and speaker) or dial-in using PSTN (phone).

This guide covers core audio features like starting, stopping, muting, and switching audio devices. See audio best practices for suggestions on how to create the best user experience.

Start audio

To connect to the session audio, call stream.startAudio(). This also unmutes the user's microphone and prompts the browser to ask for microphone permissions. The Video SDK automatically uses the device's default speaker and microphone.

Call this function from a user-initiated event, like a button click. Otherwise, the browser might block programmatic access to the microphone.

// This should be in a click handler
stream.startAudio();

If the SDK fails to auto-play audio after stream.startAudio() is called, it dispatches the auto-play-audio-failed event.

Stop audio

To disconnect from the session audio, call stream.stopAudio().

stream.stopAudio();

Note:

stream.stopAudio() completely disconnects the user from the audio portion of the session. Do not call this function when the user is not speaking; use stream.muteAudio() instead. stream.stopAudio() should only be used when the user has, for example, clicked a button to disconnect from the audio stream.

Mute and unmute

To mute the user's own microphone, call stream.muteAudio().

stream.muteAudio();

To unmute their own microphone, call stream.unmuteAudio().

stream.unmuteAudio();

Get audio status

To get a user's current audio status, get the user object and check the audio property.

For the current user:

const currentUser = client.getCurrentUserInfo();
if (currentUser.muted === false) {
    console.log("User is unmuted");
} else {
    console.log("User is muted");
}

For any user in the session:

const user = client.getUser(userId);
if (currentUser.muted === false) {
    console.log("User is unmuted");
} else {
    console.log("User is muted");
}

Note: currentUser.muted can be true, false or undefined (if audio isn't joined).

Host can ask user to unmute

While only users can unmute themselves, a host can request a user to unmute by calling stream.unmuteAudio() with the user's userId.

// Host calls this
stream.unmuteAudio(userId);

The target user's app receives the host-ask-unmute-audio event. You must handle this event and display a UI prompt to let the user accept or decline the request.

// User receives this event
client.on("host-ask-unmute-audio", (payload) => {
    console.log(payload); // { userId: (ID of host who asked) }
    console.log("Host asked me to unmute");
    // Example: Show a confirmation dialog to the user
    if (window.confirm("The host has asked you to unmute. Unmute?")) {
        stream.unmuteAudio();
    }
});

Detect active speaker

To identify who is currently speaking, use the active-speaker event. This event fires frequently, making it ideal for UI animations like highlighting the speaker's video frame or an audio icon.

client.on("active-speaker", (payload) => {
    // payload is an array of active speakers
    // e.g., [{ userId: 123, displayName: 'Jane' }]
    console.log("Active speaker(s):", payload);
    // Update your UI to indicate who is speaking
});

For use cases where you want to change the video layout based on a more sustained period of speaking (e.g., pinning the speaker), use the video-active-change event. See Video: Dynamically render active speaker for details.

Switch audio devices

You can get lists of available microphones and speakers and allow users to switch between them.

Switch microphone

  1. Get a list of available microphones using stream.getMicList().
  2. Get the currently active microphone using stream.getActiveMicrophone().
  3. To switch, pass the deviceId of the desired microphone to stream.switchMicrophone().

We recommend presenting the list of microphones to the user in your UI.

const microphones = stream.getMicList();
const activeMicrophoneId = stream.getActiveMicrophone();
// Example: Switch to the first available microphone
if (microphones.length) {
    stream.switchMicrophone(microphones[0].deviceId);
}

Switch speaker

Similarly, you can switch the audio output device.

  1. Get a list of available speakers using stream.getSpeakerList().
  2. Get the currently active speaker using stream.getActiveSpeaker().
  3. To switch, pass the deviceId of the desired speaker to stream.switchSpeaker().
const speakers = stream.getSpeakerList();
const activeSpeakerId = stream.getActiveSpeaker();
// Example: Switch to the first available speaker
if (speakers.length) {
    stream.switchSpeaker(speakers[0].deviceId);
}

More audio features

For the full set of audio features, see the Stream class in the Video SDK Reference.