التعرّف على مفاهيم واجهة برمجة التطبيقات Media API
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح واجهة برمجة التطبيقات Google Meet Media لتطبيقك الانضمام إلى مؤتمر على Google Meet واستهلاك بث الوسائط في الوقت الفعلي.
يستخدم العملاء WebRTC للتواصل مع خوادم Meet. توضّح برامج العميل المرجعية المتوفّرة (C++ وTypeScript) الممارسات المقترَحة، وننصحك بالاستفادة منها مباشرةً.
ومع ذلك، يمكنك أيضًا إنشاء برامج عميل WebRTC مخصّصة بالكامل تتوافق مع المتطلبات الفنية لواجهة برمجة تطبيقات Meet Media.
توضّح هذه الصفحة المفاهيم الأساسية في WebRTC المطلوبة لإجراء جلسة ناجحة باستخدام Meet Media API.
إشارات العرض والرد
WebRTC هو إطار عمل من نظير إلى نظير (P2P)، حيث يتواصل النظراء من خلال إرسال إشارات إلى بعضهم البعض. لبدء جلسة، يرسل الجهاز المضيف عرض 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
مرشّحات إنشاء الاتصالات التفاعلية (ICE، RFC
8445) الخاصة بنظير هي قائمة
بالطرق التي يمكن لنظير بعيد استخدامها لإنشاء اتصال.
يمثّل حاصل الضرب الديكارتي لقائمتَي الأجهزة المتصلة، والمعروف باسم أزواج المرشحين، المسارات المحتملة بين جهازَين متصلَين. ويتم اختبار هذه الأزواج لتحديد المسار الأمثل.
importcom.google.api.core.ApiFuture;importcom.google.apps.meet.v2beta.ConnectActiveConferenceRequest;importcom.google.apps.meet.v2beta.ConnectActiveConferenceResponse;importcom.google.apps.meet.v2beta.SpaceName;importcom.google.apps.meet.v2beta.SpacesServiceClient;publicclassAsyncConnectActiveConference{publicstaticvoidmain(String[]args)throwsException{asyncConnectActiveConference();}publicstaticvoidasyncConnectActiveConference()throwsException{// 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_librarytry(SpacesServiceClientspacesServiceClient=SpacesServiceClient.create()){ConnectActiveConferenceRequestrequest=ConnectActiveConferenceRequest.newBuilder().setName(SpaceName.of("[SPACE]").toString()).setOffer("offer105650780").build();ApiFuture<ConnectActiveConferenceResponse>future=spacesServiceClient.connectActiveConferenceCallable().futureCall(request);// Do something.ConnectActiveConferenceResponseresponse=future.get();}}}
usingGoogle.Apps.Meet.V2Beta;usingSystem.Threading.Tasks;publicsealedpartialclassGeneratedSpacesServiceClientSnippets{/// <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>publicasyncTaskConnectActiveConferenceAsync(){// Create clientSpacesServiceClientspacesServiceClient=awaitSpacesServiceClient.CreateAsync();// Initialize request argument(s)stringname="spaces/[SPACE]";// Make the requestConnectActiveConferenceResponseresponse=awaitspacesServiceClient.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 libraryconst{SpacesServiceClient}=require('@google-apps/meet').v2beta;// Instantiates a clientconstmeetClient=newSpacesServiceClient();asyncfunctioncallConnectActiveConference(){// Construct requestconstrequest={name,offer,};// Run requestconstresponse=awaitmeetClient.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.htmlfromgoogle.appsimportmeet_v2betaasyncdefsample_connect_active_conference():# Create a clientclient=meet_v2beta.SpacesServiceAsyncClient()# Initialize request argument(s)request=meet_v2beta.ConnectActiveConferenceRequest(name="name_value",offer="offer_value",)# Make the requestresponse=awaitclient.connect_active_conference(request=request)# Handle the responseprint(response)
مثال على مسار الربط
إليك عرضًا يتضمّن وصفًا لوسائط صوتية:
الشكل 1. مثال على عرض يتضمّن وصفًا لوسائط صوتية
يستجيب الجهاز البعيد بنوع SDP
answer الذي يحتوي على العدد نفسه من أسطر وصف الوسائط. يشير كل سطر إلى الوسائط التي يرسلها الجهاز البعيد إلى الجهاز الذي يقدّم العرض، إن وُجدت، عبر بث SRTP. قد يرفض الجهاز البعيد أيضًا بثًا معيّنًا من الجهاز الذي يقدّم العرض من خلال ضبط إدخال وصف الوسائط على recvonly.
بالنسبة إلى Meet Media API، يرسل العملاء دائمًا عرض SDP لبدء اتصال. لا يبدأ Meet الاجتماع أبدًا.
تتم إدارة هذا السلوك داخليًا من خلال برامج العميل المرجعية
(C++ وTypeScript)،
ولكن يمكن لمطوّري برامج العميل المخصّصة استخدام PeerConnectionInterface في WebRTC
لإنشاء عرض.
لربط العرض الترويجي بتطبيق Meet Meet، يجب أن يستوفي العرض الترويجي
المتطلبات التالية:
يجب أن يعمل العميل دائمًا كعميل في عملية المصافحة عبر DTLS، لذا يجب أن يحدّد كل وصف وسائط في العرض إما a=setup:actpass أو a=setup:active.
يجب أن يتوافق كل سطر من سطور وصف الوسائط مع جميع برامج الترميز المطلوبة لنوع الوسائط هذا:
المحتوى الصوتي:Opus
الفيديو:VP8، VP9، AV1
لتلقّي الصوت، يجب أن يتضمّن العرض 3 أوصاف لوسائط صوتية مخصّصة للتلقّي فقط. يمكنك إجراء ذلك من خلال ضبط أجهزة الإرسال والاستقبال على عنصر اتصال الند للند.
C++
// ...rtc::scoped_refptr<webrtc::PeerConnectionInterface>peer_connection;for(inti=0;i < 3;++i){webrtc::RtpTransceiverInitaudio_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()){returnabsl::InternalError(absl::StrCat("Failed to add audio transceiver: ",audio_result.error().message()));}}
JavaScript
pc=newRTCPeerConnection();// Configure client to receive audio from Meet servers.pc.addTransceiver('audio',{'direction':'recvonly'});pc.addTransceiver('audio',{'direction':'recvonly'});pc.addTransceiver('audio',{'direction':'recvonly'});
لتلقّي الفيديو، يجب أن يتضمّن العرض أوصاف وسائط فيديو مخصّصة للتلقّي فقط تتراوح بين 1 و3. يمكنك إجراء ذلك من خلال ضبط أجهزة الإرسال والاستقبال على عنصر اتصال الند للند.
C++
// ...rtc::scoped_refptr<webrtc::PeerConnectionInterface>peer_connection;for(uint32_ti=0;i < configurations.receiving_video_stream_count;++i){webrtc::RtpTransceiverInitvideo_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()){returnabsl::InternalError(absl::StrCat("Failed to add video transceiver: ",video_result.error().message()));}}
JavaScript
pc=newRTCPeerConnection();// Configure client to receive video from Meet servers.pc.addTransceiver('video',{'direction':'recvonly'});pc.addTransceiver('video',{'direction':'recvonly'});pc.addTransceiver('video',{'direction':'recvonly'});
يجب أن يتضمّن العرض دائمًا قنوات بيانات. يجب أن تكون القناتان session-control وmedia-stats مفتوحتَين دائمًا على الأقل. يجب أن تكون جميع قنوات البيانات ordered.
C++
// ...// All data channels must be ordered.constexprwebrtc::DataChannelInitkDataChannelConfig={.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()){returnabsl::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()){returnabsl::InternalError(absl::StrCat("Failed to create data channel ",data_channel_label,": ",stats_create_result.error().message()));}
JavaScript
// ...pc=newRTCPeerConnection();// All data channels must be ordered.constdataChannelConfig={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 تتضمّن الصوت وفيديو واحدًا.
لاحظ أنّ هناك ثلاثة أوصاف لملفات وسائط صوتية، ووصف واحد لملف وسائط فيديو، ووصف ملف وسائط التطبيق المطلوب.
Client SDP offer
استيفاء إجابة بروتوكول وصف الجلسة (SDP) لواجهة Media API
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[],[]]
