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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
* You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
interface mozIDOMWindow;
typedef uint32_t nsSuspendedTypes;
[scriptable, builtinclass, uuid(2822a840-f009-11e5-a837-0800200c9a66)]
interface nsISuspendedTypes : nsISupports
{
/**
* The suspended enum is used in three different situations,
* - platform audio focus (Fennec/B2G)
* - remote media control (Fennec)
* - block auto-play video in non-active page
*
* Note: the "remote side" must control the AudioChannelAgent using
* nsIAudioChannelAgentCallback.windowSuspendChanged() callback instead using
* play/pause methods or any button in the webpage.
*
* - SUSPENDED_PAUSE :
* It's used when transiently losing audio focus, the media can't be resumed
* until we gain the audio focus again. It would change the internal state of
* MediaElement when it's being suspended/resumed, and it would trigger the
* related JS event. eg. "play" and "pause" event.
*
* - SUSPENDED_BLOCK
* It's used to prevent auto-playing media in inactive page in order to
* reduce the power consumption, and the media can't be resumed until the
* page becomes active again. It would change the internal state of
* MediaElement when it's being blocked/resumed, so it won't trigger the
* related JS event. eg. "play" and "pause" event.
*
* - SUSPENDED_PAUSE_DISPOSABLE
* It's used for remote media-control to pause the playing media and when we
* lose audio focus permanently. It's disposable suspended, so the media can
* be resumed arbitrary after that. Same as SUSPENDED_PAUSE, it would change
* the internal state of MediaElement when it's being suspended.
*
* - SUSPENDED_STOP_DISPOSABLE
* It's used for remote media-control to stop the playing media. The remote
* control would disappear after stopping the media, so we would disconnect
* the audio channel agent. It's disposable suspended, so the media can be
* resumed arbitrary after that. Same as SUSPENDED_PAUSE, it would change
* the internal state of MediaElement when it's being suspended.
*/
const uint32_t NONE_SUSPENDED = 0;
const uint32_t SUSPENDED_PAUSE = 1;
const uint32_t SUSPENDED_BLOCK = 2;
const uint32_t SUSPENDED_PAUSE_DISPOSABLE = 3;
const uint32_t SUSPENDED_STOP_DISPOSABLE = 4;
};
%{C++
namespace mozilla {
namespace dom {
// It's defined in dom/audiochannel/AudioChannelService.h.
class AudioPlaybackConfig;
}
}
%}
[ptr] native AudioPlaybackConfig(mozilla::dom::AudioPlaybackConfig);
[uuid(15c05894-408e-4798-b527-a8c32d9c5f8c)]
interface nsIAudioChannelAgentCallback : nsISupports
{
/**
* Notified when the window volume/mute is changed
*/
void windowVolumeChanged(in float aVolume, in bool aMuted);
/**
* Notified when the window needs to be suspended or resumed.
*/
void windowSuspendChanged(in uint32_t aSuspend);
/**
* Notified when the capture state is changed.
*/
void windowAudioCaptureChanged(in bool aCapture);
};
/**
* This interface provides an agent for gecko components to participate
* in the audio channel service. Gecko components are responsible for
* 1. Indicating what channel type they are using (via the init() member
* function).
* 2. Notifying the agent when they start/stop using this channel.
* 3. Notifying the agent when they are audible.
*
* The agent will invoke a callback to notify Gecko components of
* 1. Changes to the playable status of this channel.
*/
[uuid(ab7e21c0-970c-11e5-a837-0800200c9a66)]
interface nsIAudioChannelAgent : nsISupports
{
const long AUDIO_AGENT_CHANNEL_NORMAL = 0;
const long AUDIO_AGENT_CHANNEL_CONTENT = 1;
const long AUDIO_AGENT_CHANNEL_NOTIFICATION = 2;
const long AUDIO_AGENT_CHANNEL_ALARM = 3;
const long AUDIO_AGENT_CHANNEL_TELEPHONY = 4;
const long AUDIO_AGENT_CHANNEL_RINGER = 5;
const long AUDIO_AGENT_CHANNEL_PUBLICNOTIFICATION = 6;
const long AUDIO_AGENT_CHANNEL_SYSTEM = 7;
const long AUDIO_AGENT_CHANNEL_ERROR = 1000;
const long AUDIO_AGENT_STATE_NORMAL = 0;
const long AUDIO_AGENT_STATE_MUTED = 1;
const long AUDIO_AGENT_STATE_FADED = 2;
/**
* Before init() is called, this returns AUDIO_AGENT_CHANNEL_ERROR.
*/
readonly attribute long audioChannelType;
%{C++
inline int32_t AudioChannelType() {
int32_t channel;
return NS_SUCCEEDED(GetAudioChannelType(&channel)) ? channel : AUDIO_AGENT_CHANNEL_ERROR;
}
%}
/**
* Initialize the agent with a channel type.
* Note: This function should only be called once.
*
* @param window
* The window
* @param channelType
* Audio Channel Type listed as above
* @param callback
* 1. Once the playable status changes, agent uses this callback function
* to notify Gecko component.
* 2. The callback is allowed to be null. Ex: telephony doesn't need to
* listen change of the playable status.
* 3. The AudioChannelAgent keeps a strong reference to the callback
* object.
*/
void init(in mozIDOMWindow window, in long channelType,
in nsIAudioChannelAgentCallback callback);
/**
* This method is just like init(), except the audio channel agent keeps a
* weak reference to the callback object.
*
* In order for this to work, |callback| must implement
* nsISupportsWeakReference.
*/
void initWithWeakCallback(in mozIDOMWindow window, in long channelType,
in nsIAudioChannelAgentCallback callback);
/**
* Notify the agent that we want to start playing.
* Note: Gecko component SHOULD call this function first then start to
* play audio stream only when return value is true.
*
* @param config
* It contains the playback related states (volume/mute/suspend)
*/
void notifyStartedPlaying(in AudioPlaybackConfig config, in uint8_t audible);
/**
* Notify the agent we no longer want to play.
*
* Note : even if notifyStartedPlaying() returned false, the agent would
* still be registered with the audio channel service and receive callbacks
* for status changes. So notifyStoppedPlaying must still eventually be
* called to unregister the agent with the channel service.
*/
void notifyStoppedPlaying();
/**
* Notify agent that we already start producing audible data.
*
* Note : sometime audio might become silent during playing, this method is used to
* notify the actually audible state to other services which want to know
* about that, ex. tab sound indicator.
*/
void notifyStartedAudible(in uint8_t audible, in uint32_t reason);
};
|
