תיאור
משתמשים ב-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
סטטוס הצילום החדש של הכרטיסייה.
-
tabId
מספר
המזהה של הכרטיסייה שהסטטוס שלה השתנה.
CaptureOptions
תכונות
-
אודיו
בוליאני אופציונלי
-
audioConstraints
MediaStreamConstraint אופציונלי
-
סרטון
בוליאני אופציונלי
-
videoConstraints
MediaStreamConstraint אופציונלי
GetMediaStreamOptions
תכונות
-
consumerTabId
מספר אופציונלי
מזהה כרטיסייה אופציונלי של הכרטיסייה, שמאוחר יותר יפעיל את
getUserMedia()
כדי לצפות בשידור. אם לא מציינים שום אפשרות, השידור שנוצר יכול לשמש רק את תוסף השיחה. ניתן להשתמש בשידור החי רק למסגרות בכרטיסייה הנתונה שמקור האבטחה שלהן תואם למקור של כרטיסיית הצריכה. מקור הכרטיסייה חייב להיות מקור מאובטח, למשל HTTPS. -
targetTabId
מספר אופציונלי
מזהה כרטיסייה אופציונלי של הכרטיסייה שתיקלט. אם לא מציינים שום אפשרות, הכרטיסייה הפעילה הנוכחית תיבחר. אפשר להשתמש רק בכרטיסיות שבהן לתוסף הוענקה ההרשאה
activeTab
.
MediaStreamConstraint
תכונות
-
חובה
אובייקט
-
אופציונלי
אובייקט אופציונלי
TabCaptureState
טיפוסים בני מנייה (enum)
שיטות
capture()
chrome.tabCapture.capture(
options: CaptureOptions,
callback: function,
)
צילום האזור הגלוי של הכרטיסייה שפעילה כרגע. ניתן להתחיל בצילום בכרטיסייה שפעילה כרגע רק אחרי שהתוסף מופעל, בדומה לאופן שבו פועלת activeTab. הצילום נשמר בכל הניווטים בדפים בתוך הכרטיסייה, ומפסיק כאשר הכרטיסייה נסגרת או כשהתוסף סוגר את שידור המדיה.
פרמטרים
-
אפשרויות
המדיניות מגדירה את שידור המדיה המוחזר.
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(stream: LocalMediaStream) => void
-
מקור נתונים
LocalMediaStream
-
getCapturedTabs()
chrome.tabCapture.getCapturedTabs(
callback?: function,
)
מחזירה רשימה של כרטיסיות שביקשו הקלטה או שתועדו. לדוגמה, סטטוס != הופסק ושגיאה בסטטוס !=. כך התוספים יכולים ליידע את המשתמש על כך שיש לכידת כרטיסייה קיימת שעלולה למנוע מצילום כרטיסייה חדשה להצליח (או למנוע בקשות מיותרות עבור אותה כרטיסייה).
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: CaptureInfo[]) => void
-
תוצאה אחת
-
החזרות
-
Promise<CaptureInfo[]>
Chrome 116 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getMediaStreamId()
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
-
מידע
-