Proposal of Audio Channel Management API

proposal-of-audio-channel-managerment-api.md

Proposal of Audio Channel Management API v0.0.6

mozBrowser1 API

Properties

• mozBrowser.allowedAudioChannels: List of audio channels allowed to play. Implement this like DOMTokenList { 0: "class1", 1: "class2", 2: "class3", length: 3, add: function, remove: function, toggle: function, contains: function }2.
• mozBrowser.audioChannels['channelName'].volume: 0 to 1, set/get volumes of all allowed audio channels.
• mozBrowser.audioChannels['channelName'].paused: boolean, true means pause the playing, false means allow the playing.
• mozBrowser.activeAudioChannels: List of active audio channels.

Events

• mozaudiochannelchange: Sent when audio channel changes.

mozaudiochannelchange

Properties

Detail

• channel: A new audio channel app would like to play.
• state: States of the audio channel: start, pause and end.
• type: video or audio.

Examples

Allow a channel

app.element.addEventListener('mozaudiochannelchange', function(evt) {
  var channel = evt.detail.channel;
  app.element.allowedAudioChannels.add(channel);
});

Handle audio channel competing

var audioChannelManager = new AudioChannelManager();
// When a new app is opened, add it into AudioChannelManager.
audioChannelManager.register(newApp);

function AudioChannelManager() {
  this._playingApps = [];
}

AudioChannelManager.prototype = {
  // A list of mozBrowser elements.
  _playingApps: null,

  register: function(appElement) {
    appElement.addEventListener('mozaudiochannelchange', function(evt) {
      var channel = evt.detail.channel;

      if (this.isAllowed(channel)) {
        var playingApps = this._playingApps;

        playingApps.forEach(function(ele) {
          // Deny all channels.
          var allowedAudioChannels = ele.allowedAudioChannels;
          Array.prototype.forEach.call(allowedAudioChannels, function(channel) {
            allowedAudioChannels.remove(channel);
          });
        });
        playingApps = [];

        appElement.allowedAudioChannels.add(channel);
        playingApps.push(appElement);
      }
    });
  },

  isAllowed: function(audioChannel) {
    // Compete with `_playingApps`.
  }
};

mozAudioChannelManager6 API

Properties

• navigator.mozAudioChannelManager.volume: 0 to 1, to replace the mozSetting value of audio.volume.[channel]7.

References

• HierarchyManager3
• AudioChannelService4
• The architecture of Gaia's audio channnel manager5
• WebAPI/AudioChannels 8, 9
• Firefox Add-ons for audio channel management: FMix 10, 11
• Current audio channel management in B2G 12

Versions

• v0.0.5
• v0.0.4
• v0.0.3
• v0.0.2
• v0.0.1

Still has no idea to handle the loop issue, even we have the above APIs.

mozBrowser.allowedAudioChannels.add('content') => mozBrowser.channels.content = 1

=>

mozBrowser.allowedAudioChannels[audioChannel]
AudioChannel {
  active,
  volume,
  muted
}

mozBrowser.allowedAudioChannels['content'].muted = true; // allow the playing
mozBrowser.allowedAudioChannels['content'].muted = false; // pause the playing

mozBrowser.enable(ch)
mozBrowser.disable(ch)
mozBrowser.getChannelState(ch): enable, disable
mozBrowser.changeVolume(ch, vol)

mozaudiochannelchanged: state, ch, video