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를 사용할 수 있습니다. 즉, 서비스 워커에서 가져온 스트림 ID는 오프스크린 문서에서 사용할 수 있습니다.

Chrome 116 이전에는 consumerTabId를 지정하지 않으면 스트림 ID가 호출자의 보안 출처, 렌더링 프로세스, 렌더링 프레임으로 모두 제한되었습니다.

자세히 알아보기

chrome.tabCapture API 사용 방법에 관한 자세한 내용은 오디오 녹음 및 화면 캡처를 참고하세요. tabCapture 및 관련 API를 사용하여 여러 가지 일반적인 사용 사례를 해결하는 방법을 보여줍니다.

유형

CaptureInfo

속성

  • 전체 화면

    boolean

    캡처 중인 탭의 요소가 전체 화면 모드인지 여부입니다.

  • 탭의 새로운 캡처 상태입니다.

  • tabId

    숫자

    상태가 변경된 탭의 ID입니다.

CaptureOptions

속성

GetMediaStreamOptions

Chrome 71 이상

속성

  • consumerTabId

    number 선택사항

    스트림을 사용하기 위해 나중에 getUserMedia()를 호출할 탭의 탭 ID(선택사항)입니다. 지정하지 않으면 호출 확장 프로그램에서만 결과 스트림을 사용할 수 있습니다. 스트림은 보안 출처가 소비자 탭의 출처와 일치하는 지정된 탭의 프레임에서만 사용할 수 있습니다. 탭의 출처는 보안 출처(예: HTTPS)여야 합니다.

  • targetTabId

    number 선택사항

    캡처할 탭의 탭 ID(선택사항)입니다. 지정하지 않으면 현재 활성 탭이 선택됩니다. 확장 프로그램에 activeTab 권한이 부여된 탭만 타겟 탭으로 사용할 수 있습니다.

MediaStreamConstraint

속성

  • 필수

    객체

  • 선택 사항

    객체 선택사항

TabCaptureState

열거형

방법

capture()

포그라운드 전용 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
)

현재 활성 탭의 보이는 영역을 캡처합니다. activeTab 작동 방식과 유사하게 확장 프로그램이 호출된 후에만 현재 활성 탭에서 캡처를 시작할 수 있습니다. 캡처는 탭 내의 페이지 탐색에서 유지되고 탭이 닫히거나 확장 프로그램에 의해 미디어 스트림이 닫히면 중지됩니다.

매개변수

  • 반환된 미디어 스트림을 구성합니다.

  • 콜백

    기능

    callback 매개변수는 다음과 같습니다. 

    (stream: LocalMediaStream)=>void

    • 스트림

      LocalMediaStream

getCapturedTabs()

프로미스 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

캡처를 요청했거나 캡처 중인 탭 목록(예: status != 중지됨 및 status != error)을 반환합니다. 이렇게 하면 확장 프로그램에서 사용자에게 새 탭 캡처의 성공을 막는 (또는 동일한 탭에 대한 중복 요청을 방지)하는 기존 탭 캡처가 있음을 사용자에게 알릴 수 있습니다.

매개변수

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (result: CaptureInfo[])=>void

반환 값

  • Promise<CaptureInfo[]>

    Chrome 116 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getMediaStreamId()

Promise Chrome 71 이상 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

타겟 탭을 캡처하기 위한 스트림 ID를 만듭니다. chrome.tabCapture.capture() 메서드와 비슷하지만 미디어 스트림 대신 미디어 스트림 ID를 소비자 탭에 반환합니다.

매개변수

  • 옵션

    GetMediaStreamOptions 선택사항

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (streamId: string)=>void

    • streamId

      string

반환 값

  • 프로미스<string>

    Chrome 116 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

이벤트

onStatusChanged

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

탭의 캡처 상태가 변경되면 이벤트가 실행됩니다. 이를 통해 확장 프로그램 작성자는 탭의 캡처 상태를 추적하여 페이지 작업과 같은 UI 요소의 동기화를 유지할 수 있습니다.

매개변수