dom/audiochannel/nsIAudioChannelAgent.idl
author Mozilla Releng Treescript <release+treescript@mozilla.org>
Fri, 05 Mar 2021 19:00:18 +0000
changeset 635466 8de0bcd695eb843bfdf551ed86bccd612fbfba72
parent 580119 769dc257c2ba68ad22b365529911b1be53b8b8e9
permissions -rw-r--r--
no bug - Bumping Firefox l10n changesets r=release a=l10n-bump cy -> 7c9ee1d240d733756ac1d57db603bb7ce1b31ac8 de -> fc79f430a1a2bbeaf5fc5e7c6007584eef4814d8 dsb -> c62b593074d828a01e14a10b7d5400f8161b684e en-GB -> 11251d0bee34b3970506646dab241af73caaf3ff es-AR -> 840ecc44aa14aa1f3c51e8307ecfdd9016fee53c fa -> 9122ab2a8c096c8e5d4aeb9792e13fe77812e5dc gn -> 54e05d70d159b502a983a22ef77a6e22f5a9c1d2 hsb -> 49797cdb8e1f9775bada8e2d85c3a098633aa5b0 ia -> f973e894eedb3c9f692632377c064cacd3a56165 it -> e80120436229ce8febc8ef5801bea5311a87d941 kab -> 42c13f4608f8c7a917d7abcdf36fc9da12c70e8c kk -> 54b061ce346c3cdaa9df23a5c2b1a2f5a5e9cd2a ko -> b312d7a036bd8b8716c4bb7ebd21369827bd2e18 nl -> 10ca045e001682fb7cf69c16beac98051209c893 oc -> 2e25e1e9273ec907071d3afee44d00ca35dc0617 rm -> 7f4d395a08e74859ff0fb947249dd7536f2a91a7 sv-SE -> 583d2dbb8fe04eafc5b4e927823736ecd07620ee tr -> 50700d3abdf3d019c54cd93f1f0af7bd7648e6b0 uk -> f88cf7af88a9d1962f11f073c406486cbb3bfe38 zh-CN -> 59df069c5736df81677f3988278f754b178eafd3

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface mozIDOMWindow;

typedef uint32_t nsSuspendedTypes;

[scriptable, builtinclass, uuid(2822a840-f009-11e5-a837-0800200c9a66)]
interface nsISuspendedTypes : nsISupports
{
  /**
   * The suspended enum is used for delaying autoplay video in non-visited tab
   *
   * Note: the "remote side" must control the AudioChannelAgent using
   * nsIAudioChannelAgentCallback.windowSuspendChanged() callback instead using
   * play/pause methods or any button in the webpage.
   *
   * - SUSPENDED_BLOCK
   * It's used to prevent auto-playing media in inactive page in order to
   * reduce the power consumption, and the media can't be resumed until the
   * page becomes active again. It would change the internal state of
   * MediaElement when it's being blocked/resumed, so it won't trigger the
   * related JS event. eg. "play" and "pause" event.
   */

  const uint32_t NONE_SUSPENDED             = 0;
  const uint32_t SUSPENDED_BLOCK            = 1;
};

[uuid(15c05894-408e-4798-b527-a8c32d9c5f8c)]
interface nsIAudioChannelAgentCallback : nsISupports
{
  /**
   * Notified when the window volume/mute is changed
   */
  void windowVolumeChanged(in float aVolume, in bool aMuted);

   /**
   * Notified when the window needs to be suspended or resumed.
   */
  void windowSuspendChanged(in uint32_t aSuspend);

  /**
   * Notified when the capture state is changed.
   */
  void windowAudioCaptureChanged(in bool aCapture);
};

/**
 * This interface provides an agent for gecko components to participate
 * in the audio channel service. Gecko components are responsible for
 *   1. Notifying the agent when they start/stop using this channel.
 *   2. Notifying the agent when they are audible.
 *
 * The agent will invoke a callback to notify Gecko components of
 *   1. Changes to the playable status of this channel.
 */

[uuid(4d212770-5d7b-446f-9394-632e351d96ee)]
interface nsIAudioChannelAgent : nsISupports
{
  const long AUDIO_AGENT_STATE_NORMAL               = 0;
  const long AUDIO_AGENT_STATE_MUTED                = 1;
  const long AUDIO_AGENT_STATE_FADED                = 2;

  /**
   * Initialize the agent with a channel type.
   * Note: This function should only be called once.
   *
   * @param window
   *    The window
   * @param callback
   *    1. Once the playable status changes, agent uses this callback function
   *       to notify Gecko component.
   *    2. The callback is allowed to be null. Ex: telephony doesn't need to
   *       listen change of the playable status.
   *    3. The AudioChannelAgent keeps a strong reference to the callback
   *       object.
   */
  void init(in mozIDOMWindow window, in nsIAudioChannelAgentCallback callback);

  /**
   * This method is just like init(), except the audio channel agent keeps a
   * weak reference to the callback object.
   *
   * In order for this to work, |callback| must implement
   * nsISupportsWeakReference.
   */
  void initWithWeakCallback(in mozIDOMWindow window,
                            in nsIAudioChannelAgentCallback callback);

  /**
   * Notify the agent that we want to start playing.
   * Note: Gecko component SHOULD call this function first then start to
   *          play audio stream only when return value is true.
   */
  void notifyStartedPlaying(in uint8_t audible);

  /**
   * Notify the agent we no longer want to play.
   *
   * Note : even if notifyStartedPlaying() returned false, the agent would
   * still be registered with the audio channel service and receive callbacks
   * for status changes. So notifyStoppedPlaying must still eventually be
   * called to unregister the agent with the channel service.
   */
  void notifyStoppedPlaying();


  /**
   * Notify agent that we already start producing audible data.
   *
   * Note : sometime audio might become silent during playing, this method is used to
   * notify the actually audible state to other services which want to know
   * about that, ex. tab sound indicator.
   */
  void notifyStartedAudible(in uint8_t audible, in uint32_t reason);
};