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 を指定すると、指定されたタブ内の同じセキュリティ オリジンを持つ任意のフレームの getUserMedia() 呼び出しで、この ID を使用できます。
• これが指定されていない場合、Chrome 116 以降では、呼び出し元と同じレンダリング プロセスで、同じセキュリティ オリジンを持つすべてのフレームで ID を使用できます。つまり、Service Worker で取得したストリーム ID を画面外のドキュメントで使用できます。

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

詳細

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

型

CaptureInfo

プロパティ

• 全画面表示

  boolean

  キャプチャ対象のタブの要素が全画面モードかどうか。

• status

  TabCaptureState

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

• tabId

  数値

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

CaptureOptions

プロパティ

• 使った

  ブール値（省略可）

• audioConstraints

  MediaStreamConstraint 省略可

• 動画

  ブール値（省略可）

• videoConstraints

  MediaStreamConstraint 省略可

GetMediaStreamOptions

Chrome 71 以降

プロパティ

• consumerTabId

  number（省略可）

  後で getUserMedia() を呼び出してストリームを使用するタブのオプションのタブ ID。指定しなかった場合、結果のストリームは呼び出し元の拡張機能でのみ使用できます。ストリームは、セキュリティ オリジンが [ユーザー] タブのオリジンと一致する特定のタブのフレームでのみ使用できます。タブのオリジンは安全なオリジン（HTTPS など）である必要があります。

• targetTabId

  number（省略可）

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

MediaStreamConstraint

プロパティ

• 必須

  オブジェクト

• 省略可

  オブジェクト 省略可

TabCaptureState

Enum

"error"

Methods

capture()

フォアグラウンドのみ

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

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

パラメータ

• オプション

  CaptureOptions

  返されるメディア ストリームを設定します。

• callback

  機能

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

  (stream: LocalMediaStream)=>void

  • ストリーム

    LocalMediaStream

getCapturedTabs()

Promise

chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

キャプチャをリクエストしたタブやキャプチャ中のタブのリストを返します（例: status != stopped および status != error）。これにより、拡張機能は、新しいタブのキャプチャの成功を妨げる既存のタブキャプチャがあることをユーザーに通知できます（または、同じタブに対する重複リクエストを防止できます）。

パラメータ

• callback

  関数（省略可）

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

  (result: CaptureInfo[])=>void

  • 件の結果

    CaptureInfo[]

戻り値

• Promise<CaptureInfo[]>

  Chrome 116 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

getMediaStreamId()

Promise Chrome 71 以降

chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

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

パラメータ

• オプション

  GetMediaStreamOptions 省略可

• callback

  関数（省略可）

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

  (streamId: string)=>void

  • streamId

    文字列

戻り値

• Promise<文字列>

  Chrome 116 以降

  Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

イベント

onStatusChanged

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

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

パラメータ

• callback

  機能

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

  (info: CaptureInfo)=>void

  • 情報

    CaptureInfo