bredele / peer

WebRTC peer connection made easy

peer

Composable and clean webrtc peer connection.

Installation

$ npm install bredele/peer --save

Usage

initialize a local peer connection with an optional list of servers:

var peer = require('peer');
var master = peer();

create peer connection:

master.create();

API

The following API is entirely private and should only be access through plugins or codecs.

Here's a list of available plugins:

• connect creates local peer-to-peer connection

• signal creates remote peer-to-peer connection
• video attach video stream to a peer-to-peer connection

Here's a list of available codecs:

• rate changes data channel speed/rate limitation
• opus set opus as preferred audio codec

Related projects:

• hangout peer-to-peer video through localtunnel

a plugin can add codecs as well

create

create a peer connection

master.create();

offer

create an offer (initialize a master session description) and set local session description.

master.offer();

A master peer connection is a client which shares a media.

anwer

create an answer (initialize a slave session description) and set local session description.

var slave = peer();
slave.answer();

A slave peer connection is a client (remote or local) which reads a shared media.

local

set local session description

master.local(sdp);

remote

set remote session description

master.local(sdp);

ice

set ice (network) candidate

master.ice(candidate);

stream

add peer local stream

master.stream(stream);

message

send a message through the peer connection

master.send('hello')

a message will be sent through a data channel if initialized by constraints

codec

public interface to set codec on the peer session description.

master.codec(function(sdp) {
  // do something on sdp and return result
});

codecs are session descriptions filters so make sure your codec return the session description.

use

public interface to create plugins.

master.use(function(peer) {
  // do something
});

Concepts

plugins

Peer is not a framework, think of it as the minimum amount of glue necessary to create a peer to peer connection. The beauty part is that it provides a mechanism to compose other modules aka plugins. A plugin is trivial and do one thing but do it well. At the end you can compose your webrtc application, reuse some plugins or create your own and get what you really want.

Oh, and it makes developping a webrtc ridiculously simple. For example, with channel and video you can create a skype-like application in 2 lines:

var skype = peer();
skype.use(video('#id'));
skype.use(channel('chat'));

Peer has been developped to let flourish an ecosystem of plugins.

codecs

A session description (SDP) contains all the information needed to initialize a peer connection. It contains for example the types of media to be exchanged (such as audio, video, data), the network topology, the bandwidth information and other metadata.

A codec in peer is a piece of JavaScript which modifies the session description and therfore the parameters of a peer-to-peer communication. You can for example set opus as the preferred type of audio stream or change the speed limitation or a data channel with rate.

License

The MIT License (MIT)

Copyright (c) 2014 Olivier Wietrich

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

peer's Issues

Peer create is ugly!

peer and media?

Peer initialize a peer connection and is independent from media implementation.

offer/anwer and constraints

'wedge' offer and answer constraints on offer/answer. It makes sense to create a constraint module which merge and format multiple constraints.

peer and plugins

some plugins extend a peer with some functions. For example channel add a send method to send data through a data channel.

peer.send = function(data) {
  channel.send(data);
};

if the channel is not create yet, send will trigger an exception. Is there a way to have something cleaner?
May be send should be in the peer module and emit an event hook.

on add stream

Should it be in peer or in some plugins such as video, audio, etc?

trickle ice

trickle ice allows to accelerate the session handshake by sending ice candidates asynchronously (instead waiting the sdp to be ready). But we should not set the ice candidates until a remote description is set...there is two solutions:

• slow down handshake...bah
• or may be check connection state change on each peer

use and streams

The handler use should accept streams. A good example is channel, the plugin channel should be a duplex stream but we should be able to add it as a plugin to peer.

handle data channel

could be a fake constraint

cleanup

clean events and trigger an event that can be used by plugins.

before offer/answer

Just add hooks 'before offer' and 'after offer'

peer and doors

Some plugins can be asynchronous (like turn for example) and we could add a door in peer for these plugins which trigger a ready event once the door is unlocked. For example we don't want to start a handshake (signal) before we get the turn server information (turn).

peer.to.peer

method to to bind a peer connection to an other one (just event delegation)

offer/answer and session

create a private handler to generate sessions by type ('offer' or 'answer').

Peer and states

Maybe use mood and expose peer states

plugins and modules

record
audio
virus
spider

constraints
detect
morse

rename channel events

create answer/offer after check can trickle

channel plugin and channel emitter

Using a channel emitter would allows us to change the input and output of a data stream.

congestion

Peer.prototype.local = function(session) {
    var sdp = session.sdp;
    var split = sdp.split("b=AS:30");
    if(split.length > 1) {
        sdp = split[0] + "b=AS:1638400" + split[1];
    }
    session.sdp = sdp;
    this.connection.setLocalDescription(new Session(session));
};

we should control the flow and the congestion