browser.tabCapture

شرح

از chrome.tabCapture API برای تعامل با جاری‌سازی‌های رسانه برگه استفاده کنید.

اجازه‌ها

tabCapture

مفاهیم و کاربرد

‫browser.tabCapture API به شما امکان می‌دهد به MediaStream حاوی ویدیو و صدای برگه فعلی دسترسی پیدا کنید. این روش فقط پس‌از اینکه کاربر افزونه‌ای را فراخوانی می‌کند، مثلاً با کلیک کردن روی دکمه کنش افزونه، می‌تواند فراخوانی شود. این مشابه رفتار اجازه "activeTab" است.

حفظ صدای سیستم

وقتی MediaStream برای برگه‌ای دریافت می‌شود، صدای آن برگه دیگر برای کاربر پخش نخواهد شد. این شبیه به رفتار تابع getDisplayMedia() است وقتی پرچم suppressLocalAudioPlayback روی درست تنظیم شده باشد.

برای ادامه پخش صدا برای کاربر، از موارد زیر استفاده کنید:

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

با این کار، AudioContext جدیدی ایجاد می‌شود و صدای MediaStream برگه را به مقصد پیش‌فرض متصل می‌کند.

شناسه‌های جریان داده

فراخوانی browser.tabCapture.getMediaStreamId() شناسه جاری‌سازی را برمی‌گرداند. برای دسترسی بعدی به MediaStream از شناسه، از موارد زیر استفاده کنید:

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

محدودیت‌های استفاده

پس‌از فراخوانی getMediaStreamId()، محدودیت‌هایی برای محل استفاده از شناسه جاری‌سازی برگردانده‌شده وجود دارد:

• اگر consumerTabId مشخص شده باشد، شناسه می‌تواند توسط تماس getUserMedia() در هر قابی در برگه داده‌شده که منبع امنیتی یکسانی دارد استفاده شود.
• وقتی این مورد مشخص نشده باشد، از Chrome 116 به بعد، می‌توان از شناسه در هر قابی با همان مبدأ امنیتی در همان فرایند پردازش ارائه‌دهنده استفاده کرد. این یعنی شناسه جاری‌سازی به‌دست‌آمده در یک سرویس‌کار می‌تواند در یک سند خارج از صفحه استفاده شود.

پیش‌از Chrome 116، وقتی consumerTabId مشخص نشده بود، شناسه جاری‌سازی به هر دو مبدأ امنیتی، فرایند پردازش، و چارچوب پردازش تماس‌گیرنده محدود می‌شد.

بیشتر بدانید

برای کسب اطلاعات بیشتر درباره نحوه استفاده از browser.tabCapture API، به ضبط صدا و ضبط صفحه مراجعه کنید. این نشان می‌دهد که چگونه از tabCapture و میاناهای برنامه‌سازی کاربردی مرتبط برای حل تعدادی از موارد استفاده رایج استفاده کنید.

انواع

CaptureInfo

مشخصات

• تمام‌صفحه

  بولی

  آیا عنصری در برگه ضبط‌شده در حالت تمام‌صفحه است یا نه.

• وضعیت

  TabCaptureState

  وضعیت ضبط جدید برگه.

• tabId

  شماره

  شناسه زبانه‌ای که وضعیت آن تغییر کرده است.

CaptureOptions

مشخصات

• صوتی

  بولی اختیاری

• audioConstraints

  MediaStreamConstraint اختیاری

• ویدیو

  بولی اختیاری

• videoConstraints

  MediaStreamConstraint اختیاری

GetMediaStreamOptions

Chrome 71+ browser.* since Chrome 148

مشخصات

• consumerTabId

  شماره اختیاری

  شناسه زبانه اختیاری زبانه‌ای که بعداً getUserMedia() را برای مصرف جاری‌سازی فراخوانی می‌کند. اگر مشخص نشده باشد، فقط افزونه تماس‌گیرنده می‌تواند از جاری‌سازی حاصل استفاده کند. فقط قاب‌هایی در برگه ارائه‌شده می‌توانند از جاری‌سازی استفاده کنند که مبدأ امنیتی آن‌ها با مبدأ برگه مصرف‌کننده مطابقت داشته باشد. مبدأ برگه باید مبدأی امن باشد، مثلاً HTTPS.

