5.1 RTCPeerConnection Interface Extensions

The RTP media API extends the RTCPeerConnection interface as described below.

WebIDL          partial interface RTCPeerConnection {
  sequence<RTCRtpSender> getSenders();
  sequence<RTCRtpReceiver> getReceivers();
  sequence<RTCRtpTransceiver> getTransceivers();
  RTCRtpSender addTrack(MediaStreamTrack track, MediaStream... streams);
  undefined removeTrack(RTCRtpSender sender);
  RTCRtpTransceiver addTransceiver((MediaStreamTrack or DOMString) trackOrKind,
                                   optional RTCRtpTransceiverInit init = {});
  attribute EventHandler ontrack;
};

Attributes

ontrack of type EventHandler

The event type of this event handler is track.

Methods

getSenders

Returns a sequence of RTCRtpSender objects representing the RTP senders that belong to non-stopped RTCRtpTransceiver objects currently attached to this RTCPeerConnection object.

When the getSenders method is invoked, the user agent MUST return the result of executing the CollectSenders algorithm.

We define the CollectSenders algorithm as follows:

1. Let transceivers be the result of executing the CollectTransceivers algorithm.
2. Let senders be a new empty sequence.
3. For each transceiver in transceivers,
   1. If transceiver.[[Stopped]] is false, add transceiver.[[Sender]] to senders.
4. Return senders.

getReceivers

Returns a sequence of RTCRtpReceiver objects representing the RTP receivers that belong to non-stopped RTCRtpTransceiver objects currently attached to this RTCPeerConnection object.

When the getReceivers method is invoked, the user agent MUST run the following steps:

1. Let transceivers be the result of executing the CollectTransceivers algorithm.
2. Let receivers be a new empty sequence.
3. For each transceiver in transceivers,
   1. If transceiver.[[Stopped]] is false, add transceiver.[[Receiver]] to receivers.
4. Return receivers.

getTransceivers

Returns a sequence of RTCRtpTransceiver objects representing the RTP transceivers that are currently attached to this RTCPeerConnection object.

The getTransceivers method MUST return the result of executing the CollectTransceivers algorithm.

We define the CollectTransceivers algorithm as follows:

1. Let transceivers be a new sequence consisting of all RTCRtpTransceiver objects in this RTCPeerConnection object’s set of transceivers, in insertion order.
2. Return transceivers.

addTrack

Adds a new track to the RTCPeerConnection, and indicates that it is contained in the specified MediaStreams.

When the addTrack method is invoked, the user agent MUST run the following steps:

1. Let connection be the RTCPeerConnection object on which this method was invoked.

2. Let track be the MediaStreamTrack object indicated by the method’s first argument.

3. Let kind be track.kind.

4. Let streams be a list of MediaStream objects constructed from the method’s remaining arguments, or an empty list if the method was called with a single argument.

5. If connection.[[IsClosed]] is true, throw an InvalidStateError.

6. Let senders be the result of executing the CollectSenders algorithm. If an RTCRtpSender for track already exists in senders, throw an InvalidAccessError.

7. The steps below describe how to determine if an existing sender can be reused. Doing so will cause future calls to createOffer and createAnswer to mark the corresponding media description as sendrecv or sendonly and add the MSID of the sender’s streams, as defined in [RFC8829] (section 5.2.2. and section 5.3.2.).

   If any RTCRtpSender object in senders matches all the following criteria, let sender be that object, or null otherwise:

   • The sender’s track is null.

   • The transceiver kind of the RTCRtpTransceiver, associated with the sender, matches kind.

   • The [[Stopping]] slot of the RTCRtpTransceiver associated with the sender is false.

   • The sender has never been used to send. More precisely, the [[CurrentDirection]] slot of the RTCRtpTransceiver associated with the sender has never had a value of “sendrecv“ or “sendonly“.

8. If sender is not null, run the following steps to use that sender:

   1. Set sender.[[SenderTrack]] to track.

   2. Set sender.[[AssociatedMediaStreamIds]] to an empty set.

   3. For each stream in streams, add stream.id to [[AssociatedMediaStreamIds]] if it’s not already there.

   4. Let transceiver be the RTCRtpTransceiver associated with sender.

   5. If transceiver.[[Direction]] is “recvonly“, set transceiver.[[Direction]] to “sendrecv“.

   6. If transceiver.[[Direction]] is “inactive“, set transceiver.[[Direction]] to “sendonly“.

9. If sender is null, run the following steps:

   1. Create an RTCRtpSender with track, kind and streams, and let sender be the result.

   2. Create an RTCRtpReceiver with kind, and let receiver be the result.

   3. Create an RTCRtpTransceiver with sender, receiver and an RTCRtpTransceiverDirection value of “sendrecv“, and let transceiver be the result.

   4. Add transceiver to connection’s set of transceivers.

