chrome.tabCapture

תיאור

משתמשים ב-API chrome.tabCapture לאינטראקציה עם שידורי מדיה של כרטיסיות.

הרשאות

tabCapture

מושגים ושימוש

ה-API chrome.tabCapture מאפשר לכם לגשת לקובץ 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() בכל מסגרת בכרטיסייה הנתונה בעלת אותו מקור אבטחה.
• אם לא מגדירים את הערך הזה, החל מגרסה 116 של Chrome, ניתן להשתמש במזהה בכל מסגרת עם אותו מקור אבטחה באותו תהליך עיבוד כמו מבצע הקריאה החוזרת. כלומר, אפשר להשתמש במזהה מקור נתונים שמתקבל ב-Service Worker במסמך מחוץ למסך.

לפני Chrome 116, כשלא צוין consumerTabId, מזהה השידור היה מוגבל גם למקור האבטחה, לתהליך העיבוד ולמסגרת העיבוד של מבצע הקריאה.

מידע נוסף

למידע נוסף על השימוש ב-API chrome.tabCapture, תוכלו לקרוא על הקלטת אודיו וצילום מסך. כאן אנחנו מדגימים איך להשתמש ב-tabCapture ובממשקי API קשורים כדי לפתור כמה תרחישים נפוצים לדוגמה.

סוגים

CaptureInfo

תכונות

• מסך מלא

  boolean

  מציין אם רכיב בכרטיסייה שמצלמים נמצא במצב מסך מלא.

• status

  TabCaptureState

  סטטוס הצילום החדש של הכרטיסייה.

• tabId

  מספר

  המזהה של הכרטיסייה שהסטטוס שלה השתנה.

CaptureOptions

תכונות

• אודיו

  בוליאני אופציונלי

• audioConstraints

  MediaStreamConstraint אופציונלי

• סרטון

  בוליאני אופציונלי

• videoConstraints

  MediaStreamConstraint אופציונלי

GetMediaStreamOptions

Chrome 71 ומעלה

תכונות

• consumerTabId

  מספר אופציונלי

  מזהה כרטיסייה אופציונלי של הכרטיסייה, שמאוחר יותר יפעיל את getUserMedia() כדי לצפות בשידור. אם לא מציינים שום אפשרות, השידור שנוצר יכול לשמש רק את תוסף השיחה. ניתן להשתמש בשידור החי רק למסגרות בכרטיסייה הנתונה שמקור האבטחה שלהן תואם למקור של כרטיסיית הצריכה. מקור הכרטיסייה חייב להיות מקור מאובטח, למשל HTTPS.

• targetTabId

  מספר אופציונלי

  מזהה כרטיסייה אופציונלי של הכרטיסייה שתיקלט. אם לא מציינים שום אפשרות, הכרטיסייה הפעילה הנוכחית תיבחר. אפשר להשתמש רק בכרטיסיות שבהן לתוסף הוענקה ההרשאה activeTab.

MediaStreamConstraint

תכונות

• חובה

  אובייקט

• אופציונלי

  אובייקט אופציונלי

TabCaptureState

טיפוסים בני מנייה (enum)

שיטות

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 ומעלה

  יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

getMediaStreamId()

הבטחה Chrome 71 ואילך

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

יוצר מזהה מקור נתונים כדי לצלם את כרטיסיית היעד. דומה לשיטה chrome.tabCapture.capture() , אבל מוחזר מזהה של מקור מדיה, במקום מקור נתוני מדיה, לכרטיסיית הצרכן.

פרמטרים

• אפשרויות

  GetMediaStreamOptions אופציונלי

• קריאה חוזרת (callback)

  פונקציה אופציונלי

  הפרמטר callback נראה כך:

  (streamId: string)=>void

  • streamId

    מחרוזת

החזרות

• הבטחה<string>

  Chrome 116 ומעלה

  יש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.

אירועים

onStatusChanged

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

האירוע מופעל כשסטטוס הצילום של כרטיסייה משתנה. כך מחברים של תוספים יכולים לעקוב אחרי סטטוס הצילום של כרטיסיות כדי לסנכרן רכיבים בממשק המשתמש כמו פעולות בדף.

פרמטרים

• קריאה חוזרת (callback)

  פונקציה

  הפרמטר callback נראה כך:

  (info: CaptureInfo)=>void

  • מידע

    CaptureInfo