Final cleanup pass over audio device API

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.
@@ skipping 63 matching lines @@
     // 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 DeviceFilter {
+    // If set, only audio devices whose stream type is included in this list
+    // will satisfy the filter.
+    StreamType[]? streamTypes;
+
+    // If set, only audio devices whose active state matches this value will
+    // satisfy the filter.
+    boolean? isActive;
+  };
+
   dictionary DeviceProperties {
     // True if this is muted.
     [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;
+    [deprecated="Use |level| to set output volume."] double? volume;

[Devlin, 2017/02/10 20:24:29]

Remind me - what's the plan for removing these?

[tbarzic, 2017/02/10 21:05:18]

I'll send out a cl that makes these available only to currently whitelisted app
(https://codereview.chromium.org/2688773002/); I'll remove them when the current
usages are migrated (I'm not completely certain on timing of that, though).

+
     // 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;
+    [deprecated="Use |level| to set input gain."] double? gain;
+ 
+    // <p>
+    //   The audio device's desired sound level. Defaults to the device's
+    //   current sound level.
+    // </p> 
+    // <p>If used with audio input device, represents audio device gain.</p>
+    // <p>If used with audio output device, represents audio device volume.</p>
+    long? level;

[Devlin, 2017/02/10 20:24:29]

Would it make sense to rename gain/volume on the device infos to level?  WDYT?

[tbarzic, 2017/02/10 21:05:18]

Those are actually also deprecated - they're only used with audio.getInfo.
(AudioDeviceInfo already uses level).

   };
 
   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 {
     // The type of the stream for which the mute value changed. The updated mute
     // value applies to all devices with this stream type.
     StreamType streamType;
 
     // Whether or not the stream is now muted.
     boolean isMuted;
   };
 
+  dictionary LevelChangedEvent {
+    // ID of device whose sound level has changed.
+    DOMString deviceId;
+
+    // The device's new sound level.
+    long level;
+  };
+
   callback GetInfoCallback = void(OutputDeviceInfo[] outputInfo,
                                   InputDeviceInfo[] inputInfo);
+  callback GetDevicesCallback = void(AudioDeviceInfo[] devices);
+  callback GetMuteCallback = void(boolean value);
   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);
+    // Gets a list of audio devices filtered based on |filter|.
+    // |filter|: Device properties by which to filter the list of returned
+    //     audio devices. Use <code>{}</code> to get all available audio
+    //     devices.
+    // |callback|: Reports the requested list of audio devices. 
+    static void getDevices(DeviceFilter filter, GetDevicesCallback callback);

[Devlin, 2017/02/10 20:24:29]

should filter be optional?

[tbarzic, 2017/02/10 21:05:18]

I slightly prefer it not being optional, but I can make it optional if you
prefer it like that.

[Devlin, 2017/02/13 23:18:09]

If there's no reason to require it, it seems odd to force developers to specify
{} (since we don't do that most places).  I'd say it should be optional.

[tbarzic, 2017/02/14 00:27:13]

OK, done.

 
     // 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.
+    //     $(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 the 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 state should be set.
     // |isMuted|: New mute value.
     static void setMute(StreamType streamType,
                         boolean isMuted,
                         optional EmptyCallback callback);
+
+    // Gets the information of all audio output and input devices.
+    [deprecated="Use $(ref:getDevices) instead."]
+    static void getInfo(GetInfoCallback callback);
   };
 
   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);
+    static void onLevelChanged(LevelChangedEvent event);
 
     // Fired when the mute state of the audio input or output changes.
     // 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);
 
     // 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);

[Devlin, 2017/02/10 20:24:29]

Did we check that no one is currently using this event?  Is that why the name is
changed, instead of deprecated?

[tbarzic, 2017/02/10 21:05:18]

yes, I checked the event is not currently in use.

+    static void onDeviceListChanged(AudioDeviceInfo[] devices);
+
+    // Fired when anything changes to the audio device configuration.
+    [deprecated="Use more granular $(ref:onLevelChanged),
+                 $(ref:onMuteChanged) and $(ref:onDeviceListChanged) instead."]
+    static void onDeviceChanged();
   };
 };