chrome.audio API: treat mute as system wide property

extensions/common/api/audio.idl

Index: extensions/common/api/audio.idl
diff --git a/extensions/common/api/audio.idl b/extensions/common/api/audio.idl
index 2d68b5d2c36b24f44d5d1ad4de6fcce076f0939b..592b96e0f1c7b6157b0d8d664a4b2ff21d395d1c 100644
--- a/extensions/common/api/audio.idl
+++ b/extensions/common/api/audio.idl
@@ -7,6 +7,12 @@
 // system. This API is currently only implemented for ChromeOS.
 namespace audio {
 
+  // Type of stream an audio device provides.
+  enum StreamType {
+    INPUT,
+    OUTPUT
+  };
+
   dictionary OutputDeviceInfo {
     // The unique identifier of the audio output device.
     DOMString id;
@@ -36,8 +42,10 @@ namespace audio {
   dictionary AudioDeviceInfo {
     // The unique identifier of the audio device.
     DOMString id;
+    // Stream type associated with this device (input or output).

[Devlin, 2017/01/25 16:12:24]

nit: given we specify what StreamType can be above, we shouldn't have (input or
output) here.

[tbarzic, 2017/01/25 19:32:29]

Done.

+    StreamType streamType;
     // True for input device; false for output device.
-    boolean isInput;
+    [deprecated="Use |streamType|."] boolean isInput;
     // Type of the device, including "INTERNAL_SPEAKER", "INTERNAL_MIC",
     // "HEADPHONE", "USB", "BLUETOOTH", "HDMI", "MIC", "KEYBOARD_MIC",
     // "AOKR", and "OTHER".
@@ -58,7 +66,7 @@ namespace audio {
 
   dictionary DeviceProperties {
     // True if this is muted.
-    boolean isMuted;
+    [deprecated="Use $(ref:setMute) to set mute state."] boolean? isMuted;
     // If this is an output device then this field indicates the output volume.
     // If this is an input device then this field is ignored.
     double? volume;
@@ -79,9 +87,19 @@ namespace audio {
     DOMString[]? output;
   };
 
+  dictionary MuteChangedEvent {
+    // Type of the stream for which mute value has changed. The updated mute

[Devlin, 2017/01/25 16:12:23]

nitty nit:
The type of the stream for which the mute value changed. The updated...

[tbarzic, 2017/01/25 19:32:29]

Done.

+    // value applies to all devices with this stream type.
+    StreamType streamType;
+
+    // Value to which mute state changed.

[Devlin, 2017/01/25 16:12:23]

nitty nit:
Whether or not the stream is now muted

[tbarzic, 2017/01/25 19:32:29]

Done.

+    boolean value;

[Devlin, 2017/01/25 16:12:23]

|value| is a little less descriptive than something like "isMuted"

[tbarzic, 2017/01/25 19:32:29]

Done.

+  };
+
   callback GetInfoCallback = void(OutputDeviceInfo[] outputInfo,
                                   InputDeviceInfo[] inputInfo);
   callback EmptyCallback = void();
+  callback GetMuteCallback = void(boolean value);
 
   interface Functions {
     // Gets the information of all audio output and input devices.
@@ -105,6 +123,20 @@ namespace audio {
     static void setProperties(DOMString id,
                               DeviceProperties properties,
                               EmptyCallback callback);
+
+    // Gets system-wide mute state for the specified stream type.
+    // |streamType|: Stream type for which mute state should be fetched.
+    // |callback|: Callback reporting whether mute is set or not for specified
+    // stream type.
+    static void getMute(StreamType streamType, GetMuteCallback callback);
+
+    // Sets mute state for a stream type. The mute state will apply to all audio
+    // devices with the specified audio stream type.
+    // |streamType|: Stream type for which mute status should be set.
+    // |value|: New mute value.
+    static void setMute(StreamType streamType,
+                        boolean value,
+                        EmptyCallback callback);

[Devlin, 2017/01/25 16:12:23]

can this be an optional callback?

[tbarzic, 2017/01/25 19:32:29]

Done.

   };
 
   interface Events {
@@ -117,9 +149,9 @@ namespace audio {
     static void OnLevelChanged(DOMString id, long level);
 
     // Fired when the mute state of the audio input or output changes.
-    // |isInput|: true indicating audio input; false indicating audio output.
-    // |isMuted|: new value of mute state.
-    static void OnMuteChanged(boolean isInput, boolean isMuted);
+    // Note that mute state is system-wide and the new value applies to every
+    // audio device with specified stream type.
+    static void onMuteChanged(MuteChangedEvent event);

[Devlin, 2017/01/25 16:12:23]

Are we okay with this breaking change since this API isn't publicly available? 
If so, can we just remove the [deprecated=] properties above?

[tbarzic, 2017/01/25 19:32:29]

We are OK with this because the event doesn't seem to be used for now (no entry
in event histograms, also nothing turns up in the code search).

Items marked deprecated are in use - note that I plan to make those nodoc when
the API goes stable.

 
     // Fired when audio devices change, either new devices being added, or
     // existing devices being removed.