World's easiest webrtc

Downloads in past


3.0.26 years ago11 years agoMinified + gzip package size for simplewebrtc in KB


The open-source version of SimpleWebRTC has been deprecated. This repository will remain as-is but is no longer actively maintained. Read more about the "new" SimpleWebRTC (which is an entirely different thing) on
SimpleWebRTC - World's easiest WebRTC lib
Want to see it in action? Check out the demo:
Want to run it locally?
  1. Install all dependencies and run the test page
npm install && npm run test-page

  1. open your browser to

It's so easy:

  1. Some basic html

<!DOCTYPE html>
        <script src=""></script>
            #remoteVideos video {
                height: 150px;
            #localVideo {
                height: 150px;
        <video id="localVideo"></video>
        <div id="remoteVideos"></div>

Installing through NPM

npm install --save simplewebrtc

# for yarn users
yarn add simplewebrtc
After that simply import simplewebrtc into your project
import SimpleWebRTC from 'simplewebrtc';

  1. Create our WebRTC object

var webrtc = new SimpleWebRTC({
    // the id/element dom element that will hold "our" video
    localVideoEl: 'localVideo',
    // the id/element dom element that will hold remote videos
    remoteVideosEl: 'remoteVideos',
    // immediately ask for camera access
    autoRequestMedia: true

  1. Tell it to join a room when ready

// we have to wait until it's ready
webrtc.on('readyToCall', function () {
    // you can name it anything
    webrtc.joinRoom('your awesome room name');

Available options

peerConnectionConfig - Set this to specify your own STUN and TURN servers. By default, SimpleWebRTC uses Google's public STUN server (, which is intended for public use according to:
Note that you will most likely also need to run your own TURN servers. See for a basic tutorial.


Sending files between individual participants is supported. See for a demo.
Note that this is not file sharing between a group which requires a completely different approach.

It's not always that simple...

Sometimes you need to do more advanced stuff. See for some examples.

Got questions?

Join the Gitter channel:



new SimpleWebRTC(options)
  • object options - options object provided to constructor consisting of:
- string url - required url for signaling server. Defaults to signaling server URL which can be used for development. You must use your own signaling server for production. - object socketio - optional object to be passed as options to the signaling server connection. - Connection connection - optional connection object for signaling. See Connection below. Defaults to a new SocketIoConnection - bool debug - optional flag to set the instance to debug mode - [string|DomElement] localVideoEl - ID or Element to contain the local video element - [string|DomElement] remoteVideosEl - ID or Element to contain the remote video elements - bool autoRequestMedia - optional(=false) option to automatically request user media. Use true to request automatically, or false to request media later with startLocalVideo - bool enableDataChannels optional(=true) option to enable/disable data channels (used for volume levels or direct messaging) - bool autoRemoveVideos - optional(=true) option to automatically remove video elements when streams are stopped. - bool adjustPeerVolume - optional(=false) option to reduce peer volume when the local participant is speaking - number peerVolumeWhenSpeaking - optional(=.0.25) value used in conjunction with adjustPeerVolume. Uses values between 0 and 1. - object media - media options to be passed to getUserMedia. Defaults to { video: true, audio: true }. Valid configurations described on MDN with official spec at w3c. - object receiveMedia - optional RTCPeerConnection options. Defaults to { offerToReceiveAudio: 1, offerToReceiveVideo: 1 }. - object localVideo - optional options for attaching the local video stream to the page. Defaults to ```javascript {
autoplay: true, // automatically play the video stream on the page
mirror: true, // flip the local video to mirror mode (for UX)
muted: true // mute local video stream to prevent echo
} `` - object logger` - optional alternate logger for the instance; any object that implements log, warn, and error methods. - object peerConnectionConfig - optional options to specify own your own STUN/TURN servers. By default these options are overridden when the signaling server specifies the STUN/TURN server configuration. Example on how to specify the peerConnectionConfig: ```javascript {
"iceServers": [{
        "url": ""
        "url": "",
        "username": "your.turn.server.username",
        "credential": "your.turn.server.password"
iceTransports: 'relay'
} ```


capabilities - the webrtcSupport object that describes browser capabilities, for convenience
config - the configuration options extended from options passed to the constructor
connection - the socket (or alternate) signaling connection
webrtc - the underlying WebRTC session manager


To set up event listeners, use the SimpleWebRTC instance created with the constructor. Example:
var webrtc = new SimpleWebRTC(options);
webrtc.on('connectionReady', function (sessionId) {
    // ...

'connectionReady', sessionId - emitted when the signaling connection emits the connect event, with the unique id for the session.
'createdPeer', peer - emitted three times:
  • when joining a room with existing peers, once for each peer
  • when a new peer joins a joined room
  • when sharing screen, once for each peer

  • peer - the object representing the peer and underlying peer connection

'channelMessage', peer, channelLabel, {messageType, payload} - emitted when a broadcast message to all peers is received via dataChannel by using the method sendDirectlyToAll().
'stunservers', [...args] - emitted when the signaling connection emits the same event
'turnservers', [...args] - emitted when the signaling connection emits the same event
'localScreenAdded', el - emitted after triggering the start of screen sharing
  • el the element that contains the local screen stream

'joinedRoom', roomName - emitted after successfully joining a room with the name roomName
'leftRoom', roomName - emitted after successfully leaving the current room, ending all peers, and stopping the local screen stream
'videoAdded', videoEl, peer - emitted when a peer stream is added
  • videoEl - the video element associated with the stream that was added
  • peer - the peer associated with the stream that was added

'videoRemoved', videoEl, peer - emitted when a peer stream is removed
  • videoEl - the video element associated with the stream that was removed
  • peer - the peer associated with the stream that was removed


createRoom(name, callback) - emits the create event on the connection with name and (if provided) invokes callback on response
joinRoom(name, callback) - joins the conference in room name. Callback is invoked with callback(err, roomDescription) where roomDescription is yielded by the connection on the join event. See signalmaster for more details.
startLocalVideo() - starts the local media with the media options provided in the config passed to the constructor
testReadiness() - tests that the connection is ready and that (if media is enabled) streams have started
mute() - mutes the local audio stream for all peers (pauses sending audio)
unmute() - unmutes local audio stream for all peers (resumes sending audio)
pauseVideo() - pauses sending video to peers
resumeVideo() - resumes sending video to all peers
pause() - pauses sending audio and video to all peers
resume() - resumes sending audio and video to all peers
sendToAll(messageType, payload) - broadcasts a message to all peers in the room via the signaling channel (websocket)
  • string messageType - the key for the type of message being sent
  • object payload - an arbitrary value or object to send to peers

sendDirectlyToAll(channelLabel, messageType, payload) - broadcasts a message to all peers in the room via a dataChannel
  • string channelLabel - the label for the dataChannel to send on
  • string messageType - the key for the type of message being sent
  • object payload - an arbitrary value or object to send to peers

getPeers(sessionId, type) - returns all peers by sessionId and/or type
shareScreen(callback) - initiates screen capture request to browser, then adds the stream to the conference
getLocalScreen() - returns the local screen stream
stopScreenShare() - stops the screen share stream and removes it from the room
stopLocalVideo() - stops all local media streams
setVolumeForAll(volume) - used to set the volume level for all peers
  • volume - the volume level, between 0 and 1

leaveRoom() - leaves the currently joined room and stops local screen share
disconnect() - calls disconnect on the signaling connection and deletes it
handlePeerStreamAdded(peer) - used internally to attach media stream to the DOM and perform other setup
handlePeerStreamRemoved(peer) - used internally to remove the video container from the DOM and emit videoRemoved
getDomId(peer) - used internally to get the DOM id associated with a peer
getEl(idOrEl) - helper used internally to get an element where idOrEl is either an element, or an id of an element
getLocalVideoContainer() - used internally to get the container that will hold the local video element
getRemoteVideoContainer() - used internally to get the container that holds the remote video elements


By default, SimpleWebRTC uses a connection to communicate with the signaling server. However, you can provide an alternate connection object to use. All that your alternate connection need provide are four methods:
  • on(ev, fn) - A method to invoke fn when event ev is triggered
  • emit() - A method to send/emit arbitrary arguments on the connection
  • getSessionId() - A method to get a unique session Id for the connection
  • disconnect() - A method to disconnect the connection