Update WebRTC media source stats #32538
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 sent from this video source over its lifetime. | ||
hamishwillee marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Value | ||
|
|
||
| A number indicating the total number of frames from this source. | ||
hamishwillee marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## 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}} | ||
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 from this source in the last second. | ||
wbamberg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## 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 | ||
hamishwillee marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 because the property | ||
| // 'height' does not exist until frames are being produced. | ||
hamishwillee marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 sent from this video source. | ||
| - {{domxref("RTCVideoSourceStats.framesPerSecond", "framesPerSecond")}} {{optional_inline}} | ||
| - : A number that represents the number of frames sent 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 positive number that represents the height, in pixels, of the last frame originating from this source. | ||
hamishwillee marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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 thewidth, in pixels, of the last frame originating from this source. | ||
hamishwillee marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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; | ||
| } | ||
| }); | ||
|
|
||
| // framesPerSecond, width, height, may initially be defined on the stats object | ||
| const frames = videoSourceStats.frames; | ||
| const fps = videoSourceStats?.framesPerSecond; | ||
| const width = videoSourceStats?.width; | ||
| const height = videoSourceStats?.height; | ||
hamishwillee marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ``` | ||
|
|
||
| ## 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}} |
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.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can't comment on the line, but the spec URL is wrong for this, it is https://w3c.github.io/webrtc-stats/#dom-rtcstatstype-media-source but should be something like https://w3c.github.io/webrtc-stats/#dom-rtcaudiosourcestats.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This was because the
media-source"type" is shared by both audio and video objects, and this is how the items are sorted in BCD. I added aspec-urlsfrontmatter for video and audio to fix this.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do you also need that for the individual members? And this looks like a systemic issue, e.g. https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnectionStats#specifications
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@wbamberg Whlle it is "systemic" I am fairly sure we don't need to panic about this.
Taking
RTCPeerConnectionStatsas an example, this links to https://w3c.github.io/webrtc-stats/#dom-rtcstatstype-peer-connection. This is the top level enum description for the type, which is used for searching. BUT, since all types exceptmedia-sourcemap 1:1 with a stats object, the text usefully explains a particular stats object and links direct to the object itself.I don't think that needs to be fixed. But if you do, we could fix in the same way (I'd prefer not to mess with BCD because I think it would be harder).
The individual members should be fine.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah I agree that setting spec-url is easier. I think it is wrong to link to the enum type but don't care much, since we don't AFAIK have particularly precise policies for what to link to in spec URLs.