Audio Session API

Concepts and usage

People increasingly consume media through the web: it is now a primary channel for accessing audio and video content. However, media on the web often lacks seamless integration with underlying platforms. The Audio Session API addresses this gap by allowing developers to specify how the audio produced by their web applications interacts with audio from other applications on the device — for example, playing along with other audio, ducking it (reducing its volume), or pausing it so their audio can play on its own.

A web page can perform audio processing in various ways using APIs such as HTMLMediaElement and the Web Audio API. An audio session represents the aggregated audio produced by a web page, enabling it to express the general nature of its audio output.

Audio session types

The API supports several audio session types, which specify the type of audio an application is producing:

• "auto" — The default. The user agent automatically chooses the best type based on the audio APIs being used.
• "playback" — For media playback such as music or video. This type should not mix with other audio playback .
• "transient" — For short sounds like notifications. This type usually plays on top of other audio.
• "transient-solo" — For audio that should play exclusively, pausing all other audio (such as voice prompts).
• "ambient" — For audio that can mix with other audio sources.
• "play-and-record" — For applications that both play and record audio, such as video conferencing.

Interfaces

AudioSession

The main interface for controlling audio session behavior, including setting the audio session type.

Extensions to other interfaces

Navigator.audioSession Read only

Returns the AudioSession object for the current document.

Examples

Setting up a video conferencing audio session

In a video conferencing application, both playback and recording are required simultaneously; this is something the Audio Session API can help with.

First, we set the audio session type to "play-and-record" to inform the platform that this page requires microphone access alongside audio output. On supporting platforms, this may adjust system volume routing (for example, using the earpiece instead of the speaker on mobile devices) and prevent audio from other applications from interrupting the call.

navigator.audioSession.type = "play-and-record";

Next, we set up the media streams for the video call as usual. The platform will now handle the audio produced by these streams according to the "play-and-record" session type.

// Start playing remote media
remoteVideo.srcObject = remoteMediaStream;
remoteVideo.play();

// Start capturing local media
navigator.mediaDevices
  .getUserMedia({ audio: true, video: true })
  .then((stream) => {
    localVideo.srcObject = stream;
  });

Specifications

Browser compatibility

api.AudioSession

api.Navigator.audioSession

See also

• AudioSession
• Navigator.audioSession
• Web Audio API
• HTMLMediaElement