Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/peermetrics/webrtc-stats

Helps you collect stats for peer connections
https://github.com/peermetrics/webrtc-stats

webrtc webrtc-stats webrtc-tools

Last synced: 2 days ago
JSON representation

Helps you collect stats for peer connections

Awesome Lists containing this project

README 

        
# WebRTCStats






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.



#### `.clearTimeline()`



Clears the internal timeline array.



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



[](https://peermetrics.io/)



## License



MIT