chrome.tabCapture

คำอธิบาย

ใช้ chrome.tabCapture API เพื่อโต้ตอบกับสตรีมสื่อในแท็บ

สิทธิ์

tabCapture

แนวคิดและการใช้งาน

chrome.tabCapture API ช่วยให้คุณเข้าถึง MediaStream ที่มีวิดีโอและเสียงของแท็บปัจจุบันได้ โดยสามารถเรียกใช้หลังจากที่ผู้ใช้เรียกใช้ส่วนขยายเท่านั้น เช่น ด้วยการคลิกปุ่มการทำงานของส่วนขยาย ซึ่งคล้ายกับลักษณะการทำงานของสิทธิ์ "activeTab"

รักษาเสียงของระบบ

เมื่อได้รับ MediaStream สําหรับแท็บ ผู้ใช้จะไม่เล่นเสียงในแท็บนั้นอีกต่อไป ซึ่งคล้ายกับลักษณะการทำงานของฟังก์ชัน getDisplayMedia() เมื่อตั้งค่าแฟล็ก suppressLocalAudioPlayback เป็น "จริง"

หากต้องการเล่นเสียงให้ผู้ใช้ดำเนินการต่อ ให้ใช้การตั้งค่าต่อไปนี้

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

การดำเนินการนี้จะสร้าง AudioContext ใหม่และเชื่อมต่อเสียงของ MediaStream ของแท็บกับปลายทางเริ่มต้น

รหัสสตรีม

การโทร chrome.tabCapture.getMediaStreamId() จะส่งคืนรหัสสตรีม หากต้องการเข้าถึง MediaStream จากรหัสในภายหลัง ให้ใช้รายการต่อไปนี้

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

ข้อจำกัดการใช้งาน

หลังจากโทรหา getMediaStreamId() แล้ว เราอาจใช้รหัสสตรีมที่ส่งคืนได้ดังต่อไปนี้

• หากระบุ consumerTabId แล้ว การเรียกใช้ getUserMedia() จะใช้รหัสในเฟรมใดก็ได้ในแท็บที่ระบุซึ่งมีต้นทางความปลอดภัยเดียวกัน
• หากไม่ได้ระบุไว้ ตั้งแต่ Chrome 116 เป็นต้นไป คุณจะใช้รหัสในเฟรมใดก็ได้ที่มีต้นทางความปลอดภัยเดียวกันในกระบวนการแสดงผลเดียวกันกับที่เรียกใช้ ซึ่งหมายความว่ารหัสสตรีมที่ได้รับจาก Service Worker จะใช้ในเอกสารนอกหน้าจอได้

ก่อนใช้ Chrome 116 เมื่อไม่ได้ระบุ consumerTabId รหัสสตรีมจะจำกัดไว้ทั้งสำหรับต้นทางการรักษาความปลอดภัย กระบวนการแสดงผล และเฟรมการแสดงผลของผู้โทร

ดูข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้ chrome.tabCapture API ได้ที่การบันทึกเสียงและการจับภาพหน้าจอ ภาพนี้สาธิตวิธีใช้ tabCapture และ API ที่เกี่ยวข้องเพื่อแก้ปัญหา Use Case ที่พบบ่อยจำนวนหนึ่ง

ประเภท

CaptureInfo

พร็อพเพอร์ตี้

• เต็มหน้าจอ

  boolean

  องค์ประกอบในแท็บที่จับภาพอยู่ในโหมดเต็มหน้าจอหรือไม่

• status

  TabCaptureState

  สถานะการจับภาพใหม่ของแท็บ

• tabId

  ตัวเลข

  รหัสของแท็บที่สถานะเปลี่ยนแปลง

CaptureOptions

พร็อพเพอร์ตี้

• เสียง

  บูลีน ไม่บังคับ

• audioConstraints

  MediaStreamConstraint ไม่บังคับ

• วิดีโอ

  บูลีน ไม่บังคับ

• videoConstraints

  MediaStreamConstraint ไม่บังคับ

GetMediaStreamOptions

Chrome เวอร์ชัน 71 ขึ้นไป

พร็อพเพอร์ตี้

