replaceTrack() replaces the track currently being used as the sender's source with a new
MediaStreamTrack. The new track must be of the same media kind (audio, video, etc) and switching the track should not require negotiation.
Among the use cases for
replaceTrack() is the common need to switch between the rear- and front-facing cameras on a phone. With
replaceTrack(), you can simply have a track object for each camera and switch between the two as needed. See the example Switching cameras below.
trackReplacedPromise = sender.replaceTrack(newTrack);
MediaStreamTrackspecifying the track with which to replace the
RTCRtpSender's current source track. The new track's
kindmust be the same as the current track's, or the replace track request will fail.
Promise which is fulfilled once the track has been successfully replaced. The promise is rejected if the track cannot be replaced for any reason; this is commonly because the change would require renegotiation of the codec, which is not allowed (see Things that require negotiation).
newTrack was omitted or was
replaceTrack() simply stops the sender. No negotiation is required in this case.
When the promise is fulfilled, the fulfillment handler receives a value of
If the returned promise is rejected, one of the following exceptions is provided to the rejection handler:
- Replacing the
RTCRtpSender's current track with the new one would require negotiation.
- The track on which this method was called is stopped rather than running.
- The new track's
kinddoesn't match the original track.
Things that trigger negotiation
Not all track replacements require renegotiation. In fact, even changes that seem huge can be done without requiring negotation. Here are the changes that can trigger negotiaton:
- The new track has a resolution which is outside the bounds of the bounds of the current track; that is, the new track is either wider or taller than the current one.
- The new track's frame rate is high enough to cause the codec's block rate to be exceeded.
- The new track is a video track and its raw or pre-encoded state differs from that of the original track.
- The new track is an audio track with a different number of channels fom the original.
- Media sources that have built-in encoders — such as hardware encoders — may not be able to provide the negotiated codec. Software sources may not implement the negotiated codec.
|WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCRtpSender.replaceTrack()' in that specification.