ستتم إزالة واجهة برمجة التطبيقات getStats() WebRTC API القديمة في الإصدار 117 من Chrome، وبالتالي سيكون على التطبيقات التي تستخدمها نقل البيانات إلى واجهة برمجة التطبيقات العادية. توضّح هذه المقالة كيفية نقل بيانات الرمز البرمجي والإجراءات التي يجب اتّخاذها إذا كنت بحاجة إلى مزيد من الوقت لإجراء هذا التغيير.
في السابق، كان هناك إصداران متنافسان من واجهة برمجة تطبيقات WebRTC getStats(). واجهة برمجة التطبيقات (getStats() القديمة، التي تحدِّد تاريخ عملية توحيد المقاييس مسبقًا وتأخذ وسيطة استدعاء استدعاء وواجهة برمجة التطبيقات الموحدة والمدعومة على نطاق واسع والتي تفي بنتائج واعدة.
تتميز واجهة برمجة التطبيقات العادية بأنها غنية بالميزات أكثر وتضم مقاييس محددة جيدًا وموثقة بشكل علني في مواصفات W3C معرفات واجهة برمجة التطبيقات لإحصاءات WebRTC. تتضمن المواصفات أوصافًا لكل مقياس مدرج في هذا الدليل وغير ذلك الكثير.
من Chrome 117، ستطرح واجهة برمجة التطبيقات getStats() القديمة استثناءً في قناة الإصدار الثابت (سيتم طرح طرح الاستثناء تدريجيًا). اتّبِع هذا الدليل لتسهيل عملية النقل إلى واجهة برمجة التطبيقات العادية.
أنواع الإحصاءات القديمة في مقابل البيانات العادية
يمكن العثور على القائمة الكاملة لأنواع الإحصاءات العادية بالاطّلاع على التعداد RTCStatsType في المواصفات. يتضمن ذلك تعريف قاموس الإحصاءات الذي يصف المقاييس التي تم جمعها لكل نوع.
تحتوي جميع كائنات الإحصاءات على سمة "id" (المعرّف) التي تحدِّد بشكلٍ فريد العنصر الأساسي في استدعاءات getStats() المتعددة. سيكون للكائن نفسه المعرف نفسه في كل مرة يتم فيها استدعاء الطريقة. ويكون هذا مفيدًا لحساب معدّل تغيُّر المقاييس (في ما يلي مثال في القسم التالي). تُشكّل المعرّفات أيضًا علاقات من المراجع. على سبيل المثال، يشير كائن الإحصائيات outbound-rtp إلى عنصر إحصاءات media-source المرتبط به من خلال السمة outbound-rtp.mediaSourceId. إذا رسمت كل العلاقات ...Id، ستحصل على رسم بياني.
وتتضمّن واجهة برمجة التطبيقات القديمة أنواع الإحصاءات التالية، بما يتوافق مع الأنواع العادية على النحو التالي:
النوع القديم |
النوع العادي |
|---|---|
ssrc
|
ويمثِّل ذلك بث RTP ومقاييس عن MediaStreamTrack المرتبط.تشمل الأنواع العادية لهذا النوع inbound-rtp (لأحداث بث RTP وعمليات الإرسال المرتبطة بها MediaStreamTrack) وoutbound-rtp (لأحداث بث RTP) وmedia-source (لمقاييس MediaStreamTrack المحلية المرتبطة ببث RTP للإرسال). تحتوي مقاييس بث RTP أيضًا على معلومات حول برنامج التشفير أو برنامج فك الترميز المستخدم بواسطة بث RTP. |
VideoBwe
|
مقاييس تقدير معدل نقل البيانات ومعدل نقل البيانات المستهدف ومعدل نقل بيانات برنامج الترميز ومعدل نقل البيانات الفعلي تشكّل هذه الأنواع من المقاييس جزءًا من مقياسَي RTP ( outbound-rtp وinbound-rtp) ومقياسَي إقران مرشح ICE (candidate-pair). |
googComponent
|
يمثل النقل (ICE وDTLS). الإصدار العادي هو transport. |
localcandidate and remotecandidate
|
يمثّل مرشّحًا من ICE. والإصدار العادي هو local-candidate وremote-candidate. |
googCandidatePair
|
ويمثل زوجًا من مرشحي ICE، وهو زوج من مرشح محلي ومرشح عن بُعد. الإصدار العادي هو candidate-pair. |
googCertificate
|
يمثل ذلك شهادة مستخدمة في عملية نقل بروتوكول أمان طبقة النقل لمخطّطات البيانات (DTLS). الإصدار العادي هو certificate. |
googLibjingleSession
|
يمثل RTCPeerConnection. على الرغم من أنّ محتواه لا يرتبط بأي عنصر في المعيار العادي، فإنّه يتضمن نوعًا مرتبطًا بـ RTCPeerConnection: peer-connection. |
غير متوفّر في واجهة برمجة التطبيقات القديمة |
تمت إضافة أنواع الإحصاءات التالية إلى واجهة برمجة التطبيقات العادية التي لا تحتوي على أي نوع قديم مقابل:
|
ربط المقاييس القديمة والعادية
يهدف هذا التعيين إلى مساعدة المطوّرين في العثور على المقياس القديم الذي يتوافق مع أي مقياس عادي، ولكن يُرجى العلم أنّ المقياس المقابل قد يستخدم وحدات مختلفة أو يتم التعبير عنه كعدّاد إجمالي بدلاً من قيمة فورية. ارجع إلى مواصفات تعريفات المقاييس.
تفضّل واجهة برمجة التطبيقات العادية عرض العدّادات الإجمالية بدلاً من الأسعار. وهذا يعني أنّه للحصول على المعدّل المقابل (على سبيل المثال، معدل نقل البيانات) كما في واجهة برمجة التطبيقات القديمة، يجب أن يحسب التطبيق متوسط معدّل الضريبة من خلال احتساب الدلتا بين طلبَي getStats(). على سبيل المثال:
// Periodically (e.g. every second or every 10 seconds)...
const currReport = await pc.getStats();
// Calculate bitrate since the last getStats() call.
// Handling of undefined is omitted for clarity.
const currOutboundRtp = currReport.values().find(s => s.type == 'outbound-rtp');
const prevOutboundRtp = prevReport.get(currOutboundRtp.id);
const deltaBits = (currOutboundRtp.bytesSent - prevOutboundRtp.bytesSent) * 8;
const deltaSeconds = (currOutboundRtp.timestamp - prevOutboundRtp.timestamp) / 1000;
logBitrateMeasurement(deltaBits / deltaSeconds);
// Remember the report for next time.
prevReport = currReport;
قد يبدو الاضطرار إلى حساب المعدلات والمتوسطات بنفسك على هذا النحو خطوة إضافية مرهقة، ولكن من الأفضل أن تتيح لك الحصول على المتوسطات على مدى أي فترة زمنية مطلوبة. هناك بعض مزايا الأداء لاستدعاء واجهة برمجة التطبيقات العادية بمعدّل أقل مما كنت تفعله بخلاف ذلك باستخدام واجهة برمجة التطبيقات القديمة.
المقياس القديم
googCertificate |
المراسلة العادية
certificate |
|---|---|
.googFingerprint
|
.fingerprint
|
.googFingerprintAlgorithm
|
.fingerprintAlgorithm
|
.googDerBase64
|
.base64Certificate
|
المقياس القديم
googComponent |
المراسلة العادية
transport |
|---|---|
.localCertificateId
|
.localCertificateId
|
.remoteCertificateId
|
.remoteCertificateId
|
.selectedCandidatePairId
|
.selectedCandidatePairId
|
.dtlsCipher
|
.dtlsCipher
|
.srtpCipher
|
.srtpCipher
|
المقياس القديم
localcandidate |
المراسلة العادية
local-candidate أو candidate-pair |
|---|---|
.stunKeepaliveRequestsSent
|
candidate-pair.requestsSent (البحث العكسي candidate-pair عبر candidate-pair.localCandidateId) |
.portNumber
|
local-candidate.port
|
.networkType
|
local-candidate.networkType
|
.ipAddress
|
local-candidate.address
|
.stunKeepaliveResponsesReceived
|
candidate-pair.responsesReceived
|
.stunKeepaliveRttTotal
|
candidate-pair.totalRoundTripTime
|
.transport
|
local-candidate.protocol
|
.candidateType
|
local-candidate.candidateType
|
.priority
|
local-candidate.priority
|
المقياس القديم
remotecandidate |
المراسلة العادية
remote-candidate |
|---|---|
هذه الأسعار مساوية لـ localcandidate أعلاه. |
هذه الأسعار مساوية لـ local-candidate أعلاه. |
المقياس القديم
googCandidatePair |
المراسلة العادية
candidate-pair |
|---|---|
.responsesSent
|
candidate-pair.responsesSent
|
.requestsReceived
|
candidate-pair.requestsReceived
|
.googRemoteCandidateType
|
remote-candidate.candidateType (البحث في remote-candidate عبر candidate-pair.remoteCandidateId) |
.googReadable
|
googReadable هي قيمة منطقية تعكس ما إذا كنا قد قمنا مؤخرًا بزيادة candidate-pair.requestsReceived أو candidate-pair.responsesReceived أم لا.
|
.googLocalAddress
|
local-candidate.address (البحث في local-candidate عبر candidate-pair.localCandidateId) |
.consentRequestsSent
|
candidate-pair.consentRequestsSent
|
.googTransportType
|
هذه الأسعار تساوي local-candidate.protocol وremote-candidate.protocol. |
.googChannelId
|
candidate-pair.transportId
|
.googLocalCandidateType
|
local-candidate.candidateType
|
.googWritable
|
تمثّل googWritable قيمة منطقية تعكس ما إذا كنا قمنا مؤخرًا بزيادة candidate-pair.responsesReceived أم لا.
|
.googRemoteAddress
|
remote-candidate.address
|
.googRtt
|
candidate-pair.currentRoundTripTime
|
.googActiveConnection
|
يشير الاتصال النشط إلى الزوج المرشح الذي يتم اختياره حاليًا من خلال عملية النقل، مثل المكان الذي يكون فيه candidate-pair.id == transport.selectedCandidatePairId |
.packetsDiscardedOnSend
|
candidate-pair.packetsDiscardedOnSend
|
.bytesReceived
|
candidate-pair.bytesReceived
|
.responsesReceived
|
candidate-pair.responsesReceived
|
.remoteCandidateId
|
candidate-pair.remoteCandidateId
|
.localCandidateId
|
candidate-pair.localCandidateId
|
.bytesSent
|
candidate-pair.bytesSent
|
.packetsSent
|
candidate-pair.packetsSent
|
.bytesReceived
|
candidate-pair.bytesReceived
|
.bytesReceived
|
candidate-pair.bytesReceived
|
المقياس القديم
ssrc |
المراسلة العادية
inbound-rtp وoutbound-rtp وmedia-source |
|---|---|
.audioInputLevel
|
media-source.audioLevel. يقع المقياس القديم في النطاق [0..32768] لكن المقياس العادي يقع في النطاق [0..1]. |
.audioOutputLevel
|
inbound-rtp.audioLevel يقع المقياس القديم في النطاق [0..32768] لكن المقياس العادي يقع في النطاق [0..1]. |
.packetsLost
|
inbound-rtp.packetsLost
|
.googTrackId
|
media-source.trackIdentifier لأجهزة MediaStreamTrack المحلية وinbound-rtp.trackIdentifier لأجهزة MediaStreamTrack عن بُعد |
.googRtt
|
remote-inbound-rtp.roundTripTime (اطّلِع على outbound-rtp.remoteId) |
.googEchoCancellationReturnLossEnhancement
|
inbound-rtp.echoReturnLossEnhancement
|
.googCodecName
|
اسم برنامج الترميز هو النوع الفرعي من "النوع/النوع الفرعي" نوع MIME، codec.mimeType (راجِع inbound-rtp.codecId وoutbound-rtp.codecId) |
.transportId
|
inbound-rtp.transportId وoutbound-rtp.transportId |
.mediaType
|
inbound-rtp.kind وoutbound-rtp.kind أو media-source.kind
|
.googEchoCancellationReturnLoss
|
inbound-rtp.echoReturnLoss
|
.totalAudioEnergy
|
inbound-rtp.totalAudioEnergy وmedia-source.totalAudioEnergy
|
ssrc.totalSamplesDuration
|
inbound-rtp.totalSamplesDuration وmedia-source.totalSamplesDuration
|
.ssrc
|
inbound-rtp.ssrc وoutbound-rtp.ssrc
|
.googJitterReceived
|
inbound-rtp.jitter
|
.packetsSent
|
outbound-rtp.packetsSent
|
.bytesSent
|
outbound-rtp.bytesSent
|
.googContentType
|
inbound-rtp.contentType وoutbound-rtp.contentType |
.googFrameWidthInput
|
media-source.width
|
.googFrameHeightInput
|
media-source.height
|
.googFrameRateInput
|
media-source.framesPerSecond
|
.googFrameWidthSent
|
outbound-rtp.frameWidth
|
.googFrameHeightSent
|
outbound-rtp.frameHeight
|
.googFrameRateSent
|
على الرغم من أنّ معدّل اللقطات في الثانية للإرسال هو معدّل التغيير في outbound-rtp.framesSent، يتم تنفيذه في الواقع على أنّه outbound-rtp.framesPerSecond وهو ترميز عدد اللقطات في الثانية. |
.googFrameWidthReceived
|
inbound-rtp.frameWidth
|
.googFrameHeightReceived
|
inbound-rtp.frameHeight
|
.googFrameRateDecoded
|
معدّل التغيير في inbound-rtp.framesDecoded |
.googFrameRateOutput
|
معدل التغيير من inbound-rtp.framesDecoded - inbound-rtp.framesDropped |
.hugeFramesSent
|
outbound-rtp.hugeFramesSent
|
.qpSum
|
|
.framesEncoded
|
outbound-rtp.framesEncoded
|
.googAvgEncodeMs
|
|
.codecImplementationName
|
|
.googCpuLimitedResolution
|
صواب إذا outbound-rtp.qualityLimitationReason == "cpu" |
.googBandwidthLimitedResolution
|
صواب إذا outbound-rtp.qualityLimitationReason == "bandwidth" |
.googAdaptationChanges
|
يحتسب المقياس القديم عدد المرات التي تم فيها تغيير درجة الدقة أو عدد اللقطات في الثانية لسببَين ( qualityLimitationReason) مرتبطَين. يمكن استنتاج ذلك من مقاييس أخرى (على سبيل المثال، اختلاف درجة دقة الإرسال أو عدد اللقطات في الثانية عن درجة دقة المصدر أو عدد اللقطات في الثانية)، ولكن قد تكون المدة التي تم حصرها، outbound-rtp.qualityLimitationDurations، أكثر فائدة من معدّل تغيير درجة الدقة أو عدد اللقطات في الثانية. |
.googNacksReceived
|
inbound-rtp.nackCount
|
.googNacksSent
|
inbound-rtp.nackCount
|
.googPlisReceived
|
inbound-rtp.pliCount
|
.googPlisSent
|
inbound-rtp.pliCount
|
.googFirsReceived
|
inbound-rtp.firCount
|
.googFirsSent
|
inbound-rtp.firCount
|
.googSecondaryDecodedRate
|
النسبة الحديثة للحزم التي تحتوي على تصحيح الخطأ: inbound-rtp.fecPacketsReceived - inbound-rtp.fecPacketsDiscarded |
.packetsReceived
|
inbound-rtp.packetsReceived
|
.googJitterBufferMs
|
inbound-rtp.jitterBufferDelay / inbound-rtp.jitterBufferEmittedCount
|
.googTargetDelayMs (فيديو) |
inbound-rtp.jitterBufferTargetDelay / inbound-rtp.jitterBufferEmittedCount
|
.googPreferredJitterBufferMs (صوت) |
inbound-rtp.jitterBufferTargetDelay / inbound-rtp.jitterBufferEmittedCount
|
.googExpandRate
|
النسبة الحديثة للعيّنات المخفية: inbound-rtp.concealedSamples / inbound-rtp.totalSamplesReceived |
.googSpeechExpandRate
|
النسبة المئوية الأخيرة للعيّنات المخفية عندما كان البث غير صامت: من (inbound-rtp.concealedSamples إلى inbound-rtp.silentConcealedSamples) / inbound-rtp.concealedSamples |
.googAccelerateRate
|
النسبة الحديثة للعيّنات التي تم تجاهلها لتسريع سرعة التشغيل: inbound-rtp.removedSamplesForAcceleration / inbound-rtp.totalSamplesReceived |
.googPreemptiveExpandRate
|
النسبة الحديثة للعيّنات التي تم مزجها بهدف إبطاء سرعة التشغيل: inbound-rtp.insertedSamplesForDeceleration / inbound-rtp.totalSamplesReceived |
.googSecondaryDiscardedRate
|
inbound-rtp.fecPacketsDiscarded
|
.bytesReceived
|
inbound-rtp.bytesReceived
|
s.googCurrentDelayMs
|
inbound-rtp.jitterBufferDelay + media-playout.totalPlayoutDelay
|
.googDecodeMs
|
inbound-rtp.totalDecodeTime / inbound-rtp.framesDecoded
|
.googTimingFrameInfo
|
مقياس goog الوحيد المتبقي. inbound-rtp.googTimingFrameInfo |
.framesDecoded
|
inbound-rtp.framesDecoded
|
المقياس القديم
VideoBwe |
المراسلة العادية
outbound-rtp وcandidate-pair |
|---|---|
.googTargetEncBitrate
|
outbound-rtp.targetBitrate كقيمة لحظية أو outbound-rtp.totalEncodedBytesTarget / outbound-rtp.framesEncoded كمتوسط |
.googActualEncBitrate
|
وحدات البايت الناتجة عن برنامج الترميز هي وحدات بايت الحمولة، باستثناء عمليات إعادة الإرسال: معدّل التغيير بين outbound-rtp.bytesSent وoutbound-rtp.retransmittedBytesSent. |
.googBucketDelay
|
outbound-rtp.totalPacketSendDelay / outbound-rtp.packetsSent
|
.googTransmitBitrate
|
معدّل التغيير في outbound-rtp.headerBytesSent + outbound-rtp.bytesSent لمعدل نقل بيانات البث لكل تطبيق "مراسلة نصية في الوقت الفعلي"، candidate-pair.bytesSent في معدل نقل البيانات المرشَّح لكل ICE، أو transport.bytesSent بالنسبة إلى معدل نقل البيانات لكل وسيلة نقل |
.googRetransmitBitrate
|
نطاق التغيير في outbound-rtp.retransmittedBytesSent |
.googAvailableSendBandwidth
|
candidate-pair.availableOutgoingBitrate
|
.googAvailableReceiveBandwidth
|
candidate-pair.availableIncomingBitrate
|
واجهة برمجة التطبيقات العادية تعتمد على البث المتزامن
في حال استخدام البث المتزامن، قد تكون لاحظت أنّ واجهة برمجة التطبيقات القديمة لا تُبلِغ إلا عن رمز SSRC واحد حتى عند استخدام البث المتزامن لإرسال (على سبيل المثال) ثلاثة عمليات بث في الوقت الفعلي على أساس ثلاثة رموز SSRC منفصلة.
لا تشارك واجهة برمجة التطبيقات العادية هذا القيد، وستعرض ثلاثة عناصر إحصاءات outbound-rtp، واحد لكل من رموز SSRC. وهذا يعني أنّه يمكنك تحليل كل عملية بث مباشر بتقنية RTP بشكل فردي، ولكن يعني هذا أيضًا أنّه للحصول على إجمالي معدل نقل البيانات لجميع عمليات بث RTP، ستحتاج إلى تجميعها بنفسك.
من ناحية أخرى، تظهر أحداث بث SVC أو RTP مع الطبقات المكانية المتعددة التي تم ضبطها عبر واجهة برمجة تطبيقات scalabilityMode في شكل outbound-rtp واحد لأنّه يتم إرسالها عبر رمز SSRC واحد.
في حال كنت بحاجة إلى مزيد من الوقت لنقل البيانات
عند إزالة واجهة برمجة التطبيقات القديمة في Chrome 117، سيؤدي استخدامها إلى إنشاء استثناء. إذا لم تتمكّن من نقل الرمز في الوقت المناسب، ستمنح التجربة المصدر لواجهة برمجة التطبيقات getStats() المستنِدة إلى معاودة الاتصال مزيدًا من الوقت للمواقع الإلكترونية المسجَّلة. باستخدام الرمز المميز الخاص بمراحل التجربة والتقييم، قد يستمر استخدام واجهة برمجة التطبيقات getStats() القديمة حتى الإصدار 121 من Chrome.