• targetTabId

  شماره اختیاری

  شناسه برگه اختیاری برگه‌ای که ضبط خواهد شد. اگر مشخص نشده باشد، برگه فعال فعلی انتخاب خواهد شد. فقط زبانه‌هایی که اجازه activeTab به افزونه اعطا شده است می‌توانند به‌عنوان زبانه هدف استفاده شوند.

MediaStreamConstraint

مشخصات

• اجباری

  شیء

• اختیاری

  شیء اختیاری

TabCaptureState

شمارشی

«درانتظار»

«فعال»

«متوقف شد»

"error"

روش‌ها

capture()

فقط پیش‌زمینه

browser.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

ناحیه قابل‌مشاهده برگه فعال کنونی را ضبط می‌کند. ضبط فقط در برگه فعال فعلی پس‌از فراخوانی افزونه می‌تواند شروع شود، مشابه نحوه عملکرد activeTab. ضبط در سراسر پیمایش‌های صفحه در برگه حفظ می‌شود و وقتی برگه بسته شود یا جریان رسانه توسط افزونه بسته شود، متوقف می‌شود.

پارامترها

• گزینه‌ها

  CaptureOptions

  جاری‌سازی رسانه برگردانده‌شده را پیکربندی می‌کند.

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

  (stream: LocalMediaStream) => void

  • جاری‌سازی

    LocalMediaStream

getCapturedTabs()

browser.tabCapture.getCapturedTabs(): Promise<CaptureInfo[]>

فهرستی از برگه‌هایی را برمی‌گرداند که درخواست ضبط داده‌اند یا درحال ضبط شدن هستند، یعنی وضعیت != متوقف‌شده و وضعیت != خطا. این کار به افزونه‌ها اجازه می‌دهد به کاربر اطلاع دهند که ضبط برگه موجودی وجود دارد که مانع از موفقیت ضبط برگه جدید می‌شود (یا از درخواست‌های تکراری برای همان برگه جلوگیری می‌کند).

بازگشتی‌ها

• Promise<CaptureInfo[]>

  Chrome نسخه ۱۱۶ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

  یک Promise برمی‌گرداند که با CaptureInfo[] برای برگه‌های ضبط‌شده حل می‌شود.

getMediaStreamId()

Chrome 71+ browser.* since Chrome 148

browser.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

شناسه جاری‌سازی‌ای برای ضبط برگه هدف ایجاد می‌کند. مشابه روش chrome.tabCapture.capture()‎، اما به‌جای جاری‌سازی رسانه، شناسه جاری‌سازی رسانه را به برگه مصرف‌کننده برمی‌گرداند.

پارامترها

• گزینه‌ها

  GetMediaStreamOptions اختیاری

بازگشتی‌ها

• Promise<string>

  Chrome نسخه ۱۱۶ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

  یک Promise برمی‌گرداند که با نتیجه حل می‌شود. اگر موفقیت‌آمیز باشد، نتیجه یک رشته مات است که می‌تواند به getUserMedia() API ارسال شود تا یک جاری‌سازی رسانه تولید کند که با برگه هدف مطابقت دارد. streamId ایجادشده فقط یک‌بار قابل‌استفاده است و اگر استفاده نشود، پس‌از چند ثانیه منقضی می‌شود.

رویدادها

onStatusChanged

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

رویداد زمانی فعال می‌شود که وضعیت ضبط برگه تغییر کند. این کار به نویسندگان افزونه اجازه می‌دهد وضعیت ضبط برگه‌ها را پیگیری کنند تا عناصر میانای کاربر مثل کنش‌های صفحه را همگام‌سازی کنند.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

  (info: CaptureInfo) => void

  • اطلاعات

    CaptureInfo