-
Notifications
You must be signed in to change notification settings - Fork 22.4k
/
index.md
137 lines (108 loc) · 4.5 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
---
title: RTCPeerConnection.getStats()
slug: Web/API/RTCPeerConnection/getStats
page-type: web-api-instance-method
tags:
- API
- Connection
- Method
- RTCPeerConnection
- RTCStats
- RTCStatsReport
- Reference
- Statistics
- Stats
- WebRTC
- WebRTC API
- WebRTC Stats
- getStats
- rtc
browser-compat: api.RTCPeerConnection.getStats
---
{{APIRef("WebRTC")}}
The {{domxref("RTCPeerConnection")}} method
**`getStats()`** returns a promise which resolves with data
providing statistics about either the overall connection or about the specified
{{domxref("MediaStreamTrack")}}.
## Syntax
```js
getStats()
getStats(selector)
```
### Parameters
- `selector` {{optional_inline}}
- : A {{domxref("MediaStreamTrack")}} for which to gather statistics. If this is
`null` (the default value), statistics will be gathered for the entire
{{domxref("RTCPeerConnection")}}.
### Return value
A {{jsxref("Promise")}} which resolves with an {{domxref("RTCStatsReport")}} object
providing connection statistics. The contents of the report depend on the
`selector` as well as other details of the connection.
### Exceptions
This method does not throw exceptions; instead, it rejects the returned promise with
one of the following errors:
- `InvalidAccessError`
- : There is no {{domxref("RTCRtpSender")}} or {{domxref("RTCRtpReceiver")}} whose
`track` matches the specified `selector`, or
`selector` matches more than one sender or receiver.
### Obsolete syntax
Previously, `getStats()` used success and failure callbacks to report the
results to you, instead of using a promise.
This version of `getStats()` is obsolete; in addition, the data it returns
is entirely different from the current specification, and the form of that data was
never documented. This form of `getStats()` has been or will soon be removed
from most browsers; you _should not use it, and should update existing code to use
the new promise-based version_. Check the [Browser compatibility](#browser_compatibility) table
to verify the state of this method.
```js
promise = rtcPeerConnection.getStats(selector, successCallback, failureCallback) {{deprecated_inline}}
```
#### Parameters
- `selector` {{optional_inline}}
- : A {{domxref("MediaStreamTrack")}} for which to gather statistics. If this is
`null` (the default value), statistics will be gathered for the entire
{{domxref("RTCPeerConnection")}}.
- `successCallback`
- : A callback function to call when the stats have been retrieved. The function
receives as input a single parameter: an {{domxref("RTCStatsReport")}} with the
collected statistics. No output is expected from the function.
- `failureCallback`
- : A function to call when an error occurs while attempting to collect statistics. The
callback receives as input the exception (a {{domxref("DOMException")}} object
describing the error which occurred. No return value is expected from the callback.
## Examples
This example creates a periodic function using
{{domxref("setInterval()")}} that collects
statistics for an {{domxref("RTCPeerConnection")}} every second, generating an
HTML-formatted report and inserting it into a specific element in the DOM.
```js
window.setInterval(function() {
myPeerConnection.getStats(null).then(stats => {
let statsOutput = "";
stats.forEach(report => {
statsOutput += `<h2>Report: ${report.type}</h2>\n<strong>ID:</strong> ${report.id}<br>\n` +
`<strong>Timestamp:</strong> ${report.timestamp}<br>\n`;
// Now the statistics for this report; we intentionally drop the ones we
// sorted to the top above
Object.keys(report).forEach(statName => {
if (statName !== "id" && statName !== "timestamp" && statName !== "type") {
statsOutput += `<strong>${statName}:</strong> ${report[statName]}<br>\n`;
}
});
});
document.querySelector(".stats-box").innerHTML = statsOutput;
});
}, 1000);
```
This works by calling `getStats()`, then, when the promise is resolved,
iterates over the {{domxref("RTCStats")}} objects on the returned
{{domxref("RTCStatsReport")}}. A section is created for each report with a header and
all of the statistics below, with the type, ID, and timestamp handled specially to place
them at the top of the list.
Once the [HTML](/en-US/docs/Web/HTML) for the report is generated, it is
injected into the element whose class is `"stats-box"` by setting its
{{domxref("Element.innerHTML", "innerHTML")}} property.
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}