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 requesting process.
   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 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   dictionary RequestInfo {
  45     // The tab identifier from the chrome.tabs API, if the request is from a
  46     // tab.
  47     long? tabId;
  48     // The guest process id for the requester, if the request is from a
  49     // webview.
  50     long? guestProcessId;
  51   };
  52
  53   interface Functions {
  54     // Retrieves a list of available audio sink devices.
  55     static void getSinks(GetSinksCallback callback);
  56
  57     // Retrieves the currently active audio sink for the given requesting
  58     // process.
  59     static void getActiveSink(RequestInfo request,
  60                               SinkIdCallback callback);
  61
  62     // Sets the active audio sink device for the specified requesting process.
  63     static void setActiveSink(RequestInfo request,
  64                               DOMString sinkId,
  65                               optional CompletionCallback callback);
  66
  67     // Given a security origin and an input device ID valid for that
  68     // security origin, retrieve an audio sink ID valid for the
  69     // extension, or the empty string if there is no associated audio
  70     // sink.
  71     //
  72     // The associated sink ID can be used as a sink ID for
  73     // setActiveSink. It is valid irrespective of which process you are
  74     // setting the active sink for.
  75     static void getAssociatedSink(DOMString securityOrigin,
  76                                   DOMString sourceIdInOrigin,
  77                                   SinkIdCallback cb);
  78   };
  79
  80   interface Events {
  81     // Fired when audio sink devices are added or removed.
  82     static void onSinksChanged();
  83   };
  84 };