RTCAudioSourceStats

The RTCAudioSourceStats dictionary of the WebRTC 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 the RTCStatsReport returned by RTCRtpSender.getStats() or RTCPeerConnection.getStats() until you find a report with the type of media-source and a kind of audio.

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

Instance properties

audioLevel Experimental Optional

A number that represents the audio level of the media source.

totalAudioEnergy Experimental Optional

A number that represents the total audio energy of the media source over the lifetime of the stats object.

totalSamplesDuration Experimental Optional

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 both RTCAudioSourceStats and RTCVideoSourceStats:

trackIdentifier

A string that contains the id value of the MediaStreamTrack associated with the audio source.

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.

id

A string that uniquely identifies the object that is being monitored to produce this set of statistics.

timestamp

A DOMHighResTimeStamp 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 either RTCAudioSourceStats or 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 \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, 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 duration \times⁢ \left(\left(\right. \frac{sample{\_}level}{max{\_}level} \left.\right)\right)^{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 \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 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

Specification
Identifiers for WebRTC's Statistics API
# dom-rtcaudiosourcestats

Browser compatibility

BCD tables only load in the browser