RTCAudioSourceStats

Baseline 2023 *

Newly available

Since ⁨May 2023⁩, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Some parts of this feature may have varying levels of support.

TheRTCAudioSourceStats dictionary of theWebRTC API provides statistics information about an audio track (MediaStreamTrack) that is attached to one or more senders (RTCRtpSender).

These statistics can be obtained by iterating theRTCStatsReport returned byRTCRtpSender.getStats() orRTCPeerConnection.getStats() until you find a report with thetype ofmedia-source and akind ofaudio.

Note:For audio information about remotely sourced tracks (that are being received), seeRTCInboundRtpStreamStats.

Instance properties

audioLevelExperimentalOptional: A number that represents the audio level of the media source.
totalAudioEnergyExperimentalOptional: A number that represents the total audio energy of the media source over the lifetime of the stats object.
totalSamplesDurationExperimentalOptional: A number that represents the total duration of all samples produced by the media source over the lifetime of the stats object.

Common media-source properties

The following properties are present in bothRTCAudioSourceStats andRTCVideoSourceStats:

trackIdentifier: A string that contains theid value of theMediaStreamTrack associated with the audio source.
kind: A string indicating whether this object represents stats for a video source or a media source. For anRTCAudioSourceStats this will always beaudio.

Common instance properties

The following properties are common to all statistics objects.

id: A string that uniquely identifies the object that is being monitored to produce this set of statistics.
timestamp: ADOMHighResTimeStamp object indicating the time at which the sample was taken for this statistics object.
type: A string with the value"media-source", indicating that the object is an instance of eitherRTCAudioSourceStats orRTCVideoSourceStats.

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 asaudioLevel using the following formula:

\sqrt{\frac{totalAudioEnergy}{totalSamplesDuration}} \sqrt{\frac{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, wheresample_level is the level of the sample,max_level is the highest-intensity encodable value, andduration is the duration of the sample in seconds:

duration \times {(\frac{sample_level}{max_level})}^{2} duration \times⁢ \left(\left(\right. \frac{sample{\_}level}{max{\_}level} \left.\right)\right)^{2}

The average audio level between any two differentgetStats() calls, over any duration, can be calculated using the following equation:

\sqrt{\frac{{totalAudioEnergy}_{2} - {totalAudioEnergy}_{1}}{{totalSamplesDuration}_{2} - {totalSamplesDuration}_{1}}} \sqrt{\frac{\left(totalAudioEnergy\right)_{2} - \left(totalAudioEnergy\right)_{1}}{\left(totalSamplesDuration\right)_{2} - \left(totalSamplesDuration\right)_{1}}}

Examples

This example shows how you might iterate the stats object returned fromRTCRtpSender.getStats() to get the audio source stats, and then extract theaudioLevel.

// where sender is an RTCRtpSenderconst 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;