Memahami konsep Media API

Google Meet Media API memungkinkan aplikasi Anda bergabung ke konferensi Google Meet dan menggunakan streaming media real-time.

Klien menggunakan WebRTC untuk berkomunikasi dengan server Meet. Klien referensi yang disediakan (C++, TypeScript) menunjukkan praktik yang direkomendasikan dan Anda disarankan untuk mem-build langsung berdasarkannya.

Namun, Anda juga dapat mem-build klien WebRTC yang sepenuhnya kustom dan mematuhi persyaratan teknis Meet Media API.

Halaman ini menguraikan konsep WebRTC utama yang diperlukan untuk sesi Meet Media API yang berhasil.

Sinyal jawaban penawaran

WebRTC adalah framework peer-to-peer (P2P), tempat peer berkomunikasi dengan saling memberi sinyal. Untuk memulai sesi, peer yang memulai mengirimkan penawaran SDP ke peer jarak jauh. Penawaran ini menyertakan detail penting berikut:

Deskripsi media untuk audio dan video

Deskripsi media menunjukkan apa yang dikomunikasikan selama sesi P2P. Ada tiga jenis deskripsi: audio, video, dan data.

Untuk menunjukkan streaming audio n, penawar menyertakan deskripsi media audio n dalam penawaran. Hal yang sama berlaku untuk video. Namun, hanya akan ada maksimal satu deskripsi media data.

Arah

Setiap deskripsi audio atau video menjelaskan setiap aliran data Secure Real-time Transport Protocol (SRTP), yang diatur oleh RFC 3711. Koneksi ini bersifat dua arah, sehingga memungkinkan dua peer mengirim dan menerima media melalui koneksi yang sama.

Oleh karena itu, setiap deskripsi media (baik dalam penawaran maupun jawaban) berisi salah satu dari tiga atribut yang menjelaskan cara penggunaan streaming:

• sendonly: Hanya mengirim media dari peer penawaran. Peer jarak jauh tidak akan mengirim media di streaming ini.

• recvonly: Hanya menerima media dari peer jarak jauh. Peer penawaran tidak akan mengirim media di streaming ini.

• sendrecv: Kedua peer dapat mengirim dan menerima di streaming ini.

Codec

Setiap deskripsi media juga menentukan codec yang didukung peer. Dalam kasus Meet Media API, penawaran klien akan ditolak kecuali jika mendukung (setidaknya) codec yang ditentukan dalam persyaratan teknis.

Handshake DTLS

Streaming SRTP diamankan oleh handshake Datagram Transport Layer Security ("DTLS", RFC 9147) awal antara peer. DTLS secara tradisional adalah protokol klien ke server; selama proses sinyal, satu peer setuju untuk bertindak sebagai server, sedangkan yang lain bertindak sebagai peer.

Karena setiap aliran SRTP mungkin memiliki koneksi DTLS khusus, setiap deskripsi media menentukan salah satu dari tiga atribut untuk menunjukkan peran peer dalam handshake DTLS:

• a=setup:actpass: Peer penawaran menunda pilihan peer jarak jauh.

• a=setup:active: Peer ini bertindak sebagai klien.

• a=setup:passive: Peer ini bertindak sebagai server.

Deskripsi media aplikasi

Saluran data (RFC 8831) adalah abstraksi dari Stream Control Transmission Protocol ("SCTP", RFC 9260).

Untuk membuka saluran data selama fase sinyal awal, penawaran harus berisi deskripsi media aplikasi. Tidak seperti deskripsi audio dan video, deskripsi aplikasi tidak menentukan arah atau codec.

Kandidat ICE

Calon Interactive Connectivity Establishment ("ICE", RFC 8445) peer adalah daftar rute yang dapat digunakan peer jarak jauh untuk membuat koneksi.

Produk Kartesius dari dua daftar peer, yang dikenal sebagai pasangan kandidat, mewakili rute potensial antara dua peer. Pasangan ini diuji untuk menentukan rute yang optimal.

Sinyal melalui Meet REST API

Gunakan Meet REST API untuk melakukan sinyal penawaran-jawaban ini. Aplikasi Anda memberikan penawaran SDP ke metode connectActiveConference() dan menerima jawaban SDP sebagai gantinya.

Contoh alur koneksi

Berikut adalah penawaran dengan deskripsi media audio:

Peer jarak jauh merespons dengan jawaban SDP yang berisi jumlah baris deskripsi media yang sama. Setiap baris menunjukkan media apa, jika ada, yang dikirim kembali oleh peer jarak jauh ke klien penawaran melalui streaming SRTP. Peer jarak jauh juga dapat menolak streaming tertentu dari penawar dengan menetapkan entri deskripsi media tersebut ke recvonly.

Untuk Meet Media API, klien selalu mengirim penawaran SDP untuk memulai koneksi. Meet tidak pernah menjadi inisiator.

Perilaku ini dikelola secara internal oleh klien referensi (C++, TypeScript), tetapi developer klien kustom dapat menggunakan PeerConnectionInterface WebRTC untuk membuat penawaran.

Untuk terhubung ke Meet, penawaran harus mematuhi persyaratan tertentu:

