Web platformunda Screen Capture API ile sekmeleri, pencereleri ve ekranları paylaşmak zaten mümkündür. Bir web uygulaması getDisplayMedia() işlevini çağırdığında Chrome, kullanıcıdan bir sekme, pencere veya ekranı web uygulamasıyla MediaStreamTrack videosu olarak paylaşmasını ister.
getDisplayMedia() kullanan birçok web uygulaması, kullanıcılara yakalanan yüzeyin video önizlemesini gösterir. Örneğin, video konferans uygulamaları bu videoyu genellikle hem uzak kullanıcılara aktarır hem de yerel bir HTMLVideoElement üzerinde oluşturur. Böylece yerel kullanıcı, paylaştığı içeriğin önizlemesini sürekli olarak görür.
Bu dokümanda, Chrome'daki yeni Captured Surface Control API tanıtılmaktadır. Bu API, web uygulamanızın yakalanan bir sekmede kaydırma yapmasına, yakalanan bir sekmenin yakınlaştırma düzeyini okumasına ve yazmasına olanak tanır.
Neden Yakalanan Yüzey Kontrolü'nü kullanmalısınız?
Tüm video konferans uygulamaları aynı dezavantaja sahiptir. Kullanıcı, yakalanan bir sekme veya pencereyle etkileşim kurmak isterse bu yüzeye geçmesi gerekir. Bu durumda kullanıcı, video konferans uygulamasından ayrılır. Bu durum bazı zorluklara yol açar:
- Kullanıcı, pencere içinde pencere özelliğini kullanmadığı veya görüntülü konferans sekmesi ile paylaşılan sekme için yan yana ayrı pencereler açmadığı sürece yakalanan uygulamayı ve uzaktaki kullanıcıların video feed'lerini aynı anda göremez. Daha küçük bir ekranda bu işlem zor olabilir.
- Kullanıcı, video konferans uygulaması ile yakalanan yüzey arasında geçiş yapma ihtiyacından dolayı zorlanır.
- Kullanıcı, video konferans uygulamasından uzaklaştığında bu uygulamanın sunduğu kontrollere erişimini kaybeder. Örneğin, yerleştirilmiş bir sohbet uygulaması, emoji tepkileri, görüşmeye katılmak isteyen kullanıcılarla ilgili bildirimler, multimedya ve düzen kontrolleri ile diğer faydalı video konferans özellikleri.
- Sunu sahibi, kontrolü uzaktaki katılımcılara devredemez. Bu durum, uzak kullanıcıların sunum yapan kişiden slaytı değiştirmesini, biraz yukarı ve aşağı kaydırmasını veya yakınlaştırma düzeyini ayarlamasını istediği çok tanıdık bir senaryoya yol açar.
Captured Surface Control API bu sorunları ele alır.
How do I use Captured Surface Control?
Yakalanan yüzey kontrolünü başarılı bir şekilde kullanmak için birkaç adım gerekir. Örneğin, yakalanan sekmede kaydırma ve yakınlaştırma yapabilmek için önce tarayıcı sekmesini açıkça yakalamak ve kullanıcıdan izin almak gerekir.
Tarayıcı sekmesini yakalama
Kullanıcıdan getDisplayMedia() kullanarak paylaşılacak bir yüzey seçmesini isteyerek başlayın ve bu süreçte CaptureController nesnesini yakalama oturumuyla ilişkilendirin. Kısa süre içinde, yakalanan yüzeyi kontrol etmek için bu nesneyi kullanacağız.
const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });
Ardından, yakalanan yüzeyin <video> öğesi biçiminde yerel bir önizlemesini oluşturun:
const previewTile = document.querySelector('video');
previewTile.srcObject = stream;
Kullanıcı bir pencere veya ekran paylaşmayı seçerse bu durum şu an için kapsam dışındadır. Ancak kullanıcı bir sekme paylaşmayı seçerse devam edebiliriz.
const [track] = stream.getVideoTracks();
if (track.getSettings().displaySurface !== 'browser') {
// Bail out early if the user didn't pick a tab.
return;
}
İzin istemi
Belirli bir CaptureController nesnesinde forwardWheel(), increaseZoomLevel(), decreaseZoomLevel() veya resetZoomLevel()'ün ilk çağrılması, izin istemi oluşturur. Kullanıcı izin verirse bu yöntemlerin daha sonraki çağrılarına izin verilir.
Kullanıcıya izin istemi göstermek için kullanıcı hareketi gerekir. Bu nedenle, uygulama yalnızca izni varsa veya kullanıcı hareketine (ör. web uygulamasındaki ilgili bir düğmeye click) yanıt olarak yukarıda belirtilen yöntemleri çağırmalıdır.
Kaydırma
Bir yakalama uygulaması, forwardWheel() kullanarak yakalama uygulamasının kendisindeki bir kaynak öğeden gelen tekerlek etkinliklerini yakalanan sekmenin görünüm alanına iletebilir. Bu etkinlikler, doğrudan kullanıcı etkileşiminden yakalanan uygulama için ayırt edilemez.
Yakalama uygulamasının "previewTile" adlı bir <video> öğesi kullandığını varsayarsak aşağıdaki kodda, tekerlek gönderme etkinliklerinin yakalanan sekmeye nasıl iletileceği gösterilmektedir:
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() yöntemi, aşağıdakilerden biri olabilen tek bir giriş alır:
- Tekerlek etkinliklerinin yakalanan sekmeye yönlendirileceği bir HTML öğesi.
nullsimgesini tıklayın. Bu simge, yönlendirmenin durdurulması gerektiğini belirtir.
forwardWheel() için yapılan başarılı bir çağrı, önceki çağrıları geçersiz kılar.
forwardWheel() tarafından döndürülen söz aşağıdaki durumlarda reddedilebilir:
- Kayıt oturumu henüz başlamadıysa veya zaten durdurulduysa
- Kullanıcı ilgili izni vermediyse.
Tarih aralığını
Yakalanan sekmenin yakınlaştırma düzeyiyle etkileşim, aşağıdaki CaptureController API yüzeyleri aracılığıyla yapılır:
getSupportedZoomLevels()
Bu yöntem, yakalanan yüzey türü için tarayıcı tarafından desteklenen yakınlaştırma düzeylerinin listesini döndürür. Bu listedeki değerler, %100 olarak tanımlanan "varsayılan yakınlaştırma düzeyi"ne göre yüzde olarak gösterilir. Liste, tekdüze bir şekilde artıyor ve 100 değerini içeriyor.
Bu yöntem yalnızca desteklenen görüntüleme yüzeyi türleri için çağrılabilir. Şu anda bu, yalnızca sekmeler için geçerlidir.
Aşağıdaki koşullar geçerliyse controller.getSupportedZoomLevels() çağrılabilir:
controlleretkin bir kayıtla ilişkilendirilmiş.- Yakalama, bir sekmeye ait olmalıdır.
Aksi takdirde hata oluşur.
Bu yöntemi çağırmak için "captured-surface-control" izni gerekli değildir.
zoomLevel
Bu salt okunur özellik, yakalanan sekmenin mevcut yakınlaştırma düzeyini tutar. Boş değer atanabilir bir özelliktir ve yakalanan yüzey türünün anlamlı bir yakınlaştırma düzeyi tanımı yoksa null değerini içerir. Şu anda yalnızca sekmeler için tanımlanmış olan yakınlaştırma düzeyi, pencereler veya ekranlar için tanımlanmamıştır.
Çekim sona erdikten sonra özellik, son yakınlaştırma düzeyi değerini tutar.
Bu özelliği okumak için "captured-surface-control" izni gerekli değildir.
onzoomlevelchange
Bu etkinlik işleyici, yakalanan sekmenin yakınlaştırma düzeyindeki değişikliklerin dinlenmesini kolaylaştırır. Bunlar şu durumlarda gerçekleşir:
- Kullanıcı, yakalanan sekmenin yakınlaştırma düzeyini manuel olarak değiştirmek için tarayıcıyla etkileşimde bulunduğunda.
- Aşağıda açıklanan, yakalama uygulamasının yakınlaştırma ayarı yöntemlerine yaptığı çağrılara yanıt olarak.
Bu özelliği okumak için "captured-surface-control" izni gerekli değildir.
increaseZoomLevel(), decreaseZoomLevel() ve resetZoomLevel()
Bu yöntemler, yakalanan sekmenin yakınlaştırma düzeyinin değiştirilmesine olanak tanır.
increaseZoomLevel() ve decreaseZoomLevel(), getSupportedZoomLevels() tarafından döndürülen sıralamaya göre yakınlaştırma düzeyini sırasıyla bir sonraki veya önceki yakınlaştırma düzeyine değiştirir. resetZoomLevel() değeri 100 olarak ayarlar.
Bu yöntemlerin çağrılması için "captured-surface-control" izni gerekir. Kaydetme uygulamasında bu izin yoksa kullanıcıdan izni vermesi veya reddetmesi istenir.
Bu yöntemlerin tümü, arama başarılı olursa çözülen, aksi takdirde reddedilen bir söz döndürür. Reddedilmenin olası nedenleri şunlardır:
- İzin eksik.
- Görüntü yakalama başlamadan önce arama yapıldı.
- Kaydetme işlemi sona erdikten sonra arama yapıldıysa
- Desteklenmeyen bir görüntüleme yüzeyi türünün yakalanmasıyla ilişkili bir
controllerüzerinde çağrıldı. (Yani, sekme yakalama dışındaki her şey.) - Sırasıyla maksimum veya minimum değerin ötesine artırma ya da azaltma girişimleri.
Özellikle, controller.zoomLevel == controller.getSupportedZoomLevels().at(0) ise decreaseZoomLevel() numarası aranmamalı ve increaseZoomLevel() numarasıyla yapılan aramalar .at(-1) ile benzer şekilde korunmalıdır.
Aşağıdaki örnekte, kullanıcının yakalanan bir sekmenin yakınlaştırma düzeyini doğrudan yakalama uygulamasından artırmasına nasıl izin verileceği gösterilmektedir:
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.
// ...
}
});
Aşağıdaki örnekte, yakalanan bir sekmenin yakınlaştırma düzeyi değişikliklerine nasıl tepki verileceği gösterilmektedir:
controller.addEventListener('zoomlevelchange', (event) => {
const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});
Özellik algılama
Captured Surface Control API'lerinin desteklenip desteklenmediğini kontrol etmek için:
if (!!window.CaptureController?.prototype.forwardWheel) {
// CaptureController forwardWheel() is supported.
}
increaseZoomLevel veya decreaseZoomLevel gibi diğer Captured Surface Control API yüzeylerinden herhangi birini kullanmak ya da hepsini kontrol etmek de mümkündür.
Tarayıcı desteği
Yakalanan Yüzey Kontrolü yalnızca masaüstünde Chrome 136 ve sonraki sürümlerde kullanılabilir.
Güvenlik ve gizlilik
"captured-surface-control" İzin politikası, yakalama uygulamanızın ve yerleştirilmiş üçüncü taraf iFrame'lerinin Captured Surface Control'e nasıl erişebileceğini yönetmenize olanak tanır. Güvenlikteki ödünleşmeleri anlamak için Captured Surface Control açıklayıcısının Gizlilik ve Güvenlikle İlgili Hususlar bölümüne göz atın.
Demo
Demoyu çalıştırarak Captured Surface Control ile oynayabilirsiniz.
Geri bildirim
Chrome ekibi ve web standartları topluluğu, Captured Surface Control ile ilgili deneyimlerinizi öğrenmek istiyor.
Tasarım hakkında bilgi verin
Yakalama Yüzeyi Yakalama özelliğiyle ilgili olarak beklediğiniz gibi çalışmayan bir şey var mı? Yoksa fikrinizi uygulamak için eksik yöntemler veya özellikler mi var? Güvenlik modeliyle ilgili sorunuz veya yorumunuz mu var? GitHub deposunda bir spesifikasyon sorunu bildirin veya düşüncelerinizi mevcut bir soruna ekleyin.
Uygulamayla ilgili sorun mu yaşıyorsunuz?
Chrome'un uygulamasında bir hata mı buldunuz? Yoksa uygulama, spesifikasyondan farklı mı? https://new.crbug.com adresinden hata bildirin. Mümkün olduğunca fazla ayrıntı ve yeniden üretme talimatları eklediğinizden emin olun.