Media API kavramlarını öğrenme

Google Meet Media API, uygulamanızın Google Meet konferansına katılmasına ve gerçek zamanlı medya akışlarını kullanmasına olanak tanır.

İstemciler, Meet sunucularıyla iletişim kurmak için WebRTC'yi kullanır. Sağlanan referans istemciler (C++, TypeScript) önerilen uygulamaları gösterir ve doğrudan bu istemciler üzerinde geliştirme yapmanız önerilir.

Ancak Meet Media API'nin teknik koşullarına uyan tamamen özel WebRTC istemcileri de oluşturabilirsiniz.

Bu sayfada, başarılı bir Meet Media API oturumu için gereken temel WebRTC kavramları özetlenmektedir.

Teklif-yanıt sinyali

WebRTC, eşlerin birbirlerine sinyal göndererek iletişim kurduğu bir eşler arası (P2P) çerçevedir. Bir oturum başlatmak için oturumu başlatan eş, uzak bir eşe SDP teklifi gönderir. Bu teklif aşağıdaki önemli ayrıntıları içerir:

Ses ve video için medya açıklamaları

Medya açıklamaları, eşler arası oturumlar sırasında neyin iletildiğini gösterir. Üç tür açıklama vardır: ses, video ve veri.

Teklif sahibi, n ses akışını belirtmek için teklife n sesli medya açıklaması ekler. Aynı durum video için de geçerlidir. Ancak en fazla bir veri medya açıklaması olacaktır.

Yön belirleme

Her sesli veya görüntülü açıklama, RFC 3711 tarafından yönetilen ayrı Güvenli Gerçek Zamanlı İletim Protokolü (SRTP) akışlarını açıklar. Bu bağlantılar çift yönlüdür. İki eşin aynı bağlantı üzerinden medya göndermesine ve almasına olanak tanır.

Bu nedenle, her medya açıklaması (hem teklifte hem de yanıtta), akışın nasıl kullanılması gerektiğini açıklayan üç özellikten birini içerir:

• sendonly: Yalnızca teklif veren eşten medya gönderir. Uzak eş, bu akışta medya göndermeyecek.

• recvonly: Yalnızca uzak taraftan gelen medyayı alır. Teklifi sunan eş, bu akışta medya göndermeyecek.

• sendrecv: Her iki taraf da bu akışta gönderme ve alma işlemi yapabilir.

Codec'ler

Her medya açıklaması, bir eşin desteklediği codec'leri de belirtir. Meet Media API'de, istemci teklifleri teknik koşullarda belirtilen codec'leri (en azından) desteklemediği sürece reddedilir.

DTLS el sıkışması

SRTP akışları, eşler arasında ilk Datagram Taşıma Katmanı Güvenliği ("DTLS", RFC 9147) el sıkışmasıyla güvence altına alınır. DTLS geleneksel olarak istemciden sunucuya protokolüdür. Sinyal verme işlemi sırasında bir eş sunucu olarak hareket etmeyi kabul ederken diğeri eş olarak hareket eder.

Her SRTP akışının kendi özel DTLS bağlantısı olabileceğinden, her medya açıklaması, DTLS el sıkışmasında eşin rolünü belirtmek için üç özellikten birini belirtir:

• a=setup:actpass: Teklif veren eş, uzak eşin seçimine uyar.

• a=setup:active: Bu eş, istemci olarak hareket eder.

• a=setup:passive: Bu eş, sunucu görevi görür.

Uygulama medya açıklamaları

Veri kanalları (RFC 8831), Akış Denetimi İletim Protokolü'nün ("SCTP", RFC 9260) bir soyutlamasıdır.

İlk sinyal aşamasında veri kanallarını açmak için teklif application media description içermelidir. Ses ve video açıklamalarının aksine, uygulama açıklamalarında yön veya codec'ler belirtilmez.

ICE adayları

Bir eşin Etkileşimli Bağlantı Kurma ("ICE", RFC 8445) adayları, uzak bir eşin bağlantı kurmak için kullanabileceği rotaların listesidir.

Aday çiftler olarak bilinen iki eşin listelerinin kartezyen çarpımı, iki eş arasındaki olası rotaları temsil eder. Bu çiftler, en uygun rotayı belirlemek için test edilir.

Meet REST API üzerinden sinyal gönderme

Bu teklif-yanıt sinyalini gerçekleştirmek için Meet REST API'yi kullanın. Uygulamanız, connectActiveConference() yöntemine bir SDP teklifi sunar ve karşılığında bir SDP yanıtı alır.

Aşağıdaki kod örneklerinde yöntemin nasıl çağrılacağı gösterilmektedir:

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)

Örnek bağlantı akışı

Sesli medya açıklaması içeren bir teklif:

Uzak eş, aynı sayıda medya açıklaması satırı içeren bir SDP yanıtı ile yanıt verir. Her satır, uzak tarafın SRTP akışları üzerinden teklif veren istemciye geri gönderdiği medyayı (varsa) gösterir. Uzak uç, teklif verenden gelen belirli akışları da reddedebilir. Bunun için medya açıklaması girişini recvonly olarak ayarlaması gerekir.

Meet Media API'de istemciler, bağlantı başlatmak için her zaman SDP teklifi gönderir. Meet hiçbir zaman başlatıcı olmaz.

Bu davranış, referans istemciler (C++, TypeScript) tarafından dahili olarak yönetilir ancak özel istemcilerin geliştiricileri, teklif oluşturmak için WebRTC'nin PeerConnectionInterface özelliğini kullanabilir.

Meet Meet'e bağlanmak için teklifin belirli koşullara uyması gerekir:

1. İstemci, DTLS el sıkışmasında her zaman istemci olarak hareket etmelidir. Bu nedenle, teklifteki her medya açıklaması a=setup:actpass veya a=setup:active değerini belirtmelidir.

2. Her medya açıklaması satırı, söz konusu medya türü için tüm gerekli codec'leri desteklemelidir:

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

3. Ses almak için teklif tam olarak 3 adet yalnızca alım amaçlı sesli medya açıklaması içermelidir. Bunu, eş bağlantısı nesnesinde alıcı-vericileri ayarlayarak yapabilirsiniz.

   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. Video almak için teklif, 1-3 adet yalnızca video alma amaçlı medya açıklaması içermelidir. Bunu, eş bağlantısı nesnesinde alıcı-vericileri ayarlayarak yapabilirsiniz.

   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. Teklif her zaman veri kanallarını içermelidir. En azından session-control ve media-stats kanalları her zaman açık olmalıdır. Tüm veri kanalları ordered olmalıdır.

   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);
   };
   

Örnek SDP teklifi ve yanıtı

Geçerli bir SDP teklifi ve eşleşen SDP yanıtının tam örneğini aşağıda bulabilirsiniz. Bu teklif, ses ve tek bir video akışıyla Meet Media API oturumu başlatır.

Üç sesli medya açıklaması, bir video medya açıklaması ve gerekli uygulama medya açıklamasının olduğunu gözlemleyin.

İlgili konular

• Başlayın