1. Klien harus selalu bertindak sebagai klien dalam handshake DTLS, sehingga setiap deskripsi media dalam penawaran harus menentukan a=setup:actpass atau a=setup:active.

2. Setiap baris deskripsi media harus mendukung semua codec yang diperlukan untuk jenis media tersebut:

   • Audio: Opus
   • Video: VP8, VP9, AV1

3. Untuk menerima audio, penawaran harus menyertakan tepat 3 deskripsi media audio khusus terima. Anda dapat melakukannya dengan menyetel transceiver pada objek koneksi peer.

   C++

   // ...
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   for (int i = 0; i < 3; ++i) {
     webrtc::RtpTransceiverInit audio_init;
     audio_init.direction = webrtc::RtpTransceiverDirection::kRecvOnly;
     audio_init.stream_ids = {absl::StrCat("audio_stream_", i)};
   
     webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::RtpTransceiverInterface>>
       audio_result = peer_connection->AddTransceiver(
         cricket::MediaType::MEDIA_TYPE_AUDIO, audio_init);
   
     if (!audio_result.ok()) {
       return absl::InternalError(absl::StrCat("Failed to add audio transceiver: ",
                                               audio_result.error().message()));
     }
   }
   

   JavaScript

   pc = new RTCPeerConnection();
   
   // Configure client to receive audio from Meet servers.
   pc.addTransceiver('audio', {'direction':'recvonly'});
   pc.addTransceiver('audio', {'direction':'recvonly'});
   pc.addTransceiver('audio', {'direction':'recvonly'});
   

4. Untuk menerima video, penawaran harus menyertakan 1–3 deskripsi media video khusus terima. Anda dapat melakukannya dengan menyetel transceiver pada objek koneksi peer.

   C++

   // ...
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   for (uint32_t i = 0; i < configurations.receiving_video_stream_count; ++i) {
     webrtc::RtpTransceiverInit video_init;
     video_init.direction = webrtc::RtpTransceiverDirection::kRecvOnly;
     video_init.stream_ids = {absl::StrCat("video_stream_", i)};
   
     webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::RtpTransceiverInterface>>
         video_result = peer_connection->AddTransceiver(
           cricket::MediaType::MEDIA_TYPE_VIDEO, video_init);
   
     if (!video_result.ok()) {
       return absl::InternalError(absl::StrCat("Failed to add video transceiver: ",
                                               video_result.error().message()));
     }
   }
   

   JavaScript

   pc = new RTCPeerConnection();
   
   // Configure client to receive video from Meet servers.
   pc.addTransceiver('video', {'direction':'recvonly'});
   pc.addTransceiver('video', {'direction':'recvonly'});
   pc.addTransceiver('video', {'direction':'recvonly'});
   

5. Penawaran harus selalu menyertakan saluran data. Minimal, saluran session-control dan media-stats harus selalu terbuka. Semua saluran data harus berupa ordered.

   C++

   // ...
   // All data channels must be ordered.
   constexpr webrtc::DataChannelInit kDataChannelConfig = {.ordered = true};
   
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   // Signal session-control data channel.
   webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::DataChannelInterface>>
     session_create_result = peer_connection->CreateDataChannelOrError(
       "session-control", &kDataChannelConfig);
   
   if (!session_create_result.ok()) {
     return absl::InternalError(absl::StrCat("Failed to create data channel ",
                                             data_channel_label, ": ",
                                             session_create_result.error().message()));
   }
   
   // Signal media-stats data channel.
   webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::DataChannelInterface>>
     stats_create_result = peer_connection->CreateDataChannelOrError(
       "media-stats", &kDataChannelConfig);
   
   if (!stats_create_result.ok()) {
     return absl::InternalError(absl::StrCat("Failed to create data channel ",
                                             data_channel_label, ": ",
                                             stats_create_result.error().message()));
   }
   

   JavaScript

   // ...
   pc = new RTCPeerConnection();
   
   // All data channels must be ordered.
   const dataChannelConfig = {
     ordered: true,
   };
   
   // Signal session-control data channel.
   sessionControlChannel = pc.createDataChannel('session-control', dataChannelConfig);
   sessionControlChannel.onopen = () => console.log("data channel is now open");
   sessionControlChannel.onclose = () => console.log("data channel is now closed");
   sessionControlChannel.onmessage = async (e) => {
     console.log("data channel message", e.data);
   };
   
   // Signal media-stats data channel.
   mediaStatsChannel = pc.createDataChannel('media-stats', dataChannelConfig);
   mediaStatsChannel.onopen = () => console.log("data channel is now open");
   mediaStatsChannel.onclose = () => console.log("data channel is now closed");
   mediaStatsChannel.onmessage = async (e) => {
     console.log("data channel message", e.data);
   };
   

Contoh penawaran dan jawaban SDP

Berikut adalah contoh lengkap penawaran SDP yang valid dan jawaban SDP yang cocok. Penawaran ini melakukan negosiasi sesi Meet Media API dengan audio dan satu streaming video.

Perhatikan bahwa ada tiga deskripsi media audio, satu deskripsi media video, dan deskripsi media aplikasi yang diperlukan.

Topik terkait

• Mulai