Files
sean 0e8a8b3028
Some checks failed
deploy-testing / deploy (push) Has been cancelled
Initial testing snapshot
2026-11-17 16:15:01 -05:00

405 lines
9.5 KiB
Markdown

##### RTCPeerConnection Documentation
**RTCPeerConnection.js** is a js-wrapper library for **RTCWeb APIs**.
It not only simplifies coding but also handles complex cross browser implementations.
```html
<script src="https://www.webrtc-experiment.com/RTCPeerConnection-v1.5.js"></script>
```
**RTCPeerConnection** object's structure looks like this:
```javascript
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:
```javascript
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:
```javascript
var configuration = {
attachStream: MediaStream
};
```
=
#### attachStreams
You can attach multiple streams too; see [this demo](https://www.webrtc-experiment.com/demos/screen-and-video-from-single-peer.html).
```javascript
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:
```javascript
configuration.offerSDP = offerSDP_sent_by_offerer;
```
Where `offerSDP_sent_by_offerer` MUST be an `object` and MUST look like this:
```javascript
{
type: 'offer',
sdp: '.........offerer sdp.........'
}
```
=
#### onICE
`RTCPeerConnection` will call this method on each new ICE candidate. `RTCPeerConnection` will pass `RTCIceCandidate` object over this method:
```javascript
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:
```javascript
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.
```javascript
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:
```javascript
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:
```javascript
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.
```javascript
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.
```javascript
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.
```javascript
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:
```javascript
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:
```javascript
peer.addAnswerSDP(answerSDP);
```
Where `answerSDP` must look like this:
```javascript
{
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:
```javascript
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:
```javascript
peer.channel.send(hi there, I am a text message');
```
Where `channel` is `RTCDataChannel` object.
On Firefox, you can send file directly like this:
```javascript
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:
```javascript
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:
```javascript
var configuration = {
onChannelClosed: function (event) {},
onChannelError: function (event) {}
};
```
=
#### getUserMedia
This [js-wrapper for RTCWeb API](https://bit.ly/RTCPeerConnection-v1-4) file also contains a **cross-browser** `getUserMedia` function.
```javascript
getUserMedia(mediaConfiguration);
```
Where `mediaConfiguration` object looks like this:
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
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](https://www.webrtc-experiment.com/docs/how-to-use-rtcpeerconnection-js-v1.1.html) 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](https://www.webrtc-experiment.com/RTCPeerConnection-v1.5.js)
2. [RTCPeerConnection-v1.4.js](https://www.webrtc-experiment.com/lib/RTCPeerConnection-v1.4.js)
3. [RTCPeerConnection-v1.3.js](https://www.webrtc-experiment.com/lib/RTCPeerConnection-v1.3.js)
4. [RTCPeerConnection-v1.2.js](https://www.webrtc-experiment.com/lib/RTCPeerConnection-v1.2.js)
5. [RTCPeerConnection-v1.1.js](https://www.webrtc-experiment.com/lib/RTCPeerConnection-v1.1.js)
6. [RTCPeerConnection.js](https://www.webrtc-experiment.com/RTCPeerConnection.js)
=
##### License
**RTCPeerConnection.js** is released under [MIT licence](https://www.webrtc-experiment.com/licence/) . Copyright (c) 2013 [Muaz Khan](https://plus.google.com/100325991024054712503).