RTCPeerConnection Documentation

RTCPeerConnection.js is a js-wrapper library for RTCWeb APIs.

It not only simplifies coding but also handles complex cross browser implementations.

<script src="https://www.webrtc-experiment.com/RTCPeerConnection-v1.5.js"></script>

RTCPeerConnection object's structure looks like this:

var peer = RTCPeerConnection(configuration);

Actually you're calling a method; and passing some data over it; and that's it!

configuration is an object contains a few properties and methods:

var configuration = {
    attachStream: MediaStream,
    attachStreams: [MediaStream_1, MediaStream_2, MediaStream_3],
	
    offerSDP: offerSDP_sent_from_offerer,

    onICE: function (candidate) {},
    onRemoteStream: function (stream) {},
    onRemoteStreamEnded: function (stream) {},

    onOfferSDP: function (offerSDP) {},
    onAnswerSDP: function (answerSDP) {},

    onChannelMessage: function (event) {},
    onChannelOpened: function (_RTCDataChannel) {}
};

=

attachStream

The MediaStream you want to attach. To understand it better; RTCPeerConnection will use it like this:

var configuration = {
    attachStream: MediaStream
};

=

attachStreams

You can attach multiple streams too; see this demo.

var configuration = {
    attachStreams: [screenStream, audioStream, videoStream]
};

=

offerSDP

This object is only useful for answerer. As soon as you'll receive offer sdp sent by offerer; use that offer sdp like this:

configuration.offerSDP = offerSDP_sent_by_offerer;

Where offerSDP_sent_by_offerer MUST be an object and MUST look like this:

{
    type: 'offer',
    sdp: '.........offerer sdp.........'
}

=

onICE

RTCPeerConnection will call this method on each new ICE candidate. RTCPeerConnection will pass RTCIceCandidate object over this method:

onICE: function (_RTCIceCandidate) {
    // _RTCIceCandidate.candidate
    // _RTCIceCandidate.sdpMLineIndex
    // etc.
};

You can use SIP or any other signaling method to send these ICE candidates on the other end.

=

onRemoteStream

RTCPeerConnection will call this method as soon as peer.onaddstream event will fire. RTCPeerConnection will pass RemoteStream object over this method:

onRemmoteSteam: function (remoteMediaStream) {
    // if(moz) remoteVideo.mozSrcObject = remoteMediaStream;
    // if(!moz) remoteVideo.src = window.webkitURL.createObjectURL(remoteMediaStream);
}

=

onRemoteStreamEnded

It is fired when remote stream stops flowing.

onRemoteStreamEnded: function (remoteMediaStream) {
    // var video = document.getElementById(remoteMediaStream.id);
    // if(video) video.parentNode.removeChild(video);
}

=

onOfferSDP

RTCPeerConnection will call this method after successfully creating offer SDP. An object of type RTCSessionDescription will be passed over this method:

onOfferSDP: function (offerSDP) {
    // offerSDP.type === 'offer'
    // offerSDP.sdp
    // to POST using XHR: JSON.stringify(offerSDP)
}

Pass offer sdp on the answerer's side using your own preferred signaling method.

=

onAnswerSDP

RTCPeerConnection will call this method after successfully creating answer SDP. An object of type RTCSessionDescription will be passed over this method:

onAnswerSDP: function (answerSDP) {
    // answerSDP.type === 'answer'
    // answerSDP.sdp
    // to POST using XHR: JSON.stringify(answerSDP)
}

Pass answer sdp on the offerer's side using your own preferred signaling method.

=

onChannelMessage

Pass this method only if you want to create/open (cross browser RTC) data channels to share data/text or files.

RTCPeerConnection object will call this method as soon as new data-message will be received over SCTP or RTP data ports.

onChannelMessage: function (event) {
    // to get data:	event.data
    // on chrome: JSON.parse(event.data)
}

=

onChannelOpened

RTCPeerConnection object will call this method as soon as SCTP/RTP data ports will successfully get open.

onChannelOpened: function (channel) {
    // channel.send('hi there, data ports are ready to transfer data');
}

=

Public instance methods

RTCPeerConnection object has some public methods/objects that can be used/called later.

var peer = RTCPeerConnection(configuration);

