extensions/common/api/audio.idl

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // The <code>chrome.audio</code> API is provided to allow users to
   6 // get information about and control the audio devices attached to the
   7 // system. This API is currently only implemented for ChromeOS.
   8 namespace audio {
   9
  10   dictionary OutputDeviceInfo {
  11     // The unique identifier of the audio output device.
  12     DOMString id;
  13     // The user-friendly name (e.g. "Bose Amplifier").
  14     DOMString name;
  15     // True if this is the current active device.
  16     boolean isActive;
  17     // True if this is muted.
  18     boolean isMuted;
  19     // The output volume ranging from 0.0 to 100.0.
  20     double volume;
  21   };
  22
  23   dictionary InputDeviceInfo {
  24     // The unique identifier of the audio input device.
  25     DOMString id;
  26     // The user-friendly name (e.g. "USB Microphone").
  27     DOMString name;
  28     // True if this is the current active device.
  29     boolean isActive;
  30     // True if this is muted.
  31     boolean isMuted;
  32     // The input gain ranging from 0.0 to 100.0.
  33     double gain;
  34   };
  35
  36   dictionary AudioDeviceInfo {
  37     // The unique identifier of the audio device.
  38     DOMString id;
  39     // True for input device; false for output device.
  40     boolean isInput;
  41     // Type of the device, including "INTERNAL_SPEAKER", "INTERNAL_MIC",
  42     // "HEADPHONE", "USB", "BLUETOOTH", "HDMI", "MIC", "KEYBOARD_MIC",
  43     // "AOKR", and "OTHER".
  44     DOMString deviceType;
  45     // The user-friendly name (e.g. "USB Microphone").
  46     DOMString displayName;
  47     // Device name.
  48     DOMString deviceName;
  49     // True if this is the current active device.
  50     boolean isActive;
  51     // True if this is muted.
  52     boolean isMuted;
  53     // The sound level of the device, volume for output, gain for input.
  54     long level;
  55     // The stable/persisted device id string when available.
  56     DOMString? stableDeviceId;
  57   };
  58
  59   dictionary DeviceProperties {
  60     // True if this is muted.
  61     boolean isMuted;
  62     // If this is an output device then this field indicates the output volume.
  63     // If this is an input device then this field is ignored.
  64     double? volume;
  65     // If this is an input device then this field indicates the input gain.
  66     // If this is an output device then this field is ignored.
  67     double? gain;
  68   };
  69
  70   callback GetInfoCallback = void(OutputDeviceInfo[] outputInfo,
  71                                   InputDeviceInfo[] inputInfo);
  72   callback SetActiveDevicesCallback = void();
  73   callback SetPropertiesCallback = void();
  74
  75   interface Functions {
  76     // Gets the information of all audio output and input devices.
  77     static void getInfo(GetInfoCallback callback);
  78
  79   // Sets the active devices to the devices specified by |ids|.
  80   // It can pass in the "complete" active device id list of either input
  81   // devices, or output devices, or both. If only input device ids are passed
  82   // in, it will only change the input devices' active status, output devices will
  83   // NOT be changed; similarly for the case if only output devices are passed.
  84   // If the devices specified in |new_active_ids| are already active, they will
  85   // remain active. Otherwise, the old active devices will be de-activated
  86   // before we activate the new devices with the same type(input/output).
  87     static void setActiveDevices(DOMString[] ids,
  88                                  SetActiveDevicesCallback callback);
  89
  90     // Sets the properties for the input or output device.
  91     static void setProperties(DOMString id,
  92                               DeviceProperties properties,
  93                               SetPropertiesCallback callback);
  94      };
  95
  96   interface Events {
  97     // Fired when anything changes to the audio device configuration.
  98     static void onDeviceChanged();
  99
 100     // Fired when sound level changes for an active audio device.
 101     // |id|: id of the audio device.
 102     // |level|: new sound level of device(volume for output, gain for input).
 103     static void OnLevelChanged(DOMString id, long level);
 104
 105     // Fired when the mute state of the audio input or output changes.
 106     // |isInput|: true indicating audio input; false indicating audio output.
 107     // |isMuted|: new value of mute state.
 108     static void OnMuteChanged(boolean isInput, boolean isMuted);
 109
 110     // Fired when audio devices change, either new devices being added, or
 111     // existing devices being removed.
 112     // |devices|: List of all present audio devices after the change.
 113     static void OnDevicesChanged(AudioDeviceInfo[] devices);
 114   };
 115 };