Concetti dell'API Meet Media

L'API Media di Google Meet consente alla tua app di partecipare a una conferenza di Google Meet e di consumare stream multimediali in tempo reale.

I client utilizzano WebRTC per comunicare con i server di Meet. I client di riferimento forniti (C++, TypeScript) mostrano le best practice consigliate e ti invitiamo a basarti direttamente su di essi.

Tuttavia, puoi anche creare client WebRTC completamente personalizzati che rispettino i requisiti tecnici dell'API Meet Media.

Questa pagina illustra i concetti chiave di WebRTC necessari per una sessione dell'API Meet Media di successo.

Indicatori di risposta all'offerta

WebRTC è un framework peer-to-peer (P2P), in cui i peer comunicano inviandosi annunci. Per avviare una sessione, il peer che avvia la sessione invia un'offerta SDP a un peer remoto. Questa offerta include i seguenti dettagli importanti:

Descrizioni dei contenuti multimediali per audio e video

Le descrizioni dei contenuti multimediali indicano cosa viene comunicato durante le sessioni P2P. Esistono tre tipi di descrizioni: audio, video e dati.

Per indicare n stream audio, l'offerente include n descrizioni dei contenuti multimediali audio nell'offerta. Lo stesso vale per i video. Tuttavia, esisterà al massimo una descrizione dei media di dati.

Senso di marcia

Ogni descrizione audio o video descrive singoli stream Secure Real-time Transport Protocol (SRTP), regolati da RFC 3711. Sono bidirezionali, permettono a due peer di inviare e ricevere contenuti multimediali tramite la stessa connessione.

Per questo motivo, ogni descrizione multimediale (sia nell'offerta che nella risposta) contiene uno di tre attributi che descrivono come deve essere utilizzato lo stream:

• sendonly: invia solo i contenuti multimediali del peer dell'offerta. Il peer remoto non invierà contenuti multimediali su questo stream.

• recvonly: riceve solo contenuti multimediali dal peer remoto. Il peer dell'offerta non invierà contenuti multimediali su questo stream.

• sendrecv: entrambi i peer possono inviare e ricevere su questo stream.

Codec

Ogni descrizione dei contenuti multimediali specifica anche i codec supportati da un peer. Nel caso dell'API Meet Media, le offerte dei client vengono rifiutate a meno che non supportino almeno i codec specificati nei requisiti tecnici.

Handshake DTLS

Gli stream SRTP sono protetti da un handshake iniziale di Datagram Transport Layer Security ("DTLS", RFC 9147) tra i peer. DTLS è tradizionalmente un protocollo client-to-server; durante la procedura di segnalazione, un peer accetta di agire come server, mentre l'altro come peer.

Poiché ogni stream SRTP potrebbe avere una propria connessione DTLS dedicata, ogni descrizione multimediale specifica uno di tre attributi per indicare il ruolo del peer nell'handshake DTLS:

• a=setup:actpass: il peer dell'offerta rimanda alla scelta del peer remoto.

• a=setup:active: questo peer agisce come client.

• a=setup:passive: questo peer funge da server.

Descrizioni dei contenuti multimediali delle applicazioni

I canali di dati (RFC 8831) sono un'astrazione del Stream Control Transmission Protocol ("SCTP", RFC 9260).

Per aprire i canali di dati durante la fase di segnalazione iniziale, l'offerta deve contenere una descrizione dei contenuti multimediali dell'applicazione. A differenza delle descrizioni audio e video, le descrizioni delle applicazioni non specificano la direzione o i codec.

Candidati ICE

I candidati per l'Interactive Connectivity Establishment ("ICE", RFC 8445) di un peer sono un elenco di route che un peer remoto può utilizzare per stabilire una connessione.

Il prodotto cartesiano degli elenchi dei due peer, noto come coppie candidate, rappresenta i potenziali percorsi tra due peer. Queste coppie vengono testate per determinare il percorso ottimale.

Segnale tramite l'API REST di Meet

Utilizza l'API REST di Meet per eseguire questo segnale di offerta-risposta. La tua app fornisce un'offerta SDP al metodo connectActiveConference() e riceve in cambio una risposta SDP.

Esempio di flusso di connessione

Ecco un'offerta con una descrizione dei contenuti multimediali audio:

Il peer remoto risponde con una risposta SDP contenente lo stesso numero di righe di descrizione dei contenuti multimediali. Ogni riga indica i contenuti multimediali, se presenti, che il peer remoto invia al client dell'offerta tramite gli stream SRTP. Il peer remoto potrebbe anche rifiutare stream specifici dell'offerente impostando la voce della descrizione dei contenuti multimediali su recvonly.

Per l'API Meet Media, i client inviano sempre l'offerta SDP per avviare una connessione. Meet non è mai l'iniziatore.

Questo comportamento viene gestito internamente dai client di riferimento (C++, TypeScript), ma gli sviluppatori di client personalizzati possono utilizzare PeerConnectionInterface di WebRTC per generare un'offerta.

Per connettersi a Meet, l'offerta deve soddisfare specifici requisiti:

1. Il client deve sempre agire come client nell'handshake DTLS, pertanto ogni descrizione dei contenuti multimediali nell'offerta deve specificare a=setup:actpass o a=setup:active.

2. Ogni riga di descrizione dei contenuti multimediali deve supportare tutti i codec obbligatori per quel tipo di contenuti multimediali:

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

3. Per ricevere l'audio, l'offerta deve includere esattamente 3 descrizioni di media audio solo per la ricezione. Puoi farlo impostando i transceiver sull'oggetto connessione 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. Per ricevere video, l'offerta deve includere 1-3 descrizioni di contenuti multimediali video di sola ricezione. Puoi farlo impostando i transceiver sull'oggetto connessione 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. L'offerta deve sempre includere i canali di dati. Come minimo, i canali session-control e media-stats devono essere sempre aperti. Tutti i canali di dati devono essere 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);
   };
   

Esempio di offerta e risposta SDP

Di seguito è riportato un esempio completo di un'offerta SDP valida e di una risposta SDP corrispondente. Questa offerta negozia una sessione dell'API Media di Meet con audio e un singolo stream video.

Notare che sono presenti tre descrizioni di contenuti multimediali audio, una descrizione di contenuti multimediali video e la descrizione di contenuti multimediali dell'applicazione richiesta.

Argomenti correlati

• Inizia