Fork me on GitHub

rtc-quickconnect

This is a high level helper module designed to help you get up an running with WebRTC really, really quickly. By using this module you are trading off some flexibility, so if you need a more flexible configuration you should drill down into lower level components of the rtc.io suite. In particular you should check out rtc.

NPM

Build Status unstable rtc.io google group

Example Usage

In the simplest case you simply call quickconnect with a single string argument which tells quickconnect which server to use for signaling:

var quickconnect = require('rtc-quickconnect');

quickconnect('https://switchboard.rtc.io/', { room: 'qc-simple-demo' })
  .on('call:started', function(id, pc, data) {
    console.log('we have a new connection to: ' + id);
  });

Events

The following events are emitted from the signalling object created by calling quickconnect(). Additionally, any of the underlying signaller events can also be used.

Peer Level Events

The peer level events provided in quickconnect provide you the ability to tap into the various stages of the lifecycle for connecting with a peer, before the connection actually migrates to the status of a connected "call".

Call Level Events

A "call" in quickconnect is equivalent to an established RTCPeerConnection between this quickconnect instance a remote peer.

Data Channel Level Events

Stream Level Events

Example Usage (using data channels)

When working with WebRTC data channels, you can call the createDataChannel function helper that is attached to the object returned from the quickconnect call. The createDataChannel function signature matches the signature of the RTCPeerConnection createDataChannel function.

At the minimum it requires a label for the channel, but you can also pass through a dictionary of options that can be used to fine tune the data channel behaviour. For more information on these options, I'd recommend having a quick look at the WebRTC spec:

http://dev.w3.org/2011/webrtc/editor/webrtc.html#dictionary-rtcdatachannelinit-members

If in doubt, I'd recommend not passing through options.

var freeice = require('freeice');
var quickconnect = require('rtc-quickconnect');
var opts = {
  room: 'qcexample-dctest',
  // debug: true,
  iceServers: freeice()
};

quickconnect('https://switchboard.rtc.io/', opts)
  // tell quickconnect we want a datachannel called test
  .createDataChannel('test')
  // when the test channel is open, let us know
  .on('channel:opened:test', function(id, dc) {
    dc.onmessage = function(evt) {
      console.log('peer ' + id + ' says: ' + evt.data);
    };

    console.log('test dc open for peer: ' + id);
    dc.send('hi');
  });

Example Usage (using captured media)

Another example is displayed below, and this example demonstrates how to use rtc-quickconnect to create a simple video conferencing application:

var quickconnect = require('rtc-quickconnect');
var crel = require('crel');
var getUserMedia = require('getusermedia');
var attachmediastream = require('attachmediastream');
var qsa = require('fdom/qsa');

// create containers for our local and remote video
var local = crel('div', { class: 'local' });
var remote = crel('div', { class: 'remote' });
var peerMedia = {};

// once media is captured, connect
getUserMedia({ audio: true, video: true }, function(err, localStream) {
  if (err) {
    return console.error('could not capture media: ', err);
  }

  // render the local media
  local.appendChild(attachmediastream(localStream));

  // initiate connection
  quickconnect('https://switchboard.rtc.io/', { room: 'conftest' })
    // broadcast our captured media to other participants in the room
    .addStream(localStream)
    // when a peer is connected (and active) pass it to us for use
    .on('call:started', function(id, pc, data) {
      var videos = pc.getRemoteStreams().map(attachmediastream);
      videos.forEach(function(video) {
        video.dataset.peer = id;
        remote.appendChild(video);
      });
    })
    // when a peer leaves, remove teh media
    .on('call:ended', function(id) {
      qsa('*[data-peer="' + id + '"]', remote).forEach(function(el) {
        el.parentNode.removeChild(el);
      });
    });
});

/* extra code to handle dynamic html and css creation */

// add some basic styling
document.head.appendChild(crel('style', [
  '.local { position: absolute;  right: 10px; }',
  '.local video { max-width: 200px; }'
].join('\n')));

// add the local and remote elements
document.body.appendChild(local);
document.body.appendChild(remote);

Regarding Signalling and a Signalling Server

Signaling is an important part of setting up a WebRTC connection and for our examples we use our own test instance of the rtc-switchboard. For your testing and development you are more than welcome to use this also, but just be aware that we use this for our testing so it may go up and down a little. If you need something more stable, why not consider deploying an instance of the switchboard yourself - it's pretty easy :)

Reference

quickconnect(signalhost, opts?) => rtc-sigaller instance (+ helpers)

Valid Quick Connect Options

The options provided to the rtc-quickconnect module function influence the behaviour of some of the underlying components used from the rtc.io suite.

Listed below are some of the commonly used options:

Write rtc.io suite debug output to the browser console.

Options for Peer Connection Creation

Options that are passed onto the rtc.createConnection function:

This provides a list of ice servers that can be used to help negotiate a connection between peers.

Options for P2P negotiation

Under the hood, quickconnect uses the rtc/couple logic, and the options passed to quickconnect are also passed onto this function.

Quickconnect Broadcast and Data Channel Helper Functions

The following are functions that are patched into the rtc-signaller instance that make working with and creating functional WebRTC applications a lot simpler.

addStream

addStream(stream:MediaStream) => qc

Add the stream to active calls and also save the stream so that it can be added to future calls.

endCalls()

The endCalls function terminates all the active calls that have been created in this quickconnect instance. Calling endCalls does not kill the connection with the signalling server.

close()

The close function provides a convenient way of closing all associated peer connections. This function simply uses the endCalls function and the underlying leave function of the signaller to do a "full cleanup" of all connections.

createDataChannel(label, config)

Request that a data channel with the specified label is created on the peer connection. When the data channel is open and available, an event will be triggered using the label of the data channel.

For example, if a new data channel was requested using the following call:

var qc = quickconnect('https://switchboard.rtc.io/').createDataChannel('test');

Then when the data channel is ready for use, a test:open event would be emitted by qc.

join()

The join function is used when manualJoin is set to true when creating a quickconnect instance. Call the join function once you are ready to join the signalling server and initiate connections with other people.

get(name)

The get function returns the property value for the specified property name.

getLocalStreams()

Return a copy of the local streams that have currently been configured

reactive()

Flag that this session will be a reactive connection.

removeStream

removeStream(stream:MediaStream)

Remove the specified stream from both the local streams that are to be connected to new peers, and also from any active calls.

requestChannel

requestChannel(targetId, label, callback)

This is a function that can be used to respond to remote peers supplying a data channel as part of their configuration. As per the receiveStream function this function will either fire the callback immediately if the channel is already available, or once the channel has been discovered on the call.

requestStream

requestStream(targetId, idx, callback)

Used to request a remote stream from a quickconnect instance. If the stream is already available in the calls remote streams, then the callback will be triggered immediately, otherwise this function will monitor stream:added events and wait for a match.

In the case that an unknown target is requested, then an exception will be thrown.

profile(data)

Update the profile data with the attached information, so when the signaller announces it includes this data in addition to any room and id information.

waitForCall

waitForCall(targetId, callback)

Wait for a call from the specified targetId. If the call is already active the callback will be fired immediately, otherwise we will wait for a call:started event that matches the requested targetId

License(s)

Apache 2.0

Copyright 2015 National ICT Australia Limited (NICTA)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.