Update WebRTC media source stats #32538

hamishwillee · 2024-03-04T06:15:27Z

This updates docs for RTCAudioSourceStats, and adds docs for RTCVideoSourceStats - both of which are type=media-source objects you can get by iterating a RTCStatsReport (differentiating via their kind property).

This is part of the ongoing work to finished RTC stats, which was started in #27028

The changes to Audio source are mostly about API docs consistency.

This has an associated BCD update in mdn/browser-compat-data#22510

github-actions · 2024-03-04T06:16:53Z

Preview URLs (17 pages)

Flaws (7)

Note! 10 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/RTCAudioSourceStats/audioLevel
Title: RTCAudioSourceStats: audioLevel property
Flaw count: 1

macros:
- /en-US/docs/Web/API/RTCInboundRtpStreamStats/audioLevel does not exist

URL: /en-US/docs/Web/API/RTCAudioSourceStats/totalAudioEnergy
Title: RTCAudioSourceStats: totalAudioEnergy property
Flaw count: 1

macros:
- /en-US/docs/Web/API/RTCInboundRtpStreamStats/totalAudioEnergy does not exist

URL: /en-US/docs/Web/API/RTCAudioSourceStats/totalSamplesDuration
Title: RTCAudioSourceStats: totalSamplesDuration property
Flaw count: 1

macros:
- /en-US/docs/Web/API/RTCInboundRtpStreamStats/totalSamplesDuration does not exist

URL: /en-US/docs/Web/API/RTCVideoSourceStats/frames
Title: RTCVideoSourceStats: frames property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.RTCStatsReport.type_media-source.frames

URL: /en-US/docs/Web/API/RTCVideoSourceStats/width
Title: RTCVideoSourceStats: width property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.RTCStatsReport.type_media-source.width

URL: /en-US/docs/Web/API/RTCVideoSourceStats/framesPerSecond
Title: RTCVideoSourceStats: framesPerSecond property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.RTCStatsReport.type_media-source.framesPerSecond

URL: /en-US/docs/Web/API/RTCVideoSourceStats/height
Title: RTCVideoSourceStats: height property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.RTCStatsReport.type_media-source.height

(comment last updated: 2024-03-19 00:00:34)

hamishwillee · 2024-03-05T01:19:59Z

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


 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 `audio`.

 > **Note:** For audio information about remotely sourced tracks (that are being received), see {{domxref("RTCInboundRtpStreamStats")}}.

 ## Instance properties

- {{domxref("RTCAudioSourceStats.audioLevel", "audioLevel")}} {{Experimental_Inline}}
+- {{domxref("RTCAudioSourceStats.audioLevel", "audioLevel")}} {{Experimental_Inline}}{{optional_inline}}


The ones that are not marked required in the IDL have been marked as optional.

… mark optional audio source stats

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

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

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

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

wbamberg · 2024-03-15T17:51:52Z

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

@@ -7,27 +7,29 @@ browser-compat: api.RTCStatsReport.type_media-source

 {{APIRef("WebRTC")}}

