Note

    A may become associated with a new pending description in RFC8829 while still being disassociated with the current description. This may happen in check if negotiation is needed.

    The transceiver kind of an is defined by the kind of the associated RTCRtpReceiver‘s object.

    To create an RTCRtpTransceiver with an RTCRtpReceiver object, receiver, object, sender, and an RTCRtpTransceiverDirection value, direction, run the following steps:

    1. Let transceiver be a new object.

    2. Let transceiver have a [[Sender]] internal slot, initialized to sender.

    3. Let transceiver have a [[Receiver]] internal slot, initialized to receiver.

    4. Let transceiver have a [[Stopping]] internal slot, initialized to false.

    5. Let transceiver have a [[Stopped]] internal slot, initialized to false.

    6. Let transceiver have a [[Direction]] internal slot, initialized to direction.

    7. Let transceiver have a [[Receptive]] internal slot, initialized to false.

    8. Let transceiver have a [[CurrentDirection]] internal slot, initialized to null.

    9. Let transceiver have a [[FiredDirection]] internal slot, initialized to null.

    10. Let transceiver have a [[PreferredCodecs]] internal slot, initialized to an empty list.

    11. Let transceiver have a [[JsepMid]] internal slot, initialized to null. This is the “RtpTransceiver mid property” defined in [RFC8829] ( and section 5.3.1.), and is only modified there.

    12. Let transceiver have a [[Mid]] internal slot, initialized to null.

    13. Return transceiver.

    Note

    Creating a transceiver does not create the underlying and RTCIceTransport objects. This will only occur as part of the process of .

    Attributes

    mid of type DOMString, readonly, nullable

    The mid attribute is the negotiated and present in the local and remote descriptions. On getting, the attribute MUST return the value of the [[Mid]] slot.

    sender of type , readonly

    The sender attribute exposes the corresponding to the RTP media that may be sent with mid = [[Mid]]. On getting, the attribute MUST return the value of the slot.

    receiver of type RTCRtpReceiver, readonly

    The attribute is the RTCRtpReceiver corresponding to the RTP media that may be received with mid = . On getting the attribute MUST return the value of the [[Receiver]] slot.

    direction of type

    As defined in [RFC8829] (), the direction attribute indicates the preferred direction of this transceiver, which will be used in calls to createOffer and . An update of directionality does not take effect immediately. Instead, future calls to createOffer and mark the corresponding media description as sendrecv, sendonly, recvonly or inactive as defined in [] (section 5.2.2. and )

    On getting, the user agent MUST run the following steps:

    1. Let transceiver be the RTCRtpTransceiver object on which the getter is invoked.

    2. If transceiver. is true, return “stopped“.

    3. Otherwise, return the value of the slot.

    On setting, the user agent MUST run the following steps:

    1. Let transceiver be the RTCRtpTransceiver object on which the setter is invoked.

    2. Let connection be the object associated with transceiver.

    3. If transceiver.[[Stopping]] is true, an InvalidStateError.

    4. Let newDirection be the argument to the setter.

    5. If newDirection is equal to transceiver., abort these steps.

    6. If newDirection is equal to “stopped“, a TypeError.

    8. for connection.

    currentDirection of type RTCRtpTransceiverDirection, readonly, nullable

    As defined in [] (section 4.2.5.), the currentDirection attribute indicates the current direction negotiated for this transceiver. The value of currentDirection is independent of the value of .active since one cannot be deduced from the other. If this transceiver has never been represented in an offer/answer exchange, the value is null. If the transceiver is , the value is “stopped“.

    On getting, the user agent MUST run the following steps:

    1. Let transceiver be the object on which the getter is invoked.

    2. If transceiver.[[Stopped]] is true, return ““.

    Methods

    stop

    Irreversibly marks the transceiver as stopping, unless it is already . This will immediately cause the transceiver’s sender to no longer send, and its receiver to no longer receive. Calling stop() also for the RTCRtpTransceiver‘s associated .

    A stopping transceiver will cause future calls to to generate a zero port in the for the corresponding transceiver, as defined in [RFC8829] () (The user agent MUST treat a stopping transceiver as for the purposes of RFC8829 only in this case). However, to avoid problems with [RFC8843], a transceiver that is , but not stopped, will not affect .

    A stopped transceiver will cause future calls to createOffer or to generate a zero port in the media description for the corresponding transceiver, as defined in [] (section 4.2.1.).

    The transceiver will remain in the state, unless it becomes stopped by processing a rejected m-line in a remote offer or answer.

    Note

    A transceiver that is stopping but not will always need negotiation. In practice, this means that calling stop() on a transceiver will cause the transceiver to become eventually, provided negotiation is allowed to complete on both ends.

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

    1. Let transceiver be the object on which the method is invoked.

    2. Let connection be the RTCPeerConnection object associated with transceiver.

    3. If connection. is true, throw an .

    4. If transceiver.[[Stopping]] is true, abort these steps.

    5. with transceiver.

    6. Update the negotiation-needed flag for connection.

    The stop sending and receiving algorithm given a transceiver and, optionally, a disappear boolean defaulting to false, is as follows:

    1. Let sender be transceiver..

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

    3. Stop sending media with sender.

    4. Send an RTCP BYE for each RTP stream that was being sent by sender, as specified in [].

    5. Stop receiving media with receiver.

    6. If disappear is false, execute the steps for receiver.[[ReceiverTrack]] to be . This fires an event.

    7. Set transceiver.[[Direction]] to ““.

    8. Set transceiver.[[Stopping]] to true.

    The stop the RTCRtpTransceiver algorithm given a transceiver and, optionally, a disappear boolean defaulting to false, is as follows:

    1. If transceiver. is false, stop sending and receiving with transceiver and disappear.

    2. Set transceiver. to true.

    3. Set transceiver.[[Receptive]] to false.

    4. Set transceiver. to null.

    setCodecPreferences

    The setCodecPreferences method overrides the default codec preferences used by the . When generating a session description using either createOffer or , the user agent MUST use the indicated codecs, in the order specified in the codecs argument, for the media section corresponding to this .

    This method allows applications to disable the negotiation of specific codecs (including RTX/RED/FEC). It also allows an application to cause a remote peer to prefer the codec that appears first in the list for sending.

    Note

    Codecs have their payload types listed under each m= section in the SDP, defining the mapping between payload types and codecs. These payload types are referenced by the m=video or m=audio lines in the order of preference, and codecs that are not negotiated do not appear in this list as defined in section 5.2.1 of [RFC8829]. A previously negotiated codec that is subsequently removed disappears from the m=video or m=audio line, and while its codec payload type is not to be reused in future offers or answers, its payload type may also be removed from the mapping of payload types in the SDP.

    The codecs sequence passed into can only contain codecs that are returned by RTCRtpSender.(kind) or RTCRtpReceiver.(kind), where kind is the kind of the RTCRtpTransceiver on which the method is called. Additionally, the dictionary members cannot be modified. If codecs does not fulfill these requirements, the user agent MUST throw an .

    Note

    Due to a recommendation in [SDP], calls to SHOULD use only the common subset of the codec preferences and the codecs that appear in the offer. For example, if codec preferences are “C, B, A”, but only codecs “A, B” were offered, the answer should only contain codecs “B, A”. However, [RFC8829] () allows adding codecs that were not in the offer, so implementations can behave differently.

    When setCodecPreferences() in invoked, the MUST run the following steps:

    1. Let transceiver be the RTCRtpTransceiver object this method was invoked on.

    2. Let codecs be the first argument.

    3. If codecs is an empty list, set transceiver. to codecs and abort these steps.

    4. Remove any duplicate values in codecs. Start at the back of the list such that the priority of the codecs is maintained; the index of the first occurrence of a codec within the list is the same before and after this step.

    5. Let kind be the transceiver’s transceiver kind.

    6. If the intersection between codecs and .getCapabilities(kind). or the intersection between codecs and RTCRtpReceiver.(kind).codecs only contains RTX, RED or FEC codecs or is an empty set, throw . This ensures that we always have something to offer, regardless of transceiver.direction.

    7. Let codecCapabilities be the union of .getCapabilities(kind). and RTCRtpReceiver.(kind).codecs.

    8. For each codec in codecs,

      1. If codec is not in codecCapabilities, throw .
    9. Set transceiver.[[PreferredCodecs]] to codecs.

    Note

    If set, the offerer’s codec preferences will decide the order of the codecs in the offer. If the answerer does not have any codec preferences then the same order will be used in the answer. However, if the answerer also has codec preferences, these preferences override the order in the answer. In this case, the offerer’s preferences would affect which codecs were on offer but not the final order.

    5.4.1 Simulcast functionality

    Simulcast functionality is provided via the method of the RTCPeerConnection object and the method of the object.

    The method establishes the simulcast envelope which includes the maximum number of simulcast streams that can be sent, as well as the ordering of the encodings. While characteristics of individual simulcast streams can be modified using the method, the simulcast envelope cannot be changed. One of the implications of this model is that the () method cannot provide simulcast functionality since it does not take sendEncodings as an argument, and therefore cannot configure an to send simulcast.

    Another implication is that the answerer cannot set the simulcast envelope directly. Upon calling the method of the RTCPeerConnection object, the is configured on the RTCRtpTransceiver to contain the layers described by the specified session description. Once the envelope is determined, layers cannot be removed. They can be marked as inactive by setting the member to false effectively disabling the layer.

    While setParameters cannot modify the , it is still possible to control the number of streams that are sent and the characteristics of those streams. Using setParameters, simulcast streams can be made inactive by setting the member to false, or can be reactivated by setting the active member to true. Using , stream characteristics can be changed by modifying attributes such as maxBitrate.

    Note

    Simulcast is frequently used to send multiple encodings to an SFU, which will then forward one of the simulcast streams to the end user. The user agent is therefore expected to allocate bandwidth between encodings in such a way that all simulcast streams are usable on their own; for instance, if two simulcast streams have the same , one would expect to see a similar bitrate on both streams. If bandwidth does not permit all simulcast streams to be sent in an usable form, the user agent is expected to stop sending some of the simulcast streams.

    As defined in [RFC8829] (), an offer from a user-agent will only contain a “send” description and no “recv” description on the a=simulcast line. Alternatives and restrictions (described in [RFC8853]) are not supported.

    This specification does not define how to configure reception of multiple RTP encodings using , createAnswer or . However when setRemoteDescription is called with a corresponding remote description that is able to send multiple RTP encodings as defined in [], and the browser supports receiving multiple RTP encodings, the RTCRtpReceiver may receive multiple RTP encodings and the parameters retrieved via the transceiver’s .getParameters() will reflect the encodings negotiated.

    Note

    An can receive multiple RTP streams in a scenario where a Selective Forwarding Unit (SFU) switches between simulcast streams it receives from user agents. If the SFU does not rewrite RTP headers so as to arrange the switched streams into a single RTP stream prior to forwarding, the RTCRtpReceiver will receive packets from distinct RTP streams, each with their own SSRC and sequence number space. While the SFU may only forward a single RTP stream at any given time, packets from multiple RTP streams can become intermingled at the receiver due to reordering. An equipped to receive multiple RTP streams will therefore need to be able to correctly order the received packets, recognize potential loss events and react to them. Correct operation in this scenario is non-trivial and therefore is optional for implementations of this specification.

    5.4.1.1 Encoding Parameter Examples

    This section is non-normative.

    Examples of simulcast scenarios implemented with encoding parameters:

    Example 3

    1. // Example of 3-layer spatial simulcast with all but the lowest resolution layer disabled
    2. var encodings = [
    3.   {rid: 'q', active: true, scaleResolutionDownBy: 4.0}
    4.   {rid: 'f', active: false},
    5. ];

    5.4.2 “Hold” functionality

    This section is non-normative.

    Together, the attribute and the replaceTrack method enable developers to implement “hold” scenarios.

    To send music to a peer and cease rendering received audio (music-on-hold):

    To respond to a remote peer’s “sendonly” offer:

    Example 5

    1. async function handleSendonlyOffer() {
    2.   try {
    3.     // Apply the sendonly offer first,
    4.     // to ensure the receiver is ready for ICE candidates.
    5.     await pc.setRemoteDescription(sendonlyOffer);
    6.     // Stop sending audio
    7.     await audio.sender.replaceTrack(null);
    8.     // Align our direction to avoid further negotiation
    9.     audio.direction = 'recvonly';
    10.     // Call createAnswer and send a recvonly answer
    11.     await doAnswer();
    12.   } catch (err) {
    13.     // handle signaling error
    14.   }
    15. }

    To stop sending music and send audio captured from a microphone, as well to render received audio:

    To respond to being taken off hold by a remote peer:

    1. async function onOffHold() {
    2.   try {
    3.     // Apply the sendrecv offer first, to ensure receiver is ready for ICE candidates.
    4.     await pc.setRemoteDescription(sendrecvOffer);
    5.     // Start sending audio
    6.     await audio.sender.replaceTrack(micTrack);
    7.     // Set the direction sendrecv (just in time for the answer)
    8.     audio.direction = 'sendrecv';
    9.     // Call createAnswer and send a sendrecv answer
    10.     await doAnswer();
    11.   } catch (err) {
    12.     // handle signaling error
    14. }