RTCMultiConnection Docs

RTCMultiConnection API Reference / "peers" object

"peers" object is a bridge between RTCMultiConnection and RTCPeerConnection API! Scroll bottom to read more about how pure RTCPeerConnection object is exposed and how everything is given in your "own" hands!

"peers" object is "also" useful to renegotiate stream(s) [privately] between two users instead of renegotiating between all conference participants.

To renegotiate screen-media in one-way direction:

connection.peers['user-id'].addStream({
    screen: true,
    oneway: true
});

To renegotiate audio+video in two-way direction:

connection.peers['user-id'].addStream({
    audio: true,
    video: true
});

"peers" object exposes another most useful method, named: "renegotiate".

This method is useful to renegotiate peer connection without appending extra media streams. For example; to hold/unhold audio/video tracks by changing single word in the SDP.

If connection is dropped out of network issues; or out of huge CPU usage; then you can call same method to re-establish peer connection:

connection.peers['user-id'].renegotiate();

If you want to forward remote media stream to an existing peer connection:

connection.onstream = function(e) {
    if(e.type === 'remote') {
        connection.peers['user-id'].renegotiate(e.stream);
    }
};

"peers" object also exposes main "Peer" object; which gives you full control over following functionalities:

  1. Manually create/recreate offer/answer descriptions.
  2. Add extra/external ICE candidates.
  3. Get local/remote session descriptions.
  4. Invoke "getStats" API to analyze peer connection for bandwidth usage and the medium of the connection.
  5. Create many data channels using single peer connection.

And all those things, that you can do using purse browser-based RTCPeerConnection API!

// it is either webkitRTCPeerConnection or mozRTCPeerConnection
var rtcPeerConnection = connection.peers['user-id'].peer.connection;
rtcPeerConnection.addIceCandidate('your-custom-ice-candidate');

var localStreams  = rtcPeerConnection.getLocalStreams();
var remoteStreams = rtcPeerConnection.getRemoteStreams();

var localSDP  = rtcPeerConnection.localDescription;
var remoteSDP = rtcPeerConnection.remoteDescription;

rtcPeerConnection.getStats(function() { 
    // iterate over "stats" API!
});

You can append custom media streams and renegotiate!

connection.peers['user-id'].peer.connection.addStream(Your_Custom_MediaStream);
connection.peers['user-id'].renegotiate();

// above two lines are identical to following single line!
connection.peers['user-id'].renegotiate( Your_Custom_MediaStream );

Above code snippet is playing directly with pure RTCPeerConnection API!

You can create data channels using pure RTCPeerConnection API:

var rtcPeerConnection = connection.peers['user-id'].peer.connection;

var channel = rtcPeerConnection.creatDataChannel('channel-name', {});
rtcPeerConnection.ondatachannel = function(event) {
    channel = event.channel;
};

channel.onmessage = function() {};
channel.onopen    = function() {};
channel.onclose   = function() {};
channel.onerror   = function() {};

Above two-snippets were lower-level stuff. You were playing directly with RTCPeerConnection API instead of using RTCMultiConnection API!

You can use RTCMultiConnection API instead, to create data channels:

var rtcMultiConnectionPeer = connection.peers['user-id'].peer;
rtcMultiConnectionPeer.createDataChannel('channel-identifier');

// You can access all data channels using "channels" array
for(var i = 0; i < rtcMultiConnectionPeer.channels.length; i++) {
    rtcMultiConnectionPeer.channels[i].send('hello world!');
}

Lower Level Details

"peers" object exposes three objects and four methods:

  1. var socket = connection.peers['user-id'].socket;
    

    "socket": This object allows you exchange custom data privately between two users using your preferred signaling gateway.

  2. var peer = connection.peers['user-id'].peer;
    

    "peer": This object refers to RTCMultiConnection "Peer" object; which is actually a standalone wrapper object for browser-based RTCPeerConnection API.

    RTCMultiConnection "Peer" object is responsible to create peer connections along with cross-browser data channel; it also gives you full control over renegotiation stuff; etc.

    RTCMultiConnection "Peer" object exposes a "connection" object; which is a reference to pure browser-based RTCPeerConnection object!

    // sub-object of RTCMultiConnection API
    var rtcMultiConnectionPeer = connection.peers['user-id'].peer;
    
    // pure browser-based RTCPeerConnection object
    var rtcPeerConnection = rtcMultiConnectionPeer.connection;
    
  3. var targetUser = connection.peers['user-id'].userid;
    

    "userid": Unique identifier of the user. WebRTC supports "only" two-way handshake; that's why this object is not an array; it is a simple string!

  4. connection.peers['user-id'].addStream({
        audio : true,
        video : true,
        data  : true,
        screen: true
    });
    

    "addStream": This method allows complex renegotiation scenarios between two peers.

  5. connection.peers['user-id'].renegotiate();
    

    "renegotiate": This method allows one-way renegotiation scenarios; useful when you don't want to add extra media streams.

  6. connection.peers['user-id'].changeBandwidth({
        audio: 20,
        video: 30,
        data : 50
    });
    

    "changeBandwidth": This method allows you change bandwidth at runtime! Just make sure that you're not crossing the limit of minimum or maximum allowed bandwidth!

  7. connection.peers['user-id'].sendCustomMessage('custom-message');
    connection.peers['user-id'].onCustomMessage = function(message) {
        console.log('this is a private message', message);
    };
    

    "sendCustomMessage": This method allows you exchange data privately between both users; where your preferred signaling gateway is used to exchange data!

  8. connection.peers['user-id'].drop();
    

    "drop": This method allows you drop call same like skype! It removes all media stream from both users' sides.

  9. // hold call same like skype
    connection.peers['user-id'].hold();
    
    // fired if call is on hold
    connection.onhold = function(e) {
    	// e.mediaElement || e.stream || e.userid || e.streamid
    };
    
    // unhold call same like skype
    connection.peers['user-id'].unhold();
    
    // fired if call is resumed from hold state
    connection.onunhold = function(e) {
    	// e.mediaElement || e.stream || e.userid || e.streamid
    };
    

    "holde and unhold": Same like skype; both methods allows hold/unhold media streams.

Now, removeStream method quickly removes streams and auto renegotiates. You can also call removeStream over peers object:

connection.peers['target-userid'].removeStream( 'stream-id' );

Useful Resources

  1. How to switch streams?
  2. Renegotiation in RTCMultiConnection
  3. connection.peers (hold/unhold/drop/etc.)
  4. connection.addStream
  5. connection.renegotiate

Want to ask a Question?

You can include your email for private conversation!

Latest Updates