Concepts de l'API Meet Media

L'API Google Meet Media permet à votre application de rejoindre une visioconfé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 et nous vous encourageons à les utiliser directement.

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 clés de WebRTC nécessaires pour une session Meet Media API réussie.

Signalisation 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 de contenus multimédias pour l'audio et la vidéo

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

Pour indiquer les flux audio n, l'offrant inclut des descriptions de contenu multimédia audio n dans l'offre. Il en va de même pour les vidéos. Toutefois, il n'y aura qu'une seule description de support data au maximum.

Sens de circulation

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

C'est pourquoi chaque description de contenu multimédia (dans l'offre et la réponse) contient l'un des trois attributs décrivant comment le flux doit être utilisé :

• sendonly : n'envoie que le contenu multimédia du pair proposant. Le pair distant n'enverra pas de contenu multimédia sur ce flux.

• recvonly : ne reçoit que les contenus multimédias du pair distant. Le pair proposant 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 de contenu multimédia spécifie également les codecs compatibles avec un pair. Dans le cas de l'API Meet Media, les offres client sont refusées, sauf si elles sont compatibles avec (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. DTLS est traditionnellement un protocole client-serveur. Pendant le 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 de support spécifie l'un des trois attributs pour indiquer le rôle du pair dans l'établissement de liaison DTLS :

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

• a=setup:active : ce pair agit en tant que client.

• a=setup:passive : ce pair fait office de serveur.

Descriptions des contenus multimédias de l'application

Les canaux de données (RFC 8831) sont une abstraction du protocole SCTP (Stream Control Transmission Protocol), RFC 9260.

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

Candidats 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 l'itinéraire optimal.

Signaler un problème via l'API Meet REST

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

Les exemples de code suivants montrent comment appeler la méthode :

import com.google.api.core.ApiFuture;
import com.google.apps.meet.v2beta.ConnectActiveConferenceRequest;
import com.google.apps.meet.v2beta.ConnectActiveConferenceResponse;
import com.google.apps.meet.v2beta.SpaceName;
import com.google.apps.meet.v2beta.SpacesServiceClient;

public class AsyncConnectActiveConference {

  public static void main(String[] args) throws Exception {
    asyncConnectActiveConference();
  }

  public static void asyncConnectActiveConference() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SpacesServiceClient spacesServiceClient = SpacesServiceClient.create()) {
      ConnectActiveConferenceRequest request =
          ConnectActiveConferenceRequest.newBuilder()
              .setName(SpaceName.of("[SPACE]").toString())
              .setOffer("offer105650780")
              .build();
      ApiFuture<ConnectActiveConferenceResponse> future =
          spacesServiceClient.connectActiveConferenceCallable().futureCall(request);
      // Do something.
      ConnectActiveConferenceResponse response = future.get();
    }
  }
}

using Google.Apps.Meet.V2Beta;
using System.Threading.Tasks;

public sealed partial class GeneratedSpacesServiceClientSnippets
{
    /// <summary>Snippet for ConnectActiveConferenceAsync</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public async Task ConnectActiveConferenceAsync()
    {
        // Create client
        SpacesServiceClient spacesServiceClient = await SpacesServiceClient.CreateAsync();
        // Initialize request argument(s)
        string name = "spaces/[SPACE]";
        // Make the request
        ConnectActiveConferenceResponse response = await spacesServiceClient.ConnectActiveConferenceAsync(name);
    }
}

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Resource name of the space.
 *  Format: spaces/{spaceId}
 */
// const name = 'abc123'
/**
 *  Required. WebRTC SDP (Session Description Protocol) offer from the client.
 *  The format is defined by RFC
 *  8866 (https://www.rfc-editor.org/rfc/rfc8866) with mandatory keys defined
 *  by RFC 8829 (https://www.rfc-editor.org/rfc/rfc8829). This is the standard
 *  SDP format generated by a peer connection's createOffer() and
 *  createAnswer() methods.
 */
// const offer = 'abc123'

// Imports the Meet library
const {SpacesServiceClient} = require('@google-apps/meet').v2beta;

// Instantiates a client
const meetClient = new SpacesServiceClient();

async function callConnectActiveConference() {
  // Construct request
  const request = {
    name,
    offer,
  };

  // Run request
  const response = await meetClient.connectActiveConference(request);
  console.log(response);
}

callConnectActiveConference();

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.apps import meet_v2beta


async def sample_connect_active_conference():
    # Create a client
    client = meet_v2beta.SpacesServiceAsyncClient()

    # Initialize request argument(s)
    request = meet_v2beta.ConnectActiveConferenceRequest(
        name="name_value",
        offer="offer_value",
    )

    # Make the request
    response = await client.connect_active_conference(request=request)

    # Handle the response
    print(response)

Exemple de parcours de connexion

Voici une offre avec une description audio :

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

Pour l'API Meet Media, les clients envoient toujours l'offre SDP pour initier 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 se connecter à Meet Meet, l'offre doit respecter certaines exigences :

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

2. Chaque ligne de description du contenu multimédia doit être compatible avec tous les codecs requis pour ce type de contenu :

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

3. Pour recevoir de l'audio, l'offre doit inclure exactement trois descriptions de supports audio en réception seule. Pour ce faire, définissez des émetteurs-récepteurs sur l'objet de connexion pair à pair.

   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 contenus vidéo en réception seule. Pour ce faire, définissez des émetteurs-récepteurs sur l'objet de connexion pair à pair.

   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 un flux audio et un flux vidéo unique.

Notez qu'il existe trois descriptions de contenu audio, une description de contenu vidéo et la description de contenu d'application requise.

Articles associés

• Commencer