5.3 RTCRtpReceiver Interface

The RTCRtpReceiver interface allows an application to inspect the receipt of a MediaStreamTrack.

To create an RTCRtpReceiver with a string, kind, run the following steps:

  1. Let receiver be a new RTCRtpReceiver object.

  2. Let track be a new MediaStreamTrack object [GETUSERMEDIA]. The source of track is a remote source provided by receiver. Note that the track.id is generated by the user agent and does not map to any track IDs on the remote side.

  3. Initialize track.kind to kind.

  4. Initialize track.label to the result of concatenating the string "remote " with kind.

  5. Initialize track.readyState to live.

  6. Initialize track.muted to true. See the MediaStreamTrack section about how the muted attribute reflects if a MediaStreamTrack is receiving media data or not.

  7. Let receiver have a [[ReceiverTrack]] internal slot initialized to track.

  8. Let receiver have a [[ReceiverTransport]] internal slot initialized to null.

  9. Let receiver have a [[LastStableStateReceiverTransport]] internal slot initialized to null.

  10. Let receiver have an [[AssociatedRemoteMediaStreams]] internal slot, representing a list of MediaStream objects that the MediaStreamTrack object of this receiver is associated with, and initialized to an empty list.

  11. Let receiver have a [[LastStableStateAssociatedRemoteMediaStreams]] internal slot and initialize it to an empty list.

  12. Let receiver have a [[ReceiveCodecs]] internal slot, representing a list of RTCRtpCodecParameters dictionaries, and initialized to an empty list.

  13. Let receiver have a [[LastStableStateReceiveCodecs]] internal slot and initialize it to an empty list.

  14. Return receiver.

  1. WebIDL[Exposed=Window]
  2. interface RTCRtpReceiver {
  3.   readonly attribute MediaStreamTrack track;
  4.   readonly attribute RTCDtlsTransport? transport;
  5.   static RTCRtpCapabilities? getCapabilities(DOMString kind);
  6.   RTCRtpReceiveParameters getParameters();
  7.   sequence<RTCRtpContributingSource> getContributingSources();
  8.   sequence<RTCRtpSynchronizationSource> getSynchronizationSources();
  9.   Promise<RTCStatsReport> getStats();
  10. };

Attributes

track of type MediaStreamTrack, readonly

The track attribute is the track that is associated with this RTCRtpReceiver object receiver.

Note that track.stop() is final, although clones are not affected. Since receiver.track.stop() does not implicitly stop receiver, Receiver Reports continue to be sent. On getting, the attribute MUST return the value of the [[ReceiverTrack]] slot.

transport of type RTCDtlsTransport, readonly, nullable

The transport attribute is the transport over which media for the receiver’s track is received in the form of RTP packets. Prior to construction of the RTCDtlsTransport object, the transport attribute will be null. When bundling is used, multiple RTCRtpReceiver objects will share one transport and will all receive RTP and RTCP over the same transport.

On getting, the attribute MUST return the value of the [[ReceiverTransport]] slot.

Methods

getCapabilities, static

The getCapabilities() method returns the most optimistic view of the capabilities of the system for receiving media of the given kind. It does not reserve any resources, ports, or other state but is meant to provide a way to discover the types of capabilities of the browser including which codecs may be supported. User agents MUST support kind values of "audio" and "video". If the system has no capabilities corresponding to the value of the kind argument, getCapabilities returns null.

These capabilities provide generally persistent cross-origin information on the device and thus increases the fingerprinting surface of the application. In privacy-sensitive contexts, browsers can consider mitigations such as reporting only a common subset of the capabilities. (This is a fingerprinting vector.)

Note

The codec capabilities returned affect the setCodecPreferences() algorithm and what inputs it throws InvalidModificationError on, and should also be consistent with information revealed by createOffer() and createAnswer() about codecs negotiated for reception, to ensure any privacy mitigations are effective.

getParameters

The getParameters() method returns the RTCRtpReceiver object’s current parameters for how track is decoded.

When getParameters is called, the RTCRtpReceiveParameters dictionary is constructed as follows:

  • The headerExtensions sequence is populated based on the header extensions that the receiver is currently prepared to receive.

  • codecs is set to the value of the [[ReceiveCodecs]] internal slot.

    Note

    Both the local and remote description may affect this list of codecs. For example, if three codecs are offered, the receiver will be prepared to receive each of them and will return them all from getParameters. But if the remote endpoint only answers with two, the absent codec will no longer be returned by getParameters as the receiver no longer needs to be prepared to receive it.

  • rtcp.reducedSize is set to true if the receiver is currently prepared to receive reduced-size RTCP packets, and false otherwise. rtcp.cname is left out.

