با مفاهیم Media API آشنا شوید

رابط برنامه‌نویسی کاربردی رسانه گوگل میت (Google Meet Media API) به برنامه شما اجازه می‌دهد تا به یک کنفرانس گوگل میت بپیوندد و از پخش جریانی رسانه‌ای در لحظه (real-time media streams) استفاده کند.

کلاینت‌ها از WebRTC برای ارتباط با سرورهای Meet استفاده می‌کنند. کلاینت‌های مرجع ارائه شده ( C++ ، TypeScript ) شیوه‌های توصیه‌شده را نشان می‌دهند و شما را تشویق می‌کنیم که مستقیماً بر اساس آنها کار خود را انجام دهید.

با این حال، شما همچنین می‌توانید کلاینت‌های WebRTC کاملاً سفارشی بسازید که به الزامات فنی Meet Media API پایبند باشند.

این صفحه مفاهیم کلیدی WebRTC مورد نیاز برای یک جلسه موفق Meet Media API را شرح می‌دهد.

سیگنالینگ پیشنهاد-پاسخ

WebRTC یک چارچوب نظیر به نظیر (P2P) است که در آن نظیرها با ارسال سیگنال به یکدیگر ارتباط برقرار می‌کنند. برای شروع یک جلسه، نظیر آغازگر یک پیشنهاد SDP به نظیر راه دور ارسال می‌کند. این پیشنهاد شامل جزئیات مهم زیر است:

توضیحات رسانه برای صدا و تصویر

توضیحات رسانه‌ای نشان می‌دهد که در طول جلسات P2P چه چیزی رد و بدل می‌شود. سه نوع توضیحات وجود دارد: صدا، تصویر و داده.

برای نشان دادن n جریان صوتی، ارائه دهنده n توصیف رسانه صوتی را در پیشنهاد خود قرار می‌دهد. همین امر در مورد ویدیو نیز صادق است. با این حال، حداکثر فقط یک توصیف رسانه داده وجود خواهد داشت.

جهت‌گیری

هر توصیف صوتی یا تصویری، جریان‌های پروتکل انتقال امن بلادرنگ (SRTP) را که توسط RFC 3711 اداره می‌شوند، توصیف می‌کند. این‌ها دو جهته هستند و به دو همتا اجازه می‌دهند تا از طریق یک اتصال، رسانه ارسال و دریافت کنند.

به همین دلیل، هر توصیف رسانه (هم در پیشنهاد و هم در پاسخ) شامل یکی از سه ویژگی است که نحوه استفاده از جریان را توصیف می‌کند:

• sendonly : فقط رسانه را از همتای ارائه‌دهنده ارسال می‌کند. همتای راه دور رسانه‌ای را روی این جریان ارسال نمی‌کند.

• recvonly : فقط رسانه را از همتای راه دور دریافت می‌کند. همتای ارائه‌دهنده، رسانه‌ای را در این جریان ارسال نمی‌کند.

• sendrecv : هر دو طرف می‌توانند در این جریان ارسال و دریافت کنند.

کدک‌ها

توضیحات هر رسانه همچنین کدک‌هایی را که یک همتا پشتیبانی می‌کند، مشخص می‌کند. در مورد Meet Media API، پیشنهادات کلاینت رد می‌شوند مگر اینکه (حداقل) از کدک‌های مشخص شده در الزامات فنی پشتیبانی کنند.

دست دادن DTLS

جریان‌های SRTP توسط یک دست‌دهی اولیه Datagram Transport Layer Security ("DTLS", RFC 9147 ) بین همتاها ایمن می‌شوند. DTLS به طور سنتی یک پروتکل کلاینت به سرور است؛ در طول فرآیند سیگنالینگ، یک همتا موافقت می‌کند که به عنوان سرور عمل کند در حالی که دیگری به عنوان همتا عمل می‌کند.

از آنجا که هر جریان SRTP ممکن است اتصال DTLS اختصاصی خود را داشته باشد، هر توصیف رسانه یکی از سه ویژگی را برای نشان دادن نقش طرف مقابل در DTLS handshake مشخص می‌کند:

• a=setup:actpass : همتای ارائه‌دهنده ، تابع انتخاب همتای راه دور است.

• a=setup:active : این نظیر به عنوان کلاینت عمل می‌کند.

• a=setup:passive : این نظیر به عنوان سرور عمل می‌کند.

توضیحات رسانه برنامه

