blob: c744cffb8531058d56333bb9d10fd32b9bfab930 [file] [log] [blame]
// Copyright 2012 The Chromium Authors
// 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 $(ref: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.
[supportsPromises] static void getCapturedTabs(
GetCapturedTabsCallback 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.
[supportsPromises] 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);