# Audio core features

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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](/docs/video-sdk/web/pstn/) (phone).

This guide covers core audio features like starting, stopping, muting, and switching audio devices. See [audio best practices](/docs/video-sdk/web/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.

```javascript
// 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`](https://marketplacefront.zoom.us/sdk/custom/web/modules/ZoomVideo.html#event_auto_play_audio_failed) event.

## Stop audio

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

```javascript
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()`.

```javascript
stream.muteAudio();
```

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

```javascript
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:

```javascript
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:

```javascript
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`.

```javascript
// 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.

```javascript
// 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.

```javascript
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](/docs/video-sdk/web/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.

```javascript
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()`.

```javascript
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](https://marketplacefront.zoom.us/sdk/custom/web/modules/ZoomVideo.Stream.html).