Memahami konsep Media API

Google Meet Media API memungkinkan aplikasi Anda bergabung ke konferensi Google Meet dan menggunakan streaming media real-time.

Klien menggunakan WebRTC untuk berkomunikasi dengan server Meet. Klien referensi yang disediakan (C++, TypeScript) menunjukkan praktik yang direkomendasikan dan Anda dianjurkan untuk membuat aplikasi langsung berdasarkan klien tersebut.

Namun, Anda juga dapat membuat klien WebRTC yang sepenuhnya kustom dan mematuhi persyaratan teknis Meet Media API.

Halaman ini menguraikan konsep WebRTC utama yang diperlukan untuk sesi Meet Media API yang berhasil.

Sinyal penawaran-jawaban

WebRTC adalah framework peer-to-peer (P2P), tempat peer berkomunikasi dengan saling memberi sinyal. Untuk memulai sesi, peer yang memulai mengirimkan penawaran SDP ke peer jarak jauh. Penawaran ini mencakup detail penting berikut:

Deskripsi media untuk audio dan video

Deskripsi media menunjukkan apa yang dikomunikasikan selama sesi P2P. Ada tiga jenis deskripsi: audio, video, dan data.

Untuk menunjukkan n streaming audio, penawar menyertakan n deskripsi media audio dalam penawaran. Hal yang sama berlaku untuk video. Namun, hanya akan ada satu deskripsi media data.

Arah

Setiap deskripsi audio atau video menjelaskan streaming Secure Real-time Transport Protocol (SRTP) individual, yang diatur oleh RFC 3711. Deskripsi ini bersifat dua arah, sehingga memungkinkan dua peer mengirim dan menerima media melalui koneksi yang sama.

Oleh karena itu, setiap deskripsi media (dalam penawaran dan jawaban) berisi salah satu dari tiga atribut yang menjelaskan cara streaming harus digunakan:

• sendonly: Hanya mengirim media dari peer penawaran. Peer jarak jauh tidak akan mengirim media di streaming ini.

• recvonly: Hanya menerima media dari peer jarak jauh. Peer penawaran tidak akan mengirim media di streaming ini.

• sendrecv: Kedua peer dapat mengirim dan menerima di streaming ini.

Codec

Setiap deskripsi media juga menentukan codec yang didukung peer. Dalam kasus Meet Media API, penawaran klien akan ditolak kecuali jika mendukung (setidaknya) codec yang ditentukan dalam persyaratan teknis.

Handshake DTLS

Streaming SRTP diamankan oleh handshake awal Datagram Transport Layer Security ("DTLS", RFC 9147) antara peer. DTLS secara tradisional adalah protokol klien-ke-server; selama proses sinyal, satu peer setuju untuk bertindak sebagai server, sedangkan peer lainnya bertindak sebagai peer.

Karena setiap streaming SRTP mungkin memiliki koneksi DTLS khusus, setiap deskripsi media menentukan salah satu dari tiga atribut untuk menunjukkan peran peer dalam handshake DTLS:

• a=setup:actpass: Peer penawaran akan mengikuti pilihan peer jarak jauh.

• a=setup:active: Peer ini bertindak sebagai klien.

• a=setup:passive: Peer ini bertindak sebagai server.

Deskripsi media aplikasi

Channel data (RFC 8831) adalah abstraksi dari Stream Control Transmission Protocol ("SCTP", RFC 9260).

Untuk membuka channel data selama fase sinyal awal, penawaran harus berisi deskripsi media aplikasi. Tidak seperti deskripsi audio dan video, deskripsi aplikasi tidak menentukan arah atau codec.

Kandidat ICE

Kandidat Interactive Connectivity Establishment ("ICE", RFC 8445) peer adalah daftar rute yang dapat digunakan peer jarak jauh untuk membuat koneksi.

Produk kartesius dari daftar dua peer, yang dikenal sebagai pasangan kandidat, mewakili rute potensial antara dua peer. Pasangan ini diuji untuk menentukan rute yang optimal.

Sinyal melalui Meet REST API

Gunakan Meet REST API untuk melakukan sinyal penawaran-jawaban ini. Aplikasi Anda memberikan penawaran SDP ke metode connectActiveConference() dan menerima jawaban SDP sebagai balasannya.

Contoh kode berikut menunjukkan cara memanggil metode:

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")
              .setConfig(ConnectActiveConferenceRequest.ConnectionConfig.newBuilder().build())
              .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'
/**
 *  Optional. Additional configuration options for a Media API session.
 *  If unset, default values will be provided for the session.
 */
// const config = {}

// 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)

Contoh alur koneksi

Berikut adalah penawaran dengan deskripsi media audio:

Peer jarak jauh merespons dengan jawaban SDP yang berisi jumlah baris deskripsi media yang sama. Setiap baris menunjukkan media apa, jika ada, yang dikirim kembali oleh peer jarak jauh ke klien penawaran di seluruh streaming SRTP. Peer jarak jauh juga dapat menolak streaming tertentu dari penawar dengan menetapkan entri deskripsi media tersebut ke recvonly.

Untuk Meet Media API, klien selalu mengirim penawaran SDP untuk memulai koneksi. Meet tidak pernah menjadi inisiator.

Perilaku ini dikelola secara internal oleh klien referensi (C++, TypeScript), tetapi developer klien kustom dapat menggunakan PeerConnectionInterface WebRTC untuk membuat penawaran.

Untuk terhubung ke Meet, penawaran harus mematuhi persyaratan tertentu requirements:

1. Klien harus selalu bertindak sebagai klien dalam handshake DTLS, sehingga setiap deskripsi media dalam penawaran harus menentukan a=setup:actpass atau a=setup:active.

2. Setiap baris deskripsi media harus mendukung semua codec yang diperlukan untuk jenis media tersebut:

   • Audio: Opus
   • Video: VP8, VP9, AV1

3. Untuk menerima audio, penawaran harus menyertakan tepat 3 deskripsi media audio hanya terima. Anda dapat melakukannya dengan menetapkan transceiver pada objek koneksi 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. Untuk menerima video, penawaran harus menyertakan 1–3 deskripsi media video hanya terima. Anda dapat melakukannya dengan menetapkan transceiver pada objek koneksi 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. Penawaran harus selalu menyertakan channel data. Minimal, channel session-control dan media-stats harus selalu terbuka. Semua channel data harus 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);
   };
   

Contoh penawaran dan jawaban SDP

Berikut adalah contoh lengkap penawaran SDP yang valid dan jawaban SDP yang cocok. Penawaran ini menegosiasikan sesi Meet Media API dengan audio dan satu streaming video.

Perhatikan bahwa ada tiga deskripsi media audio, satu deskripsi media video, dan deskripsi media aplikasi yang diperlukan.

Topik terkait

• Mulai