getContributingSources

Returns an RTCRtpContributingSource for each unique CSRC identifier received by this RTCRtpReceiver in the last 10 seconds, in descending timestamp order.

getSynchronizationSources

Returns an RTCRtpSynchronizationSource for each unique SSRC identifier received by this RTCRtpReceiver in the last 10 seconds, in descending timestamp order.

getStats

Gathers stats for this receiver only and reports the result asynchronously.

When the getStats() method is invoked, the user agent MUST run the following steps:

  1. Let selector be the RTCRtpReceiver object on which the method was invoked.

  2. Let p be a new promise, and run the following steps in parallel:

    1. Gather the stats indicated by selector according to the stats selection algorithm.

    2. Resolve p with the resulting RTCStatsReport object, containing the gathered stats.

  3. Return p.

The RTCRtpContributingSource and RTCRtpSynchronizationSource dictionaries contain information about a given contributing source (CSRC) or synchronization source (SSRC) respectively. When an audio or video frame from one or more RTP packets is delivered to the RTCRtpReceiver‘s MediaStreamTrack, the user agent MUST queue a task to update the relevant information for the RTCRtpContributingSource and RTCRtpSynchronizationSource dictionaries based on the content of those packets. The information relevant to the RTCRtpSynchronizationSource dictionary corresponding to the SSRC identifier, is updated each time, and if an RTP packet contains CSRC identifiers, then the information relevant to the RTCRtpContributingSource dictionaries corresponding to those CSRC identifiers is also updated. The user agent MUST process RTP packets in order of ascending RTP timestamps. The user agent MUST keep information from RTP packets delivered to the RTCRtpReceiver‘s MediaStreamTrack in the previous 10 seconds.

Note

Even if the MediaStreamTrack is not attached to any sink for playout, getSynchronizationSources and getContributingSources returns up-to-date information as long as the track is not ended; sinks are not a prerequisite for decoding RTP packets.

Note

As stated in the conformance section, requirements phrased as algorithms may be implemented in any manner so long as the end result is equivalent. So, an implementation does not need to literally queue a task for every frame, as long as the end result is that within a single event loop task execution, all returned RTCRtpSynchronizationSource and RTCRtpContributingSource dictionaries for a particular RTCRtpReceiver contain information from a single point in the RTP stream.

  1. WebIDLdictionary RTCRtpContributingSource {
  2.   required DOMHighResTimeStamp timestamp;
  3.   required unsigned long source;
  4.   double audioLevel;
  5.   required unsigned long rtpTimestamp;
  6. };

Dictionary RTCRtpContributingSource Members

timestamp of type DOMHighResTimeStamp, required

The timestamp indicating the most recent time a frame from an RTP packet, originating from this source, was delivered to the RTCRtpReceiver‘s MediaStreamTrack. The timestamp is defined as Performance.timeOrigin + Performance.now() at that time.

source of type unsigned long, required

The CSRC or SSRC identifier of the contributing or synchronization source.

audioLevel of type double

Only present for audio receivers. This is a value between 0..1 (linear), where 1.0 represents 0 dBov, 0 represents silence, and 0.5 represents approximately 6 dBSPL change in the sound pressure level from 0 dBov.

For CSRCs, this MUST be converted from the level value defined in [RFC6465] if the RFC 6465 header extension is present, otherwise this member MUST be absent.

For SSRCs, this MUST be converted from the level value defined in [RFC6464]. If the RFC 6464 header extension is not present in the received packets (such as if the other endpoint is not a user agent or is a legacy endpoint), this value SHOULD be absent.

Both RFCs define the level as an integral value from 0 to 127 representing the audio level in negative decibels relative to the loudest signal that the system could possibly encode. Thus, 0 represents the loudest signal the system could possibly encode, and 127 represents silence.

To convert these values to the linear 0..1 range, a value of 127 is converted to 0, and all other values are converted using the equation: 10^(-rfc_level/20).

rtpTimestamp of type unsigned long, required

The last RTP timestamp, as defined in [RFC3550] Section 5.1, of the media played out at timestamp.

  1. WebIDL          dictionary RTCRtpSynchronizationSource : RTCRtpContributingSource {
  2. };

The RTCRtpSynchronizationSource dictionary is expected to serve as an extension point for the specification to surface data only available in SSRCs.