Deprecated
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 https://simplewebrtc.comSimpleWebRTC - 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:
- 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';
- 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
});
- 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/354105684591251456Note 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.Got questions?
Join the Gitter channel:https://gitter.im/HenrikJoreteg/SimpleWebRTC
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
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": "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 convenienceconfig
- the configuration options extended from options passed to the
constructorconnection
- the socket (or alternate) signaling connectionwebrtc
- the underlying WebRTC session managerEvents
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 sharingel
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 addedvideoEl
- 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 removedvideoEl
- 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 responsejoinRoom(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 constructortestReadiness()
- tests that the connection is ready and that (if media is
enabled) streams have startedmute()
- 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 peersresumeVideo()
- resumes sending video to all peerspause()
- pauses sending audio and video to all peersresume()
- resumes sending audio and video to all peerssendToAll(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 dataChannelstring 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 conferencegetLocalScreen()
- returns the local screen streamstopScreenShare()
- stops the screen share stream and removes it from the roomstopLocalVideo()
- stops all local media streamssetVolumeForAll(volume)
- used to set the volume level for all peersvolume
- the volume level, between 0 and 1
leaveRoom()
- leaves the currently joined room and stops local screen sharedisconnect()
- calls disconnect
on the signaling connection and deletes ithandlePeerStreamAdded(peer)
- used internally to attach media stream to the
DOM and perform other setuphandlePeerStreamRemoved(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 peergetEl(idOrEl)
- helper used internally to get an element where idOrEl
is
either an element, or an id of an elementgetLocalVideoContainer()
- used internally to get the container that will hold
the local video elementgetRemoteVideoContainer()
- used internally to get the container that holds
the remote video elementsConnection
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 invokefn
when eventev
is 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