blob: 5dd0e6c25d2614b853657386f8ae0f099ce31f13 [file] [log] [blame]
// 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 {
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:
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);