Audio Autoplay Blocking

Updated on 2024-11-15 GMT+08:00

View PDF

What Is Audio Autoplay Blocking?

Automatically starting the playback of audio (or videos with audio tracks) immediately upon page load can be an unwelcome surprise to users. In order to give users control over this, browsers often provide audio autoplay blocking policies. During audio autoplay, audio autoplay blocking policies may be triggered when users do not engage with the page. However, audio autoplay will not be blocked in non-autoplay or muted autoplay scenarios. Specifically, if the audio or video tag contains the autoplay attribute, autoplay is blocked after the page is loaded. If the play API is forcibly called, an error message similar to Uncaught (in promise) DOMException: play() failed because the user didn't interact with the document first will be reported.

HTML:

<video src="/video_with_audio.mp4" autoplay></video>

JavaScript:

videoElement.play();

Autoplay of a video with an audio track on a new page will be denied by the browser.

Generally, audio autoplay is not allowed by the browser until users engage with the page. For example, the play API will be called when users click the playback button on the page.

PlayButton.addEventListener('click', () => {   
  videoElement.play(); 
})

LLL SDK Error Messages Caused by Audio Autoplay Blocking

When the LLL SDK is used to autoplay an LLL livestream with sound:

const options = {
  elementId: 'elementId',
  autoPlay: true,
}
startPlayPromise = playClient.startPlay(streamUrl, options)

Set autoPlay to true. If autoPlay is not specified, the default value true is used. When audio autoplay is blocked, the browser console reports the following error message:

[HWLLS] [error] [HLLSTrack] [play audio failed: ["code": 51000000, "message": "the user didn't interact with the document first, please trigger by gesture."] ]
### lll play SDK occur error: {"errCode":51000000,"errDesc":"the user didn't interact with the document first, please trigger by gesture."}

If Error is reported during listening, error code 51000000 is displayed:

playClient.on('Error', (resp) => {
  if (resp.errCode === 51000000) {
    // Error message on audio autoplay blocking
  }
})

Best Practices

Manual playback

Example of muted autoplay using the LLL SDK:

const options = {
  elementId: 'elementId',
  autoPlay: false
}
startPlayPromise = playClient.startPlay(streamUrl, options)

Set autoPlay to false and add a playback button so that the playback starts only when the user clicks the button.

Figure 1 Effect picture

Listening on autoplay errors

Autoplay with sound:

const options = {
  elementId: 'elementId',
  autoPlay: true,
 }
startPlayPromise = playClient.startPlay(streamUrl, options)

Listening error code on audio autoplay blocking:

playClient.on('Error', (resp) => {
  if (resp.errCode === 51000000) {
    // Error message on audio autoplay blocking
    // Add the button unmute on the page.
  }
})

In this case, even if audio autoplay is blocked, the video is still played without sound. If the user wants to hear the sound, the user can click unmute to play the audio. When audio autoplay is not blocked, the video will be played with sound.

Figure 2 Effect picture 1