Deprecated
The open-source version of SimpleWebRTC has been deprecated. This repository will remain as-is but is no longer actively maintained. You can find the old website in the gh-pages branch.
Read more about the "new" SimpleWebRTC (which is an entirely different thing) on https://simplewebrtc.com
SimpleWebRTC - World's easiest WebRTC lib
Want to see it in action?
Check out the demo: https://simplewebrtc.com/demo.html
Want to run it locally?
- Install all dependencies and run the test page
npm install && npm run test-page
- open your browser to https://0.0.0.0:8443/test/
It's so easy:
1. Some basic html
<!DOCTYPE html>
<html>
<head>
<script src="https://simplewebrtc.com/latest-v2.js"></script>
<style>
#remoteVideos video {
height: 150px;
}
#localVideo {
height: 150px;
}
</style>
</head>
<body>
<video id="localVideo"></video>
<div id="remoteVideos"></div>
</body>
</html>
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';
2. 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
});
3. 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
(stun.l.google.com:19302), which is intended for public use according to:
https://twitter.com/HenrikJoreteg/status/354105684591251456
Note that you will most likely also need to run your own TURN servers. See
http://www.html5rocks.com/en/tutorials/webrtc/infrastructure/ for a basic
tutorial.
Filetransfer
Sending files between individual participants is supported. See
http://simplewebrtc.com/filetransfer.html 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
http://simplewebrtc.com/notsosimple.html for some examples.
API
Constructor
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
Connectionbelow. Defaults to a new SocketIoConnectionbool 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 elementsbool autoRequestMedia- optional(=false) option to automatically request
user media. Usetrueto request automatically, orfalseto request media
later withstartLocalVideobool enableDataChannelsoptional(=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 speakingnumber peerVolumeWhenSpeaking- optional(=.0.25) value used in
conjunction withadjustPeerVolume. Uses values between 0 and 1.object media- media options to be passed togetUserMedia. 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
{ 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 implementslog,warn, anderrormethods.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:
{ "iceServers": [{ "url": "stun3.l.google.com:19302" }, { "url": "turn:your.turn.servers.here", "username": "your.turn.server.username", "credential": "your.turn.server.password" } ], iceTransports: 'relay' }
Fields
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
Events
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
elthe 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 addedpeer- 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 removedpeer- the peer associated with the stream that was removed
Methods
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 sentobject 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 onstring messageType- the key for the type of message being sentobject 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
Connection
By default, SimpleWebRTC uses a socket.io 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 invokefnwhen eventevis triggeredemit()- A method to send/emit arbitrary arguments on the connectiongetSessionId()- A method to get a unique session Id for the connectiondisconnect()- A method to disconnect the connection