npm package: @peermetrics/webrtc-stats
Description: Library that helps collect and parse webrtc stats.
Author: Andrei Onel
Latest version: 5.7.1

# WebRTCStats

<img src="https://img.shields.io/npm/v/@peermetrics/webrtc-stats">

WebRTCStats is the most complete utility belt that helps with everything related to getting and parsing the stats for WebRTC `PeerConnection`s.

The main advantage of WebRTCStats is that it parses and groups the stats from `PeerConnection`s and offers them in a easy to read way

On top of that, it offers the `timeline` which is a list of all the events fired while setting up a `PeerConnection`. Optionally, you can also wrap `getUserMedia` to get a better picture.

WebRTCStats extends `EventEmitter` and uses the same event system to communicate with the rest of the app.

## Install

```sh
npm install @peermetrics/webrtc-stats
```

## Usage
### Loading the module
WebRTC Stats can be loaded as an ES6 module, node module or directly in the browser.

After loading, the library needs to be initialized.  *See [Options](#options) for all the initialize options*

```js
import {WebRTCStats} from '@peermetrics/webrtc-stats'

let webrtcStats = new WebRTCStats({
    getStatsInterval: 5000
})
```
Add event listeners for `stats`:
```js
webrtcStats.on('stats', (ev) => {
    console.log('stats', ev)
})
```
Use `addConnection` to add connections to the list of monitored peers:
```js
let pc1 = new RTCPeerConnection({...})
webrtcStats.addConnection({
    pc: pc1, // RTCPeerConnection instance
    peerId: '1', // any string that helps you identify this peer,
   	connectionId: '06d54adc-e478-4f95-9144-bbb3562a2aad', // optional, an id that you can use to keep track of this connection
    remote: false // optional, override the global remote flag
})
```
Now every `5000` ms  WebRTCStats will fire the `stats` event which will come with the object:
```js
{
    event: 'stats',
    tag: 'stats',
    peerId: '1',
    timestamp: 'Sun Mar 22 2020 18:02:02', // a timestamp when this was fired
    data: {...}, // an object created after parsing the stats
    timeTaken: 5, // how many ms the .getStats() call took
    rawStats: RTCStatsReport, // the actual RTCStatsReport results from `getStats()`
    statsObject: {}, // an object created from RTCStatsReport that uses the `id` for each report as a key
    filteredStats: {}, // same as statsObject but with some report types filtered out (eg: `codec`, `certificate`)
}
```

### Options
The module accepts the following options when initialized:
```js
let stats = new WebRTCStats({
    // the interval in ms of how often we should get stats
    getStatsInterval: 5000, // Default: 1000

    // if we should include the original RTCStatsReport map when firing the `stats` event
    rawStats: false, // Default: false

    // include an object that resulted from transforming RTCStatsReport into an oject (`report.id` as the key)
    statsObject: true, // Default: false
    
    // if we should filter out some stats
    filteredStats: false, // Default: false

    // If the data object should contain a remote attribute that will contain stats for the remote peer, from `remote-inbound-rtp`, etc
    remote: true, // Default: true

    // If we should wrap the `geUserMedia` calls so we can gather events when the methods is called or success/error
    wrapGetUserMedia: false, // Default: false
    
    // If we should log messages
    debug: false, // Default: false
    
    // What kind of level of logs the lib should display. Values: 'none', 'error', 'warn', 'info', 'debug'
    logLevel: 'warn' // Default: 'none'
})
```

### API
#### `.addConnection(options)`
Adds a connection to the watch list.
`options`

  - `pc`: the `RTCPeerConnection` instance
  - `peerId`: String a unique Id to identify this peer
    Monitoring of a peer will automatically end when the connection is closed.
  - `connectionId`: optional, string. A way to identify this connection. If a `connectionId` is not offered, the lib will assign a random one

Returns:

```js
{
    connectionId: '', // the ID assigned to this connection
}
```



#### `.removeConnection(options)`

Removes the `RTCPeerConnection` from the list of watched connections for that peer.

`options` object:

- `peerId`: the peer id for which we want to remove the connection

- `pc`: The `RTCPeerConnection` instance we want to remove

  or

- `connectionId`: the id of the connection (the one returned when calling `.addConnection()`)

#### `.removePeer(peerId)`

Stop listening for events/stats on all connections for this peer

#### `.removeAllPeers()`

Used to stop listening to all the peers and connections added.

#### `.getTimeline([filter])`
Return the array of events from the timeline up to that point.
If the optional `filter` string is present it will filter out events. Possible values: `peer`, `connection`, `track`, `stats`, `getUserMedia`

#### `.destroy()`

Stop listening to all event listeners and reset the state of the instance. Useful for cleanup. 

A new instance of `WebRTCStats` should be used if you would like to start monitoring again.

### Events
The module uses `EventEmitter` to emit events. You can listen to them using `.on()`
```js
stats.on('eventName', (ev) => {
    
})
```
`ev` will have the following structure:

```js
{
    // The event name. Usually the method called (addTrack, createAnswer)
    event: '',
    // The tag for this event. `stats`, `sdp`, `getUserMedia`, etc
    tag: '',
    // The id for the peer that fired this event
    peerId: '',
    // A timestamp for when the event happened
    timestamp: '',
    // Data for each event type
    data: {},
    
    // The following attrs appear at certain times
    // The error that appeared in the method we were watching
    error: {},
    // These appear on the `stats` event
    rawStats: {},
    statsObject: {},
    filteredStats: {}
}
```

#### List of fired events

The tags for the events fired by `WebRTCStats` are:

- `timeline`: this will fire when something has been added to the timeline. This event is a duplicate of the following events
- `stats`: fired for each peer when we've collected stats for it
- `getUserMedia`: when `getUserMedia` is called initially
- `peer`: when a peer was added
- `track`: a track event: addTrack, removeTrack, mute, unmute, overconstrained
- `connection`: any event related to connection
- `datachannel`: any datachannel event

## Developed by 

[<img src="https://peermetrics.io/static/img/logo.png" style="zoom:25%;" />](https://peermetrics.io/)

## License

MIT