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

Google Meet Media API به برنامه شما اجازه می‌دهد به کنفرانس Google Meet بپیوندد و جریان‌های رسانه‌ای را در زمان واقعی مصرف کند.

کلاینت ها از 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 Layer Security ("DTLS"، RFC 9147 ) بین همتایان ایمن می شوند. DTLS به طور سنتی یک پروتکل مشتری به سرور است. در طول فرآیند سیگنالینگ، یک همتا موافقت می کند که به عنوان سرور عمل کند در حالی که دیگری به عنوان یک همتا عمل می کند.

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

• 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")
              .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)

نمونه جریان اتصال

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

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

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

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

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

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

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

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

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

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

   جاوا اسکریپت

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

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

   جاوا اسکریپت

   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 شوند.

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

   جاوا اسکریپت

   // ...
   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 با پخش صدا و یک ویدیو مذاکره می کند.

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

موضوعات مرتبط

• شروع کنید