# SimpleWebRTC - World's easiest WebRTC lib
[](https://gitter.im/HenrikJoreteg/SimpleWebRTC?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Want to see it in action? Check out the demo: https://simplewebrtc.com/demo.html
## It's so easy:
### 1. Some basic html
```html
```
### 2. Create our WebRTC object
```js
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
```js
// 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.
## Got questions?
Join the SimpleWebRTC discussion list:
http://lists.andyet.com/mailman/listinfo/simplewebrtc
or 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](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)
with official spec
[at w3c](http://w3c.github.io/mediacapture-main/#dom-mediadevices-getusermedia).
- `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.
### Fields
`capabilities` - the
[`webrtcSupport`](https://github.com/HenrikJoreteg/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:
```javascript
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
`'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
`'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
### 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](https://github.com/andyet/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
### Connection
By default, SimpleWebRTC uses a [socket.io](http://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 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