RTCPeerConnection.addTrack()

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

The RTCPeerConnection method addTrack() adds a new media track to the connection. The track is added to the set of tracks which will be transmitted to the other peer.

Adding a track to a connection triggers renegotiation by firing an negotiationneeded event.

Syntax

rtpSender = RTCPeerConnection.addTrack(track, stream...);

Parameters

track
A MediaStreamTrack object representing the media track to add to the peer connection.
stream...
One or more MediaStream objects in which the specified track are to be contained.

The specified track doesn't necessarily have to already be part of any of the specified streams. Instead, the streams are simply a way to group tracks together on the receiving end of the connection, making sure they are synchronized.

Return value

The RTCRtpSender object which will be used to transmit the media data.

Exceptions

InvalidAccessError
The specified track is already a member of the set of senders for the RTCPeerConnection.
InvalidStateError
The RTCPeerConnection is closed.

Example

This example is drawn from the code presented in the article Signaling and video calling and its corresponding sample code. It comes from the handleVideoOfferMsg() method there, which is called when an offer message is received from the remote peer.

var mediaConstraints = {
  audio: true,            // We want an audio track
  video: true             // ...and we want a video track
};
var desc = new RTCSessionDescription(sdp);
pc.setRemoteDescription(desc).then(function () {
  return navigator.mediaDevices.getUserMedia(mediaConstraints);
})
.then(function(stream) {
  previewElement.srcObject = stream;
  stream.getTracks().forEach(track => pc.addTrack(track, stream));
})

This code takes SDP which has been received from the remote peer and constructs a new RTCSessionDescription to pass into setRemoteDescription(). Once that succeeds, it uses MediaDevices.getUserMedia() to obtain access to the local webcam and microphone.

If that succeeds, the resulting stream is assigned as the source for a <video> element which is referenced by the variable previewElement.

The final step is to begin sending the local video across the peer connection to the caller. This is done by adding each track in the stream by iterating over the list returned by MediaStream.getTracks() and passing them to addTrack() along with the stream which they're a component of.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.addTrack()' in that specification.		 Working Draft Initial specification.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support No support[1] 45 (45) [2] ? ? ?
Feature Android Webview Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support No support[1] No support[1] 45 (45) ? ? ?

[1] Chrome still uses the deprecated addStream()

[2] Prior to Firefox 49, the specified track was required to be component of all passed MediaStreams. Starting in Firefox 49, this is no longer the case. See bug 1271669 for specifics.

See also

Document Tags and Contributors

Tags: 
 Contributors to this page: Jib, jpmedley, Sheppy
 Last updated by: Jib,