WebRTC: คำแนะนำในการย้ายข้อมูล getStats() เดิม

Henrik Boström

ระบบจะนำ getStats() WebRTC API รุ่นเดิมออกจาก Chrome 117 ดังนั้นแอปที่ใช้ API ดังกล่าวจะต้องย้ายข้อมูลไปยัง API มาตรฐาน บทความนี้อธิบายวิธีย้ายข้อมูลโค้ดและสิ่งที่คุณต้องทำหากต้องการเวลาเพิ่มเติมเพื่อทำการเปลี่ยนแปลงนี้

ที่ผ่านมา WebRTC getStats() API มี 2 เวอร์ชันที่แข่งขันกัน API getStats() เดิมซึ่งอยู่ก่อนกระบวนการมาตรฐานและรับอาร์กิวเมนต์ Callback และ API ที่ได้รับการมาตรฐานและรองรับอย่างกว้างขวางซึ่งแสดงผล Promise

API มาตรฐานมีฟีเจอร์ที่หลากหลายกว่าและมีเมตริกที่ระบุไว้อย่างชัดเจนซึ่งเผยแพร่ในเอกสารข้อกำหนด W3C ตัวระบุสำหรับ Statistics API ของ WebRTC ข้อกําหนดนี้ประกอบด้วยคําอธิบายของเมตริกแต่ละรายการที่ระบุไว้ในคู่มือนี้และอื่นๆ อีกมากมาย

ตั้งแต่ Chrome 117 เป็นต้นไป getStats() API รุ่นเดิมจะแสดงข้อยกเว้นในเวอร์ชันการเผยแพร่เสถียร (การแสดงข้อยกเว้นจะทยอยเปิดตัว) ทําตามคู่มือนี้เพื่อให้การเปลี่ยนไปใช้ API มาตรฐานเป็นไปอย่างราบรื่น

หมายเหตุ: คุณสามารถเปรียบเทียบเมตริกเดิมและเมตริกมาตรฐานแบบเรียลไทม์ขณะที่แอปทํางานอยู่ได้โดยไปที่ chrome://webrtc-internals/ ในแท็บแยกต่างหาก จากนั้นเลือกเมตริกเดิมหรือมาตรฐานโดยใช้ตารางแบบเลื่อนลง

ประเภทสถิติเดิมเทียบกับสถิติมาตรฐาน

ดูรายการประเภทสถิติมาตรฐานทั้งหมดได้โดยดูที่ RTCStatsType enum ในข้อกำหนด ซึ่งรวมถึงคําจํากัดความของพจนานุกรมสถิติที่อธิบายเมตริกที่รวบรวมสําหรับแต่ละประเภท

ออบเจ็กต์สถิติทั้งหมดมีแอตทริบิวต์รหัสซึ่งระบุออบเจ็กต์พื้นฐานที่ไม่ซ้ำกันในการเรียกใช้ getStats() หลายครั้ง ออบเจ็กต์เดียวกันจะมีรหัสเดียวกันทุกครั้งที่มีการเรียกใช้เมธอด ซึ่งมีประโยชน์สําหรับคํานวณอัตราการเปลี่ยนแปลงของเมตริก (ดูตัวอย่างได้ในส่วนถัดไป) รหัสเหล่านี้ยังสร้างความสัมพันธ์ของข้อมูลอ้างอิงด้วย เช่น ออบเจ็กต์สถิติ outbound-rtp จะอ้างอิงออบเจ็กต์สถิติ media-source ที่เชื่อมโยงผ่านแอตทริบิวต์ outbound-rtp.mediaSourceId หากวาดความสัมพันธ์ ...Id ทั้งหมด คุณจะได้กราฟ

API รุ่นเดิมมีประเภทสถิติต่อไปนี้ ซึ่งสอดคล้องกับประเภทมาตรฐานดังต่อไปนี้

ประเภทเดิม	ประเภทมาตรฐาน
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
ไม่มีใน API เดิม	เราได้เพิ่มสถิติประเภทต่อไปนี้ลงใน API มาตรฐานที่ไม่มีประเภทเดิมที่เกี่ยวข้อง codec: ตัวแปลงรหัสที่สตรีม RTP กำลังใช้อยู่เพื่อเข้ารหัสหรือถอดรหัส รายการนี้เป็นชุดย่อยของโค้ดที่เจรจาต่อรองใน SDP remote-inbound-rtp: สตรีม RTP ขาเข้าของอุปกรณ์ปลายทางระยะไกลซึ่งสอดคล้องกับสตรีม RTP ขาออกที่อุปกรณ์ปลายทางนี้ส่ง (outbound-rtp) ระบบจะวัดที่อุปกรณ์ปลายทางระยะไกลและรายงานในรายงานตัวรับ RTCP (RR) หรือรายงานแบบขยายของ RTCP (XR) remote-outbound-rtp: สตรีม RTP ขาออกของปลายทางระยะไกลซึ่งสอดคล้องกับสตรีม RTP ขาเข้าที่ปลายทางนี้รับ (inbound-rtp) โดยระบบจะวัดที่ปลายทางระยะไกลและรายงานในรายงานผู้ส่ง RTCP (SR) media-playout: เมตริกเกี่ยวกับการเล่น MediaStreamTrack ระยะไกลที่เชื่อมโยงกับสตรีม RTP ขาเข้า (inbound-rtp) data-channel: แสดง RTCDataChannel

การแมปเมตริกเดิมกับเมตริกมาตรฐาน