• consumerTabId

  ตัวเลข ไม่บังคับ

  รหัสแท็บที่ไม่บังคับของแท็บ ซึ่งจะเรียกใช้ getUserMedia() ในภายหลังเพื่อใช้สตรีม หากไม่ระบุ สตรีมผลลัพธ์จะสามารถใช้ได้โดยส่วนขยายการโทรเท่านั้น สตรีมจะใช้ได้โดยเฟรมในแท็บที่ระบุซึ่งมีต้นทางการรักษาความปลอดภัยตรงกับต้นทางของแท็บ Consumber เท่านั้น ต้นทางของแท็บต้องเป็นต้นทางที่ปลอดภัย เช่น HTTPS

• targetTabId

  ตัวเลข ไม่บังคับ

  รหัสแท็บที่ไม่บังคับของแท็บที่จะถูกบันทึก หากไม่ได้ระบุ ระบบจะเลือกแท็บที่ใช้งานอยู่ในปัจจุบัน เฉพาะแท็บที่ส่วนขยายได้รับสิทธิ์ activeTab เท่านั้นที่จะใช้เป็นแท็บเป้าหมายได้

MediaStreamConstraint

พร็อพเพอร์ตี้

• บังคับ

  ออบเจ็กต์

• ไม่บังคับ

  ออบเจ็กต์ ไม่บังคับ

TabCaptureState

ค่าแจกแจง

วิธีการ

capture()

ส่วนหน้าเท่านั้น

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

จับภาพพื้นที่ที่มองเห็นได้ของแท็บที่ใช้งานอยู่ในปัจจุบัน การบันทึกจะเริ่มต้นได้ในแท็บที่ใช้งานอยู่ในปัจจุบันเท่านั้นหลังจากที่เรียกใช้ส่วนขยายแล้ว ซึ่งคล้ายกับวิธีการทำงานของ activeTab การจับภาพจะดำเนินการตลอดการนำทางหน้าเว็บภายในแท็บ และจะหยุดเมื่อแท็บปิดอยู่ หรือสตรีมสื่อปิดอยู่โดยส่วนขยาย

พารามิเตอร์

• ตัวเลือก

  CaptureOptions

  กำหนดค่าสตรีมสื่อที่แสดงผล

• Callback

  ฟังก์ชัน

  พารามิเตอร์ callback มีลักษณะดังนี้

  (stream: LocalMediaStream)=>void

  • สตรีม

    LocalMediaStream

getCapturedTabs()

สัญญา

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

แสดงรายการแท็บที่ขอการจับภาพหรือที่กำลังบันทึกไว้ เช่น สถานะ != หยุด และ สถานะ != ข้อผิดพลาด วิธีนี้ช่วยให้ส่วนขยายแจ้งผู้ใช้ว่ามีการจับภาพแท็บอยู่แล้วซึ่งจะป้องกันไม่ให้การจับภาพแท็บใหม่ทำได้สำเร็จ (หรือเพื่อป้องกันไม่ให้มีการส่งคำขอซ้ำซ้อนสำหรับแท็บเดียวกัน)

พารามิเตอร์

• Callback

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback มีลักษณะดังนี้

  (result: CaptureInfo[])=>void

  • ผลลัพธ์

    CaptureInfo[]

การคืนสินค้า

• Promise<CaptureInfo[]>

  Chrome 116 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getMediaStreamId()

คำมั่นสัญญา Chrome เวอร์ชัน 71 ขึ้นไป

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

สร้างรหัสสตรีมเพื่อบันทึกแท็บเป้าหมาย คล้ายกับเมธอด chrome.tabจับภาพหน้าจอ.capture() แต่แสดงผลรหัสสตรีมสื่อไปยังแท็บผู้บริโภคแทนสตรีมสื่อ

พารามิเตอร์

• ตัวเลือก

  GetMediaStreamOptions ไม่บังคับ

• Callback

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback มีลักษณะดังนี้

  (streamId: string)=>void

  • streamId

    string

การคืนสินค้า

• คำสัญญา<string>

  Chrome 116 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

กิจกรรม

onStatusChanged

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

เหตุการณ์เริ่มทำงานเมื่อสถานะการบันทึกของแท็บเปลี่ยนแปลง วิธีนี้ช่วยให้ผู้เขียนส่วนขยายติดตามสถานะการจับภาพของแท็บเพื่อซิงค์องค์ประกอบ UI เช่น การดำเนินการในหน้าเว็บ

พารามิเตอร์

• Callback

  ฟังก์ชัน

  พารามิเตอร์ callback มีลักษณะดังนี้

  (info: CaptureInfo)=>void

  • ข้อมูล

    CaptureInfo