Berbagi tab, jendela, dan layar sudah dapat dilakukan di platform web dengan Screen Capture API. Saat aplikasi web memanggil getDisplayMedia(), Chrome akan meminta pengguna untuk membagikan tab, jendela, atau layar ke aplikasi web sebagai video MediaStreamTrack.
Banyak aplikasi web yang menggunakan getDisplayMedia() menampilkan pratinjau video permukaan yang diambil kepada pengguna. Misalnya, aplikasi konferensi video akan sering melakukan streaming video ini ke pengguna jarak jauh sekaligus merendernya ke HTMLVideoElement lokal, sehingga pengguna lokal akan terus melihat pratinjau dari apa yang mereka bagikan.
Dokumentasi ini memperkenalkan Captured Surface Control API baru di Chrome, yang memungkinkan aplikasi web Anda men-scroll tab yang diambil, serta membaca dan menulis tingkat zoom tab yang diambil.
Mengapa menggunakan Captured Surface Control?
Semua aplikasi konferensi video mengalami kekurangan yang sama. Jika pengguna ingin berinteraksi dengan tab atau jendela yang direkam, pengguna harus beralih ke platform tersebut, sehingga mereka keluar dari aplikasi konferensi video. Hal ini menimbulkan beberapa tantangan:
- Pengguna tidak dapat melihat aplikasi yang direkam dan feed video pengguna jarak jauh secara bersamaan, kecuali jika mereka menggunakan Picture-in-Picture atau jendela terpisah berdampingan untuk tab konferensi video dan tab bersama. Pada layar yang lebih kecil, hal ini mungkin sulit dilakukan.
- Pengguna terbebani dengan kebutuhan untuk beralih antara aplikasi konferensi video dan platform yang direkam.
- Pengguna kehilangan akses ke kontrol yang ditampilkan oleh aplikasi konferensi video saat mereka tidak berada di aplikasi tersebut; misalnya, aplikasi chat tersemat, reaksi emoji, notifikasi tentang pengguna yang meminta untuk bergabung ke panggilan, kontrol multimedia dan tata letak, serta fitur konferensi video berguna lainnya.
- Presentator tidak dapat mendelegasikan kontrol kepada peserta jarak jauh. Hal ini menyebabkan skenario yang sudah terlalu sering terjadi, yaitu pengguna jarak jauh meminta presenter untuk mengubah slide, men-scroll sedikit ke atas dan ke bawah, atau menyesuaikan tingkat zoom.
Captured Surface Control API mengatasi masalah ini.
Bagaimana cara menggunakan Kontrol Permukaan yang Ditangkap?
Menggunakan Captured Surface Control dengan sukses memerlukan beberapa langkah, seperti mengambil tab browser secara eksplisit dan mendapatkan izin dari pengguna sebelum dapat men-scroll dan melakukan zoom pada tab yang diambil.
Mengambil gambar tab browser
Mulai dengan meminta pengguna untuk memilih platform yang akan dibagikan menggunakan getDisplayMedia(), dan dalam prosesnya, kaitkan objek CaptureController dengan sesi pengambilan. Kita akan segera menggunakan objek tersebut untuk mengontrol platform yang diambil.
const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });
Selanjutnya, buat pratinjau lokal platform yang diambil dalam bentuk elemen <video>:
const previewTile = document.querySelector('video');
previewTile.srcObject = stream;
Jika pengguna memilih untuk membagikan jendela atau layar, hal itu di luar cakupan untuk saat ini—tetapi jika mereka memilih untuk membagikan tab, kita dapat melanjutkan.
const [track] = stream.getVideoTracks();
if (track.getSettings().displaySurface !== 'browser') {
// Bail out early if the user didn't pick a tab.
return;
}
Permintaan izin
Pemanggilan pertama forwardWheel(), increaseZoomLevel(), decreaseZoomLevel(), atau resetZoomLevel() pada objek CaptureController tertentu akan menghasilkan perintah izin. Jika pengguna memberikan izin, pemanggilan metode ini lebih lanjut akan diizinkan.
Gestur pengguna diperlukan untuk menampilkan perintah izin kepada pengguna, sehingga aplikasi hanya boleh memanggil metode yang disebutkan di atas jika sudah memiliki izin, atau sebagai respons terhadap gestur pengguna, seperti click pada tombol yang relevan di aplikasi Web.
Scroll
Dengan menggunakan forwardWheel(), aplikasi pengambilan dapat meneruskan peristiwa roda dari elemen sumber dalam aplikasi pengambilan itu sendiri ke area pandang tab yang diambil. Peristiwa ini tidak dapat dibedakan oleh aplikasi yang direkam dari interaksi pengguna langsung.
Dengan asumsi aplikasi pengambilan menggunakan elemen <video> yang disebut "previewTile", kode berikut menunjukkan cara meneruskan peristiwa roda pengiriman ke tab yang diambil:
const previewTile = document.querySelector('video');
try {
// Relay the user's action to the captured tab.
await controller.forwardWheel(previewTile);
} catch (error) {
// Inspect the error.
// ...
}
Metode forwardWheel() menggunakan satu input yang dapat berupa salah satu dari hal berikut:
- Elemen HTML tempat peristiwa roda akan diteruskan ke tab yang diambil.
null, yang menunjukkan bahwa penerusan harus dihentikan.
Panggilan yang berhasil ke forwardWheel() akan menggantikan panggilan sebelumnya.
Promise yang ditampilkan oleh forwardWheel() dapat ditolak dalam kasus berikut:
- Jika sesi pengambilan belum dimulai atau telah dihentikan.
- Jika pengguna tidak memberikan izin yang relevan.
Zoom
Interaksi dengan tingkat zoom tab yang diambil dilakukan melalui platform CaptureController API berikut:
getSupportedZoomLevels()
Metode ini menampilkan daftar tingkat zoom yang didukung oleh browser untuk jenis platform yang diambil. Nilai dalam daftar ini direpresentasikan sebagai persentase yang relatif terhadap "tingkat zoom default", yang ditetapkan sebagai 100%. Daftar meningkat secara monoton dan berisi nilai 100.
Metode ini hanya boleh dipanggil untuk jenis platform tampilan yang didukung, yang saat ini berarti hanya untuk tab.
controller.getSupportedZoomLevels() dapat dipanggil jika kondisi berikut berlaku:
controllerdikaitkan dengan pengambilan aktif.- Rekaman adalah tab.
Jika tidak, error akan muncul.
Izin "captured-surface-control" tidak diperlukan untuk memanggil metode ini.
zoomLevel
Atribut hanya baca ini menyimpan tingkat zoom tab yang diambil saat ini. Ini adalah atribut nullable, dan menyimpan null jika jenis platform yang diambil tidak memiliki definisi tingkat zoom yang bermakna. Saat ini, tingkat zoom hanya ditentukan untuk tab, bukan untuk jendela atau layar.
Setelah pengambilan gambar berakhir, atribut akan menyimpan nilai tingkat zoom terakhir.
Izin "captured-surface-control" tidak diperlukan untuk membaca atribut ini.
onzoomlevelchange
Pengendali peristiwa ini memfasilitasi pemrosesan perubahan pada tingkat zoom tab yang diambil. Hal ini terjadi:
- Saat pengguna berinteraksi dengan browser untuk mengubah tingkat zoom tab yang diambil secara manual.
- Sebagai respons terhadap panggilan aplikasi pengambilan ke metode setelan zoom (dijelaskan di bawah).
Izin "captured-surface-control" tidak diperlukan untuk membaca atribut ini.
increaseZoomLevel(), decreaseZoomLevel(), dan resetZoomLevel()
Metode ini memungkinkan manipulasi tingkat zoom tab yang diambil.
increaseZoomLevel() dan decreaseZoomLevel() masing-masing mengubah tingkat zoom ke tingkat zoom berikutnya atau sebelumnya, sesuai dengan pengurutan yang ditampilkan oleh getSupportedZoomLevels(). resetZoomLevel() menetapkan nilai ke 100.
Izin "captured-surface-control" diperlukan untuk memanggil metode ini. Jika aplikasi pengambilan tidak memiliki izin ini, pengguna akan diminta untuk memberikan atau menolaknya.
Semua metode ini menampilkan promise yang di-resolve jika panggilan berhasil dan ditolak jika tidak. Kemungkinan penyebab penolakan meliputi:
- Izin tidak ada.
- Dipanggil sebelum perekaman dimulai.
- Dipanggil setelah pengambilan gambar berakhir.
- Dipanggil pada
controlleryang terkait dengan pengambilan jenis platform tampilan yang tidak didukung. (Artinya, apa pun kecuali rekam tab.) - Mencoba menaikkan atau menurunkan nilai maksimum atau minimum.
Secara khusus, sebaiknya hindari memanggil decreaseZoomLevel() jika controller.zoomLevel == controller.getSupportedZoomLevels().at(0), dan untuk melindungi panggilan ke increaseZoomLevel() dengan cara yang serupa dengan .at(-1).
Contoh berikut menunjukkan cara mengizinkan pengguna meningkatkan tingkat zoom tab yang diambil langsung dari aplikasi pengambilan:
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.
// ...
}
});
Contoh berikut menunjukkan cara bereaksi terhadap perubahan tingkat zoom tab yang diambil:
controller.addEventListener('zoomlevelchange', (event) => {
const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});
Deteksi fitur
Untuk memeriksa apakah Captured Surface Control API didukung, gunakan:
if (!!window.CaptureController?.prototype.forwardWheel) {
// CaptureController forwardWheel() is supported.
}
Anda juga dapat menggunakan platform Captured Surface Control API lainnya, seperti increaseZoomLevel atau decreaseZoomLevel, atau bahkan memeriksa semuanya.
Dukungan browser
Kontrol Permukaan yang Direkam hanya tersedia di Chrome 136 di desktop.
Keamanan dan privasi
Kebijakan izin "captured-surface-control" memungkinkan Anda mengelola cara aplikasi pengambilan dan iframe pihak ketiga tersemat memiliki akses ke Kontrol Permukaan yang Diambil. Untuk memahami kompromi keamanan, lihat bagian Pertimbangan Privasi dan Keamanan dalam penjelasan Kontrol Permukaan yang Direkam.
Demo
Anda dapat bermain dengan Captured Surface Control dengan menjalankan demo di Glitch. Pastikan untuk melihat kode sumbernya.
Masukan
Tim Chrome dan komunitas standar web ingin mengetahui pengalaman Anda dengan Captured Surface Control.
Beri tahu kami tentang desain
Apakah ada sesuatu tentang Captured Surface Capture yang tidak berfungsi seperti yang Anda harapkan? Atau apakah ada metode atau properti yang hilang yang Anda perlukan untuk menerapkan ide Anda? Ada pertanyaan atau komentar tentang model keamanan? Ajukan masalah spesifikasi di repo GitHub, atau tambahkan pendapat Anda ke masalah yang ada.
Mengalami masalah dengan penerapan?
Apakah Anda menemukan bug pada penerapan Chrome? Atau apakah implementasinya berbeda dengan spesifikasi? Laporkan bug di https://new.crbug.com. Pastikan untuk menyertakan detail sebanyak mungkin, serta petunjuk untuk mereproduksinya. Glitch sangat cocok untuk membagikan bug yang dapat direproduksi.