Home | History | Annotate | Download | only in api 
      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 };
     75