การแมปนี้มีไว้เพื่อช่วยนักพัฒนาซอฟต์แวร์ค้นหาว่าเมตริกเดิมเมตริกใดสอดคล้องกับเมตริกมาตรฐานเมตริกใด แต่โปรดทราบว่าเมตริกที่เกี่ยวข้องอาจใช้หน่วยวัดที่แตกต่างกันหรือแสดงเป็นเคาน์เตอร์ทั้งหมดแทนค่าทันที โปรดดูคำจำกัดความของเมตริกในข้อกําหนด
API มาตรฐานต้องการแสดงเคาน์เตอร์ทั้งหมดแทนอัตรา ซึ่งหมายความว่าหากต้องการอัตราที่เกี่ยวข้อง (เช่น อัตราบิต) เช่นเดียวกับใน API รุ่นเดิม แอปจะต้องคำนวณอัตราเฉลี่ยโดยนำค่าต่างระหว่างการเรียก getStats() 2 ครั้ง เช่น

// 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;

การต้องคำนวณราคาและค่าเฉลี่ยด้วยตนเองเช่นนี้อาจดูเหมือนเป็นขั้นตอนเพิ่มเติมที่ยุ่งยาก แต่ข้อดีคือช่วยให้คุณได้รับค่าเฉลี่ยในช่วงเวลาที่ต้องการ การเรียก API มาตรฐานให้ถี่น้อยกว่าที่คุณอาจต้องทำกับ API รุ่นเดิมจะมีประโยชน์ด้านประสิทธิภาพบางอย่าง

เมตริกเดิม 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 "type/subtype" ซึ่งก็คือ 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	แม้ว่า FPS ที่ส่งจะเป็นอัตราการเปลี่ยนแปลงของ outbound-rtp.framesSent แต่จริง ๆ แล้วจะใช้เป็น outbound-rtp.framesPerSecond ซึ่งเป็น FPS ที่เข้ารหัส
.googFrameWidthReceived	inbound-rtp.frameWidth
.googFrameHeightReceived	inbound-rtp.frameHeight
.googFrameRateDecoded	อัตราการเปลี่ยนแปลงของ inbound-rtp.framesDecoded
.googFrameRateOutput	อัตราการเปลี่ยนแปลงของ inbound-rtp.framesDecoded - inbound-rtp.framesDropped
.hugeFramesSent	outbound-rtp.hugeFramesSent
.qpSum	inbound-rtp.qpSum และ outbound-rtp.qpSum
.framesEncoded	outbound-rtp.framesEncoded
.googAvgEncodeMs	outbound-rtp.totalEncodeTime / outbound-rtp.framesEncoded
.codecImplementationName	inbound-rtp.decoderImplementation และ outbound-rtp.encoderImplementation
.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 สำหรับอัตราบิตของสตรีม RTP ต่อ 1 รายการ, candidate-pair.bytesSent สำหรับอัตราบิตของตัวเลือก ICE ต่อ 1 รายการ หรือ transport.bytesSent สำหรับอัตราบิตของสื่อกลางต่อ 1 รายการ
.googRetransmitBitrate	ช่วงการเปลี่ยนแปลงของ outbound-rtp.retransmittedBytesSent
.googAvailableSendBandwidth	candidate-pair.availableOutgoingBitrate
.googAvailableReceiveBandwidth	candidate-pair.availableIncomingBitrate

API มาตรฐานรองรับการออกอากาศแบบพร้อมกัน

หากใช้การออกอากาศแบบพร้อมกัน คุณอาจสังเกตเห็นว่า API เดิมรายงาน SSRC เพียงรายการเดียว แม้ว่าคุณจะใช้การออกอากาศแบบพร้อมกันเพื่อส่ง (เช่น) สตรีม RTP 3 รายการผ่าน SSRC แยกกัน 3 รายการก็ตาม

API มาตรฐานไม่มีข้อจํากัดนี้ และจะแสดงผลออบเจ็กต์สถิติ outbound-rtp 3 รายการ โดย 1 รายการสําหรับ SSRC แต่ละรายการ ซึ่งหมายความว่าคุณสามารถวิเคราะห์สตรีม RTP แต่ละรายการแยกกันได้ แต่คุณจะต้องรวบรวมสตรีมเหล่านั้นด้วยตนเองเพื่อดูอัตราบิตทั้งหมดของสตรีมการส่ง RTP ทั้งหมด

สตรีม SVC หรือสตรีม RTP ที่มีเลเยอร์เชิงพื้นที่หลายเลเยอร์ซึ่งกำหนดค่าผ่าน scalabilityMode API ในทางกลับกันจะยังคงแสดงเป็น outbound-rtp รายการเดียว เนื่องจากมีการส่งผ่าน SSRC รายการเดียว

หากต้องการเวลาเพิ่มเติมในการย้ายข้อมูล

เมื่อนำ API รุ่นเดิมออกใน Chrome 117 การใช้ API ดังกล่าวจะทำให้เกิดข้อยกเว้น หากย้ายข้อมูลโค้ดไม่ทัน ช่วงทดลองใช้ต้นทางสําหรับ getStats() API ตามการเรียกกลับ RTCPeerConnection จะช่วยให้เว็บไซต์ที่ลงทะเบียนมีเวลาในการย้ายข้อมูลมากขึ้น หากมีโทเค็นช่วงทดลองใช้จากต้นทาง คุณอาจใช้ getStats() API แบบเดิมได้จนถึง Chrome 121