-The [WebRTC API](/en-US/docs/Web/API/WebRTC_API)'s **`RTCAudioSourceStats`** dictionary provides information about an audio track that is attached to one or more senders.
+The **`RTCAudioSourceStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics information about an audio track ({{domxref("MediaStreamTrack")}}) that is attached to one or more senders ({{domxref("RTCRtpSender")}}).


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.

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 a spec-urls frontmatter for video and audio to fix this.

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

@wbamberg Whlle it is "systemic" I am fairly sure we don't need to panic about this.

Taking RTCPeerConnectionStats as 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 except media-source map 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.

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.

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

github-actions · 2024-03-18T03:00:40Z

This pull request has merge conflicts that must be resolved before it can be merged.

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

…into media_source

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

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

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

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Co-authored-by: wbamberg <will@bootbonnet.ca>

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

hamishwillee · 2024-03-18T04:17:58Z

@wbamberg Thank you for the review. I think I've fixed this except for the question on optional chaining - please see my response here that I don't think it matters #32538

(If I'm wrong, how would you address this?)

wbamberg · 2024-03-18T05:24:14Z

@wbamberg Thank you for the review. I think I've fixed this except for the question on optional chaining - please see my response here that I don't think it matters #32538

(If I'm wrong, how would you address this?)

If I'm right :) I'd address it with something like:

// Note, test is conditional in case the stats object
// does not include video source stats

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

hamishwillee · 2024-03-18T05:30:19Z

Thanks very much. I must warn you, this is an "easy one" compared to the remote inbound stats :-0. There you have to get your head around who is reporting what.

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

wbamberg · 2024-03-18T19:05:11Z

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

@@ -7,27 +7,29 @@ browser-compat: api.RTCStatsReport.type_media-source

 {{APIRef("WebRTC")}}

-The [WebRTC API](/en-US/docs/Web/API/WebRTC_API)'s **`RTCAudioSourceStats`** dictionary provides information about an audio track that is attached to one or more senders.
+The **`RTCAudioSourceStats`** dictionary of the [WebRTC API](/en-US/docs/Web/API/WebRTC_API) provides statistics information about an audio track ({{domxref("MediaStreamTrack")}}) that is attached to one or more senders ({{domxref("RTCRtpSender")}}).


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

Co-authored-by: wbamberg <will@bootbonnet.ca>

bsmth · 2024-03-19T10:14:35Z

Removing myself from review as Will's got it covered! 😉

hamishwillee · 2024-03-22T00:39:51Z

Ready for you to review when ready @wbamberg - the systemic question, is addressed in #32538 (comment)

wbamberg

👍 thank you Hamish!

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Mar 4, 2024

hamishwillee commented Mar 5, 2024

View reviewed changes

hamishwillee marked this pull request as ready for review March 5, 2024 01:20

hamishwillee requested a review from a team as a code owner March 5, 2024 01:20

hamishwillee requested review from wbamberg and removed request for a team March 5, 2024 01:20

hamishwillee added 3 commits March 5, 2024 12:20

RTCAudioSourceStats - make consistent, improve docs on kind property,…

0003fde

… mark optional audio source stats

RTCVideoSourceStats - draft

0721d9e

Add remainder of Video source updates

6fa2a92

hamishwillee force-pushed the media_source branch from c15eee3 to 6fa2a92 Compare March 5, 2024 01:20

wbamberg requested changes Mar 15, 2024

View reviewed changes

Add spec-urls for audiosource and videosource

6968d9a

hamishwillee requested a review from a team as a code owner March 18, 2024 03:00

hamishwillee requested review from bsmth and removed request for a team March 18, 2024 03:00

github-actions bot added the merge conflicts 🚧 [PR only] label Mar 18, 2024

hamishwillee commented Mar 18, 2024

View reviewed changes

files/en-us/web/api/rtcvideosourcestats/index.md Outdated Show resolved Hide resolved

hamishwillee added 3 commits March 18, 2024 14:09

Make kind consistent

09063a7

Fix missing frames case

839665d

Merge branch 'media_source' of https://github.com/hamishwillee/content …

be1a877

…into media_source

hamishwillee commented Mar 18, 2024

View reviewed changes

files/en-us/web/api/rtcvideosourcestats/frames/index.md Outdated Show resolved Hide resolved

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

a7f7878

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

hamishwillee commented Mar 18, 2024

View reviewed changes

files/en-us/web/api/rtcvideosourcestats/frames/index.md Outdated Show resolved Hide resolved

wbamberg and others added 3 commits March 17, 2024 20:40

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

ada4746

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

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

4009de9

Co-authored-by: wbamberg <will@bootbonnet.ca>

Apply suggestions from code review

4ef125b

hamishwillee commented Mar 18, 2024

View reviewed changes

files/en-us/web/api/rtcvideosourcestats/index.md Outdated Show resolved Hide resolved

hamishwillee added 2 commits March 18, 2024 15:14

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

1d559ce

Merge branch 'main' into media_source

f346f20

github-actions bot removed the merge conflicts 🚧 [PR only] label Mar 18, 2024

hamishwillee requested a review from wbamberg March 18, 2024 04:18

hamishwillee commented Mar 18, 2024

View reviewed changes

files/en-us/web/api/rtcvideosourcestats/width/index.md Outdated Show resolved Hide resolved

Improve conditional comment a'la wbamberg suggestion

6c61039

wbamberg requested changes Mar 18, 2024

View reviewed changes

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

c459884

Co-authored-by: wbamberg <will@bootbonnet.ca>

hamishwillee requested a review from wbamberg March 19, 2024 00:11

bsmth removed their request for review March 19, 2024 10:14

wbamberg approved these changes Mar 22, 2024

View reviewed changes

wbamberg merged commit d32ba6a into mdn:main Mar 22, 2024
10 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update WebRTC media source stats #32538

Update WebRTC media source stats #32538

hamishwillee commented Mar 4, 2024 •

edited

Loading

github-actions bot commented Mar 4, 2024 •

edited

Loading

hamishwillee Mar 5, 2024 •

edited

Loading

wbamberg Mar 15, 2024

hamishwillee Mar 18, 2024

wbamberg Mar 18, 2024

hamishwillee Mar 19, 2024

wbamberg Mar 22, 2024

github-actions bot commented Mar 18, 2024

hamishwillee commented Mar 18, 2024

wbamberg commented Mar 18, 2024

hamishwillee commented Mar 18, 2024

wbamberg Mar 18, 2024

bsmth commented Mar 19, 2024

hamishwillee commented Mar 22, 2024

wbamberg left a comment

Update WebRTC media source stats #32538

Update WebRTC media source stats #32538

Conversation

hamishwillee commented Mar 4, 2024 • edited Loading

github-actions bot commented Mar 4, 2024 • edited Loading

hamishwillee Mar 5, 2024 • edited Loading

Choose a reason for hiding this comment

wbamberg Mar 15, 2024

Choose a reason for hiding this comment

hamishwillee Mar 18, 2024

Choose a reason for hiding this comment

wbamberg Mar 18, 2024

Choose a reason for hiding this comment

hamishwillee Mar 19, 2024

Choose a reason for hiding this comment

wbamberg Mar 22, 2024

Choose a reason for hiding this comment

github-actions bot commented Mar 18, 2024

hamishwillee commented Mar 18, 2024

wbamberg commented Mar 18, 2024

hamishwillee commented Mar 18, 2024

wbamberg Mar 18, 2024

Choose a reason for hiding this comment

bsmth commented Mar 19, 2024

hamishwillee commented Mar 22, 2024

wbamberg left a comment

Choose a reason for hiding this comment

hamishwillee commented Mar 4, 2024 •

edited

Loading

github-actions bot commented Mar 4, 2024 •

edited

Loading

hamishwillee Mar 5, 2024 •

edited

Loading