nsIAudioChannelAgent.idl (4272B)
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 boolean 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 boolean 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 };