WebAPI/SpeakerManager

Speaker Control API

General Use Cases: Allow application can output audio through speaker on b2g devices

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 onforcespeakerchange;
};

Example:Turn on speaker

var sm = new MozSpeakerManager();
// fired anytime when device's speaker status changed
sm.onforcespeakerchange = function() {
  bool enabled = sm.speakerforced;
  // Refresh UI
}
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.
• Voice call can force output sound 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	None	No access
Certified Web Apps	General use cases	Implicit