WebAPI/SpeakerManager: Difference between revisions
< WebAPI
No edit summary |
|||
| (5 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
== Speaker Control API == | == Speaker Control API == | ||
General Use Cases: Allow application can output | General Use Cases: Allow application can control acoustic sound output through speaker. | ||
==Proposed API== | ==Proposed API== | ||
| Line 10: | Line 10: | ||
attribute boolean forcespeaker; | attribute boolean forcespeaker; | ||
/* this event will be fired when force speaker status change */ | /* this event will be fired when force speaker status change */ | ||
attribute EventHandler | attribute EventHandler onspeakerforcedchange; | ||
}; | }; | ||
| Line 17: | Line 17: | ||
var sm = new MozSpeakerManager(); | var sm = new MozSpeakerManager(); | ||
// fired anytime when device's speaker status changed | // fired anytime when device's speaker status changed | ||
sm. | sm.onspeakerforcedchange = function() { | ||
bool enabled = sm.speakerforced; | bool enabled = sm.speakerforced; | ||
// Refresh UI | // Refresh UI | ||
return; | |||
} | } | ||
if (sm.speakerforced) { | if (sm.speakerforced) { | ||
| Line 26: | Line 27: | ||
sm.forcespeaker = true; | sm.forcespeaker = true; | ||
} | } | ||
== Use cases == | == Use cases == | ||
*Listen to FM Radio and want to output sounds to speaker audio path. | *Listen to FM Radio and want to output sounds to speaker audio path. | ||
* | *Dialer can force output sound from earpiece to speaker | ||
== Behavior == | == Behavior == | ||
| Line 36: | Line 38: | ||
*If a background app calls forcespeaker=true that doesn't change anything. 'speakerforced' remains false everywhere. | *If a background app calls forcespeaker=true that doesn't change anything. 'speakerforced' remains false everywhere. | ||
*If an app that has called forcespeaker=true, but no audio is currently playing in the app itself, is switched to the background we switch 'speakerforced' to false in all apps. | *If an app that has called forcespeaker=true, but no audio is currently playing in the app itself, is switched to the background we switch 'speakerforced' to false in all apps. | ||
*If an app that has called forcespeaker | *If an app that has called forcespeaker=true, and audio is currently playing in the app itself, is switched to the background 'speakerforced' remains true in all apps. If/when the app stops playing audio, 'speakerforced' switches to false in all apps. | ||
*If an app that has called forcespeaker=true is switched from the background to the foreground 'speakerforced' switches to true in all apps. I.e. the app doesn't have to call forcespeaker=true again when it comes into foreground. | |||
*If an app that has called forcespeaker=true is switched from the background to the foreground 'speakerforced' switches to true in all apps. I.e. the app doesn't have to call forcespeaker | |||
=== Permissions Table=== | === Permissions Table=== | ||
| Line 52: | Line 53: | ||
| Installed Web Apps || None || No access | | Installed Web Apps || None || No access | ||
|- | |- | ||
| Privileged Web Apps || | | Privileged Web Apps || General use cases || Implicit | ||
|- | |- | ||
| Certified Web Apps || General use cases || Implicit | | Certified Web Apps || General use cases || Implicit | ||
|} | |} | ||
[[Category:Web APIs]] | |||
Latest revision as of 23:21, 1 October 2014
Speaker Control API
General Use Cases: Allow application can control acoustic sound output through speaker.
Proposed API
[Constructor()]
interface MozSpeakerManager : EventTarget {
/* query the speaker status */
readonly attribute boolean speakerforced;
/* force the device's sound go through speaker */
attribute boolean forcespeaker;
/* this event will be fired when force speaker status change */
attribute EventHandler onspeakerforcedchange;
};
Example:Turn on speaker
var sm = new MozSpeakerManager();
// fired anytime when device's speaker status changed
sm.onspeakerforcedchange = function() {
bool enabled = sm.speakerforced;
// Refresh UI
return;
}
if (sm.speakerforced) {
// device's speaker is on
} else {
sm.forcespeaker = true;
}
Use cases
- Listen to FM Radio and want to output sounds to speaker audio path.
- Dialer can force output sound from earpiece to speaker
Behavior
- speakerforced reflects phone status. I.e. if the speaker is currently forced on then this always returns true, no matter which app forced the speaker to be on.
- onspeakerforcedchange fires anytime speakerforced changes.
- forcespeaker=true means that this app attempts to force the speaker to be on. This is only honored if the app is currently in the foreground. So if a foreground app calls forcespeaker=true that means that 'speakerforced' in all applications switches to true, and any audio from any application will go to the speaker.
- If a background app calls forcespeaker=true that doesn't change anything. 'speakerforced' remains false everywhere.
- If an app that has called forcespeaker=true, but no audio is currently playing in the app itself, is switched to the background we switch 'speakerforced' to false in all apps.
- If an app that has called forcespeaker=true, and audio is currently playing in the app itself, is switched to the background 'speakerforced' remains true in all apps. If/when the app stops playing audio, 'speakerforced' switches to false in all apps.
- If an app that has called forcespeaker=true is switched from the background to the foreground 'speakerforced' switches to true in all apps. I.e. the app doesn't have to call forcespeaker=true again when it comes into foreground.
Permissions Table
| Type | Use Cases | Authorization Model | Notes & Other Controls |
|---|---|---|---|
| Web Content | None | No access | |
| Installed Web Apps | None | No access | |
| Privileged Web Apps | General use cases | Implicit | |
| Certified Web Apps | General use cases | Implicit |