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 kepada pengguna jarak jauh sekaligus merendernya ke HTMLVideoElement lokal, sehingga pengguna lokal akan terus melihat pratinjau konten yang mereka bagikan.
Dokumentasi ini memperkenalkan Captured Surface Control API baru di Chrome, yang memungkinkan aplikasi web Anda men-scroll tab yang direkam, serta membaca dan menulis tingkat zoom tab yang direkam.
Mengapa menggunakan Kontrol Permukaan yang Direkam?
Semua aplikasi konferensi video memiliki kekurangan yang sama. Jika pengguna ingin berinteraksi dengan tab atau jendela yang direkam, pengguna harus beralih ke tab atau jendela tersebut, sehingga 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 berdampingan terpisah untuk tab konferensi video dan tab yang dibagikan. Di layar yang lebih kecil, hal ini bisa sulit dilakukan.
- Pengguna terbebani oleh 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 dekatnya; misalnya, aplikasi chat yang disematkan, reaksi emoji, notifikasi tentang pengguna yang meminta untuk bergabung ke panggilan, kontrol tata letak dan multimedia, serta fitur konferensi video berguna lainnya.
- Presenter tidak dapat mendelegasikan kontrol kepada peserta jarak jauh. Hal ini menyebabkan skenario yang sudah sangat umum, 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 Direkam?
Penggunaan Kontrol Area yang Direkam dengan sukses memerlukan beberapa langkah, seperti merekam tab browser secara eksplisit dan mendapatkan izin dari pengguna sebelum dapat men-scroll dan melakukan zoom pada tab yang direkam.
Merekam tab browser
Mulai dengan meminta pengguna memilih platform untuk berbagi menggunakan getDisplayMedia(), dan dalam prosesnya, kaitkan objek CaptureController dengan sesi pengambilan. Kita akan segera menggunakan objek tersebut untuk mengontrol permukaan yang diambil.
const controller = new CaptureController();
const stream = await navigator.mediaDevices.getDisplayMedia({ controller });
Selanjutnya, buat pratinjau lokal dari permukaan 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;
}
Dialog izin
Pemanggilan pertama forwardWheel(), increaseZoomLevel(), decreaseZoomLevel(), atau resetZoomLevel() pada objek CaptureController tertentu akan menghasilkan perintah izin. Jika pengguna memberikan izin, pemanggilan lebih lanjut dari metode ini diizinkan.
Gestur pengguna diperlukan untuk menampilkan dialog 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 forwardWheel(), aplikasi yang merekam dapat meneruskan peristiwa roda dari elemen sumber dalam aplikasi yang merekam itu sendiri ke area pandang tab yang direkam. Peristiwa ini tidak dapat dibedakan oleh aplikasi yang direkam dari interaksi pengguna langsung.
Dengan asumsi aplikasi perekaman menggunakan elemen <video> yang disebut "previewTile", kode berikut menunjukkan cara mengirimkan peristiwa roda yang diteruskan ke tab yang direkam:
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 berikut:
- Elemen HTML tempat peristiwa roda akan diteruskan ke tab yang direkam.
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 perekaman belum dimulai atau sudah berhenti.
- Jika pengguna tidak memberikan izin yang relevan.
Zoom
Interaksi dengan level zoom tab yang direkam dilakukan melalui platform API CaptureController berikut:
getSupportedZoomLevels()
Metode ini menampilkan daftar tingkat zoom yang didukung oleh browser untuk jenis permukaan yang direkam. Nilai dalam daftar ini ditampilkan sebagai persentase relatif terhadap "tingkat zoom default", yang ditentukan sebagai 100%. Daftar ini meningkat secara monoton dan berisi nilai 100.
Metode ini hanya dapat dipanggil untuk jenis platform tampilan yang didukung, yang saat ini berarti hanya untuk tab.
controller.getSupportedZoomLevels() dapat dipanggil jika kondisi berikut berlaku:
controllerdikaitkan dengan perekaman aktif.- Hasil pengambilan layar 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 saat ini dari tab yang direkam. Atribut ini dapat bernilai null, dan bernilai null jika jenis permukaan yang diambil tidak memiliki definisi tingkat zoom yang bermakna. Saat ini, tingkat zoom hanya ditentukan untuk tab, bukan untuk jendela atau layar.
Setelah pengambilan berakhir, atribut akan menyimpan nilai tingkat zoom terakhir.
Izin "captured-surface-control" tidak diperlukan untuk membaca atribut ini.
onzoomlevelchange
Handler peristiwa ini memfasilitasi pemrosesan perubahan pada tingkat zoom tab yang direkam. Hal ini terjadi:
- Saat pengguna berinteraksi dengan browser untuk mengubah tingkat zoom tab yang direkam 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 direkam.
increaseZoomLevel() dan decreaseZoomLevel() mengubah tingkat zoom ke tingkat zoom berikutnya atau sebelumnya, masing-masing, sesuai dengan pengurutan yang ditampilkan oleh getSupportedZoomLevels(). resetZoomLevel() menetapkan nilai ke 100.
Izin "captured-surface-control" diperlukan untuk memanggil metode ini. Jika aplikasi perekaman 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 pengambilan dimulai.
- Dipanggil setelah pengambilan gambar berakhir.
- Dipanggil pada
controlleryang terkait dengan pengambilan jenis permukaan tampilan yang tidak didukung. (Yaitu, apa pun kecuali perekaman tab.) - Upaya untuk menaikkan atau menurunkan nilai melewati nilai maksimum atau minimum.
Khususnya, sebaiknya hindari memanggil decreaseZoomLevel() jika controller.zoomLevel == controller.getSupportedZoomLevels().at(0), dan lindungi panggilan ke increaseZoomLevel() dengan cara yang sama dengan .at(-1).
Contoh berikut menunjukkan cara mengizinkan pengguna meningkatkan level zoom tab yang direkam langsung dari aplikasi perekaman:
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 level zoom tab yang direkam:
controller.addEventListener('zoomlevelchange', (event) => {
const zoomLevelLabel = document.querySelector('#zoomLevelLabel');
zoomLevelLabel.textContent = `${controller.zoomLevel}%`;
});
Deteksi fitur
Untuk memeriksa apakah API Kontrol Permukaan yang Direkam 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 Surface yang Diambil tersedia mulai Chrome 136 di desktop saja.
Keamanan dan privasi
Kebijakan izin "captured-surface-control" memungkinkan Anda mengelola cara aplikasi pengambilan dan iframe pihak ketiga yang disematkan memiliki akses ke Kontrol Permukaan yang Direkam. Untuk memahami kompromi keamanan, lihat bagian Pertimbangan Privasi dan Keamanan dalam penjelasan Kontrol Permukaan yang Direkam.
Demo
Anda dapat bereksperimen dengan Kontrol Permukaan yang Direkam dengan menjalankan demo.
Masukan
Tim Chrome dan komunitas standar web ingin mengetahui pengalaman Anda dengan Kontrol Permukaan yang Direkam.
Beri tahu kami tentang desainnya
Apakah ada sesuatu tentang Perekaman Permukaan yang Direkam yang tidak berfungsi seperti yang Anda harapkan? Atau, apakah ada metode atau properti yang hilang yang Anda butuhkan untuk menerapkan ide Anda? Ada pertanyaan atau komentar tentang model keamanan? Laporkan masalah spesifikasi di repositori 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 mereproduksi.