RTCVideoSourceStats - draft

files/en-us/web/api/rtcvideosourcestats/framespersecond/index.md

@@ -0,0 +1,46 @@
+---
+title: "RTCVideoSourceStats: framesPerSecond property"
+short-title: framesPerSecond
+slug: Web/API/RTCVideoSourceStats/framesPerSecond
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.framesPerSecond
+---
+
+{{APIRef("WebRTC")}}
+
+The **`framesPerSecond`** property of the {{domxref("RTCVideoSourceStats")}} dictionary indicates the number of frames from this video source in the last second.
+
+The property is not defined on the stats object for the first second of its lifetime.
+
+## Value
+
+A number indicating the frames from this source in the last second.
+
+## Examples
+
+This example shows how you might iterate the stats object returned from `RTCRtpSender.getStats()` to get the video source stats, and then extract the `framesPerSecond`.
+
+```js
+// where sender is an RTCRtpSender
+const stats = await sender.getStats();
+let videoSourceStats = null;
+
+stats.forEach((report) => {
+  if (report.type === "media-source" && report.kind==="video") {
+    videoSourceStats = report;
+    break;
+  }
+});
+
+// Note, test is conditional because
+// framesPerSecond does not exist in the first second
+const fps = videoSourceStats?.framesPerSecond;
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtcvideosourcestats/id/index.md

@@ -0,0 +1,27 @@
+---
+title: "RTCVideoSourceStats: id property"
+short-title: id
+slug: Web/API/RTCVideoSourceStats/id
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.id
+---
+
+{{APIRef("WebRTC")}}
+
+The **`id`** property of the {{domxref("RTCVideoSourceStats")}} dictionary is a string which uniquely identifies the object for which this object provides statistics.
+
+Using the `id`, you can correlate this statistics object with others, in order to monitor statistics over time for a given WebRTC object, such as an {{domxref("RTCPeerConnection")}}, or an {{domxref("RTCDataChannel")}}.
+
+## Value
+
+A string that uniquely identifies the object for which this `RTCVideoSourceStats` object provides statistics.
+
+The format of the ID string is not defined by the specification, so you cannot reliably make any assumptions about the contents of the string, or assume that the format of the string will remain unchanged for a given object type.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtcvideosourcestats/index.md

@@ -0,0 +1,79 @@
+---
+title: RTCVideoSourceStats
+slug: Web/API/RTCVideoSourceStats
+page-type: web-api-interface
+browser-compat: api.RTCStatsReport.type_media-source
+---
+
+{{APIRef("WebRTC")}}
+
+The **`RTCVideoSourceStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics information about a video track that is attached to one or more senders.
+
+These statistics can be obtained by iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCRtpSender.getStats()")}} or {{domxref("RTCPeerConnection.getStats()")}} until you find a report with the [`type`](#type) of `media-source` and a [`kind`](#kind) of `video`.
+
+> **Note:** For video information about remotely sourced tracks (that are being received), see {{domxref("RTCInboundRtpStreamStats")}}.
+
+## Instance properties
+
+- {{domxref("RTCVideoSourceStats.frames", "frames")}}
+  - : A positive number that indicates the total number of frames from this video source.
+- {{domxref("RTCVideoSourceStats.framesPerSecond", "framesPerSecond")}}
+  - : A number that represents the number of frames from this video source in the last second.
+- {{domxref("RTCVideoSourceStats.height", "height")}}
+  - : A positive number that represents the height, in pixels, of the last frame originating from this source.
+    This property is not defined on the stats option until after the first frame has been produced.
+- {{domxref("RTCVideoSourceStats.width", "width")}}
+  - : A number that represents thewidth, in pixels, of the last frame originating from this source.
+    This property is not defined on the stats option until after the first frame has been produced.
+
+The following properties are present in both `RTCVideoSourceStats` and {{domxref("RTCAudioSourceStats")}}: <!-- RTCMediaSourceStats  -->
+
+- {{domxref("RTCVideoSourceStats.trackIdentifier", "trackIdentifier")}}
+  - : A string that contains the [`id`](/en-US/docs/Web/API/MediaStreamTrack/id) value of the [`MediaStreamTrack`](/en-US/docs/Web/API/MediaStreamTrack) associated with the audio source.
+- {{domxref("RTCVideoSourceStats.kind", "kind")}}
+  - : A string indicating the kind of media source. For an `RTCVideoSourceStats` this will always be `video`.
+
+### Common instance properties
+
+The following properties are common to all statistics objects. <!-- RTCStats -->
+
+- {{domxref("RTCVideoSourceStats.id", "id")}}
+  - : A string that uniquely identifies the object that is being monitored to produce this set of statistics.
+- {{domxref("RTCVideoSourceStats.timestamp", "timestamp")}}
+  - : A {{domxref("DOMHighResTimeStamp")}} object indicating the time at which the sample was taken for this statistics object.
+- {{domxref("RTCVideoSourceStats.type", "type")}}
+  - : A string with the value `"media-source"`, indicating that the object is an instance of either {{domxref("RTCVideoSourceStats")}} or {{domxref("RTCVideoSourceStats")}}.
+
+## Description
+
+The interface provides statistics about an audio media source attached to one or more senders.
+The information includes Xxxxx.
+
+## Examples
+
+This example shows how you might iterate the stats object returned from `RTCRtpSender.getStats()` to get the video source stats, and then extract the `framesPerSecond`.
+
+```js
+// where sender is an RTCRtpSender
+const stats = await sender.getStats();
+let videoSourceStats = null;
+
+stats.forEach((report) => {
+  if (report.type === "media-source" && report.kind==="video") {
+    videoSourceStats = report;
+    break;
+  }
+});
+
+// Note, test is conditional.
+// framesPerSecond does not exist in the first second
+const fps = videoSourceStats?.framesPerSecond;
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtcvideosourcestats/kind/index.md

@@ -0,0 +1,25 @@
+---
+title: "RTCVideoSourceStats: kind property"
+short-title: kind
+slug: Web/API/RTCVideoSourceStats/kind
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.kind
+---
+
+{{APIRef("WebRTC")}}
+
+The **`kind`** property of the {{domxref("RTCVideoSourceStats")}} dictionary is a string with the value `video`.
+
+The `kind` is used to differentiate between audio and video media sources when iterating an {{domxref("RTCStatsReport")}}, which both have a {{domxref("RTCVideoSourceStats.type", "type")}} of `media-source` (a `kind` of `audio` indicates an {{domxref("RTCAudioSourceStats")}} object).
+
+## Value
+
+A string with the value `video`.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtcvideosourcestats/timestamp/index.md

@@ -0,0 +1,27 @@
+---
+title: "RTCVideoSourceStats: timestamp property"
+short-title: timestamp
+slug: Web/API/RTCVideoSourceStats/timestamp
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.timestamp
+---
+
+{{APIRef("WebRTC")}}
+
+The **`timestamp`** property of the {{domxref("RTCVideoSourceStats")}} dictionary is a {{domxref("DOMHighResTimeStamp")}} object specifying the time at which the data in the object was sampled.
+
+The time is given in milliseconds elapsed since the first moment of January 1, 1970, UTC (also known as [Unix time](/en-US/docs/Glossary/Unix_time)).
+
+## Value
+
+A {{domxref("DOMHighResTimeStamp")}} value indicating the time at which the activity described by the statistics in this object was recorded, in milliseconds elapsed since the beginning of January 1, 1970, UTC.
+
+The value should be accurate to within a few milliseconds but may not be entirely precise, either because of hardware or operating system limitations or because of [fingerprinting](/en-US/docs/Glossary/Fingerprinting) protection in the form of reduced clock precision or accuracy.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtcvideosourcestats/trackidentifier/index.md

@@ -0,0 +1,23 @@
+---
+title: "RTCVideoSourceStats: trackIdentifier property"
+short-title: trackIdentifier
+slug: Web/API/RTCVideoSourceStats/trackIdentifier
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.trackIdentifier
+---
+
+{{APIRef("WebRTC")}}
+
+The **`trackIdentifier`** property of the {{domxref("RTCVideoSourceStats")}} dictionary contains the `id` attribute of the associated [`MediaStreamTrack`](/en-US/docs/Web/API/MediaStreamTrack).
+
+## Value
+
+A string containing the value of the associated [`MediaStreamTrack.id`](/en-US/docs/Web/API/MediaStreamTrack/id).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

files/en-us/web/api/rtcvideosourcestats/type/index.md

@@ -0,0 +1,26 @@
+---
+title: "RTCVideoSourceStats: type property"
+short-title: type
+slug: Web/API/RTCVideoSourceStats/type
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.type
+---
+
+{{APIRef("WebRTC")}}
+
+The **`type`** property of the {{domxref("RTCVideoSourceStats")}} dictionary is a string with value `media-source`.
+
+The type of `media-source` identifies the type of statistics as either {{domxref("RTCAudioSourceStats")}} or {{domxref("RTCVideoSourceStats")}} when iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCRtpSender.getStats()")}} or {{domxref("RTCPeerConnection.getStats()")}}.
+The type of stats can further be differentiated using the {{domxref("RTCVideoSourceStats.kind", "kind")}}, which will be `video` for `RTCVideoSourceStats`.
+
+## Value
+
+A string with the value `media-source`.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}