• Stars
    star
    200
  • Rank 195,325 (Top 4 %)
  • Language
    JavaScript
  • Created over 11 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A tiny browser module that gives normalizes and simplifies the API for WebRTC peer connections.

RTCPeerConnection

What is this?

A tiny browser module that normalizes and simplifies the API for WebRTC peer connections.

It gives us a cleaner (cross-browser) way to handle offer/answer and is based on an event emitter.

If you're not using browserify or you want AMD support use rtcpeerconnection.bundle.js.

Installing

npm install rtcpeerconnection

How to use it

Instantiation

Instantiation takes the same options as a normal peer connection constructor:

var PeerConnection = require('rtcpeerconnection');


// init it like a normal peer connection object
// passing in ice servers/constraints the initial server config
// also takes a couple other options:
// debug: true (to log out all emitted events)
var pc = new PeerConnection({config servers as usual}, {constraints as to regular PC});

Events

Unlike stock Peer Connections this inherits from a generic event emitter. Powered by WildEmitter which has a very familiar API if you're used to node.js/jQuery/Backbone but also includes a wildcard handler so you can easily debug events. Just do emitter.on('*') to log them out or whatnot.

But instead of doing pc.onicecandidate = function () {} on a peer connection you listen for events like this:

// ice candidates
pc.on('ice', function (candidate) {
    // it's your job to send these to someone
    connection.send('ice', candidate);
});

// you can listen for end of candidates (not particularly useful)
pc.on('endOfCandidates', function () {
    // no more ice candidates
});

// remote stream added
pc.on('addStream', function (event) {
    // do something with event.stream
    // probably attach it to a <video> element
    // and play it.
});

// remote stream removed
pc.on('removeStream', function (event) {
    // remote stream removed
    // now you could hide/disable removed video
});

// you can chose to listen for events for 
// offers and answers instead, if you prefer 
pc.on('answer', function (err, answer) { ... });
pc.on('offer', function (err, offer) { ... });

// on peer connection close
pc.on('close', function () { ... });

Methods

Note that all callbacks follow the "error first" convention. Meaning, rather than pass a success and fail callback, you pass a single callback.

If there is an error, the first argument passed to the callback will be a truthy value (the error itself).

The whole offer/answer cycle looks like this:

// assumptions
var pc = new PeerConnection(config, constraints);
var connection = new RealTimeConnection(); // could be socket.io or whatever


// create an offer
pc.offer(function (err, offer) {
    if (!err) connection.send('offer', offer)
});

// you can also optionally pass in constraints
// when creating an offer.
pc.offer(
    {
        offerToReceiveAudio: true,
        offerToReceiveVideo: false
    }, 
    function (err, offer) {
        if (!err) connection.send('offer', offer);
    }
);

// when you recieve an offer, you can answer
// with various options
connection.on('offer', function (offer) {
    // let the peerconnection handle the offer
    // by calling handleOffer
    pc.handleOffer(offer, function (err) {
        if (err) {
            // handle error
            return;
        }

        // you can just call answer
        pc.answer(function (err, answer) {
            if (!err) connection.send('answer', answer);
        });

        // you can call answer with contstraints
        pc.answer(MY_CONSTRAINTS, function (err, answer) {
            if (!err) connection.send('answer', answer);
        });    

        // or you can use one of the shortcuts answers

        // for video only
        pc.answerVideoOnly(function (err, answer) { ... });

        // and audio only
        pc.answerAudioOnly(function (err, answer) { ... });
    }); 
});

// when you get an answer, you just call
// handleAnswer
connection.on('answer', function (answer) {
    pc.handleAnswer(answer);
});

// the only other thing you have to do is listen, transmit, and process ice candidates

// you have to send them when generated
pc.on('ice', function (candidate) {
    connection.send('ice', candidate);
});

// process incoming ones
connection.on('ice', function (candidate) {
    pc.processIce(candidate);
});

That's it!

More

If you want higher level functionality look at SimpleWebRTC that uses this library.

License

MIT

Credits

If you like this, follow: @HenrikJoreteg on twitter.

More Repositories

1

hark

Converts an audio stream to speech events in the browser
JavaScript
566
star
2

otalk-im-client

Stanza.io webrtc capable xmpp client <3
JavaScript
306
star
3

getUserMedia

