1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
// 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);
};
};
|
