WebAPI/SpeakerManager

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