chrome.tabCapture

คำอธิบาย

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

สิทธิ์

tabCapture

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

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

เก็บเสียงของระบบ

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

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

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 รหัสสตรีมจะถูกจำกัดไว้สำหรับทั้ง 2 เวอร์ชัน ต้นทางการรักษาความปลอดภัย กระบวนการแสดงผล และเฟรมการแสดงผลของผู้โทร

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

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

ประเภท

CaptureInfo

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

  • เต็มหน้าจอ

    boolean

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

  • สถานะ

    TabCaptureState

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

  • tabId

    ตัวเลข

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

CaptureOptions

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

  • เสียง

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

  • audioConstraints

    MediaStreamConstraint ไม่บังคับ

  • วิดีโอ

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

  • videoConstraints

    MediaStreamConstraint ไม่บังคับ

GetMediaStreamOptions

Chrome 71 ขึ้นไป

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

  • consumerTabId

    หมายเลข ไม่บังคับ

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

  • targetTabId

    หมายเลข ไม่บังคับ

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

MediaStreamConstraint

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

  • บังคับ

    ออบเจ็กต์

  • ไม่บังคับ

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

TabCaptureState

ค่าแจกแจง

"pending"

"ใช้งานอยู่"

"หยุด"

"ข้อผิดพลาด"

เมธอด

capture()

เบื้องหน้าเท่านั้น 
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
)

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

พารามิเตอร์

  • ตัวเลือก

    CaptureOptions

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

  • Callback

    ฟังก์ชัน

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

    (stream: LocalMediaStream) => void

    • สตรีม

      LocalMediaStream

getCapturedTabs()

สัญญา 
chrome.tabCapture.getCapturedTabs(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (result: CaptureInfo[]) => void

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

  • Promise<CaptureInfo[]>

    Chrome 116 ขึ้นไป

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

getMediaStreamId()

สัญญา Chrome 71 ขึ้นไป 
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
  callback?: function,
)

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

พารามิเตอร์

  • ตัวเลือก

    GetMediaStreamOptions ไม่บังคับ

  • Callback

    ไม่บังคับ

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

    (streamId: string) => void

    • streamId

      สตริง

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

  • คำมั่นสัญญา<สตริง>

    Chrome 116 ขึ้นไป

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

กิจกรรม

onStatusChanged

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (info: CaptureInfo) => void