Pojęcia związane z interfejsem Media API Meet

Interfejs Google Meet Media API umożliwia aplikacji dołączenie do konferencji w Google Meet i korzystanie ze strumieni multimediów w czasie rzeczywistych.

Klienci używają WebRTC do komunikacji z serwerami Meet. Dostarczone klienty referencyjne (C++, TypeScript) pokazują zalecane praktyki i zachęcamy do tworzenia aplikacji bezpośrednio na ich podstawie.

Możesz też tworzyć w pełni niestandardowe klienty WebRTC, które spełniają wymagania techniczne interfejsu Meet Media API.

Ta strona zawiera najważniejsze informacje o WebRTC, które są potrzebne do prawidłowego działania sesji interfejsu Meet Media API.

Sygnalizacja oferty i odpowiedzi

WebRTC to platforma peer-to-peer (P2P), w której urządzenia komunikują się ze sobą za pomocą sygnalizacji. Aby rozpocząć sesję, urządzenie inicjujące wysyła ofertę SDP do urządzenia zdalnego. Ta oferta zawiera te ważne informacje:

Opisy multimediów audio i wideo

Opisy multimediów wskazują, co jest przekazywane podczas sesji P2P. Istnieją 3 typy opisów: audio, wideo i dane.

Aby wskazać n strumieni audio, oferujący umieszcza w ofercie n opisów multimediów audio. To samo dotyczy wideo. Może jednak występować co najwyżej 1 opis multimediów danych.

Dozwolone kierunki jazdy

Każdy opis audio lub wideo opisuje poszczególne Secure Real-time Transport Protocol (SRTP) strumienie, które podlegają RFC 3711. Są one dwukierunkowe, co umożliwia 2 urządzeniom wysyłanie i odbieranie multimediów przez to samo połączenie.

Z tego powodu każdy opis multimediów (zarówno w ofercie, jak i odpowiedzi) zawiera 1 z 3 atrybutów opisujących, jak należy używać strumienia:

• sendonly: wysyła tylko multimedia z urządzenia oferującego. Urządzenie zdalne nie będzie wysyłać multimediów w tym strumieniu.

• recvonly: odbiera tylko multimedia z urządzenia zdalnego. Urządzenie oferujące nie będzie wysyłać multimediów w tym strumieniu.

• sendrecv: oba urządzenia mogą wysyłać i odbierać multimedia w tym strumieniu.

Kodeki

Każdy opis multimediów określa też kodeki obsługiwane przez urządzenie. W przypadku interfejsu Meet Media API oferty klientów są odrzucane, chyba że obsługują one (co najmniej) kodeki określone w wymaganiach technicznych.

Uzgadnianie połączenia DTLS

Strumienie SRTP są zabezpieczone przez początkowe Datagram Transport Layer Security ("DTLS", RFC 9147) uzgadnianie połączenia między urządzeniami. DTLS jest tradycyjnie protokołem klient-serwer. Podczas procesu sygnalizacji 1 urządzenie zgadza się pełnić rolę serwera, a drugie – klienta.

Ponieważ każdy strumień SRTP może mieć własne dedykowane połączenie DTLS, każdy opis multimediów określa 1 z 3 atrybutów wskazujących rolę urządzenia w uzgadnianiu połączenia DTLS:

• a=setup:actpass: urządzenie oferujące odracza wybór urządzenia zdalnego.

• a=setup:active: to urządzenie pełni rolę klienta.

• a=setup:passive: to urządzenie pełni rolę serwera.

Opisy multimediów aplikacji

Kanały danych (RFC 8831) są abstrakcją Stream Control Transmission Protocol ("SCTP", RFC 9260).

Aby otworzyć kanały danych podczas początkowej fazy sygnalizacji, oferta musi zawierać opis multimediów aplikacji. W przeciwieństwie do opisów audio i wideo opisy aplikacji nie określają kierunku ani kodeków.

Kandydaci ICE

Kandydaci Interactive Connectivity Establishment („ICE”, RFC 8445) to lista tras, których urządzenie zdalne może użyć do nawiązania połączenia.

Iloczyn kartezjański list 2 urządzeń, znany jako pary kandydatów, reprezentuje potencjalne trasy między 2 urządzeniami. Te pary są testowane w celu określenia optymalnej trasy.

Sygnalizacja za pomocą interfejsu Meet REST API

Do przeprowadzenia sygnalizacji oferty i odpowiedzi użyj interfejsu Meet REST API. Twoja aplikacja przekazuje ofertę SDP do metody connectActiveConference() i otrzymuje w odpowiedzi odpowiedź SDP.

Poniższe przykłady kodu pokazują, jak wywołać tę metodę:

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)

Przykładowy przepływ połączenia

Oto oferta z opisem multimediów audio:

Urządzenie zdalne odpowiada odpowiedzią SDP zawierającą taką samą liczbę wierszy opisu multimediów. Każdy wiersz wskazuje, jakie multimedia (jeśli w ogóle) urządzenie zdalne wysyła z powrotem do klienta oferującego za pomocą strumieni SRTP. Urządzenie zdalne może też odrzucić określone strumienie od oferującego, ustawiając wpis opisu multimediów na recvonly.

W przypadku interfejsu Meet Media API klienci zawsze wysyłają ofertę SDP, aby zainicjować połączenie. Meet nigdy nie jest inicjatorem.

To zachowanie jest zarządzane wewnętrznie przez klienty referencyjne (C++, TypeScript), ale deweloperzy klientów niestandardowych mogą używać PeerConnectionInterface WebRTC do generowania oferty.

Aby połączyć się z Meet, oferta musi spełniać określone wymagania:

1. Klient musi zawsze pełnić rolę klienta w uzgadnianiu połączenia DTLS, więc każdy opis multimediów w ofercie musi określać a=setup:actpass lub a=setup:active.

2. Każdy wiersz opisu multimediów musi obsługiwać wszystkie wymagane kodeki dla danego typu multimediów:

   • Dźwięk: Opus
   • Wideo: VP8, VP9, AV1

3. Aby odbierać dźwięk, oferta musi zawierać dokładnie 3 opisy multimediów audio tylko do odbioru. Możesz to zrobić, ustawiając transceivery w obiekcie połączenia peer-to-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. Aby odbierać wideo, oferta musi zawierać 1–3 opisy multimediów wideo tylko do odbioru. Możesz to zrobić, ustawiając transceivery w obiekcie połączenia peer-to-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. Oferta musi zawsze zawierać kanały danych. Co najmniej kanały session-control i media-stats powinny być zawsze otwarte. Wszystkie kanały danych muszą być 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);
   };
   

Przykładowa oferta i odpowiedź SDP

Oto pełny przykład prawidłowej oferty SDP i pasującej odpowiedzi SDP. Ta oferta negocjuje sesję interfejsu Meet Media API z dźwiękiem i pojedynczym strumieniem wideo.

Zwróć uwagę, że są 3 opisy multimediów audio, 1 opis multimediów wideo i wymagany opis multimediów aplikacji.

Powiązane artykuły

• Rozpocznij