You can use peer object to call/use those instance methods.

=

Add ICE candidates

As soon as you'll receive ICE candidate sent by other peer; add it like this:

peer.addICE({
    sdpMLineIndex: websocketMessage.sdpMLineIndex,
    candidate: websocketMessage.candidate
});

=

Add Answer SDP

Whenever offerer will receive answer sdp sent by answerer; add that answer sdp like this:

peer.addAnswerSDP(answerSDP);

Where answerSDP must look like this:

{
    type: 'answer',
    sdp: ''
}

=

Send data/text/file over RTCDataChannel

On Firefox, you can send files directly; because Firefox supports binaryType for RTCDataChannel.

On Chrome, binaryType will be supported soon.

You can send text message like this:

peer.sendData('hi there, I am a text message');

/* to send an object */
var object = {
    number: 0123456789,
    string: 'just a string',
    object: {},
    array: [],
    _function: function() {}
};
var stringified = JSON.stringify(object);
peer.sendData(stringified);

You can send same text message like this too:

peer.channel.send(hi there, I am a text message');

Where channel is RTCDataChannel object.

On Firefox, you can send file directly like this:

peer.sendData(file);
// or otherwise: 
// peer.channel.send(file);

You can access [webkit|moz]RTCPeerConnection object too to add additional events or do extra stuff:

var rtcPeerConnection = peer.peer;
// rtcPeerConnection.getLocalStreams()[0].stop()
// rtcPeerConnection.getAudioTracks()
// rtcPeerConnection.getVideoTracks()

=

Catching RTCDataChannel Errors

To get alerted whenever a data port closes or throws an error message:

var configuration = {
    onChannelClosed: function (event) {},
    onChannelError: function (event) {}
};

=

getUserMedia

This js-wrapper for RTCWeb API file also contains a cross-browser getUserMedia function.

getUserMedia(mediaConfiguration);

Where mediaConfiguration object looks like this:

var mediaConfiguration = {
    video: HTMLAudioElement || HTMLVideoElement,
    constraints: {},
    onsuccess: function (localMediaStream) {},
    onerror: function (event) {}
};

Only onsuccess is mandatory. All other three are optional.

You can pass video element to play it as soon as navigator.getUserMedia API will give access to LocalMediaStream.

constraints object is very useful when applying custom constraints.

For example to capture screen in Google Chrome Canary:

var screen_constraints = {
    mandatory: {
        chromeMediaSource: 'screen'
    },
    optional: []
};

var mediaConfiguration = {
    constraints: {
        audio: false, /* MUST be false! */
        video: screen_constraints
    }
};

=

STUN/TURN servers and customization

RTCPeerConnection object uses STUN by default.

To understand it better; see how it is using STUN server:

var STUN = {
    iceServers: [{
        url: !moz ? 'stun:stun.l.google.com:19302' : 'stun:23.21.150.121'
    }]
};

On chrome; it is using: stun:stun.l.google.com:19302

And on Firefox; it is using: stun:23.21.150.121

RTCPeerConnection object will use this TURN server:

var TURN = {
    iceServers: [{
        url: 'turn:webrtc%40live.com@numb.viagenie.ca',
        credential: 'muazkh'
    }]
};

=

You MUST keep in mind that...

1. TURN is not yet implemented in Firefox.
2. RTCDataChannel is not yet interoperable
3. Old Firefox sometimes fails on non-DNS STUN servers

=

How to use RTCPeerConnection?

Here is a simple, step-by-step guide that not only explains how to exchange SDP/ICE but also explains "How to write a realtime one-to-one WebRTC video chatting app using socket.io or WebSockets".

In each WebRTC session; there are two circumstances:

1. One party creates offer
2. One party creates answer

You just need to exchange offer and answer between them using your preferable signaling method like XHR/socket.io/WebSockets/etc.

=

History

1. RTCPeerConnection-v1.5.js
2. RTCPeerConnection-v1.4.js
3. RTCPeerConnection-v1.3.js
4. RTCPeerConnection-v1.2.js
5. RTCPeerConnection-v1.1.js
6. RTCPeerConnection.js

=

License

RTCPeerConnection.js is released under MIT licence . Copyright (c) 2013 Muaz Khan.