Audio Session API
The AudioSession interface of the Audio Session API lets a web page declare the type of audio it is producing — for example music playback, a video call, or a short notification.
The platform uses the declared type to decide how the page's audio and audio from other applications and tabs should coexist — whether to pause, duck (lower the volume), or play in parallel.
The interface also provides the AudioSession.state property, which indicates if audio is actively playing on the page, is inactive, or has been interrupted, and the AudioSession.statechange_event event, which provides notification when the state changes. While audible media is automatically paused/resumed by interruptions, state monitoring allows the configuration of behavior that is not automatically controlled.
Instance properties
- AudioSession.type
- : A string representing the type of the audio session. Possible values include
"auto","playback","transient","transient-solo","ambient", and"play-and-record".
- : A string representing the type of the audio session. Possible values include
- AudioSession.state
- : A string representing the current state of the audio session. Possible values are
"active","interrupted", and"inactive".
- : A string representing the current state of the audio session. Possible values are
Events
Listen to these events using EventTarget.addEventListener or by assigning an event listener to the oneventname property of this interface.
- AudioSession.statechange_event
- : Fired when the AudioSession.state property changes. Also available through the AudioSession.statechange_event event handler property.
Examples
Basic usage
The following example sets the audio session type to "playback" before starting media playback (provided AudioSession is supported).
This signals that the page is playing media such as music or video.
if ("audioSession" in navigator) {
// Set the audio session type for media playback
navigator.audioSession.type = "playback";
}
// Play some audio
audioElement.play();
Setting up a video conferencing app
This example sets the audio session type to "play-and-record" for a video conferencing application.
First we use Navigator.audioSession to signal that the page needs simultaneous playback and recording. This may cause the system to route audio through the correct output (for example, earpiece instead of speaker on mobile devices) and prevent other applications' audio from interrupting the call. Then we start playing the remote media and streaming our own video and audio.
navigator.audioSession.type = "play-and-record";
// Start playing remote media
remoteVideo.srcObject = remoteMediaStream;
remoteVideo.play();
// Start capturing local media
const stream = await navigator.mediaDevices.getUserMedia({
audio: true,
video: true,
});
localVideo.srcObject = stream;
The following code listens for the AudioSession.statechange_event event.
If the session state is "interrupted" by the platform, for example due to an incoming phone call, the handler pauses unmuted local and remote video while the interruption lasts (the platform itself will pause and restart any elements that have an audible output).
// Pause local playback and recording while the platform interrupts the call
navigator.audioSession.addEventListener("statechange", () => {
const interrupted = navigator.audioSession.state === "interrupted";
// remoteVideo is the audio/video from the remote end.
// We pause it on interruption if it was muted (and hence not paused automatically)
if (remoteVideo.muted) {
if (interrupted) {
remoteVideo.pause();
} else {
remoteVideo.play();
}
}
// localVideo is the preview for the local user.
// This is typically muted by default,
// so the page must pause and resume it explicitly.
if (interrupted) {
localVideo.pause();
} else {
localVideo.play();
}
});
Specifications
Browser compatibility
See also
- Navigator.audioSession
- Audio Session API
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
