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 bonnes pratiques recommandées et nous vous encourageons à les utiliser comme base.

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 réussie avec l'API Meet Media.

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

Les descriptions 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 n flux audio, l'offrant inclut n descriptions multimédias audio dans l'offre. Il en va de même pour la vidéo. Toutefois, il n'y aura qu'une seule description multimédia de données 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. Ils sont bidirectionnels, ce qui permet à deux pairs d'envoyer et de recevoir des contenus multimédias via la même connexion.

Pour cette raison, chaque description 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 des contenus multimédias que depuis le pair offrant. Le pair distant n'envoie pas de contenus multimédias sur ce flux.

• recvonly: ne reçoit des contenus multimédias que depuis le pair distant. Le pair offrant n'envoie pas de contenus multimédias sur ce flux.

• sendrecv: les deux pairs peuvent envoyer et recevoir des contenus multimédias 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 des clients sont rejetées, sauf si elles sont compatibles (au moins) avec les codecs spécifiés dans les exigences techniques.

Handshake DTLS

Les flux SRTP sont sécurisés par un handshake initial Datagram Transport Layer Security ("DTLS", RFC 9147) entre les pairs. DTLS est traditionnellement un protocole client-serveur. Au cours 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 du pair dans le handshake 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 agit en tant que serveur.

Descriptions multimédias d'application

Les canaux de données (RFC 8831) sont une abstraction du Stream Control Transmission Protocol ("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 d'application. Contrairement aux descriptions audio et vidéo, les descriptions d'application 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é les paires de candidats, représente les routes potentielles entre deux pairs. Ces paires sont testées pour déterminer la route optimale.

Signalisation via l'API REST Meet

Utilisez l'API REST Meet pour effectuer cette signalisation offre/réponse. Votre application fournit une offre SDP à la connectActiveConference() méthode 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 flux de connexion

Voici une offre avec une description multimédia audio :

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

Pour l'API Meet Media, les clients envoient toujours l'offre SDP pour lancer 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, l'offre doit respecter des exigences spécifiques requirements :

1. Le client doit toujours agir en tant que client dans le 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 être compatible avec tous les codecs requis pour ce type de contenu multimédia :

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

3. Pour recevoir de l'audio, l'offre doit inclure exactement trois descriptions multimédias audio en réception seule. Pour ce faire, définissez des émetteurs-récepteurs sur l'objet de connexion 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 de la vidéo, l'offre doit inclure une à trois descriptions multimédias vidéo en réception seule. Pour ce faire, définissez des émetteurs-récepteurs sur l'objet de connexion 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 d'API Meet Media avec de l'audio et un seul flux vidéo.

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

Articles associés

• Commencer