chrome.tabCapture

説明

chrome.tabCapture API を使用してタブのメディア ストリームを操作します。

権限

tabCapture

概要

chrome.tabCapture API を使用すると、現在のタブの動画と音声を含む MediaStream にアクセスできます。この関数は、ユーザーが拡張機能のアクション ボタンをクリックするなどして拡張機能を呼び出した後にのみ呼び出すことができます。これは activeTab 権限の動作と似ています。

システム音声の保持

タブの MediaStream が取得されると、そのタブの音声はユーザーに再生されなくなります。これは、suppressLocalAudioPlayback フラグが true に設定されている場合の getDisplayMedia() 関数の動作に似ています。

ユーザーに音声を再生し続けるには、次のものを使用します。

const output = new AudioContext();
const source = output.createMediaStreamSource(stream);
source.connect(output.destination);

これにより、新しい AudioContext が作成され、タブの MediaStream の音声がデフォルトの宛先に接続されます。

ストリーム ID

chrome.tabCapture.getMediaStreamId を呼び出すと、ストリーム ID が返されます。後で ID から MediaStream にアクセスするには、次のようにします。

navigator.mediaDevices.getUserMedia({
  audio: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
  video: {
    mandatory: {
      chromeMediaSource: "tab",
      chromeMediaSourceId: id,
    },
  },
});

使用制限

getMediaStreamId() を呼び出した後、返されたストリーム ID を使用できる場所には制限があります。

  • consumerTabId が指定されている場合、ID は、同じセキュリティ オリジンを持つ指定されたタブの任意のフレームの getUserMedia() 呼び出しで使用できます。
  • 指定されていない場合、Chrome 116 以降では、呼び出し元と同じレンダリング プロセスで同じセキュリティ オリジンを持つ任意のフレームで ID を使用できます。つまり、サービス ワーカーで取得したストリーム ID をオフスクリーン ドキュメントで使用できます。

Chrome 116 より前では、consumerTabId が指定されていない場合、ストリーム ID は呼び出し元のセキュリティ オリジン、レンダリング プロセス、レンダリング フレームの両方に制限されていました。

その他の情報

chrome.tabCapture API の使用方法について詳しくは、音声録音と画面キャプチャをご覧ください。ここでは、tabCapture と関連する API を使用して、一般的なユースケースを解決する方法を示します。

型

CaptureInfo

プロパティ

  • 全画面表示

    ブール値

    キャプチャされるタブ内の要素が全画面モードであるかどうか。

  • ステータス

    TabCaptureState

    タブの新しいキャプチャ ステータス。

  • tabId

    数値

    ステータスが変更されたタブの ID。

CaptureOptions

プロパティ

GetMediaStreamOptions

Chrome 71 以降

プロパティ

  • consumerTabId

    number 省略可

    後で getUserMedia() を呼び出してストリームを消費するタブの省略可能なタブ ID。指定しない場合、結果のストリームは呼び出し元の拡張機能でのみ使用できます。このストリームは、指定されたタブのフレームのうち、セキュリティ オリジンがコンシューマー タブのオリジンと一致するもののみが使用できます。タブのオリジンは安全なオリジン（HTTPS など）である必要があります。

  • targetTabId

    number 省略可

    キャプチャするタブのタブ ID（省略可）。指定しない場合、現在アクティブなタブが選択されます。拡張機能に activeTab 権限が付与されているタブのみをターゲット タブとして使用できます。

MediaStreamConstraint

プロパティ

  • 必須

    オブジェクト

  • オプション

    オブジェクト 省略可

TabCaptureState

列挙型

"pending"

"active"

"stopped"

"error"

メソッド

capture()

フォアグラウンドのみ 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

現在アクティブなタブの表示領域をキャプチャします。キャプチャは、拡張機能が呼び出された後、現在アクティブなタブでのみ開始できます。これは activeTab の動作と同様です。キャプチャはタブ内のページ移動の間は維持され、タブが閉じられるか、拡張機能によってメディア ストリームが閉じられると停止します。

パラメータ

  • オプション

    CaptureOptions

    返されたメディア ストリームを構成します。

  • callback

    関数

    callback パラメータは次のようになります。 

    (stream: LocalMediaStream) => void

    • ストリーム

      LocalMediaStream

getCapturedTabs()

Promise 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
): Promise<CaptureInfo[]>

キャプチャをリクエストしたタブまたはキャプチャ中のタブのリストを返します。つまり、ステータスが stopped でもなく error でもないタブのリストを返します。これにより、拡張機能は、新しいタブのキャプチャが成功しない原因となる既存のタブのキャプチャがあることをユーザーに通知できます（または、同じタブに対する冗長なリクエストを防ぐことができます）。

パラメータ

  • callback

    関数 省略可

    callback パラメータは次のようになります。 

    (result: CaptureInfo[]) => void

戻り値

  • Promise<CaptureInfo[]>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

getMediaStreamId()

Promise Chrome 71 以降 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
): Promise<string>

ターゲット タブをキャプチャするストリーム ID を作成します。chrome.tabCapture.capture() メソッドと似ていますが、メディア ストリームではなく、メディア ストリーム ID をコンシューマー タブに返します。

パラメータ

  • オプション

    GetMediaStreamOptions 省略可

  • callback

    関数 省略可

    callback パラメータは次のようになります。 

    (streamId: string) => void

    • streamId

      文字列

戻り値

  • Promise<string>

    Chrome 116 以降

    Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。

イベント

onStatusChanged

chrome.tabCapture.onStatusChanged.addListener(
  callback: function,
)

タブのキャプチャ ステータスが変更されたときに発生するイベント。これにより、拡張機能の作成者はタブのキャプチャ ステータスを追跡し、ページ アクションなどの UI 要素を同期させることができます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (info: CaptureInfo) => void