کانال‌های داده ( RFC 8831 ) انتزاعی از پروتکل انتقال کنترل جریان ("SCTP"، RFC 9260 ) هستند.

برای باز کردن کانال‌های داده در طول مرحله سیگنال‌دهی اولیه، پیشنهاد باید شامل توضیحات رسانه برنامه باشد. برخلاف توضیحات صدا و تصویر، توضیحات برنامه جهت یا کدک‌ها را مشخص نمی‌کنند.

نامزدهای ICE

کاندیدهای «برقراری اتصال تعاملی » ("ICE"، RFC 8445 ) یک نظیر، فهرستی از مسیرهایی هستند که یک نظیر از راه دور ممکن است برای ایجاد اتصال از آنها استفاده کند.

حاصلضرب دکارتی لیست دو همتا، که به عنوان جفت‌های کاندید شناخته می‌شود، مسیرهای بالقوه بین دو همتا را نشان می‌دهد. این جفت‌ها برای تعیین مسیر بهینه آزمایش می‌شوند.

از طریق Meet REST API سیگنال دهید

برای انجام این سیگنالینگ پیشنهاد-پاسخ از Meet REST API استفاده کنید. برنامه شما یک پیشنهاد SDP به متد connectActiveConference() ارائه می‌دهد و در عوض یک پاسخ SDP دریافت می‌کند.

نمونه کدهای زیر نحوه فراخوانی متد را نشان می‌دهند:

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)

مثال جریان اتصال

در اینجا پیشنهادی با توضیحات رسانه صوتی ارائه شده است:

همتای راه دور با یک پاسخ SDP حاوی همان تعداد خطوط توصیف رسانه پاسخ می‌دهد. هر خط نشان می‌دهد که همتای راه دور چه رسانه‌ای را، در صورت وجود، از طریق جریان‌های SRTP به کلاینت ارائه دهنده ارسال می‌کند. همتای راه دور همچنین می‌تواند جریان‌های خاصی را از ارائه دهنده با تنظیم ورودی توصیف رسانه به recvonly رد کند.

برای رابط برنامه‌نویسی کاربردی Meet Media، کلاینت‌ها همیشه پیشنهاد SDP را برای شروع اتصال ارسال می‌کنند. Meet هرگز آغازگر نیست.

این رفتار به صورت داخلی توسط کلاینت‌های مرجع ( C++ ، TypeScript ) مدیریت می‌شود، اما توسعه‌دهندگان کلاینت‌های سفارشی می‌توانند از PeerConnectionInterface در WebRTC برای ایجاد پیشنهاد استفاده کنند.

برای اتصال به Meet، پیشنهاد باید الزامات خاصی را رعایت کند:

1. کلاینت باید همیشه در فرآیند DTLS handshake به عنوان کلاینت عمل کند، بنابراین هر توصیف رسانه در پیشنهاد باید یا a=setup:actpass یا a=setup:active مشخص کند.

2. هر خط توضیحات رسانه باید از تمام کدک‌های مورد نیاز برای آن نوع رسانه پشتیبانی کند:

   • صدا: Opus
   • ویدئو: VP8 ، VP9 ، AV1

3. برای دریافت صدا، پیشنهاد باید دقیقاً شامل ۳ توصیف رسانه صوتی فقط-دریافتی باشد. می‌توانید این کار را با تنظیم فرستنده-گیرنده‌ها روی شیء اتصال همتا انجام دهید.

   سی++

   // ...
   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. برای دریافت ویدیو، پیشنهاد باید شامل ۱ تا ۳ توصیف رسانه ویدیویی فقط برای دریافت باشد. می‌توانید این کار را با تنظیم فرستنده و گیرنده‌ها روی شیء اتصال همتا انجام دهید.

   سی++

   // ...
   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. این پیشنهاد باید همیشه شامل کانال‌های داده باشد. حداقل، کانال‌های session-control و media-stats باید همیشه باز باشند. همه کانال‌های داده باید ordered شوند.

   سی++

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

مثال پیشنهاد و پاسخ SDP

در اینجا یک مثال کامل از یک پیشنهاد معتبر SDP و پاسخ SDP مطابق با آن آورده شده است. این پیشنهاد، یک جلسه Meet Media API را با صدا و یک جریان ویدیویی واحد مذاکره می‌کند.

توجه داشته باشید که سه توصیف رسانه صوتی، یک توصیف رسانه ویدیویی و توصیف رسانه مورد نیاز برنامه وجود دارد.

مباحث مرتبط

• شروع کنید