Sekme, pencere ve ekran paylaşımı, web platformunda Screen Capture API ile zaten mümkündür. Bir web uygulaması getDisplayMedia() çağrısı yaptığında Chrome, kullanıcıdan bir sekmeyi, pencereyi veya ekranı web uygulamasıyla MediaStreamTrack videosu olarak paylaşmasını ister.
getDisplayMedia() kullanan birçok web uygulaması, kullanıcıya yakalanan yüzeyin video önizlemesini gösterir. Örneğin, video konferans uygulamaları genellikle bu videoyu uzaktaki kullanıcılara aktarırken yerel bir HTMLVideoElement'a da oluşturur. Böylece yerel kullanıcı, paylaştığı içeriğin önizlemesini sürekli olarak görebilir.
Bu dokümanda, Chrome'daki yeni Captured Surface Control API (Yakalanan Yüzey Kontrol API'si) tanıtılmaktadır. Bu API, web uygulamanızın yakalanan bir sekmeyi kaydırmasına ve yakalanan sekmenin yakınlaştırma düzeyini okumasına ve yazmasına olanak tanır.
Yakalanan Yüzey Denetimi'ni neden kullanmalısınız?
Tüm video konferans uygulamaları aynı dezavantaja sahiptir. Kullanıcı, yakalanan bir sekme veya pencereyle etkileşim kurmak isterse video konferans uygulamasından ayrılarak bu yüzeye geçmesi gerekir. Bu durum bazı zorluklar doğurur:
- Kullanıcı, pencere içinde pencere özelliğini veya görüntülü konferans sekmesi ile paylaşılan sekme için ayrı yan yana pencereler kullanmadığı sürece, yakalanan uygulamayı ve uzak kullanıcıların video feed'lerini aynı anda göremez. Bu işlem, küçük ekranlarda zor olabilir.
- Kullanıcı, video konferans uygulaması ile yakalanan yüzey arasında geçiş yapmak zorunda kalır.
- Kullanıcı, görüntülü konferans uygulamasından ayrıldığında uygulama tarafından sunulan denetimlere (ör. yerleşik sohbet uygulaması, emoji tepkileri, görüşmeye katılmak isteyen kullanıcılarla ilgili bildirimler, multimedya ve düzen denetimleri ve diğer kullanışlı görüntülü konferans özellikleri) erişemez.
- Sunucu, uzak katılımcılara kontrol yetkisi veremez. Bu durum, uzaktaki kullanıcıların sunucunun slaytı değiştirmesini, biraz yukarı veya aşağı kaydırmasını ya da 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ı giderir.
Yakalanan Yüzey Denetimi'ni nasıl kullanırım?
Yakalanan Yüzey Denetimi'ni başarılı bir şekilde kullanmak için birkaç adım gerekir. Örneğin, bir tarayıcı sekmesini açıkça yakalamak ve yakalanan sekmeyi kaydırıp yakınlaştırmadan önce kullanıcıdan izin almak gerekir.
Tarayıcı sekmesi yakalama
Kullanıcıdan getDisplayMedia() kullanarak paylaşılacak bir yüzey seçmesini isteyerek başlayın ve bu süreçte yakalama oturumuyla bir CaptureController nesnesi ilişkilendirin. Yakında 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 işlem şu anda 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 nesnesi üzerinde forwardWheel(), increaseZoomLevel(), decreaseZoomLevel() veya resetZoomLevel() işlevinin ilk çağrılması bir izin istemi oluşturur. Kullanıcı izin verirse bu yöntemlerin daha fazla çağrılmasına izin verilir.
Kullanıcıya izin istemi göstermek için bir kullanıcı hareketi gerekir. Bu nedenle, uygulama yukarıda belirtilen yöntemleri yalnızca izine sahipse veya web uygulamasındaki ilgili bir düğmede click gibi bir kullanıcı hareketine yanıt olarak çağırmalıdır.
Kaydırma
forwardWheel() kullanarak, yakalama uygulaması, yakalama uygulamasındaki bir kaynak öğeden tekerlek etkinliklerini yakalanan sekmenin görüntü alanını yönlendirebilir. Bu etkinlikler, yakalanan uygulama tarafından doğrudan kullanıcı etkileşiminden ayırt edilemez.
Kaydeden uygulamanın "previewTile" adlı bir <video> öğesi kullandığı varsayıldığında, aşağıdaki kodda tekerlek etkinliklerinin yakalanan sekmeye nasıl aktarılacağı 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 olabilecek tek bir giriş alır:
- Tekerlek etkinliklerinin yakalanan sekmeye yönlendirileceği bir HTML öğesi.
null, yönlendirmenin durdurulması gerektiğini gösterir.
forwardWheel() adresine 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şlatılmamışsa veya zaten durdurulmuşsa.
- Kullanıcı ilgili izni vermediyse.
Tarih aralığını
Yakalanan sekmenin yakınlaştırma seviyesiyle etkileşim, aşağıdaki CaptureController API yüzeyleri aracılığıyla gerçekleştirilir:
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üzeyine" göre yüzde olarak gösterilir. Liste monoton olarak 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.
controller.getSupportedZoomLevels() aşağıdaki koşullar geçerliyse çağrılabilir:
controlleretkin bir yakalamayla ilişkilendirilmiş.- Yakalama, bir sekmeyi gösteriyor.
Aksi takdirde hata oluşur.
Bu yöntemi çağırmak için "captured-surface-control" izni gerekmez.
zoomLevel
Bu salt okunur özellik, yakalanan sekmenin mevcut yakınlaştırma seviyesini içerir. 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 yakınlaştırma seviyesi yalnızca sekmeler için tanımlanır, pencereler veya ekranlar için tanımlanmaz.
Kayıt sona erdikten sonra özellik, son yakınlaştırma düzeyi değerini tutar.
Bu özelliği okumak için "captured-surface-control" izni gerekmez.
onzoomlevelchange
Bu etkinlik işleyici, yakalanan sekmenin yakınlaştırma seviyesindeki değişiklikleri dinlemeyi kolaylaştırır. Bu durumlar aşağıdaki durumlarda ortaya çıkar:
- Kullanıcı, yakalanan sekmenin yakınlaştırma düzeyini manuel olarak değiştirmek için tarayıcıyla etkileşime geçtiğinde.
- Kayıt uygulamasının yakınlaştırma ayarı yöntemlerine (aşağıda açıklanmıştır) yaptığı çağrılara yanıt olarak.
Bu özelliği okumak için "captured-surface-control" izni gerekmez.
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öntemleri çağırmak için "captured-surface-control" izni gerekir. Kayıt uygulamasında bu izin yoksa kullanıcıdan izin vermesi veya reddetmesi istenir.
Bu yöntemlerin tümü, arama başarılı olursa çözülen ve aksi takdirde reddedilen bir promise döndürür. Reddetme nedenleri arasında şunlar yer alır:
- İzin eksik.
- Kayıt başlamadan önce çağrıldı.
- Kayıt sona erdikten sonra çağrılır.
- Desteklenmeyen bir ekran yüzeyi türünün yakalanmasıyla ilişkili bir
controllerüzerinde çağrılır. (Yani, sekme yakalama dışındaki her şey.) - Sırasıyla maksimum veya minimum değeri aşmaya çalışır.
controller.zoomLevel == controller.getSupportedZoomLevels().at(0) ise decreaseZoomLevel()'e arama yapmaktan kaçınılması ve .at(-1) ile benzer şekilde increaseZoomLevel()'e yapılan aramaları korumanız önerilir.
Aşağıdaki örnekte, kullanıcının yakalanan bir sekmenin yakınlaştırma düzeyini doğrudan yakalama uygulamasından nasıl artırabileceğ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
Yakalanan Yüzey Kontrolü 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 hatta bunların tümünü kontrol etmek de aynı derecede mümkündür.
Tarayıcı desteği
Yakalanan Yüzey Kontrolü, yalnızca Chrome 136'tan itibaren masaüstünde kullanılabilir.
Güvenlik ve gizlilik
"captured-surface-control" İzin politikası, yakalama uygulamanızın ve yerleştirilmiş üçüncü taraf iFrame'lerinin, yakalanan yüzey kontrolüne nasıl erişeceğini yönetmenizi sağlar. Güvenlikle ilgili avantajları ve dezavantajları anlamak için, yakalanan yüzey kontrolüyle ilgili açıklamanın Gizlilik ve Güvenlik Konusunda Dikkat Edilmesi Gerekenler bölümüne göz atın.
Demo
Glitch'te demoyu çalıştırarak Captured Surface Control ile oynayabilirsiniz. Kaynak koduna göz atmayı unutmayın.
Geri bildirim
Chrome Ekibi ve web standartları topluluğu, Captured Surface Control ile ilgili deneyimlerinizi öğrenmek istiyor.
Tasarım hakkında bilgi verin
Yakalanan Yüzey Yakalama özelliğiyle ilgili olarak beklediğiniz gibi çalışmayan bir şey mi var? Yoksa fikrinizi uygulamak için ihtiyaç duyduğunuz yöntemler veya özellikler eksik mi? Güvenlik modeliyle ilgili sorunuz veya yorumunuz mu var? GitHub deposunda spesifikasyon sorunu oluşturun veya mevcut bir soruna düşüncelerinizi 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. Olabildiğince fazla ayrıntı ve sorunun yeniden üretilmesiyle ilgili talimatlar eklediğinizden emin olun. Glitch, yeniden üretilebilir hataları paylaşmak için idealdir.