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
andAudioContext
extensionsHTMLMediaElement
andAudioContext
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
- App permissions for Firefox OS
- Using the AudioChannels API
navigator.mozAudioChannelManager
HTMLMediaElement
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/audiochannels_api