Top of pageSkip to main content

Audio


Session audio can be connected over the browser or through a phone call. This is called call out.

On this page

Start audio

To start audio (sound) and unmute the participant microphone, call the stream.startAudio() function. This will prompt the browser to ask the participant for permission to turn on their microphone. The Video SDK will automatically use the device's speaker and microphone. Additional logic is required to start audio on Safari on a desktop (desktop Safari).

stream.startAudio()

Start audio on desktop Safari

To start audio properly on desktop Safari, use the media-sdk-change event listener to see when desktop Safari audio has been initialized.

// declare audio initialization state
let audioDecode
let audioEncode

// event listener to see when desktop Safari audio has been initialized
client.on('media-sdk-change', (payload) => {
  if (payload.type === 'audio' && payload.result === 'success') {
    if (payload.action === 'encode') {
      // encode for sending audio stream (speak)
      audioEncode = true
    } else if (payload.action === 'decode') {
      // decode for receiving audio stream (hear)
      audioDecode = true
    }
  }
})

// your start audio button click
function startAudioButton() {
  // if desktop Safari https://stackoverflow.com/a/42189492/6592510
  var isSafari = window.safari !== undefined

  if(isSafari) {
    // desktop Safari, check if desktop Safari audio has been initialized
    if(audioEncode && audioDecode){
       // desktop Safari audio has been initialized, continue to start audio
       stream.startAudio()
    } else {
       // desktop Safari audio has not been initialized, retry or handle error
       console.log('safari audio has not finished initializing')
    }
  } else {
    // not desktop Safari, continue to start audio
    stream.startAudio()
  }
}

Autoplay audio

Audio can be started automatically after joining a session, however it is not recommended. Automatic playing of browser audio (sound) without a user button click may be restricted by the browser itself. This may be due to a browser with autoplay restrictions. For example, if the user does not perform any interactive actions, such as clicking on the page, the web page cannot automatically play audio.

If the stream.startAudio() function is called before a user interaction occurs, autoplay restrictions may prevent the participant from hearing session audio. But if the participant interacts with the page at any time, the SDK detects this behavior and attempts to start audio playing for the session.

We recommend tieing the stream.startAudio() function to a start audio user button click, or that you ensure a participant has interacted with the page before calling stream.startAudio(). If your user experience can't guarantee this, you can use the auto-play-audio-failed callback to prompt the user to interact with the page when the playing fails. Additional logic is required to start audio on desktop Safari and iOS/iPadOS Safari.

stream.startAudio()

client.on('auto-play-audio-failed', () => {
  console.log('auto play failed, waiting for a user interaction')
})

Autoplay audio on desktop Safari

To automatically start audio properly on desktop Safari, use the media-sdk-change event listener to see when desktop Safari audio has been initialized.

// declare audio initialization state
let audioDecode
let audioEncode

// event listener to see when desktop Safari audio has been initialized
client.on('media-sdk-change', (payload) => {
  if (payload.type === 'audio' && payload.result === 'success') {
    if (payload.action === 'encode') {
      // encode for sending audio stream (speak)
      audioEncode = true
    } else if (payload.action === 'decode') {
      // decode for receiving audio stream (hear)
      audioDecode = true
    }

    // if desktop Safari https://stackoverflow.com/a/42189492/6592510
    var isSafari = window.safari !== undefined

    if(isSafari) {
      // desktop Safari, check if desktop Safari audio has been initialized
      if (audioEncode && audioDecode) {
        // desktop Safari audio has been initialized
        try {
          // try to start audio automatically in Safari
          stream.startAudio({ autoStartAudioInSafari: true })
        } catch (error) {
          // starting audio automatically in Safari failed, retry or handle error
          console.log(error)
        }
      } else {
         // desktop Safari audio has not been initialized, retry or handle error
         console.log('safari audio has not finished initializing')
      }
    }
  }
})

// starting audio automatically in Safari failed
client.on('auto-play-audio-failed', () => {
  console.log('auto play failed, waiting for a user interaction')
})

Autoplay audio on iOS/iPadOS Safari

stream.startAudio({ autoStartAudioInSafari: true })

Stop audio

To stop audio (sound) call the stream.stopAudio() function.

stream.stopAudio()

Mute and unmute

By default, the stream.startAudio() function will unmute the participant's microphone.

Mute

To mute a participant's microphone call the stream.muteAudio() function.

stream.muteAudio()

Unmute

To unmute a participant's microphone call the stream.unmuteAudio() function. The host and participant's only have permission to unmute their own microphone.

stream.unmuteAudio()

See the Reference for additional mute functions.

Ask a participant to unmute

The host can however ask a participant to unmute their microphone by passing in a userId to the stream.unmuteAudio() function.

stream.unmuteAudio(userId)

You can use the host-ask-unmute-audio event listener to handle the ask respectively.

client.on('host-ask-unmute-audio', (payload) => {
   console.log(payload)
   console.log('Host asked me to unmute')
})

Detect active speaker

To detect who the active speaker is in a session, use the active-speaker event listener. This is useful for rendering or highlighting the active speaker's video so participants can see who is speaking.

client.on('active-speaker', (payload) => {
   console.log('Active speaker', payload)
})

Switch speaker or microphone

See below to switch the speaker output or microphone input.

Switch speaker

To switch the speaker output, get the list of speakers, and then pass in a deviceId to the stream.switchSpeaker() function.

let speakers = stream.getSpeakerList()

stream.switchSpeaker(speakers[1].deviceId)

Switch microphone

To switch the microphone input, get the list of microphones, and then pass in a deviceId to the stream.switchMicrophone() function.

let microphones = stream.getMicList()

stream.switchMicrophone(microphones[1].deviceId)

Detect new microphone or speaker

Use the device-change event to detect if a speaker or microphone has been plugged in or unplugged:

client.on('device-change', () => {
  console.log(stream.getSpeakerList())
  console.log(stream.getMicList())

  speakers = stream.getSpeakerList()
  microphones = stream.getMicList()
})

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

Next Steps

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.