# rtcpeerconnection

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

Latest version **8.4.0** (published 2018-07-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install rtcpeerconnection
pnpm add rtcpeerconnection
yarn add rtcpeerconnection
bun add rtcpeerconnection
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 8.4.0 |
| Published | 2018-07-09 |
| First published | 2013-06-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 186.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 201 |
| Author | Henrik Joreteg |
| Maintainers | andyet-ops, fippo, henrikjoreteg, lancestout, tgabi333, xdumaine |
| Keywords | browser, RTCPeerConnection, WebRTC, Jingle |

## Links

- npm: https://www.npmjs.com/package/rtcpeerconnection
- Repository: https://github.com/otalk/RTCPeerConnection
- Homepage: https://github.com/otalk/RTCPeerConnection#readme
- Issues: https://github.com/otalk/RTCPeerConnection/issues
- npm.io page: https://npm.io/package/rtcpeerconnection

## Dependencies (3)

- [wildemitter](https://npm.io/package/wildemitter.md) 1.x
- [sdp-jingle-json](https://npm.io/package/sdp-jingle-json.md) ^3.0.0
- [lodash.clonedeep](https://npm.io/package/lodash.clonedeep.md) ^4.3.2

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 8.4.0 (latest) — 2018-07-09
- 8.3.1 — 2018-07-05
- 8.3.0 — 2018-04-06
- 8.2.0 — 2018-01-17
- 8.1.0 — 2017-12-04
- 8.0.1 — 2017-07-06
- 8.0.0 — 2017-05-26
- 7.0.2 — 2017-04-03
- 7.0.1 — 2017-03-06
- 7.0.0 — 2017-02-27
- 6.1.0 — 2017-02-06
- 6.0.0 — 2016-10-21
- 5.2.1 — 2016-08-25
- 5.2.0 — 2016-07-14
- 5.1.1 — 2016-05-23
- … 68 more at https://npm.io/package/rtcpeerconnection/versions

## README

# 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:

```js
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](http://github.com/henrikjoreteg/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:


```js

// 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:

```js
// 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](http://simplewebrtc.com) that uses this library.


## License

MIT

## Credits

If you like this, follow: [@HenrikJoreteg](http://twitter.com/henrikjoreteg) on twitter.

---
_Source: https://npm.io/package/rtcpeerconnection · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._