Pojęcia związane z interfejsem Media API Meet

Interfejs Google Meet Media API umożliwia Twojej aplikacji dołączanie do konferencji w Google Meet i korzystanie z strumieni multimediów w czasie rzeczywistym.

Klienci używają WebRTC do komunikacji z serwerami Meet. Dołączone przykładowe klienci (C++, TypeScript) pokazują zalecane metody, dlatego zachęcamy do tworzenia aplikacji bezpośrednio na ich podstawie.

Możesz też tworzyć własne klienty WebRTC, które będą zgodne z wymaganiami technicznymi interfejsu Meet Media API.

Ta strona zawiera opis kluczowych pojęć związanych z WebRTC, które są wymagane do prawidłowego przeprowadzenia sesji interfejsu Meet Media API.

Sygnalizacja odpowiedzi na ofertę

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

Opisywanie multimediów w przypadku dźwięku i obrazu

Opisywanie mediów wskazuje, co jest przekazywane podczas sesji P2P. Istnieją 3 typy opisów: audio, wideo i dane.

Aby wskazać n strumienie audio, oferent podaje w ofercie n opisy multimediów audio. To samo dotyczy filmów. Maksymalnie jeden opis danych multimediów.

Dozwolone kierunki jazdy

Każdy opis audio lub wideo opisuje poszczególne strumienie protokołu Secure Real-time Transport Protocol (SRTP), które są zarządzane przez RFC 3711. Są to połączenia dwukierunkowe, które umożliwiają dwóm komputerom 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 w odpowiedzi) zawiera jeden z 3 atrybutów opisujących sposób użycia 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 media od zdalnego peera. Użytkownik oferujący nie będzie wysyłać multimediów w tym strumieniu.

• sendrecv: obie strony mogą wysyłać i odbierać dane w ramach tego strumienia.

Kodeki

Każdy opis multimediów określa też kodeki obsługiwane przez peera. W przypadku interfejsu Meet Media API oferty klienta są odrzucane, chyba że obsługują co najmniej te kodeki, które są określone w wymaganiach technicznych.

uzgadnianie połączenia DTLS,

Strumienie SRTP są chronione przez początkowe uzgadnianie połączenia Datagram Transport Layer Security („DTLS”, RFC 9147) między peerami. DTLS to tradycyjnie protokół klient-serwer; podczas procesu sygnalizacji jeden z uczestników zgadza się działać jako serwer, a drugi jako klient.

Ponieważ każdy strumień SRTP może mieć własne połączenie DTLS, każdy opis mediów określa jeden z 3 atrybutów, aby wskazać rolę peera w procesie uzgadniania połączenia DTLS:

• a=setup:actpass: oferujący peer odwołuje się do wyboru zdalonego peera.

• a=setup:active: ten węzeł działa jako klient.

• a=setup:passive: ten peer działa jako serwer.

Opisy multimediów aplikacji

Kanały danych (RFC 8831) to abstrakcja protokołu sterowania transmisją strumienia („SCTP”, RFC 9260).

Aby otworzyć kanały danych podczas początkowej fazy sygnalizacji, oferta musi zawierać opis multimediów aplikacji. W odróżnieniu od opisów dźwięku i filmów opisy aplikacji nie określają kierunku ani kodeków.

Kandydaci ICE

Interaktywne ustalanie połączeń („ICE”, RFC 8445) to lista tras, których może użyć zdalny peer do nawiązania połączenia.

Kartezja dwóch list, czyli par kandydatów, przedstawia potencjalne trasy między dwoma węzłami. Te pary są testowane w celu określenia optymalnej trasy.

sygnał za pomocą interfejsu Meet REST API,

Aby przeprowadzić tę sygnalizację oferta-odpowiedź, użyj interfejsu Meet REST API. Twoja aplikacja przesyła ofertę SDP do metody connectActiveConference() i otrzymuje w zamian odpowiedź SDP.

Poniższe przykłady kodu pokazują, jak wywoływać 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 proces łączenia

Oto oferta z opisem multimediów audio:

Urządzenie zdalne odpowiada odpowiedzią SDP zawierającą taką samą liczbę wierszy opisu multimediów. Każda linia wskazuje, jakie media (jeśli w ogóle) odległy peer wysyła z powrotem do klienta oferującego strumienie SRTP. Użytkownik zdalny może też odrzucić określone strumienie od oferenta, ustawiając dla danego wpisu opisu multimediów wartość recvonly.

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

Tą funkcją zarządzają wewnętrznie klienci referencyjni (C++, TypeScript), ale deweloperzy klientów niestandardowych mogą używać funkcji PeerConnectionInterface interfejsu WebRTC do generowania oferty.

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

1. Klient musi zawsze działać jako klient w uzgadnianiu połączenia DTLS, więc każdy opis multimediów w ofercie musi zawierać wartość a=setup:actpass lub a=setup:active.

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

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

3. Aby otrzymywać treści audio, oferta musi zawierać dokładnie 3 opisy multimediów audio przeznaczonych tylko do odbioru. Możesz to zrobić, ustawiając transceivers w obiekcie połączenia peer-to-peer.

   C++JavaScript
   // ...
   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()));
     }
   }
   

   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 otrzymać film, oferta musi zawierać 1–3 opisów multimediów wideo tylko do odbioru. Możesz to zrobić, ustawiając transceivers w obiekcie połączenia peer-to-peer.

   C++JavaScript
   // ...
   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()));
     }
   }
   

   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. Zawsze powinny być otwarte co najmniej kanały session-control i media-stats. Wszystkie kanały danych muszą być ordered.

   C++JavaScript
   // ...
   // 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()));
   }
   

   // ...
   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 odpowiadającej jej odpowiedzi SDP. Ta oferta negocjuje sesję interfejsu Meet Media API z dźwiękiem i jednym strumieniem wideo.

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

Powiązane artykuły

• Rozpocznij