10. A track could have contents that are inaccessible to the application. This can be due to anything that would make a track CORS cross-origin. These tracks can be supplied to the addTrack() method, and have an RTCRtpSender created for them, but content MUST NOT be transmitted. Silence (audio), black frames (video) or equivalently absent content is sent in place of track content.

    Note that this property can change over time.

11. Update the negotiation-needed flag for connection.

12. Return sender.

removeTrack

Stops sending media from sender. The RTCRtpSender will still appear in getSenders. Doing so will cause future calls to createOffer to mark the media description for the corresponding transceiver as “recvonly“ or “inactive“, as defined in [RFC8829] (section 5.2.2.).

When the other peer stops sending a track in this manner, the track is removed from any remote MediaStreams that were initially revealed in the track event, and if the MediaStreamTrack is not already muted, a mute event is fired at the track.

Note

The same effect as removeTrack() can be achieved by setting the RTCRtpTransceiver.direction attribute of the corresponding transceiver and invoking RTCRtpSender.replaceTrack(null) on the sender. One minor difference is that replaceTrack() is asynchronous and removeTrack() is synchronous.

When the removeTrack method is invoked, the user agent MUST run the following steps:

1. Let sender be the argument to removeTrack.

2. Let connection be the RTCPeerConnection object on which the method was invoked.

3. If connection.[[IsClosed]] is true, throw an InvalidStateError.

4. If sender was not created by connection, throw an InvalidAccessError.

5. Let senders be the result of executing the CollectSenders algorithm.

6. If sender is not in senders (which indicates its transceiver was stopped or removed due to setting a session description of type “rollback“), then abort these steps.

7. If sender.[[SenderTrack]] is null, abort these steps.

8. Set sender.[[SenderTrack]] to null.

9. Let transceiver be the RTCRtpTransceiver object corresponding to sender.

10. If transceiver.[[Direction]] is “sendrecv“, set transceiver.[[Direction]] to “recvonly“.

11. If transceiver.[[Direction]] is “sendonly“, set transceiver.[[Direction]] to “inactive“.

12. Update the negotiation-needed flag for connection.

addTransceiver

Create a new RTCRtpTransceiver and add it to the set of transceivers.

Adding a transceiver will cause future calls to createOffer to add a media description for the corresponding transceiver, as defined in [RFC8829] (section 5.2.2.).

The initial value of mid is null. Setting a session description may later change it to a non-null value.

The sendEncodings argument can be used to specify the number of offered simulcast encodings, and optionally their RIDs and encoding parameters.

When this method is invoked, the user agent MUST run the following steps:

1. Let init be the second argument.

2. Let streams be init.streams.

3. Let sendEncodings be init.sendEncodings.

4. Let direction be init.direction.

5. If the first argument is a string, let it be kind and run the following steps:

   1. If kind is not a legal MediaStreamTrack kind, throw a TypeError.

   2. Let track be null.

6. If the first argument is a MediaStreamTrack, let it be track and let kind be track.kind.

7. If connection.[[IsClosed]] is true, throw an InvalidStateError.

8. Validate sendEncodings by running the following steps:

   1. Verify that each rid value in sendEncodings conforms to the grammar specified in Section 10 of [RFC8851]. If one of the RIDs does not meet these requirements, throw a TypeError.

   2. If any RTCRtpEncodingParameters dictionary in sendEncodings contains a read-only parameter other than rid, throw an InvalidAccessError.

   3. Verify that the value of each scaleResolutionDownBy member in sendEncodings that is defined is greater than or equal to 1.0. If one of the scaleResolutionDownBy values does not meet this requirement, throw a RangeError.

   4. Let maxN be the maximum number of total simultaneous encodings the user agent may support for this kind, at minimum 1.This should be an optimistic number since the codec to be used is not known yet.

   5. If sendEncodings contains any encoding whose scaleResolutionDownBy attribute is defined, set any undefined scaleResolutionDownBy of the other encodings to 1.0.

   6. If the number of RTCRtpEncodingParameters stored in sendEncodings exceeds maxN, then trim sendEncodings from the tail until its length is maxN.

   7. If the scaleResolutionDownBy attribues of sendEncodings are still undefined, initialize each encoding’s scaleResolutionDownBy to 2^(length of sendEncodings - encoding index - 1). This results in smaller-to-larger resolutions where the last encoding has no scaling applied to it, e.g. 4:2:1 if the length is 3.

   8. If the number of RTCRtpEncodingParameters now stored in sendEncodings is 1, then remove any rid member from the lone entry.

      Note

      Providing a single, default RTCRtpEncodingParameters in sendEncodings allows the application to subsequently set encoding parameters using setParameters, even when simulcast isn’t used.

