वेब प्लैटफ़ॉर्म पर, स्क्रीन कैप्चर एपीआई की मदद से टैब, विंडो, और स्क्रीन शेयर की जा सकती हैं. जब कोई वेब ऐप्लिकेशन getDisplayMedia() को कॉल करता है, तो Chrome उपयोगकर्ता को वेब ऐप्लिकेशन के साथ टैब, विंडो या स्क्रीन को MediaStreamTrack वीडियो के तौर पर शेयर करने के लिए कहता है.
getDisplayMedia() का इस्तेमाल करने वाले कई वेब ऐप्लिकेशन, उपयोगकर्ता को कैप्चर किए गए सर्फ़ेस की वीडियो झलक दिखाते हैं. उदाहरण के लिए, वीडियो कॉन्फ़्रेंसिंग ऐप्लिकेशन अक्सर इस वीडियो को दूर बैठे लोगों के साथ स्ट्रीम करते हैं. साथ ही, इसे लोकल HTMLVideoElement पर रेंडर करते हैं, ताकि लोकल उपयोगकर्ता को लगातार यह दिखता रहे कि वह क्या शेयर कर रहा है.
इस दस्तावेज़ में, Chrome में मौजूद नए Captured Surface Control API के बारे में बताया गया है. इसकी मदद से, आपका वेब ऐप्लिकेशन कैप्चर किए गए टैब को स्क्रोल कर सकता है. साथ ही, कैप्चर किए गए टैब के ज़ूम लेवल को पढ़ और बदल सकता है.
कैप्चर किए गए सर्फ़ेस कंट्रोल का इस्तेमाल क्यों करें?
वीडियो कॉन्फ़्रेंसिंग की सुविधा देने वाले सभी ऐप्लिकेशन में एक ही समस्या होती है. अगर उपयोगकर्ता को कैप्चर किए गए टैब या विंडो से इंटरैक्ट करना है, तो उसे उस पर स्विच करना होगा. इससे वह वीडियो कॉन्फ़्रेंसिंग ऐप्लिकेशन से हट जाएगा. इससे कुछ समस्याएं आती हैं:
- उपयोगकर्ता को कैप्चर किया गया ऐप्लिकेशन और रिमोट उपयोगकर्ताओं के वीडियो फ़ीड एक साथ नहीं दिख सकते. ऐसा तब तक होता है, जब तक वे वीडियो कॉन्फ़्रेंस टैब और शेयर किए गए टैब के लिए, पिक्चर में पिक्चर सुविधा या अगल-बगल वाली अलग-अलग विंडो का इस्तेमाल नहीं करते. छोटी स्क्रीन पर, ऐसा करना मुश्किल हो सकता है.
- उपयोगकर्ता को वीडियो कॉन्फ़्रेंसिंग ऐप्लिकेशन और कैप्चर किए गए कॉन्टेंट के बीच स्विच करना पड़ता है.
- उपयोगकर्ता को वीडियो कॉन्फ़्रेंसिंग ऐप्लिकेशन के कंट्रोल का ऐक्सेस नहीं मिलता है. जैसे, एम्बेड किया गया चैट ऐप्लिकेशन, इमोजी से प्रतिक्रियाएं देने की सुविधा, कॉल में शामिल होने का अनुरोध करने वाले उपयोगकर्ताओं के बारे में सूचनाएं, मल्टीमीडिया और लेआउट कंट्रोल, और वीडियो कॉन्फ़्रेंसिंग की अन्य काम की सुविधाएं.
- प्रज़ेंटर, रिमोट से मीटिंग में हिस्सा लेने वाले लोगों को कंट्रोल नहीं सौंप सकता. इस वजह से, रिमोट से काम करने वाले लोग अक्सर प्रज़ेंटर से स्लाइड बदलने, थोड़ा ऊपर-नीचे स्क्रोल करने या ज़ूम लेवल को अडजस्ट करने के लिए कहते हैं.
Captured Surface Control API इन समस्याओं को हल करता है.
मैं कैप्चर की गई सतह के कंट्रोल का इस्तेमाल कैसे करूं?
कैप्चर किए गए कॉन्टेंट को कंट्रोल करने की सुविधा का इस्तेमाल करने के लिए, कुछ चरणों को पूरा करना ज़रूरी है. जैसे, ब्राउज़र टैब को साफ़ तौर पर कैप्चर करना और कैप्चर किए गए टैब को स्क्रोल और ज़ूम करने से पहले, उपयोगकर्ता से अनुमति लेना.
किसी ब्राउज़र टैब को कैप्चर करना
सबसे पहले, उपयोगकर्ता को getDisplayMedia() का इस्तेमाल करके, शेयर करने के लिए कोई सरफेस चुनने के लिए कहें. इस प्रोसेस में, CaptureController ऑब्जेक्ट को कैप्चर सेशन से जोड़ें. हम जल्द ही उस ऑब्जेक्ट का इस्तेमाल करके, कैप्चर किए गए सर्फ़ेस को कंट्रोल करेंगे.
const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });
इसके बाद, कैप्चर किए गए सर्फ़ेस की स्थानीय झलक को <video> एलिमेंट के तौर पर दिखाएं:
const previewTile = document.querySelector('video');
previewTile.srcObject = stream;
अगर उपयोगकर्ता कोई विंडो या स्क्रीन शेयर करता है, तो फ़िलहाल यह सुविधा काम नहीं करेगी. हालांकि, अगर वह कोई टैब शेयर करता है, तो हम आगे बढ़ सकते हैं.
const [track] = stream.getVideoTracks();
if (track.getSettings().displaySurface !== 'browser') {
// Bail out early if the user didn't pick a tab.
return;
}
अनुमति का अनुरोध करने वाला प्रॉम्प्ट
किसी CaptureController ऑब्जेक्ट पर forwardWheel(), increaseZoomLevel(), decreaseZoomLevel() या resetZoomLevel() में से किसी एक को पहली बार कॉल करने पर, अनुमति का अनुरोध करने वाला प्रॉम्प्ट दिखता है. अगर उपयोगकर्ता अनुमति देता है, तो इन तरीकों को आगे भी लागू किया जा सकता है.
उपयोगकर्ता को अनुमति का अनुरोध दिखाने के लिए, उपयोगकर्ता के जेस्चर की ज़रूरत होती है. इसलिए, ऐप्लिकेशन को सिर्फ़ तब ऊपर दिए गए तरीकों को कॉल करना चाहिए, जब उसके पास पहले से अनुमति हो या उपयोगकर्ता के जेस्चर के जवाब में ऐसा किया जा रहा हो. जैसे, वेब ऐप्लिकेशन में किसी काम के बटन पर click.
स्क्रोल करें
forwardWheel() का इस्तेमाल करके, कैप्चर करने वाला ऐप्लिकेशन, कैप्चर किए गए टैब के व्यूपोर्ट में, कैप्चर करने वाले ऐप्लिकेशन के सोर्स एलिमेंट से व्हील इवेंट फ़ॉरवर्ड कर सकता है. ये इवेंट, ऐप्लिकेशन में सीधे तौर पर किए गए यूज़र इंटरैक्शन से अलग नहीं होते.
मान लें कि कैप्चर करने वाला ऐप्लिकेशन, <video> एलिमेंट का इस्तेमाल करता है. इसे "previewTile" कहा जाता है. यहां दिए गए कोड में, कैप्चर किए गए टैब को सेंड व्हील इवेंट रिले करने का तरीका बताया गया है:
const previewTile = document.querySelector('video');
try {
// Relay the user's action to the captured tab.
await controller.forwardWheel(previewTile);
} catch (error) {
// Inspect the error.
// ...
}
forwardWheel() तरीके में एक इनपुट लिया जाता है. यह इनपुट इनमें से कोई एक हो सकता है:
- यह एक एचटीएमएल एलिमेंट है, जिससे व्हील इवेंट को कैप्चर किए गए टैब पर फ़ॉरवर्ड किया जाएगा.
null, इसका मतलब है कि फ़ॉरवर्डिंग बंद कर दी गई है.
forwardWheel() को कॉल करने पर, पिछली कॉल की जानकारी बदल जाती है.
forwardWheel() से मिले प्रॉमिस को इन मामलों में अस्वीकार किया जा सकता है:
- अगर कैप्चर सेशन अभी शुरू नहीं हुआ है या पहले ही बंद हो गया है.
- अगर उपयोगकर्ता ने ज़रूरी अनुमति नहीं दी है.
ज़ूम करें
कैप्चर किए गए टैब के ज़ूम लेवल के साथ इंटरैक्ट करने के लिए, यहां दिए गए CaptureController एपीआई का इस्तेमाल किया जाता है:
getSupportedZoomLevels()
यह तरीका, कैप्चर किए जा रहे सर्फ़ेस टाइप के लिए, ब्राउज़र के साथ काम करने वाले ज़ूम लेवल की सूची दिखाता है. इस सूची में मौजूद वैल्यू को "डिफ़ॉल्ट ज़ूम लेवल" के हिसाब से प्रतिशत के तौर पर दिखाया जाता है. डिफ़ॉल्ट ज़ूम लेवल को 100% के तौर पर तय किया जाता है. यह सूची लगातार बढ़ती है और इसमें 100 वैल्यू शामिल है.
इस तरीके को सिर्फ़ उन डिसप्ले सर्फ़ेस टाइप के लिए कॉल किया जा सकता है जिनके लिए यह उपलब्ध है. फ़िलहाल, यह सिर्फ़ टैब के लिए उपलब्ध है.
controller.getSupportedZoomLevels() को इन स्थितियों में कॉल किया जा सकता है:
controllerकिसी चालू कैप्चर से जुड़ा है.- यह कैप्चर किसी टैब का है.
ऐसा न होने पर, गड़बड़ी का मैसेज दिखेगा.
इस तरीके को कॉल करने के लिए, "captured-surface-control" अनुमति की ज़रूरत नहीं है.
zoomLevel
रीड-ओनली ऐक्सेस वाली इस एट्रिब्यूट में, कैप्चर किए गए टैब का मौजूदा ज़ूम लेवल होता है. यह एक ऐसा एट्रिब्यूट है जिसकी वैल्यू को शून्य पर सेट किया जा सकता है. अगर कैप्चर किए गए सर्फ़ेस टाइप में ज़ूम-लेवल की कोई खास परिभाषा नहीं है, तो इसकी वैल्यू null होती है. फ़िलहाल, ज़ूम-लेवल सिर्फ़ टैब के लिए तय किया जाता है, न कि विंडो या स्क्रीन के लिए.
कैप्चर खत्म होने के बाद, एट्रिब्यूट में ज़ूम-लेवल की आखिरी वैल्यू सेव हो जाएगी.
इस एट्रिब्यूट को पढ़ने के लिए, "captured-surface-control" अनुमति की ज़रूरत नहीं होती.
onzoomlevelchange
यह इवेंट हैंडलर, कैप्चर किए गए टैब के ज़ूम लेवल में हुए बदलावों को सुनने की सुविधा देता है. ऐसा इनमें से किसी एक वजह से होता है:
- जब उपयोगकर्ता, कैप्चर किए गए टैब के ज़ूम-लेवल को मैन्युअल तरीके से बदलने के लिए ब्राउज़र से इंटरैक्ट करता है.
- ज़ूम सेटिंग के तरीकों (नीचे बताया गया है) के लिए, ऐप्लिकेशन के कॉल के जवाब में.
इस एट्रिब्यूट को पढ़ने के लिए, "captured-surface-control" अनुमति की ज़रूरत नहीं होती.
increaseZoomLevel(), decreaseZoomLevel(), और resetZoomLevel()
इन तरीकों से, कैप्चर किए गए टैब के ज़ूम लेवल में बदलाव किया जा सकता है.
increaseZoomLevel() और decreaseZoomLevel(), ज़ूम लेवल को क्रमशः अगले या पिछले ज़ूम-लेवल पर ले जाते हैं. यह getSupportedZoomLevels() से मिले क्रम के हिसाब से होता है. resetZoomLevel() वैल्यू को 100 पर सेट करता है.
इन तरीकों को कॉल करने के लिए, "captured-surface-control" अनुमति ज़रूरी है. अगर कैप्चर करने वाले ऐप्लिकेशन के पास यह अनुमति नहीं है, तो उपयोगकर्ता को इसे स्वीकार या अस्वीकार करने के लिए कहा जाएगा.
ये सभी तरीके, एक प्रॉमिस दिखाते हैं. अगर कॉल सफल होता है, तो प्रॉमिस पूरा हो जाता है. ऐसा न होने पर, प्रॉमिस अस्वीकार कर दिया जाता है. आवेदन अस्वीकार होने की ये वजहें हो सकती हैं:
- अनुमति नहीं है.
- कैप्चर शुरू होने से पहले कॉल किया गया.
- कॉल, कैप्चर खत्म होने के बाद किया गया.
controllerको कॉल किया गया है. यहcontroller, डिसप्ले सर्फ़ेस के ऐसे टाइप से जुड़ा है जिसका इस्तेमाल नहीं किया जा सकता. (यानी, टैब के विज़ुअल कॉन्टेंट को कैप्चर करने की अनुमति के अलावा कोई भी अनुमति.)- ज़्यादा से ज़्यादा या कम से कम वैल्यू से ज़्यादा या कम करने की कोशिश की जाती है.
खास तौर पर, अगर controller.zoomLevel == controller.getSupportedZoomLevels().at(0) है, तो decreaseZoomLevel() को कॉल न करने का सुझाव दिया जाता है. साथ ही, .at(-1) का इस्तेमाल करके, increaseZoomLevel() को कॉल करने से बचें.
यहां दिए गए उदाहरण में, उपयोगकर्ता को कैप्चर किए गए टैब का ज़ूम लेवल बढ़ाने की अनुमति देने का तरीका बताया गया है. यह अनुमति, कैप्चर करने वाले ऐप्लिकेशन से सीधे तौर पर दी जा सकती है:
const zoomIncreaseButton = document.getElementById('zoomInButton');
zoomIncreaseButton.addEventListener('click', async (event) => {
if (controller.zoomLevel >= controller.getSupportedZoomLevels().at(-1)) {
return;
}
try {
await controller.increaseZoomLevel();
} catch (error) {
// Inspect the error.
// ...
}
});
यहां दिए गए उदाहरण में, कैप्चर किए गए टैब के ज़ूम लेवल में हुए बदलावों पर प्रतिक्रिया देने का तरीका बताया गया है:
controller.addEventListener('zoomlevelchange', (event) => {
const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});
सुविधा का पता लगाना
यह देखने के लिए कि Captured Surface Control API काम करते हैं या नहीं, इसका इस्तेमाल करें:
if (!!window.CaptureController?.prototype.forwardWheel) {
// CaptureController forwardWheel() is supported.
}
increaseZoomLevel या decreaseZoomLevel जैसे Captured Surface Control API के किसी भी अन्य सर्फ़ेस का इस्तेमाल किया जा सकता है. इसके अलावा, इन सभी सर्फ़ेस की जांच भी की जा सकती है.
ब्राउज़र समर्थन
कैप्चर किए गए Surface Control की सुविधा, सिर्फ़ डेस्कटॉप पर Chrome 136 से उपलब्ध है.
सुरक्षा और निजता
"captured-surface-control" अनुमति से जुड़ी नीति की मदद से, यह मैनेज किया जा सकता है कि कैप्चर करने वाले ऐप्लिकेशन और एम्बेड किए गए तीसरे पक्ष के iframe को, कैप्चर किए गए सर्फ़ेस कंट्रोल का ऐक्सेस कैसे मिले. सुरक्षा से जुड़े फ़ायदों और नुकसानों के बारे में जानने के लिए, कैप्चर किए गए सर्फ़ेस कंट्रोल के बारे में बताने वाले लेख का निजता और सुरक्षा से जुड़ी बातों का ध्यान रखना सेक्शन पढ़ें.
डेमो
डेमो चलाकर, कैप्चर किए गए सर्फ़ेस कंट्रोल का इस्तेमाल किया जा सकता है.
सुझाव/राय दें या शिकायत करें
Chrome टीम और वेब स्टैंडर्ड कम्यूनिटी, कैप्चर किए गए सर्फ़ेस कंट्रोल के बारे में आपके अनुभव जानना चाहती है.
हमें डिज़ाइन के बारे में बताएं
क्या कैप्चर किए गए सर्फ़ेस कैप्चर के बारे में कुछ ऐसा है जो आपकी उम्मीद के मुताबिक काम नहीं करता? इसके अलावा, क्या कोई ऐसी प्रॉपर्टी या तरीका है जो आपके आइडिया को लागू करने के लिए ज़रूरी है, लेकिन मौजूद नहीं है? क्या आपको सुरक्षा मॉडल के बारे में कोई सवाल पूछना है या कोई टिप्पणी करनी है? GitHub repo पर स्पेसिफ़िकेशन से जुड़ी समस्या की शिकायत करें या किसी मौजूदा समस्या के बारे में अपनी राय दें.
क्या आपको लागू करने में कोई समस्या आ रही है?
क्या आपको Chrome के साथ काम करने वाले किसी एक्सटेंशन में कोई गड़बड़ी मिली? या क्या लागू करने का तरीका, स्पेसिफ़िकेशन से अलग है? https://new.crbug.com पर जाकर, गड़बड़ी की रिपोर्ट सबमिट करें. इसमें ज़्यादा से ज़्यादा जानकारी शामिल करें. साथ ही, गड़बड़ी को दोबारा बनाने के निर्देश भी दें.