RTCPeerConnection/README.md
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) {}
};
=
The MediaStream you want to attach. To understand it better; RTCPeerConnection will use it like this:
var configuration = {
attachStream: MediaStream
};
=
You can attach multiple streams too; see this demo.
var configuration = {
attachStreams: [screenStream, audioStream, videoStream]
};
=
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.........'
}
=
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.
=
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);
}
=
It is fired when remote stream stops flowing.
onRemoteStreamEnded: function (remoteMediaStream) {
// var video = document.getElementById(remoteMediaStream.id);
// if(video) video.parentNode.removeChild(video);
}
=
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.
=
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.
=
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)
}
=
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');
}
=
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.
=
As soon as you'll receive ICE candidate sent by other peer; add it like this:
peer.addICE({
sdpMLineIndex: websocketMessage.sdpMLineIndex,
candidate: websocketMessage.candidate
});
=
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: ''
}
=
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()
=
To get alerted whenever a data port closes or throws an error message:
var configuration = {
onChannelClosed: function (event) {},
onChannelError: function (event) {}
};
=
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
}
};
=
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%[email protected]',
credential: 'muazkh'
}]
};
=
TURN is not yet implemented in Firefox.RTCDataChannel is not yet interoperablenon-DNS STUN servers=
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:
You just need to exchange offer and answer between them using your preferable signaling method like XHR/socket.io/WebSockets/etc.
=
=
RTCPeerConnection.js is released under MIT licence . Copyright (c) 2013 Muaz Khan.