التعرّف على مفاهيم واجهة برمجة التطبيقات Media API

تتيح Google Meet Media API لتطبيقك الانضمام إلى مؤتمر على Google Meet واستخدام بث الوسائط في الوقت الفعلي.

يستخدم العملاء WebRTC للتواصل مع خوادم Meet. يوضّح ملفَا العميلَين المرجعيَّين (C++ وTypeScript) الممارسات المقترَحة، ويُنصح بالاستناد إليهما مباشرةً.

ومع ذلك، يمكنك أيضًا إنشاء عملاء WebRTC مخصّصين بالكامل يلتزمون بالمتطلبات الفنية لواجهة برمجة التطبيقات Meet Media API.

توضّح هذه الصفحة مفاهيم WebRTC الرئيسية المطلوبة لجلسة ناجحة Meet Media API.

إشارة العرض والإجابة

‫WebRTC هو إطار عمل للتواصل بين الأجهزة (نظير إلى نظير)، حيث يتواصل الأجهزة مع بعضها البعض من خلال إرسال إشارات إلى بعضها. لبدء جلسة، يُرسِل المُشغِّل المُبادِر عرضًا لبروتوكول وصف الجلسة (SDP) إلى مُشغِّل عن بُعد. يتضمّن هذا العرض التفاصيل المهمة التالية:

أوصاف الوسائط للصوت والفيديو

تشير أوصاف الوسائط إلى ما يتم تبادله خلال جلسات الاتصال المباشر بين الأجهزة. هناك ثلاثة أنواع من الأوصاف: الصوت والفيديو والبيانات.

للإشارة إلى n بثّ صوتي، يُدرج مقدّم العرض n وصفًا لوسائط الصوت في العرض. وينطبق ذلك أيضًا على الفيديو. ومع ذلك، لن يكون هناك سوى وصف واحد لبيانات الوسائط كحد أقصى.

اتجاهات الطريق

يصف كل وصف صوت أو فيديو أحداث بث فردية بروتوكول النقل الآمن في الوقت الفعلي (SRTP) تخضع RFC 3711. وهذه القنوات ثنائية الاتجاه، وتسمح لجهازَين متصلَين بإرسال الوسائط واستلامها عبر الاتصال نفسه.

ولهذا السبب، يحتوي كل وصف وسائط (في كلّ من العرض والجواب) على إحدى السمات الثلاث التي تصف كيفية استخدام البث:

• ‫sendonly: لا يتم إرسال الوسائط إلا من نظير العرض. لن يُرسِل جهاز الكمبيوتر البعيد الوسائط في هذا البث.

• ‫recvonly: لا يتلقّى الوسائط إلا من المثيل البعيد. لن يرسل المحتوى المعروض وسائط في هذا البث.

• sendrecv: يمكن لكلا الطرفَين الإرسال والاستلام في هذا البث.

برامج الترميز

يحدّد كل وصف وسائط أيضًا برامج الترميز التي يتوافق معها جهاز نظير. في ما يتعلّق بواجهة برمجة التطبيقات Meet Media API، يتم رفض عروض العملاء ما لم تكن متوافقة مع ملفّات الترميز المحدّدة في المتطلبات التقنية (على الأقل).

تأكيد الاتصال عبر بروتوكول أمان طبقة النقل لمخطّطات البيانات (DTLS)

يتم تأمين أحداث SRTP من خلال تبادل مفتاح التشفير الأولي لبروتوكول أمان طبقة النقل لمخطّطات البيانات ("DTLS"، RFC 9147) بين الأجهزة المشارِكة. يُعدّ بروتوكول DTLS تقليديًا بروتوكولًا بين العميل والخادم. وخلال عملية الإرسال، يوافق أحد الأجهزة المشابهة على العمل كخادم بينما يعمل الآخر كجهاز مشابه.

بما أنّ كل بث SRTP قد يتضمّن اتصال DTLS مخصّصًا، يحدّد كل وصف للوسائط إحدى السمات الثلاث للإشارة إلى دور العميل في عملية تأكيد الاتصال باستخدام بروتوكول DTLS:

• a=setup:actpass: يعتمد تطبيق العرض على اختيار التطبيق البعيد.

• a=setup:active: يلعب هذا الجهاز دور العميل.

• a=setup:passive: يعمل هذا الجهاز كمثيل للخادم.

أوصاف وسائط التطبيق

قنوات البيانات (RFC 8831) هي طريقة مجردة لبروتوكول التحكّم في نقل البث ("SCTP"، RFC 9260).

لفتح قنوات البيانات أثناء مرحلة الإرسال الأولي، يجب أن يحتوي العرض على وصف وسائط التطبيق. على عكس أوصاف الصوت والفيديو، لا تحدّد أوصاف التطبيقات الاتجاه أو برامج الترميز.

المرشحون في ICE

مرشحو Interactive Connectivity Establishment (ICE، RFC 8445) للندّ هي قائمة ب المسارات التي قد يستخدمها ندّ بعيد لإنشاء اتصال.

يمثّل المنتج الديكارتي لقائمتَي الخوادم المتكافئة، المعروف باسم الأزواج المرشحة، المسارات المحتملة بين الخادمَين المتكافئَين. ويتم اختبار هذه الأزواج لتحديد المسار الأمثل.

واجهة برمجة تطبيقات Meet REST لتطبيق Signal

استخدِم Meet REST API لتنفيذ إشارة offer-answer هذه. يقدّم تطبيقك عرضًا لبروتوكول وصف الجلسة إلى connectActiveConference() الطريقة ويتلقّى بدوره إجابة بروتوكول وصف الجلسة.

مثال على مسار الربط

في ما يلي عرض يتضمّن وصفًا لوسائط صوتية:

ويستجيب النظير البعيد باستخدام إجابة SDP تحتوي على العدد نفسه من أسطر وصف الوسائط. يشير كل سطر إلى الوسائط، إن توفّرت، التي يرسلها العميل البعيد إلى العميل الموفِّر عبر أحداث SRTP. قد يرفض العميل العميق المتّصل عن بُعد أيضًا أحداث بث معيّنة من مقدّم المحتوى من خلال ضبط إدخال وصف الوسائط على recvonly.

بالنسبة إلى Meet Media API، يرسل العملاء دائمًا عرض SDP لبدء الاتصال. لا يكون Meet هو المُشغِّل أبدًا.

تتم إدارة هذا السلوك داخليًا من خلال عملاء المرجع (C++ وTypeScript)، ولكن يمكن لمطوّري العملاء المخصّصين استخدام PeerConnectionInterface في WebRTC لمحاولة إنشاء عرض.

للربط بتطبيق 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()));
     }
   }
   

   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. لتلقّي الفيديو، يجب أن يتضمّن العرض وصفًا واحدًا أو ثلاثة أوصافًا لوسائط فيديو مخصّصة للاستقبال فقط. ويمكنك إجراء ذلك من خلال ضبط أجهزة الإرسال والاستقبال في ملف تعريف اتصال الأقران.

   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. يجب أن يتضمّن العرض دائمًا قنوات البيانات. يجب أن تكون قناتا 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()));
   }
   

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

مثال على عرض وجواب وصف الجلسة

في ما يلي مثال كامل على عرض SDP صالح وإجابة SDP مطابقة. يتفاوض هذا العرض على جلسة Meet Media API مع بث صوتي ومرئي واحد.

يُرجى ملاحظة أنّ هناك ثلاثة أوصاف لملفّات الوسائط الصوتية ووصفًا واحدًا لملفّات الوسائط في الفيديو ووصفًا مطلوبًا لملفّات الوسائط في التطبيق.

مواضيع ذات صلة

• البدء