dom/audiochannel/nsIAudioChannelAgent.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface mozIDOMWindow;
   8
   9 typedef uint32_t nsSuspendedTypes;
  10
  11 [scriptable, builtinclass, uuid(2822a840-f009-11e5-a837-0800200c9a66)]
  12 interface nsISuspendedTypes : nsISupports
  13 {
  14   /**
  15    * The suspended enum is used for delaying autoplay video in non-visited tab
  16    *
  17    * Note: the "remote side" must control the AudioChannelAgent using
  18    * nsIAudioChannelAgentCallback.windowSuspendChanged() callback instead using
  19    * play/pause methods or any button in the webpage.
  20    *
  21    * - SUSPENDED_BLOCK
  22    * It's used to prevent auto-playing media in inactive page in order to
  23    * reduce the power consumption, and the media can't be resumed until the
  24    * page becomes active again. It would change the internal state of
  25    * MediaElement when it's being blocked/resumed, so it won't trigger the
  26    * related JS event. eg. "play" and "pause" event.
  27    */
  28
  29   const uint32_t NONE_SUSPENDED             = 0;
  30   const uint32_t SUSPENDED_BLOCK            = 1;
  31 };
  32
  33 [uuid(15c05894-408e-4798-b527-a8c32d9c5f8c)]
  34 interface nsIAudioChannelAgentCallback : nsISupports
  35 {
  36   /**
  37    * Notified when the window volume/mute is changed
  38    */
  39   void windowVolumeChanged(in float aVolume, in bool aMuted);
  40
  41    /**
  42    * Notified when the window needs to be suspended or resumed.
  43    */
  44   void windowSuspendChanged(in uint32_t aSuspend);
  45
  46   /**
  47    * Notified when the capture state is changed.
  48    */
  49   void windowAudioCaptureChanged(in bool aCapture);
  50 };
  51
  52 /**
  53  * This interface provides an agent for gecko components to participate
  54  * in the audio channel service. Gecko components are responsible for
  55  *   1. Notifying the agent when they start/stop using this channel.
  56  *   2. Notifying the agent when they are audible.
  57  *
  58  * The agent will invoke a callback to notify Gecko components of
  59  *   1. Changes to the playable status of this channel.
  60  */
  61
  62 [uuid(4d212770-5d7b-446f-9394-632e351d96ee)]
  63 interface nsIAudioChannelAgent : nsISupports
  64 {
  65   const long AUDIO_AGENT_STATE_NORMAL               = 0;
  66   const long AUDIO_AGENT_STATE_MUTED                = 1;
  67   const long AUDIO_AGENT_STATE_FADED                = 2;
  68
  69   /**
  70    * Initialize the agent with a channel type.
  71    * Note: This function should only be called once.
  72    *
  73    * @param window
  74    *    The window
  75    * @param callback
  76    *    1. Once the playable status changes, agent uses this callback function
  77    *       to notify Gecko component.
  78    *    2. The callback is allowed to be null. Ex: telephony doesn't need to
  79    *       listen change of the playable status.
  80    *    3. The AudioChannelAgent keeps a strong reference to the callback
  81    *       object.
  82    */
  83   void init(in mozIDOMWindow window, in nsIAudioChannelAgentCallback callback);
  84
  85   /**
  86    * This method is just like init(), except the audio channel agent keeps a
  87    * weak reference to the callback object.
  88    *
  89    * In order for this to work, |callback| must implement
  90    * nsISupportsWeakReference.
  91    */
  92   void initWithWeakCallback(in mozIDOMWindow window,
  93                             in nsIAudioChannelAgentCallback callback);
  94
  95   /**
  96    * Notify the agent that we want to start playing.
  97    * Note: Gecko component SHOULD call this function first then start to
  98    *          play audio stream only when return value is true.
  99    */
 100   void notifyStartedPlaying(in uint8_t audible);
 101
 102   /**
 103    * Notify the agent we no longer want to play.
 104    *
 105    * Note : even if notifyStartedPlaying() returned false, the agent would
 106    * still be registered with the audio channel service and receive callbacks
 107    * for status changes. So notifyStoppedPlaying must still eventually be
 108    * called to unregister the agent with the channel service.
 109    */
 110   void notifyStoppedPlaying();
 111
 112
 113   /**
 114    * Notify agent that we already start producing audible data.
 115    *
 116    * Note : sometime audio might become silent during playing, this method is used to
 117    * notify the actually audible state to other services which want to know
 118    * about that, ex. tab sound indicator.
 119    */
 120   void notifyStartedAudible(in uint8_t audible, in uint32_t reason);
 121 };