1// Copyright (c) 2012 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// Use the <code>chrome.tabCapture</code> API to interact with tab media
6// streams.
7namespace tabCapture {
8
9  enum TabCaptureState {
10    pending,
11    active,
12    stopped,
13    error
14  };
15
16  dictionary CaptureInfo {
17    // The id of the tab whose status changed.
18    long tabId;
19
20    // The new capture status of the tab.
21    TabCaptureState status;
22
23    // Whether an element in the tab being captured is in fullscreen mode.
24    boolean fullscreen;
25  };
26
27  // MediaTrackConstraints for the media streams that will be passed to WebRTC.
28  // See section on MediaTrackConstraints:
29  // http://dev.w3.org/2011/webrtc/editor/getusermedia.html
30  dictionary MediaStreamConstraint {
31    object mandatory;
32    object? _optional;
33  };
34
35  // Whether we are requesting tab video and/or audio and the
36  // MediaTrackConstraints that should be set for these streams.
37  dictionary CaptureOptions {
38    boolean? audio;
39    boolean? video;
40    MediaStreamConstraint? audioConstraints;
41    MediaStreamConstraint? videoConstraints;
42  };
43
44  callback GetTabMediaCallback =
45      void ([instanceOf=LocalMediaStream] object stream);
46
47  callback GetCapturedTabsCallback = void (CaptureInfo[] result);
48
49  interface Functions {
50    // Captures the visible area of the currently active tab.
51    // This method can only be used on the currently active page after the
52    // extension has been <em>invoked</em>, similar to the way that
53    // <a href="activeTab.html">activeTab</a> works.
54    // |options| : Configures the returned media stream.
55    // |callback| : Callback with either the stream returned or null.
56    static void capture(CaptureOptions options,
57                        GetTabMediaCallback callback);
58
59    // Returns a list of tabs that have requested capture or are being
60    // captured, i.e. status != stopped and status != error.
61    // This allows extensions to inform the user that there is an existing
62    // tab capture that would prevent a new tab capture from succeeding (or
63    // to prevent redundant requests for the same tab).
64    static void getCapturedTabs(GetCapturedTabsCallback callback);
65  };
66
67  interface Events {
68    // Event fired when the capture status of a tab changes.
69    // This allows extension authors to keep track of the capture status of
70    // tabs to keep UI elements like page actions and infobars in sync.
71    static void onStatusChanged(CaptureInfo info);
72  };
73
74};
75