diff --git a/files/en-us/web/api/rtcaudiosourcestats/audiolevel/index.md b/files/en-us/web/api/rtcaudiosourcestats/audiolevel/index.md new file mode 100644 index 000000000000000..6ccd6d877f989fe --- /dev/null +++ b/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}} diff --git a/files/en-us/web/api/rtcaudiosourcestats/id/index.md b/files/en-us/web/api/rtcaudiosourcestats/id/index.md new file mode 100644 index 000000000000000..fcb5401930354d6 --- /dev/null +++ b/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}} diff --git a/files/en-us/web/api/rtcaudiosourcestats/index.md b/files/en-us/web/api/rtcaudiosourcestats/index.md new file mode 100644 index 000000000000000..6f560866a20ee14 --- /dev/null +++ b/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")}}: + +- {{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. + +- {{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: + + + + + totalAudioEnergy + totalSamplesDuration + + + + +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: + + + + duration + ⁢ + + + ( + + sample_level + max_level + + ) + + 2 + + + + +The average audio level between any two different `getStats()` calls, over any duration, can be calculated using the following equation: + + + + + + + totalAudioEnergy + 2 + + - + + totalAudioEnergy + 1 + + + + + totalSamplesDuration + 2 + + - + + totalSamplesDuration + 1 + + + + + + +## 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}} diff --git a/files/en-us/web/api/rtcaudiosourcestats/kind/index.md b/files/en-us/web/api/rtcaudiosourcestats/kind/index.md new file mode 100644 index 000000000000000..cd75502f477851f --- /dev/null +++ b/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}} diff --git a/files/en-us/web/api/rtcaudiosourcestats/timestamp/index.md b/files/en-us/web/api/rtcaudiosourcestats/timestamp/index.md new file mode 100644 index 000000000000000..e3a9e1138fdd74d --- /dev/null +++ b/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}} diff --git a/files/en-us/web/api/rtcaudiosourcestats/totalaudioenergy/index.md b/files/en-us/web/api/rtcaudiosourcestats/totalaudioenergy/index.md new file mode 100644 index 000000000000000..773c9f0ffc063ff --- /dev/null +++ b/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: + + + + duration + ⁢ + + + ( + + sample_level + max_level + + ) + + 2 + + + + +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}} diff --git a/files/en-us/web/api/rtcaudiosourcestats/totalsamplesduration/index.md b/files/en-us/web/api/rtcaudiosourcestats/totalsamplesduration/index.md new file mode 100644 index 000000000000000..ce5a55745ccea77 --- /dev/null +++ b/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. + +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}} diff --git a/files/en-us/web/api/rtcaudiosourcestats/trackidentifier/index.md b/files/en-us/web/api/rtcaudiosourcestats/trackidentifier/index.md new file mode 100644 index 000000000000000..24755a4f38773cb --- /dev/null +++ b/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}} diff --git a/files/en-us/web/api/rtcaudiosourcestats/type/index.md b/files/en-us/web/api/rtcaudiosourcestats/type/index.md new file mode 100644 index 000000000000000..409b3b4db3ef003 --- /dev/null +++ b/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}} diff --git a/files/en-us/web/api/rtcstats/index.md b/files/en-us/web/api/rtcstats/index.md index ae4d3776f04d79c..2024648cc337dcf 100644 --- a/files/en-us/web/api/rtcstats/index.md +++ b/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}} diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index 327b806d17ecdb7..85789dc2537dd2e 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -2035,6 +2035,7 @@ "RTCRemoteOutboundRtpStreamStats", "RTCRtpContributingSourceStats", "RTCPeerConnectionStats", + "RTCAudioSourceStats", "RTCMediaStreamStats", "RTCMediaHandlerStats", "RTCVideoHandlerStats",