1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
---
title: Audio Channels API
slug: Web/API/AudioChannels_API
tags:
- API
- Audio
- AudioChannels
- Firefox OS
- Non-standard
- Obsolete
- Reference
translation_of: Archive/B2G_OS/API/Audio_Channels_API
---
<p>{{DefaultAPISidebar("Audio Channels API")}}</p>
<div class="blockIndicator nonStandard">
<p><strong>Non-standard</strong><br>
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.</p>
</div>
<p class="summary">The <strong>Audio Channels API</strong> 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.</p>
<p>Use case examples:</p>
<ul>
<li>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.</li>
<li>When you mute your phone you don't want to also mute your wake up alarm for the next morning.</li>
</ul>
<div class="note">
<p><strong>Note</strong>: 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 <a href="/en-US/docs/Web/Guide/User_experience/Using_the_Page_Visibility_API">Page Visibility API</a>, or perhaps <a href="/en-US/docs/Web/API/Window/onfocus" title="The onfocus property returns the onFocus event handler code on the current element."><code>window.onfocus</code></a>/<a href="/en-US/docs/Web/API/Window/onblur" title="The onblur property returns the onBlur event handler code, if any, that exists on the current element."><code>window.onblur</code></a>. AudioChannels are mainly useful for more complex phone uses cases involving telephony, etc.</p>
</div>
<h2 id="Concepts_and_usage">Concepts and usage</h2>
<p>The AudioChannels API extends the <a href="/en-US/docs/Web/API/HTMLMediaElement" title="The HTMLMediaElement interface adds to HTMLElement the properties and methods needed to support basic media-related capabilities that are common to audio and video."><code>HTMLMediaElement</code></a> and <a href="/en-US/docs/Web/API/AudioContext" title="The AudioContext interface represents an audio-processing graph built from audio modules linked together, each represented by an AudioNode. An audio context controls both the creation of the nodes it contains and the execution of the audio processing, or decoding. You need to create an AudioContext before you do anything else, as everything happens inside a context."><code>AudioContext</code></a> interfaces with (among other things) a <code>mozAudioChannelType</code> property that can be set to the channel you want your audio to be played in. The <a href="/en-US/docs/Web/HTML/Element/audio" title="The HTML <audio> element is used to embed sound content in documents. It may contain one or more audio sources, represented using the src attribute or the <source> element: the browser will choose the most suitable one. It can also be the destination for streamed media, using a MediaStream."><code><audio></code></a> and <a href="/en-US/docs/Web/HTML/Element/video" title="Use the HTML <video> element to embed video content in a document."><code><video></code></a> elements can also be used to set this value via the <code>mozaudiochannel</code> 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 — <code>normal</code> — 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:</p>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Channel name</th>
<th scope="col">importance</th>
<th scope="col">Used for</th>
<th scope="col">App permission level</th>
</tr>
</thead>
<tbody>
<tr>
<td>normal</td>
<td>1</td>
<td>UI sounds, app and web content</td>
<td>Normal</td>
</tr>
<tr>
<td>content</td>
<td>2</td>
<td>Music, radio, video</td>
<td>Normal</td>
</tr>
<tr>
<td>notification</td>
<td>3</td>
<td>New email, incoming SMS</td>
<td>Privileged</td>
</tr>
<tr>
<td>alarm</td>
<td>4</td>
<td>Alarm clock, calendar alarms</td>
<td>Privileged</td>
</tr>
<tr>
<td>ringer</td>
<td>5</td>
<td>Incoming phone calls</td>
<td>Certified</td>
</tr>
<tr>
<td>telephony</td>
<td>6</td>
<td>Ongoing phone calls, VOIP calls</td>
<td>Certified</td>
</tr>
<tr>
<td>publicnotification</td>
<td>7</td>
<td>Forced camera shutter sounds</td>
<td>Certified</td>
</tr>
</tbody>
</table>
<p>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 <a href="/en-US/docs/Web/API/MozAudioChannelManager" title="The documentation about this has not yet been written; please consider contributing!"><code>mozAudioChannelManager</code></a> object via the <a href="/en-US/docs/Web/API/Navigator/mozAudioChannelManager" title="The documentation about this has not yet been written; please consider contributing!"><code>navigator.mozAudioChannelManager</code></a> property.</p>
<div class="note">
<p><strong>Note</strong>: 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.</p>
</div>
<div class="note">
<p><strong>Note</strong>: Find more out about how to use the AudioChannels API in our <a href="/en-US/docs/Web/API/AudioChannels_API/Using_the_AudioChannels_API">Using the AudioChannels API</a> guide.</p>
</div>
<h2 id="AudioChannels_interfaces">AudioChannels interfaces</h2>
<dl>
<dt><a href="/en-US/docs/Web/API/AudioChannelManager" title="The documentation about this has not yet been written; please consider contributing!"><code>AudioChannelManager</code></a></dt>
<dd>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.</dd>
<dt><a href="/en-US/docs/Web/API/HTMLMediaElement" title="The HTMLMediaElement interface adds to HTMLElement the properties and methods needed to support basic media-related capabilities that are common to audio and video."><code>HTMLMediaElement</code></a> and <a href="/en-US/docs/Web/API/AudioContext" title="The AudioContext interface represents an audio-processing graph built from audio modules linked together, each represented by an AudioNode. An audio context controls both the creation of the nodes it contains and the execution of the audio processing, or decoding. You need to create an AudioContext before you do anything else, as everything happens inside a context."><code>AudioContext</code></a> extensions</dt>
<dd><code>HTMLMediaElement</code> and <code>AudioContext</code> 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.</dd>
<dt><a href="/en-US/docs/Web/API/Using_the_Browser_API">Browser API</a> extensions</dt>
<dd>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.</dd>
</dl>
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web/Apps/Build/App_permissions">App permissions for Firefox OS</a></li>
<li><a href="/en-US/docs/Web/API/AudioChannels_API/Using_the_AudioChannels_API">Using the Audio Channels API</a></li>
<li><a href="/en-US/docs/Web/API/Navigator/mozAudioChannelManager" title="The documentation about this has not yet been written; please consider contributing!"><code>navigator.mozAudioChannelManager</code></a></li>
<li><a href="/en-US/docs/Web/API/HTMLMediaElement" title="The HTMLMediaElement interface adds to HTMLElement the properties and methods needed to support basic media-related capabilities that are common to audio and video."><code>HTMLMediaElement</code></a></li>
</ul>
|
