WebAPI/SpeakerManager

From MozillaWiki
Jump to: navigation, search

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