chrome.tabCapture

Description:	Use the `chrome.tabCapture` API to interact with tab media streams.
Availability:	Since Chrome 35.
Permissions:	"tabCapture"

Summary

Types
CaptureInfo
MediaStreamConstraint
CaptureOptions
Methods
capture − `chrome.tabCapture.capture( CaptureOptions options, function callback)`
getCapturedTabs − `chrome.tabCapture.getCapturedTabs(function callback)`
captureOffscreenTab − `chrome.tabCapture.captureOffscreenTab(string startUrl, CaptureOptions options, function callback)`
getMediaStreamId − `chrome.tabCapture.getMediaStreamId(object options, function callback)`
Events
onStatusChanged

Types

CaptureInfo

properties
integer	tabId	The id of the tab whose status changed.
enum of `"pending"`, `"active"`, `"stopped"`, or `"error"`	status	The new capture status of the tab.
boolean	fullscreen	Whether an element in the tab being captured is in fullscreen mode.

MediaStreamConstraint

properties
object	mandatory
object	(optional) optional

CaptureOptions

properties
boolean	(optional) audio
boolean	(optional) video
MediaStreamConstraint	(optional) audioConstraints
MediaStreamConstraint	(optional) videoConstraints

Methods

capture


              chrome.tabCapture.capture(    CaptureOptions options, function callback)

Captures the visible area of the currently active tab. Capture can only be started on the currently active tab after the extension has been invoked, similar to the way that activeTab 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.

Parameters

CaptureOptions

options

Configures the returned media stream.

function

callback

Callback with either the tab capture MediaStream or null. null indicates an error has occurred and the client may query runtime.lastError to access the error details.

The callback parameter should be a function that looks like this:

function(LocalMediaStream stream) {...};

LocalMediaStream

stream

getCapturedTabs


              chrome.tabCapture.getCapturedTabs(function 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).

Parameters

function

callback

Callback invoked with CaptureInfo[] for captured tabs.

The callback parameter should be a function that looks like this:

function(array of CaptureInfo result) {...};

array of CaptureInfo

result

captureOffscreenTab


              chrome.tabCapture.captureOffscreenTab(string startUrl,     CaptureOptions options, function callback)

Since Chrome 47.

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.

Parameters

string startUrl

CaptureOptions

options

Constraints for the capture and returned MediaStream.

function

callback

Callback with either the tab capture MediaStream or null. null indicates an error has occurred and the client may query runtime.lastError to access the error details.

The callback parameter should be a function that looks like this:

function(LocalMediaStream stream) {...};

LocalMediaStream

stream

getMediaStreamId


              chrome.tabCapture.getMediaStreamId(object options, function callback)

Since Chrome 71.

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.

Parameters

object

(optional) options

integer	(optional) consumerTabId	Optional tab id of the tab which will later invoke `getUserMedia()` 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.
integer	(optional) targetTabId	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 `activeTab` permission can be used as the target tab.

function

callback

Callback to invoke with the result. If successful, the result is an opaque string that can be passed to the getUserMedia() API to generate a media stream that corresponds to the target tab. The created streamId can only be used once and expires after a few seconds if it is not used.

The callback parameter should be a function that looks like this:

function(string streamId) {...};

string

streamId

Events

onStatusChanged

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.

addListener


                    chrome.tabCapture.onStatusChanged.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function( CaptureInfo info) {...};

CaptureInfo

info

CaptureInfo with new capture status for the tab.