RTCStats method
[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]
Getter to retrieve the RTCStats objects that the stats report is composed of.
The set of supported property names [WEBIDL] is defined as the ids of all the RTCStats objects that has been generated for this stats report. The order of the property names is left to the user agent.
Syntax
var retval = RTCStatsReport.RTCStats(id);
Parameters
id [optional]
Type: DOMStringNullable
Return value
Type: getter
IDs for all of the RTCStats objects generated for this stats report.
Standards information
RTC Stats Dictionary
An RTCStats dictionary represents the stats gathered by inspecting a specific object. The RTCStats dictionary is a base type that specifies a set of default attributes, such as timestamp and type. Specific stats are added by extending the RTCStats dictionary.
Note While stats names are standardized, any given implementation may be using experimental values or values not yet known to the Web application. Thus, applications MUST be prepared to deal with unknown stats.
Statistics need to be synchronized with each other in order to yield reasonable values in computation; for instance, if "bytesSent" and "packetsSent" are both reported, they both need to be reported over the same interval, so that "average packet size" can be computed as "bytes / packets" - if the intervals are different, this will yield errors. Thus implementations MUST return synchronized values for all stats in a RTCStats object.
dictionary RTCStats {
DOMHighResTimeStamp timestamp;
RTCStatsType type;
DOMString id;
};
| Member | Type | Description |
|---|---|---|
| id | DOMString | A unique id that is associated with the object that was inspected to produce this RTCStats object. Two RTCStats objects, extracted from two different RTCStatsReport objects, MUST have the same id if they were produced by inspecting the same underlying object. User agents are free to pick any format for the id as long as it meets the requirements above. |
| timestamp | DOMHighResTimeStamp | The timestamp, of type DOMHiResTimeStamp[HIGHRES-TIME], associated with this object. The time is relative to the UNIX epoch (Jan 1, 1970, UTC). The timestamp for local measurements corresponds to the to the local clock and for remote measurements corresponds to the timestamp indicated in the incoming RTCP Sender Report (SR), Receiver Report (RR) or Extended Report (XR). |
| type | RTCStatsType | The type of this object. The type attribute MUST be initialized to the name of the most specific type this RTCStatsReport dictionary represents. |
RTCStatsType DOMString
RTCStatsType is equal to one of the following strings defined in [IANA-TOBE]:
| DOMString | Description |
|---|---|
| "inboundrtp" | Statistics for the inbound RTP stream. It is accessed via the RTCInboundRTPStreamStats defined in [WEBRTC-STATS] Section 4.2.3. Local inbound RTP statistics can be obtained from the RTCRtpReceiver object; remote inbound RTP statistics can be obtained from the RTCRtpSender object. |
| "outboundrtp" | Statistics for the outbound RTP stream. It is accessed via the RTCOutboundRTPStreamStats defined in [WEBRTC-STATS] Section 4.2.4. Local outbound RTP statistics can be obtained from the RTCRtpSender object; remote outbound RTP statistics can be obtained from the RTCRtpReceiver object. |
| "track" | Statistics relating to the MediaStreamTrack object. It is accessed via the RTCMediaStreamTrackStats defined in [WEBRTC-STATS] Section 4.4.2. |
| "transport" | Transport statistics related to the RTCDtlsTransport object. It is accessed via the RTCTransportStats and RTCCertificateStats defined in [WEBRTC-STATS] Sections 4.6 and 4.9. |
| "candidatepair" | ICE candidate pair statistics related to RTCIceTransport objects. It is accessed via the RTCIceCandidatePairStats defined in [WEBRTC-STATS] Section 4.8. |
| "localcandidate" | ICE local candidates, related to RTCIceGatherer objects. It is accessed via the RTCIceCandidateAttributes defined in [WEBRTC-STATS] Section 4.7. |
| "remotecandidate" | ICE remote candidate, related to RTCIceTransportobjects. It is accessed via the RTCIceCandidateAttributes defined in [WEBRTC-STATS] Section 4.7. |
RTCP matching rules
Since statistics are retrieved from objects within the ORTC API, and information within RTCP packets is used to maintain some of the statistics, the handling of RTCP packets is important to the operation of the statistics API.
RTCP packets arriving on an RTCDtlsTransport are decrypted and a notification is sent to all RTCRtpSender and RTCRtpReceiver objects utilizing that transport. RTCRtpSender and RTCRtpReceiver objects then examine the RTCP packets to determine the information relevant to their operation and the statistics maintained by them.
RTCP packets should be queued for 30 seconds and all RTCRtpSender and RTCRtpReceiver objects on the related RTCDTlsTransport have access to those packets until the packet is removed from the queue, should the RTCRtpSender or RTCRtpReceiver objects need to examine them.
Relevant SSRC fields within selected RTCP packets are summarized within [RFC3550] Section 6.4.1 (Sender Report), Section 6.4.2 (Receiver Report), Section 6.5 (SDES), Section 6.6 (BYE), [RFC4585] Section 6.1 (Feedback Messages), and [RFC3611] Section 2 (Extended Reports).
Example
Consider the case where the user is experiencing bad sound and the application wants to determine if the cause of it is packet loss. The following example code might be used:
var mySender = new RTCRtpSender(myTrack);
var myPreviousReport = null;
// ... wait a bit
setTimeout(function () {
mySender.getStats().then(function (report) {
processStats(report);
myPreviousReport = report;
});
}, aBit);
function processStats(currentReport) {
if (myPreviousReport === null) return;
// currentReport + myPreviousReport are an RTCStatsReport interface
// compare the elements from the current report with the baseline
for (var i in currentReport) {
var now = currentReport[i];
if (now.type != "outboundrtp")
continue;
// get the corresponding stats from the previous report
base = myPreviousReport[now.id];
// base + now will be of RTCRtpStreamStats dictionary type
if (base) {
remoteNow = currentReport[now.associateStatsId];
remoteBase = myPreviousReport[base.associateStatsId];
var packetsSent = now.packetsSent - base.packetsSent;
var packetsReceived = remoteNow.packetsReceived - remoteBase.packetsReceived;
// if fractionLost is > 0.3, we have probably found the culprit
var fractionLost = (packetsSent - packetsReceived) / packetsSent;
}
}
}