9. Create an RTCRtpSender with track, kind, streams and sendEncodings and let sender be the result.

   If sendEncodings is set, then subsequent calls to createOffer will be configured to send multiple RTP encodings as defined in [RFC8829] (section 5.2.2. and section 5.2.1.). When setRemoteDescription is called with a corresponding remote description that is able to receive multiple RTP encodings as defined in [RFC8829] (section 3.7.), the RTCRtpSender may send multiple RTP encodings and the parameters retrieved via the transceiver’s sender.getParameters() will reflect the encodings negotiated.

10. Create an RTCRtpReceiver with kind and let receiver be the result.

11. Create an RTCRtpTransceiver with sender, receiver and direction, and let transceiver be the result.

12. Add transceiver to connection’s set of transceivers.

13. Update the negotiation-needed flag for connection.

14. Return transceiver.

WebIDLdictionary RTCRtpTransceiverInit {
  RTCRtpTransceiverDirection direction = "sendrecv";
  sequence<MediaStream> streams = [];
  sequence<RTCRtpEncodingParameters> sendEncodings = [];
};

Dictionary RTCRtpTransceiverInit Members

direction of type RTCRtpTransceiverDirection, defaulting to “sendrecv“

The direction of the RTCRtpTransceiver.

streams of type sequence<MediaStream>

When the remote PeerConnection’s track event fires corresponding to the RTCRtpReceiver being added, these are the streams that will be put in the event.

sendEncodings of type sequence<RTCRtpEncodingParameters>

A sequence containing parameters for sending RTP encodings of media.

WebIDLenum RTCRtpTransceiverDirection {
  "sendrecv",
  "sendonly",
  "recvonly",
  "inactive",
  "stopped"
};

5.1.1 Processing Remote MediaStreamTracks

An application can reject incoming media descriptions by setting the transceiver’s direction to either “inactive“ to turn off both directions temporarily, or to “sendonly“ to reject only the incoming side. To permanently reject an m-line in a manner that makes it available for reuse, the application would need to call RTCRtpTransceiver.stop() and subsequently initiate negotiation from its end.

To process remote tracks given an RTCRtpTransceiver transceiver, direction, msids, addList, removeList, and trackEventInits, run the following steps:

1. Set the associated remote streams with transceiver.[[Receiver]], msids, addList, and removeList.

2. If direction is “sendrecv“ or “recvonly“ and transceiver.[[FiredDirection]] is neither “sendrecv“ nor “recvonly“, or the previous step increased the length of addList, process the addition of a remote track with transceiver and trackEventInits.

3. If direction is “sendonly“ or “inactive“, set transceiver.[[Receptive]] to false.

4. If direction is “sendonly“ or “inactive“, and transceiver.[[FiredDirection]] is either “sendrecv“ or “recvonly“, process the removal of a remote track for the media description, with transceiver and muteTracks.

5. Set transceiver.[[FiredDirection]] to direction.

To process the addition of a remote track given an RTCRtpTransceiver transceiver and trackEventInits, run the following steps:

1. Let receiver be transceiver.[[Receiver]].

2. Let track be receiver.[[ReceiverTrack]].

3. Let streams be receiver.[[AssociatedRemoteMediaStreams]].

4. Create a new RTCTrackEventInit dictionary with receiver, track, streams and transceiver as members and add it to trackEventInits.

To process the removal of a remote track with an RTCRtpTransceiver transceiver and muteTracks, run the following steps:

1. Let receiver be transceiver.[[Receiver]].

2. Let track be receiver.[[ReceiverTrack]].

3. If track.muted is false, add track to muteTracks.

To set the associated remote streams given RTCRtpReceiver receiver, msids, addList, and removeList, run the following steps:

1. Let connection be the RTCPeerConnection object associated with receiver.

2. For each MSID in msids, unless a MediaStream object has previously been created with that id for this connection, create a MediaStream object with that id.

3. Let streams be a list of the MediaStream objects created for this connection with the ids corresponding to msids.

4. Let track be receiver.[[ReceiverTrack]].

5. For each stream in receiver.[[AssociatedRemoteMediaStreams]] that is not present in streams, add stream and track as a pair to removeList.

6. For each stream in streams that is not present in receiver.[[AssociatedRemoteMediaStreams]], add stream and track as a pair to addList.

7. Set receiver.[[AssociatedRemoteMediaStreams]] to streams.