chrome.audio API: treat mute as system wide property

extensions/common/api/audio.idl

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // The <code>chrome.audio</code> API is provided to allow users to
 // get information about and control the audio devices attached to the
 // 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;
     // The user-friendly name (e.g. "Bose Amplifier").
     DOMString name;
     // True if this is the current active device.
     boolean isActive;
     // True if this is muted.
     boolean isMuted;
     // The output volume ranging from 0.0 to 100.0.
     double volume;
   };
 
   dictionary InputDeviceInfo {
     // The unique identifier of the audio input device.
     DOMString id;
     // The user-friendly name (e.g. "USB Microphone").
     DOMString name;
     // True if this is the current active device.
     boolean isActive;
     // True if this is muted.
     boolean isMuted;
     // The input gain ranging from 0.0 to 100.0.
     double gain;
   };
 
   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".
     DOMString deviceType;
     // The user-friendly name (e.g. "USB Microphone").
     DOMString displayName;
     // Device name.
     DOMString deviceName;
     // True if this is the current active device.
     boolean isActive;
     // True if this is muted.
     boolean isMuted;
     // The sound level of the device, volume for output, gain for input.
     long level;
     // The stable/persisted device id string when available.
     DOMString? stableDeviceId;
   };
 
   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;
     // If this is an input device then this field indicates the input gain.
     // If this is an output device then this field is ignored.
     double? gain;
   };
 
   dictionary DeviceIdLists {
     // <p>List of input devices specified by their ID.</p>
     // <p>To indicate input devices should be unaffected, leave this property
     //   unset.</p>
     DOMString[]? input;
 
     // <p>List of output devices specified by their ID.</p>
     // <p>To indicate output devices should be unaffected, leave this property
     //   unset.</p>
     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.
     static void getInfo(GetInfoCallback callback);
 
     // Sets lists of active input and/or output devices.
     // |ids|: <p>Specifies IDs of devices that should be active. If either the
     //     input or output list is not set, devices in that category are
     //     unaffected.
     //     </p>
     //     <p>It is an error to pass in a non-existent device ID.</p>
     //     <p><b>NOTE:</b> While the method signature allows device IDs to be
     //     passed as a list of strings, this method of setting active devices
     //     is deprecated and should not be relied upon to work. Please use
     //     $(ref: DeviceIdLists) instead.
     //     </p>
     static void setActiveDevices((DeviceIdLists or DOMString[]) ids,
                                  EmptyCallback callback);
 
     // Sets the properties for the input or output device.
     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 {
     // Fired when anything changes to the audio device configuration.
     static void onDeviceChanged();
 
     // Fired when sound level changes for an active audio device.
     // |id|: id of the audio device.
     // |level|: new sound level of device(volume for output, gain for input).
     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.
     // |devices|: List of all present audio devices after the change.
     static void OnDevicesChanged(AudioDeviceInfo[] devices);
   };
 };