Concepts de l'API Meet Media

L'API Google Meet Media permet à votre application de rejoindre une conférence Google Meet et de consommer des flux multimédias en temps réel.

Les clients utilisent WebRTC pour communiquer avec les serveurs Meet. Les clients de référence fournis (C++, TypeScript) illustrent les pratiques recommandées. Nous vous encourageons à vous appuyer directement sur eux.

Toutefois, vous pouvez également créer des clients WebRTC entièrement personnalisés qui respectent les exigences techniques de l'API Meet Media.

Cette page présente les concepts WebRTC clés requis pour une session API Meet Media réussie.

Signalisation de l'offre-réponse

WebRTC est un framework peer-to-peer (P2P), dans lequel les pairs communiquent en s'envoyant des signaux. Pour démarrer une session, le pair initiateur envoie une offre SDP à un pair distant. Cette offre inclut les informations importantes suivantes:

Descriptions multimédias pour l'audio et la vidéo

Les descriptions multimédias indiquent ce qui est communiqué pendant les sessions P2P. Il existe trois types de descriptions: audio, vidéo et données.

Pour indiquer les flux audio n, l'annonceur inclut des descriptions de médias audio n dans l'offre. Il en va de même pour les vidéos. Toutefois, il ne peut y avoir qu'une seule description multimédia de données.

Sens de circulation

Chaque description audio ou vidéo décrit des flux SRTP (Secure Real-time Transport Protocol) individuels, régis par RFC 3711. Ils sont bidirectionnels, ce qui permet à deux pairs d'envoyer et de recevoir des contenus multimédias via la même connexion.

Par conséquent, chaque description multimédia (dans l'offre et la réponse) contient l'un des trois attributs décrivant l'utilisation du flux:

• sendonly: n'envoie que des contenus multimédias du pair proposant l'offre. Le pair distant n'envoie pas de contenu multimédia sur ce flux.

• recvonly: ne reçoit que des contenus multimédias de l'homologue distant. Le pair de l'offre n'enverra pas de contenu multimédia sur ce flux.

• sendrecv: les deux pairs peuvent envoyer et recevoir des données sur ce flux.

Codecs

Chaque description multimédia spécifie également les codecs compatibles avec un pair. Dans le cas de l'API Meet Media, les offres client sont rejetées, sauf si elles prennent en charge (au moins) les codecs spécifiés dans les exigences techniques.

Handshake DTLS

Les flux SRTP sont sécurisés par un handshake Datagram Transport Layer Security ("DTLS", RFC 9147) initial entre les pairs. Le DTLS est traditionnellement un protocole de client à serveur. Lors du processus de signalisation, un pair accepte d'agir en tant que serveur, tandis que l'autre agit en tant que pair.

Étant donné que chaque flux SRTP peut avoir sa propre connexion DTLS dédiée, chaque description multimédia spécifie l'un des trois attributs pour indiquer le rôle de l'homologue dans l'établissement de la liaison DTLS:

• a=setup:actpass: le pair offrant s'en remet au choix du pair distant.

• a=setup:active: ce pair joue le rôle de client.

• a=setup:passive: ce pair agit en tant que serveur.

Descriptions des contenus multimédias de l'application

Les canaux de données (RFC 8831) sont une abstraction du protocole de transmission de contrôle de flux ("SCTP", RFC 9260).

Pour ouvrir des canaux de données lors de la phase de signalisation initiale, l'offre doit contenir une description multimédia de l'application. Contrairement aux descriptions audio et vidéo, les descriptions d'application ne spécifient pas la direction ni les codecs.

Candidats à l'ICE

Les candidats Interactive Connectivity Establishment ("ICE", RFC 8445) d'un pair sont une liste de routes qu'un pair distant peut utiliser pour établir une connexion.

Le produit cartésien des listes des deux pairs, appelé paires candidates, représente les routes potentielles entre deux pairs. Ces paires sont testées pour déterminer le chemin optimal.

Signaler via l'API REST Meet

Utilisez l'API REST Meet pour effectuer cette signalisation offre-réponse. Votre application fournit une offre SDP à la méthode connectActiveConference() et reçoit en retour une réponse SDP.

Exemple de parcours de connexion

Voici une offre avec une description multimédia audio:

L'homologue distant répond avec une réponse SDP contenant le même nombre de lignes de description multimédia. Chaque ligne indique les médias, le cas échéant, que le pair distant renvoie au client de l'offre via les flux SRTP. Le pair distant peut également rejeter des flux spécifiques de l'offreur en définissant cette entrée de description multimédia sur recvonly.

Pour l'API Meet Media, les clients envoient toujours l'offre SDP pour établir une connexion. Meet n'est jamais l'initiateur.

Ce comportement est géré en interne par les clients de référence (C++, TypeScript), mais les développeurs de clients personnalisés peuvent utiliser PeerConnectionInterface de WebRTC pour générer une offre.

Pour être associée à Meet, l'offre doit respecter des exigences spécifiques:

1. Le client doit toujours agir en tant que client lors du handshake DTLS. Par conséquent, chaque description multimédia de l'offre doit spécifier a=setup:actpass ou a=setup:active.

2. Chaque ligne de description multimédia doit prendre en charge tous les codecs requis pour ce type de contenu multimédia:

   • Audio: Opus
   • Vidéo:VP8, VP9, AV1

3. Pour recevoir du contenu audio, l'offre doit inclure exactement trois descriptions de médias audio en réception uniquement. Pour ce faire, définissez des transcesseurs sur l'objet de connexion entre pairs.

   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. Pour recevoir une vidéo, l'offre doit inclure une à trois descriptions de médias vidéo en mode réception uniquement. Pour ce faire, définissez des transcesseurs sur l'objet de connexion entre pairs.

   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'offre doit toujours inclure des canaux de données. Au minimum, les canaux session-control et media-stats doivent toujours être ouverts. Tous les canaux de données doivent être 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);
   };
   

Exemple d'offre et de réponse SDP

Voici un exemple complet d'offre SDP valide et de réponse SDP correspondante. Cette offre négocie une session Meet Media API avec de l'audio et un seul flux vidéo.

Notez qu'il existe trois descriptions de contenus multimédias audio, une description de contenu multimédia vidéo et la description de contenu multimédia de l'application requise.

Articles associés

• Commencer