Add RTCAudioSourceStats (mdn#26667)

* Add RTCAudioSourceStats

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

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

* Apply suggestions from code review

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

* Apply suggestions from code review

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

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

* Add keys for BCD data

* Make it clear that the audiolevel can also be calculated

---------

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

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

@@ -0,0 +1,28 @@
+---
+title: "RTCAudioSourceStats: audioLevel property"
+short-title: audioLevel
+slug: Web/API/RTCAudioSourceStats/audioLevel
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.audioLevel
+---
+
+{{APIRef("WebRTC")}}
+
+The {{domxref("RTCAudioSourceStats")}} dictionary's **`audioLevel`** property represents the audio level of the media source.
+
+The level is averaged over some small implementation-dependent interval.
+Users can alternatively calculate the average audio level over some arbitrary duration using the algorithm described in the [`RTCAudioSourceStats` description](/en-US/docs/Web/API/RTCAudioSourceStats#description).
+
+> **Note:** For audio levels of remotely sourced tracks, see {{domxref("RTCInboundRtpStreamStats.audioLevel")}}.
+
+## Value
+
+A number between 0 and 1 (linear), where 1.0 represents 0 dBov ([decibels relative to full scale (DBFS)](https://en.wikipedia.org/wiki/DBFS)), 0 represents silence, and 0.5 represents approximately 6 dB SPL change in the [sound pressure level](https://en.wikipedia.org/wiki/Sound_pressure#Sound_pressure_level) from 0 dBov.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,26 @@
+---
+title: "RTCAudioSourceStats: id property"
+short-title: id
+slug: Web/API/RTCAudioSourceStats/id
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.id
+---
+
+{{APIRef("WebRTC")}}
+
+The **`id`** property of the {{domxref("RTCAudioSourceStats")}} 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 `RTCAudioSourceStats` object provides statistics.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,140 @@
+---
+title: RTCAudioSourceStats
+slug: Web/API/RTCAudioSourceStats
+page-type: web-api-interface
+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.
+
+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")}}
+ - : A number that represents the audio level of the media source.
+- {{domxref("RTCAudioSourceStats.totalAudioEnergy", "totalAudioEnergy")}}
+ - : A number that represents the total audio energy of the media source over the lifetime of the stats object.
+- {{domxref("RTCAudioSourceStats.totalSamplesDuration", "totalSamplesDuration")}}
+ - : A number that represents the total duration of all samples produced by the media source over the lifetime of the stats object.
+
+The following properties are present in both `RTCAudioSourceStats` and {{domxref("RTCVideoSourceStats")}}: <!-- RTCMediaSourceStats -->
+
+- {{domxref("RTCAudioSourceStats.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("RTCAudioSourceStats.kind", "kind")}}
+ - : A string indicating whether this object represents stats for a video source or a media source. For an `RTCAudioSourceStats` this will always be `audio`.
+
+### Common instance properties
+
+The following properties are common to all statistics objects. <!-- RTCStats -->
+
+- {{domxref("RTCAudioSourceStats.id", "id")}}
+ - : A string that uniquely identifies the object that is being monitored to produce this set of statistics.
+- {{domxref("RTCAudioSourceStats.timestamp", "timestamp")}}
+ - : A {{domxref("DOMHighResTimeStamp")}} object indicating the time at which the sample was taken for this statistics object.
+- {{domxref("RTCAudioSourceStats.type", "type")}}
+ - : A string with the value `"media-source"`, indicating that the object is an instance of either {{domxref("RTCAudioSourceStats")}} or {{domxref("RTCVideoSourceStats")}}.
+
+## Description
+
+The interface provides statistics about an audio media source attached to one or more senders.
+The information includes the current audio level, averaged over a short (implementation dependent) duration.
+
+The statistics also include the accumulated total energy and total sample duration, at a particular timestamp.
+The totals can be used to determine the average audio level over the lifetime of the stats object.
+You can calculate a root mean square (RMS) value in the same units as `audioLevel` using the following formula:
+
+<math display="block">
+<msqrt>
+ <mfrac>
+ <mi>totalAudioEnergy</mi>
+ <mi>totalSamplesDuration</mi>
+ </mfrac>
+</msqrt>
+</math>
+
+You can also use the accumulated totals to calculate the average audio level over an arbitrary time period.
+
+The total audio energy of the stats object is accumulated by adding the energy of every sample over the lifetime of the stats object, while the total duration is accumulated by adding the duration of each sample.
+The energy of each sample is determined using the following formula, where `sample_level` is the level of the sample, `max_level` is the highest-intensity encodable value, and `duration` is the duration of the sample in seconds:
+
+<math display="block">
+<mrow>
+ <mi>duration</mi>
+ <mo>&#x2062;</mo>
+ <msup>
+ <mrow>
+  <mo>(</mo>
+  <mfrac>
+  <mi>sample_level</mi>
+  <mi>max_level</mi>
+  </mfrac>
+  <mo>)</mo>
+ </mrow>
+ <mn>2</mn>
+ </msup>
+</mrow>
+</math>
+
+The average audio level between any two different `getStats()` calls, over any duration, can be calculated using the following equation:
+
+<math display="block">
+<msqrt>
+ <mfrac>
+ <mrow>
+  <msub>
+  <mi>totalAudioEnergy</mi>
+  <mn>2</mn>
+  </msub>
+  <mo>-</mo>
+  <msub>
+  <mi>totalAudioEnergy</mi>
+  <mn>1</mn>
+  </msub>
+ </mrow>
+ <mrow>
+  <msub>
+  <mi>totalSamplesDuration</mi>
+  <mn>2</mn>
+  </msub>
+  <mo>-</mo>
+  <msub>
+  <mi>totalSamplesDuration</mi>
+  <mn>1</mn>
+  </msub>
+ </mrow>
+ </mfrac>
+</msqrt>
+</math>
+
+## Examples
+
+This example shows how you might iterate the stats object returned from `RTCRtpSender.getStats()` to get the audio source stats, and then extract the `audioLevel`.
+
+```js
+// where sender is an RTCRtpSender
+const stats = await sender.getStats();
+let audioSourceStats = null;
+
+stats.forEach((report) => {
+ if (report.type === "media-source" && report.kind==="audio") {
+ audioSourceStats = report;
+ break;
+ }
+});
+
+const audioLevel = audioSourceStats?.audioLevel;
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,25 @@
+---
+title: "RTCAudioSourceStats: kind property"
+short-title: kind
+slug: Web/API/RTCAudioSourceStats/kind
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.kind
+---
+
+{{APIRef("WebRTC")}}
+
+The {{domxref("RTCAudioSourceStats")}} dictionary's **`kind`** property is a string value that is used to differentiate `audio` and `video` media sources.
+
+Along with the {{domxref("RTCAudioSourceStats.type", "type")}}, this identifies the object as an {{domxref("RTCAudioSourceStats")}} object when iterating the {{domxref("RTCStatsReport")}} returned by {{domxref("RTCRtpSender.getStats()")}} or {{domxref("RTCPeerConnection.getStats()")}}.
+
+## Value
+
+A string with the value `audio`.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,27 @@
+---
+title: "RTCAudioSourceStats: timestamp property"
+short-title: timestamp
+slug: Web/API/RTCAudioSourceStats/timestamp
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.timestamp
+---
+
+{{APIRef("WebRTC")}}
+
+The **`timestamp`** property of the {{domxref("RTCAudioSourceStats")}} 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/rtcaudiosourcestats/totalaudioenergy/index.md

@@ -0,0 +1,50 @@
+---
+title: "RTCAudioSourceStats: totalAudioEnergy property"
+short-title: totalAudioEnergy
+slug: Web/API/RTCAudioSourceStats/totalAudioEnergy
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.totalAudioEnergy
+---
+
+{{APIRef("WebRTC")}}
+
+The {{domxref("RTCAudioSourceStats")}} dictionary's **`totalAudioEnergy`** property represents the total audio energy of the media source over the lifetime of this stats object.
+
+The total energy across a particular duration can be determined by subtracting the value of this property returned by two different `getStats()` calls.
+
+> **Note:** For audio energy of remotely sourced tracks, see {{domxref("RTCInboundRtpStreamStats.totalAudioEnergy")}}.
+
+## Value
+
+A number produced by summing the energy of every sample over the lifetime of this stats object.
+
+The energy of each sample is calculated by dividing the sample's value by the highest-intensity encodable value, squaring the result, and then multiplying by the duration of the sample in seconds.
+This is shown as an equation below:
+
+<math display="block">
+<mrow>
+ <mi>duration</mi>
+ <mo>&#x2062;</mo>
+ <msup>
+ <mrow>
+  <mo>(</mo>
+  <mfrac>
+  <mi>sample_level</mi>
+  <mi>max_level</mi>
+  </mfrac>
+  <mo>)</mo>
+ </mrow>
+ <mn>2</mn>
+ </msup>
+</mrow>
+</math>
+
+Note that if multiple audio channels are used, the audio energy of a sample refers to the highest energy of any channel.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,28 @@
+---
+title: "RTCAudioSourceStats: totalSamplesDuration property"
+short-title: totalSamplesDuration
+slug: Web/API/RTCAudioSourceStats/totalSamplesDuration
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.totalSamplesDuration
+---
+
+{{APIRef("WebRTC")}}
+
+The {{domxref("RTCAudioSourceStats")}} dictionary's **`totalSamplesDuration`** property represents the combined duration of all samples produced by the media source over the lifetime of this stats object, in seconds.
+It does not include samples dropped before reaching this media source. <!-- Dropped samples in `droppedSamplesDuration`; not implemented -->
+
+This can be used with {{domxref("RTCAudioSourceStats.totalAudioEnergy", "totalAudioEnergy")}} to compute an [average audio level over different intervals](/en-US/docs/Web/API/RTCAudioSourceStats#description).
+
+> **Note:** For audio duration of remotely sourced tracks, see {{domxref("RTCInboundRtpStreamStats.totalSamplesDuration")}}.
+
+## Value
+
+A number indicating the total duration of all samples produced by this source over the lifetime this stats object, in seconds.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -0,0 +1,23 @@
+---
+title: "RTCAudioSourceStats: trackIdentifier property"
+short-title: trackIdentifier
+slug: Web/API/RTCAudioSourceStats/trackIdentifier
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.trackIdentifier
+---
+
+{{APIRef("WebRTC")}}
+
+The {{domxref("RTCAudioSourceStats")}} dictionary's property **`trackIdentifier`** 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/rtcaudiosourcestats/type/index.md

@@ -0,0 +1,26 @@
+---
+title: "RTCAudioSourceStats: type property"
+short-title: type
+slug: Web/API/RTCAudioSourceStats/type
+page-type: web-api-instance-property
+browser-compat: api.RTCStatsReport.type_media-source.type
+---
+
+{{APIRef("WebRTC")}}
+
+The {{domxref("RTCAudioSourceStats")}} dictionary's property **`type`** 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("RTCAudioSourceStats.kind", "kind")}}, which will be `audio` for `RTCAudioSourceStats`.
+
+## Value
+
+A string with the value `media-source`.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}

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

@@ -38,6 +38,9 @@ The various dictionaries that are used to define the contents of the objects tha
  - {{domxref("RTCOutboundRtpStreamStats")}} contains statistics about the local sending endpoint of an RTP stream.
  - {{domxref("RTCRemoteOutboundRtpStreamStats")}} holds statistics related to the remote sending end an RTP stream.
 
+ - {{domxref("RTCAudioSourceStats")}} contains statistics about audio media sources.
+ - {{domxref("RTCVideoSourceStats")}} contains statistics about video media sources.
+
 ## Specifications
 
 {{Specifications}}

files/jsondata/GroupData.json

@@ -2035,6 +2035,7 @@
  "RTCRemoteOutboundRtpStreamStats",
  "RTCRtpContributingSourceStats",
  "RTCPeerConnectionStats",
+ "RTCAudioSourceStats",
  "RTCMediaStreamStats",
  "RTCMediaHandlerStats",
  "RTCVideoHandlerStats",