chrome.tabCapture

توضیحات

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

مجوزها

tabCapture

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

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

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

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

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

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

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

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

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

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

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

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

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

قبل از کروم ۱۱۶، وقتی consumerTabId مشخص نشده بود، شناسه جریان به مبدا امنیتی، فرآیند رندر و فریم رندر فراخواننده محدود می‌شد.

بیشتر بدانید

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

انواع

CaptureInfo

خواص

  • تمام صفحه

    بولی

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

  • وضعیت

    TabCaptureState

    وضعیت جدید ضبط تب.

  • شناسه برگه

    شماره

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

CaptureOptions

خواص

GetMediaStreamOptions

کروم ۷۱+

خواص

  • تب‌آی‌دی مصرف‌کننده

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

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

  • شناسه هدف

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

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

MediaStreamConstraint

خواص

  • اجباری

    شیء

  • اختیاری

    شیء اختیاری

TabCaptureState

شمارشی

«در انتظار»

"فعال"

"متوقف شد"

"خطا"

روش‌ها

capture()

فقط پیش‌زمینه
chrome.tabCapture.capture(
  options: CaptureOptions,
  callback: function,
): void

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

پارامترها

  • گزینه‌ها

    گزینه‌های ضبط

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

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (stream: LocalMediaStream) => void

    • جریان

      پخش محلی مدیا

getCapturedTabs()

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

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

بازگشت‌ها

  • قول< CaptureInfo []>

    کروم ۱۱۶+

    یک Promise برمی‌گرداند که با CaptureInfo[] برای تب‌های گرفته‌شده، اجرا می‌شود.

getMediaStreamId()

کروم ۷۱+
chrome.tabCapture.getMediaStreamId(
  options?: GetMediaStreamOptions,
): Promise<string>

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

پارامترها

بازگشت‌ها

  • قول<string>

    کروم ۱۱۶+

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

رویدادها

onStatusChanged

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

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

پارامترها