Audio Channels API

Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

The AudioChannels API is a Firefox OS-only feature allowing you to place your app audio content into a hierarchy of importance, which dictates when the audio will be paused and resumed in response to other audio playing and actions occurring and allows you to control the volume of different types of audio independently from one another.

Use case examples:

  • You want your audio player app to continue playing audio even when it is running in the background so you can do other things as it plays, but you want it to pause when someone rings your phone.
  • When you mute your phone you don't want to also mute your wake up alarm for the next morning.

Note: Since the AudioChannels API is non-standard and requires permissions, for many simple use cases such as pausing game music when the app/web page goes into the background you would be better off using the standard Page Visibility API, or perhaps window.onfocus/window.onblur. AudioChannels are mainly useful for more complex phone uses cases involving telephony, etc.

Concepts and usage

The AudioChannels API extends the HTMLMediaElement and AudioContext interfaces with (among other things) a mozAudioChannelType property that can be set to the channel you want your audio to be played in. The  <audio> and <video> elements can also be used to set this value via the mozaudiochannel attribute. When your audio is placed into a channel, it is generally paused (or interrupted) by audio in a higher priority channel being played. Audio in the least important channel — normal — is also paused by its app being put into the background (this is not the case with the other channels). The audio channels are as follows:

Channel name importance Used for App permission level
normal 1 UI sounds, app and web content Normal
content 2 Music, radio, video Normal
notification 3 New email, incoming SMS Privileged
alarm 4 Alarm clock, calendar alarms Privileged
ringer 5 Incoming phone calls Certified
telephony 6 Ongoing phone calls, VOIP calls Certified
publicnotification 7 Forced camera shutter sounds Certified

Each channel has a separate mute and volume setting, to provide more granular control over the different parts of audio on your device. These are accessed using the mozAudioChannelManager object via the navigator.mozAudioChannelManager property.

Note: If you have two apps playing audio in the content channel, only the one in the foreground can play audio, while the other is interrupted. When the foreground app is put into the background with audio playing, it will not be muted, as per normal "content" behaviour.

Note: Find more out about how to use the AudioChannels API in our Using the AudioChannels API guide.

AudioChannels interfaces

AudioChannelManager
Includes some features for managing your device's audio channels, including setting what channel's volume to affect when the volume buttons are pressed inside a particular app.
HTMLMediaElement and AudioContext extensions
HTMLMediaElement and AudioContext are extended with some proprietary features for controlling audio channels, including setting what audio channel the media is in, and events that fire when the audio is interrupted, and resumes playing.
Browser API extensions
The Browser API will also be including some audio channels features, for putting audio content inside a browser instance into audio channels, controlling its volume, etc., but it doesn't look like these have yet been implemented. This should occur soon.

Specifications

The AudioChannels API has no official spec at the moment; see https://wiki.mozilla.org/WebAPI/AudioChannels for implementation details, WebIDL, etc.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
General support No support No support No support No support No support
Feature Android Chrome Firefox Mobile (Gecko) Firefox OS IE Phone Opera Mobile Safari Mobile
General support No support No support No support 1.0.1 No support No support No support
publicnotification No support No support No support 1.2 No support No support No support

See also

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, teoli, fscholz, markg
 Last updated by: chrisdavidmills,