chrome/common/extensions/api/webrtc_audio_private.idl

   1 // Copyright 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.webrtcAudioPrivate</code> API allows enumeration
   6 // of audio output (sink) devices as well as getting and setting the
   7 // active device for a given tab.
   8 //
   9 // Note that device IDs as used in this API are opaque (i.e. they are
  10 // not the hardware identifier of the device) and while they are
  11 // unique and persistent across sessions, they are valid only to the
  12 // extension calling this API (i.e. they cannot be shared between
  13 // extensions).
  14 //
  15 // See http://goo.gl/8rOmgk for further documentation of this API.
  16
  17 [nodoc] namespace webrtcAudioPrivate {
  18
  19   dictionary SinkInfo {
  20     // The opaque identifier of the audio sink device, which is unique
  21     // and static for the extension calling the API but invalid for
  22     // others.
  23     DOMString sinkId;
  24     // The user-friendly name (e.g. "Bose Amplifier").
  25     DOMString sinkLabel;
  26     // Current sample rate of the device, in Hz. Useful e.g. to know
  27     // if the remote side should be asked to send a lower sampling
  28     // rate.
  29     long sampleRate;
  30     // True if the device is ready to play out audio. E.g. if it is a
  31     // device that takes an audio jack, whether a jack is plugged in.
  32     //
  33     // TODO(joi): Do unplugged devices even get included in enumeration?
  34     boolean isReady;
  35     // True if this device is the default audio sink device on the
  36     // machine.
  37     boolean isDefault;
  38   };
  39
  40   callback GetSinksCallback = void(SinkInfo[] sinkInfo);
  41   callback SinkIdCallback = void(DOMString sinkId);
  42   callback CompletionCallback = void();
  43
  44   interface Functions {
  45     // Retrieves a list of available audio sink devices.
  46     static void getSinks(GetSinksCallback callback);
  47
  48     // Retrieves the currently active audio sink for the given tab.
  49     static void getActiveSink(long tabId,
  50                               SinkIdCallback callback);
  51
  52     // Sets the active audio sink device for the specified tab.
  53     static void setActiveSink(long tabId,
  54                               DOMString sinkId,
  55                               optional CompletionCallback callback);
  56
  57     // Given a security origin and an input device ID valid for that
  58     // security origin, retrieve an audio sink ID valid for the
  59     // extension, or the empty string if there is no associated audio
  60     // sink.
  61     //
  62     // The associated sink ID can be used as a sink ID for
  63     // setActiveSink. It is valid irrespective of which tab you are
  64     // setting the active sink for.
  65     static void getAssociatedSink(DOMString securityOrigin,
  66                                   DOMString sourceIdInOrigin,
  67                                   SinkIdCallback cb);
  68   };
  69
  70   interface Events {
  71     // Fired when audio sink devices are added or removed.
  72     static void onSinksChanged();
  73   };
  74 };