Conceitos da API Meet Media

A API Google Meet Media permite que seu app participe de uma conferência do Google Meet e consuma streams de mídia em tempo real.

Os clientes usam o WebRTC para se comunicar com os servidores do Meet. Os clientes de referência fornecidos (C++, TypeScript) demonstram as práticas recomendadas e recomendamos que você os use como base.

No entanto, também é possível criar clientes WebRTC totalmente personalizados que aderem aos requisitos técnicos da API Meet Media.

Esta página descreve os principais conceitos do WebRTC necessários para uma sessão bem-sucedida da API Meet Media.

Indicador de resposta à oferta

O WebRTC é um framework ponto a ponto (P2P, na sigla em inglês), em que os pares se comunicam sinalizando uns aos outros. Para iniciar uma sessão, o peer de início envia uma oferta SDP a um peer remoto. Essa oferta inclui os seguintes detalhes importantes:

Descrições de mídia para áudio e vídeo

As descrições de mídia indicam o que é comunicado durante as sessões P2P. Existem três tipos de descrições: áudio, vídeo e dados.

Para indicar transmissões de áudio n, o proponente inclui descrições de mídia de áudio n na oferta. O mesmo vale para vídeos. No entanto, haverá no máximo uma descrição de mídia de dados.

Direção

Cada descrição de áudio ou vídeo descreve fluxos individuais do Secure Real-time Transport Protocol (SRTP, na sigla em inglês), regidos por RFC 3711. Elas são bidirecionais, permitindo que dois pares enviem e recebam mídia pela mesma conexão.

Por isso, cada descrição de mídia (na oferta e na resposta) contém um dos três atributos que descrevem como o stream deve ser usado:

• sendonly: envia apenas mídia do peer de oferta. O peer remoto não vai enviar mídias nesse stream.

• recvonly: recebe mídia apenas do peer remoto. O peer de oferta não vai enviar mídia neste stream.

• sendrecv: ambos os pares podem enviar e receber neste fluxo.

Codecs

Cada descrição de mídia também especifica os codecs compatíveis com um peer. No caso da API Meet Media, as ofertas de cliente são rejeitadas, a menos que ofereçam suporte (pelo menos) aos codecs especificados nos requisitos técnicos.

Handshake do DTLS

As transmissões do SRTP são protegidas por um handshake inicial Datagram Transport Layer Security ("DTLS", RFC 9147) entre os pares. O DTLS é tradicionalmente um protocolo cliente-servidor. Durante o processo de sinalização, um peer concorda em atuar como o servidor, enquanto o outro atua como um peer.

Como cada fluxo SRTP pode ter a própria conexão DTLS dedicada, cada descrição de mídia especifica um dos três atributos para indicar o papel do peer no handshake DTLS:

• a=setup:actpass: o par de oferta depende da escolha do par remoto.

• a=setup:active: esse par atua como o cliente.

• a=setup:passive: esse peer atua como o servidor.

Descrições de mídia do app

Os canais de dados (RFC 8831) são uma abstração do Stream Control Transmission Protocol ("SCTP", RFC 9260).

Para abrir canais de dados durante a fase inicial de sinalização, a oferta precisa conter uma descrição de mídia do aplicativo. Ao contrário das descrições de áudio e vídeo, as descrições de aplicativos não especificam direção ou codecs.

Candidatos do ICE

Os candidatos de Estabelecimento de conectividade interativo ("ICE", RFC 8445) de um peer são uma lista de rotas que um peer remoto pode usar para estabelecer uma conexão.

O produto cartesiano das listas dos dois peers, conhecido como pares de candidatos, representa as rotas possíveis entre dois peers. Esses pares são testados para determinar a rota ideal.

Sinal pela API REST do Meet

Use a API REST do Meet para realizar essa sinalização de oferta-resposta. O app fornece uma oferta de SDP para o método connectActiveConference() e recebe uma resposta de SDP em troca.

Exemplo de fluxo de conexão

Confira uma oferta com uma descrição de mídia de áudio:

O peer remoto responde com uma resposta SDP contendo o mesmo número de linhas de descrição de mídia. Cada linha indica qual mídia, se houver, o peer remoto envia de volta para o cliente da oferta nos fluxos de SRTP. O peer remoto também pode rejeitar streams específicos do provedor definindo essa entrada de descrição de mídia como recvonly.

Para a API Meet Media, os clientes sempre enviam a oferta SDP para iniciar uma conexão. O Meet nunca é o iniciador.

Esse comportamento é gerenciado internamente pelos clientes de referência (C++, TypeScript), mas os desenvolvedores de clientes personalizados podem usar o PeerConnectionInterface do WebRTC para gerar uma oferta.

Para se conectar ao Meet, a oferta precisa atender a requisitos específicos:

1. O cliente precisa sempre agir como o cliente na negociação DTLS. Portanto, cada descrição de mídia na oferta precisa especificar a=setup:actpass ou a=setup:active.

2. Cada linha de descrição de mídia precisa oferecer suporte a todos os codecs necessários para esse tipo de mídia:

   • Áudio:Opus
   • Vídeo:VP8, VP9, AV1

3. Para receber áudio, a oferta precisa incluir exatamente três descrições de mídia de áudio somente para recebimento. Para fazer isso, defina transceptores no objeto de conexão 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. Para receber vídeos, a oferta precisa incluir de uma a três descrições de mídia de vídeo somente para recebimento. Para fazer isso, defina transceptors no objeto de conexão 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. A oferta precisa incluir canais de dados. No mínimo, os canais session-control e media-stats precisam estar sempre abertos. Todos os canais de dados precisam ser 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);
   };
   

Exemplo de oferta e resposta de SDP

Confira um exemplo completo de uma oferta SDP válida e uma resposta SDP correspondente. Essa oferta negocia uma sessão da API Media do Meet com áudio e um único stream de vídeo.

Observe que há três descrições de mídia de áudio, uma de mídia de vídeo e a descrição de mídia de aplicativo necessária.

Temas relacionados

• Primeiros passos