chrome/common/extensions/api/tab_capture.idl

// Copyright (c) 2012 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.

// Use the <code>chrome.tabCapture</code> API to interact with tab media
// streams.
namespace tabCapture {

  enum TabCaptureState {
    pending,
    active,
    stopped,
    error
  };

  dictionary CaptureInfo {
    // The id of the tab whose status changed.
    long tabId;

    // The new capture status of the tab.
    TabCaptureState status;

    // Whether an element in the tab being captured is in fullscreen mode.
    boolean fullscreen;
  };

  // MediaTrackConstraints for the media streams that will be passed to WebRTC.
  // See section on MediaTrackConstraints:
  // http://dev.w3.org/2011/webrtc/editor/getusermedia.html
  dictionary MediaStreamConstraint {
    object mandatory;
    object? _optional;
  };

  // Whether we are requesting tab video and/or audio and the
  // MediaTrackConstraints that should be set for these streams.
  dictionary CaptureOptions {
    boolean? audio;
    boolean? video;
    MediaStreamConstraint? audioConstraints;
    MediaStreamConstraint? videoConstraints;
    [nodoc] DOMString? presentationId;
  };

  dictionary GetMediaStreamOptions {
    // Optional tab id of the tab which will later invoke
    // <code>getUserMedia()</code> to consume the stream. If not specified
    // then the resulting stream can be used only by the calling extension.
    // The stream can only be used by frames in the given tab whose security
    // origin matches the consumber tab's origin. The tab's origin must be a
    // secure origin, e.g. HTTPS.
    long? consumerTabId;

    // Optional tab id of the tab which will be captured. If not specified
    // then the current active tab will be selected. Only tabs for which the
    // extension has been granted the <code>activeTab</code> permission can be
    // used as the target tab.
    long? targetTabId;
  };

  callback GetTabMediaCallback =
      void ([instanceOf=LocalMediaStream] object stream);

  callback GetCapturedTabsCallback = void (CaptureInfo[] result);

  // To assemble MediaConstraints with this |streamId|, source type must be
  // assigned as 'tab'. For example:
  // <code>
  //   const constraints = {
  //     mandatory: {
  //       chromeMediaSource: 'tab',
  //       chromeMediaSourceId: streamId
  //     }
  //   };
  //   navigator.getUserMedia({audio: constraints, video: constraints},
  //                          successCallback, failCallback);
  // </code>
  callback GetMediaStreamIdCallback = void (DOMString streamId);

  interface Functions {
    // Captures the visible area of the currently active tab.  Capture can
    // only be started on the currently active tab after the extension has been
    // <em>invoked</em>, similar to the way that
    // <a href="activeTab#invoking-activeTab">activeTab</a> works.
    //  Capture is maintained across page navigations within
    // the tab, and stops when the tab is closed, or the media stream is closed
    // by the extension.
    //
    // |options| : Configures the returned media stream.
    // |callback| : Callback with either the tab capture MediaStream or
    //   <code>null</code>.  <code>null</code> indicates an error has occurred
    //   and the client may query chrome.runtime.lastError to access the error
    //   details.
    static void capture(CaptureOptions options,
                        GetTabMediaCallback callback);

    // Returns a list of tabs that have requested capture or are being
    // captured, i.e. status != stopped and status != error.
    // This allows extensions to inform the user that there is an existing
    // tab capture that would prevent a new tab capture from succeeding (or
    // to prevent redundant requests for the same tab).
    // |callback| : Callback invoked with CaptureInfo[] for captured tabs.
    static void getCapturedTabs(GetCapturedTabsCallback callback);

    // Creates an off-screen tab and navigates it to the given |startUrl|.
    // Then, capture is started and a MediaStream is returned via |callback|.
    //
    // Off-screen tabs are isolated from the user's normal browser experience.
    // They do not show up in the browser window or tab strip, nor are they
    // visible to extensions (e.g., via the chrome.tabs.* APIs).
    //
    // An off-screen tab remains alive until one of three events occurs: 1. All
    // MediaStreams providing its captured content are closed; 2. the page
    // self-closes (e.g., via window.close()); 3. the extension that called
    // captureOffscreenTab() is unloaded.
    //
    // Sandboxing: The off-screen tab does not have any access whatsoever to the
    // local user profile (including cookies, HTTP auth, etc.).  Instead, it is
    // provided its own sandboxed profile.  Also, it cannot access any
    // interactive resources such as keyboard/mouse input, media recording
    // devices (e.g., web cams), copy/paste to/from the system clipboard, etc.
    //
    // Note: This is a new API, currently only available in Canary/Dev channel,
    // and may change without notice.
    //
    // |options| : Constraints for the capture and returned MediaStream.
    // |callback| : Callback with either the tab capture MediaStream or
    //   <code>null</code>.  <code>null</code> indicates an error has occurred
    //   and the client may query chrome.runtime.lastError to access the error
    //   details.
    static void captureOffscreenTab(DOMString startUrl,
                                    CaptureOptions options,
                                    GetTabMediaCallback callback);

    // Creates a stream ID to capture the target tab.
    // Similar to chrome.tabCapture.capture() method, but returns a media
    // stream ID, instead of a media stream, to the consumer tab.
    //
    // |GetMediaStreamOptions| : Options for the media stream id to retrieve.
    // |callback| : Callback to invoke with the result. If successful, the
    // result is an opaque string that can be passed to the
    // <code>getUserMedia()</code> API to generate a media stream that
    // corresponds to the target tab. The created <code>streamId</code> can
    // only be used once and expires after a few seconds if it is not used.
    static void getMediaStreamId(optional GetMediaStreamOptions options,
                                 GetMediaStreamIdCallback callback);
  };

  interface Events {
    // Event fired when the capture status of a tab changes.
    // This allows extension authors to keep track of the capture status of
    // tabs to keep UI elements like page actions in sync.
    // |info| : CaptureInfo with new capture status for the tab.
    static void onStatusChanged(CaptureInfo info);
  };

};