-
Notifications
You must be signed in to change notification settings - Fork 22.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update WebRTC media source stats (#32538)
* RTCAudioSourceStats - make consistent, improve docs on kind property, mark optional audio source stats * RTCVideoSourceStats - draft * Add remainder of Video source updates * Add spec-urls for audiosource and videosource * Make kind consistent * Fix missing frames case * Update files/en-us/web/api/rtcvideosourcestats/framespersecond/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/rtcvideosourcestats/framespersecond/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/rtcvideosourcestats/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Apply suggestions from code review * Update files/en-us/web/api/rtcvideosourcestats/index.md * Improve conditional comment a'la wbamberg suggestion * Update files/en-us/web/api/rtcvideosourcestats/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> --------- Co-authored-by: wbamberg <will@bootbonnet.ca>
- Loading branch information
1 parent
0a3268b
commit d32ba6a
Showing
18 changed files
with
408 additions
and
11 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| --- | ||
| title: "RTCVideoSourceStats: frames property" | ||
| short-title: frames | ||
| slug: Web/API/RTCVideoSourceStats/frames | ||
| page-type: web-api-instance-property | ||
| browser-compat: api.RTCStatsReport.type_media-source.frames | ||
| --- | ||
|
|
||
| {{APIRef("WebRTC")}} | ||
|
|
||
| The **`frames`** property of the {{domxref("RTCVideoSourceStats")}} dictionary indicates the total number of frames originating from this video source over its lifetime. | ||
|
|
||
| ## Value | ||
|
|
||
| A number indicating the total number of frames originating from this source. | ||
|
|
||
| ## 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 `frames`. | ||
|
|
||
| ```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; | ||
| } | ||
| }); | ||
|
|
||
| const frames = videoSourceStats?.frames; | ||
| ``` | ||
| ## Specifications | ||
| {{Specifications}} | ||
| ## Browser compatibility | ||
| {{Compat}} |
46 changes: 46 additions & 0 deletions
46
files/en-us/web/api/rtcvideosourcestats/framespersecond/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 originating 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 originating 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 in case the stats object | ||
| // does not include video source stats | ||
| const fps = videoSourceStats?.framesPerSecond; | ||
| ``` | ||
| ## Specifications | ||
| {{Specifications}} | ||
| ## Browser compatibility | ||
| {{Compat}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| --- | ||
| title: "RTCVideoSourceStats: height property" | ||
| short-title: height | ||
| slug: Web/API/RTCVideoSourceStats/height | ||
| page-type: web-api-instance-property | ||
| browser-compat: api.RTCStatsReport.type_media-source.height | ||
| --- | ||
|
|
||
| {{APIRef("WebRTC")}} | ||
|
|
||
| The **`height`** property of the {{domxref("RTCVideoSourceStats")}} dictionary indicates the height, in pixels, of the last frame originating from this source. | ||
|
|
||
| This property is not defined on the stats object until after the first frame has been produced. | ||
|
|
||
| ## Value | ||
|
|
||
| A positive number indicating the height, in pixels. | ||
|
|
||
| ## 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 `height`. | ||
|
|
||
| ```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 in case the stats object | ||
| // does not include video source stats | ||
| const height = videoSourceStats?.height; | ||
| ``` | ||
| ## Specifications | ||
| {{Specifications}} | ||
| ## Browser compatibility | ||
| {{Compat}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| --- | ||
| title: RTCVideoSourceStats | ||
| slug: Web/API/RTCVideoSourceStats | ||
| page-type: web-api-interface | ||
| browser-compat: api.RTCStatsReport.type_media-source | ||
| spec-urls: https://w3c.github.io/webrtc-stats/#dom-rtcvideosourcestats | ||
| --- | ||
|
|
||
| {{APIRef("WebRTC")}} | ||
|
|
||
| The **`RTCVideoSourceStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics information about a video track ({{domxref("MediaStreamTrack")}}) that is attached to one or more senders ({{domxref("RTCRtpSender")}}). | ||
|
|
||
| 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")}} {{optional_inline}} | ||
| - : A positive number that indicates the total number of frames originating from this video source. | ||
| - {{domxref("RTCVideoSourceStats.framesPerSecond", "framesPerSecond")}} {{optional_inline}} | ||
| - : A positive number that represents the number of frames originating from this video source in the last second. | ||
| This property is not defined on this stats object for the first second of its existence. | ||
| - {{domxref("RTCVideoSourceStats.height", "height")}} {{optional_inline}} | ||
| - : A number that represents the height, in pixels, of the last frame originating from this source. | ||
| This property is not defined on this stats object until after the first frame has been produced. | ||
| - {{domxref("RTCVideoSourceStats.width", "width")}} {{optional_inline}} | ||
| - : A number that represents the width, in pixels, of the most recent frame originating from this source. | ||
| This property is not defined on this stats object until after the first frame has been produced. | ||
|
|
||
| ### Common media-source properties | ||
|
|
||
| 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 video source. | ||
| - {{domxref("RTCVideoSourceStats.kind", "kind")}} | ||
| - : A string indicating whether this object represents stats for a video source or a 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 a video media source attached to one or more senders. | ||
| The information includes a identifier for the associated `MediaStreamTrack`, along with the height and width of the last frame sent from the source, the number of frames sent from the source, and the frame rate. | ||
|
|
||
| ## Examples | ||
|
|
||
| This example shows how you might iterate the stats object returned from `RTCRtpSender.getStats()` to get the video-specific media-source stats. | ||
|
|
||
| ```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; | ||
| } | ||
| }); | ||
|
|
||
| // videoSourceStats will be null if the report did not include video source stats | ||
| const frames = videoSourceStats?.frames; | ||
| const fps = videoSourceStats?.framesPerSecond; | ||
| const width = videoSourceStats?.width; | ||
| const height = videoSourceStats?.height; | ||
| ``` | ||
| ## Specifications | ||
| {{Specifications}} | ||
| ## Browser compatibility | ||
| {{Compat}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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}} |
27 changes: 27 additions & 0 deletions
27
files/en-us/web/api/rtcvideosourcestats/timestamp/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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}} |
Oops, something went wrong.