Cross-browser getUserMedia shim with a node.js style error-first API
JavaScript
233
star
4

getScreenMedia

A browser module for attempting to get access to a MediaStream of a user's screen. With a nice node-like API.
JavaScript
154
star
5

restund

Restund. Forked from http://www.creytiv.com/
C
127
star
6

jingle.js

A generic Jingle session manager implementation, suitable for integration by other XMPP libraries.
JavaScript
89
star
7

attachMediaStream

Simple abstraction for handling differences between browsers for attaching a media stream to a video element
JavaScript
48
star
8

iOS-demo

Objective-C
46
star
9

sdp

SDP parsing and serialization utlities
JavaScript
46
star
10

mediastream-gain

A tiny browser module for creating a gain/volume controller for the audio channels in a MediaStream.
JavaScript
44
star
11

webrtc-ios

Objective-C
44
star
12

sdp-jingle-json

A parser/serializer for SDP to JSON. Useful for converting SDP to other formats like Jingle for WebRTC signalling
JavaScript
41
star
13

webrtc-tester

WebRTC Deployment Testing Toolkit
Shell
34
star
14

TLKSimpleWebRTC

Objective-C
28
star
15

jxt

JSON/XML Translation for the Browser
JavaScript
26
star
16

jxt-xmpp

JXT definitions for XMPP
JavaScript
23
star
17

stunturncheck

Check WebRTC STUN and TURN connectivity
JavaScript
17
star
18

localmedia

WebRTC abstraction for creating and managing local media streams.
JavaScript
16
star
19

rtcpeerconnection-shim

Implementation of the RTCPeerConnection API ontop of ORTC
JavaScript
15
star
20

TLKWebRTC

Objective-C
13
star
21

filetransfer

filetransfer via a webrtc datachannel
JavaScript
13
star
22

mod_muc_focus

Prosody + Jingle/COLIBRI = multimedia MUC!
Lua
10
star
23

traceablepeerconnection

Lowlevel RTCPeerConnection wrapper that traces API calls
JavaScript
10
star
24

rtt-buffer

Realtime Text Buffer
JavaScript
9
star
25

jingle-media-session

Jingle Media Session
JavaScript
8
star
26

xmpp-jid

Parse & manage XMPP addresses
JavaScript
7
star
27

otalk-media-controller

Track local & remote media streams
JavaScript
6
star
28

xmpp-uri

Parse XMPP URIs
JavaScript
5
star
29

jxt-xmpp-types

JXT types for working with XMPP data
JavaScript
5
star
30

otalk-media-stream-view

Video/audio box, with controls
JavaScript
5
star
31

sdp-jingle-table

A parser/serializer for SDP to Lua tables. Useful for converting SDP to other formats like Jingle for WebRTC signaling.
Lua
4
star
32

xmpp-constants

Protocol constants for XMPP
JavaScript
4
star
33

rtcpeerconnection-jingle

rtcpeerconnection, extended with a JSON format. And easy to map to Jingle
JavaScript
3
star
34

hostmeta.js

Easily retrieve and parse a host's /.well-known/host-meta[.json] file.
JavaScript
3
star
35

mod_influxdb

Prosody Metrics to Influxdb
Lua
3
star
36

jingle-session

Generic base Jingle session
JavaScript
3
star
37

simplewebrtc.com

This site is DEPRECATED. simplewebrtc.com is a project of &yet and has been moved to andyet/simplewebrtc.com
CSS
3
star
38

jingle-filetransfer-session

Jingle FileTransfer Session
JavaScript
3
star
39

otalk-model-media

A model for WebRTC media streams
JavaScript
2
star
40

otalk-model-message

Ampersand model for XMPP messages
JavaScript
2
star
41

otalk-specs

XMPP extensions for Otalk functionality
XSLT
2
star
42

otalk-model-peer

A base model for XMPP peer entities
JavaScript
1
star
43

mod_muc_allowners

Lua
1
star
44

otalk-media-devices

Track user media devices
JavaScript
1
star
45

mod_turncredentials

XEP-0215 implementation for the prosody xmpp server
Lua
1
star
46

otalk-model-disco

Model for XMPP service discovery information
JavaScript
1
star
47

mod_muc_allhidden

Make all MUC rooms hidden by default
Lua
1
star
48

otalk.org

otalk.org website
CSS
1
star