Skip to content

Commit 37a6a95

Browse files
author
Xander Dumaine
committed
flesh out remaining items
1 parent 64cf6b2 commit 37a6a95

File tree

1 file changed

+121
-44
lines changed

1 file changed

+121
-44
lines changed

‎README.md‎

Lines changed: 121 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Want to see it in action? Check out the demo: https://talky.io/
1414
<!DOCTYPE html>
1515
<html>
1616
<head>
17-
<script src="http://simplewebrtc.com/latest-v2.js"></script>
17+
<script src="https://simplewebrtc.com/latest-v2.js"></script>
1818
<style>
1919
#remoteVideos video {
2020
height: 150px;
@@ -58,18 +58,26 @@ webrtc.on('readyToCall', function () {
5858
### Available options
5959

6060

61-
`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
61+
`peerConnectionConfig` - Set this to specify your own STUN and TURN servers. By
62+
default, SimpleWebRTC uses Google's public STUN server
63+
(`stun.l.google.com:19302`), which is intended for public use according to:
64+
https://twitter.com/HenrikJoreteg/status/354105684591251456
6265

63-
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.
66+
Note that you will most likely also need to run your own TURN servers. See
67+
http://www.html5rocks.com/en/tutorials/webrtc/infrastructure/ for a basic
68+
tutorial.
6469

6570
## Filetransfer
66-
Sending files between individual participants is supported. See http://simplewebrtc.com/filetransfer.html for a demo.
71+
Sending files between individual participants is supported. See
72+
http://simplewebrtc.com/filetransfer.html for a demo.
6773

68-
Note that this is not file sharing between a group which requires a completly different approach.
74+
Note that this is not file sharing between a group which requires a completely
75+
different approach.
6976

7077
## It's not always that simple...
7178

72-
Sometimes you need to do more advanced stuff. See http://simplewebrtc.com/notsosimple.html for some examples.
79+
Sometimes you need to do more advanced stuff. See
80+
http://simplewebrtc.com/notsosimple.html for some examples.
7381

7482
## Got questions?
7583

@@ -88,94 +96,163 @@ https://gitter.im/HenrikJoreteg/SimpleWebRTC
8896
`new SimpleWebRTC(options)`
8997

9098
- `object options` - options object provided to constructor consisting of:
91-
- `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.
92-
- `object sockio` - *optional* object to be passed as options to the signaling server connection.
93-
- `Connection connection` - *optional* connection object for signaling. See `Connection` below. Defaults to a new SocketIoConnection
99+
- `string url` - *required* url for signaling server. Defaults to signaling
100+
server URL which can be used for development. You must use your own signaling
101+
server for production.
102+
- `object sockio` - *optional* object to be passed as options to the signaling
103+
server connection.
104+
- `Connection connection` - *optional* connection object for signaling. See
105+
`Connection` below. Defaults to a new SocketIoConnection
94106
- `bool debug` - *optional* flag to set the instance to debug mode
95-
- `[string|DomElement] locaVidelEl` - ID or Element to contain the local video element
107+
- `[string|DomElement] locaVidelEl` - ID or Element to contain the local video
108+
element
96109
- `[string|DomElement] remoteVideosEl` - ID or Element to contain the
97110
remote video elements
98-
- `bool autoRequestMedia` - *optional(=false)* option to automatically request user media. Use `true` to request automatically, or `false` to request media later with `startLocalVideo`
99-
- `bool enableDataChannels` *optional(=true)* option to enable/disable data channels (used for volume levels or direct messaging)
100-
- `bool autoRemoveVideos` - *optional(=true)* option to automatically remove video elements when streams are stopped.
101-
- `bool adjustPeerVolume` - *optional(=false)* option to reduce peer volume when the local participant is speaking
111+
- `bool autoRequestMedia` - *optional(=false)* option to automatically request
112+
user media. Use `true` to request automatically, or `false` to request media
113+
later with `startLocalVideo`
114+
- `bool enableDataChannels` *optional(=true)* option to enable/disable data
115+
channels (used for volume levels or direct messaging)
116+
- `bool autoRemoveVideos` - *optional(=true)* option to automatically remove
117+
video elements when streams are stopped.
118+
- `bool adjustPeerVolume` - *optional(=false)* option to reduce peer volume
119+
when the local participant is speaking
102120
- `number peerVolumeWhenSpeaking` - *optional(=.0.25)* value used in
103121
conjunction with `adjustPeerVolume`. Uses values between 0 and 1.
104-
- `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).
105-
- `object receiveMedia` - *optional* RTCPeerConnection options. Defaults to `{ offerToReceiveAudio: 1, offerToReceiveVideo: 1 }`.
106-
- `object localVideo` - *optional* options for attaching the local video stream to the page. Defaults to
122+
- `object media` - media options to be passed to `getUserMedia`. Defaults to
123+
`{ video: true, audio: true }`. Valid configurations described
124+
[on MDN](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia)
125+
with official spec
126+
[at w3c](http://w3c.github.io/mediacapture-main/#dom-mediadevices-getusermedia).
127+
- `object receiveMedia` - *optional* RTCPeerConnection options. Defaults to
128+
`{ offerToReceiveAudio: 1, offerToReceiveVideo: 1 }`.
129+
- `object localVideo` - *optional* options for attaching the local video
130+
stream to the page. Defaults to
107131
```javascript
108132
{
109133
autoplay: true, // automatically play the video stream on the page
110134
mirror: true, // flip the local video to mirror mode (for UX)
111135
muted: true // mute local video stream to prevent echo
112136
}
113137
```
114-
- `object logger` - *optional* alternate logger for the instance; any object that implements `log`, `warn`, and `error` methods.
138+
- `object logger` - *optional* alternate logger for the instance; any object
139+
that implements `log`, `warn`, and `error` methods.
115140

116141
### Fields
117142

118-
`capabilities` - the [`webrtcSupport`](https://github.com/HenrikJoreteg/webrtcsupport) object that describes browser capabilities, for convenience
143+
`capabilities` - the
144+
[`webrtcSupport`](https://github.com/HenrikJoreteg/webrtcsupport) object that
145+
describes browser capabilities, for convenience
119146

120-
`config` - the configuration options extended from options passed to the constructor
147+
`config` - the configuration options extended from options passed to the
148+
constructor
121149

122150
`connection` - the socket (or alternate) signaling connection
123151

124152
`webrtc` - the underlying WebRTC session manager
125153

126154
### Events
127155

128-
`'connectionReady', sessionId`
156+
To set up event listeners, use the SimpleWebRTC instance created with the
157+
constructor. Example:
129158

130-
`'createdPeer', peer`
159+
```javascript
160+
var webrtc = new SimpleWebRTC(options);
131161

132-
`'stunservers', stunServers`
162+
webrtc.on('connectionReady', function (sessionId) {
133163

134-
`'turnservers', turnservers`
164+
})
165+
```
166+
167+
`'connectionReady', sessionId` - emitted when the signaling connection emits the
168+
`connect` event, with the unique id for the session.
169+
170+
`'createdPeer', peer` - emitted three times:
171+
172+
- when joining a room with existing peers, once for each peer
173+
- when a new peer joins a joined room
174+
- when sharing screen, once for each peer
175+
176+
- `peer` - the object representing the peer and underlying peer connection
177+
178+
`'stunservers', [...args]` - emitted when the signaling connection emits the
179+
same event
180+
181+
`'turnservers', [...args]` - emitted when the signaling connection emits the
182+
same event
183+
184+
`'localScreenAdded', el` - emitted after triggering the start of screen sharing
185+
186+
- `el` the element that contains the local screen stream
187+
188+
`leftRoom, roomName` - emitted after successfully leaving the current room,
189+
ending all peers, and stopping the local screen stream
190+
191+
`videoAdded, videoEl, peer` - emitted when a peer stream is added
192+
193+
- `videoEl` - the video element associated with the stream that was added
194+
- `peer` - the peer associated with the stream that was added
195+
196+
`videoRemoved, videoEl, peer` - emitted when a peer stream is removed
135197

136-
`'localScreenAdded', el`
198+
- `videoEl` - the video element associated with the stream that was removed
199+
- `peer` - the peer associated with the stream that was removed
137200

138201
### Methods
139202

140-
`leaveRoom()`
203+
`leaveRoom()` - leaves the currently joined room and stops local screen share
141204

142-
`disconnect()`
205+
`disconnect()` - calls `disconnect` on the signaling connection and deletes it
143206

144-
`handlePeerStreamAdded(peer)`
207+
`shareScreen(callback)` - initiates screen capture request to browser, then
208+
adds the stream to the conference
145209

146-
`handlePeerStreamRemoved(peer)`
210+
`getLocalScreen()` - returns the local screen stream
147211

148-
`getDomId(peer)`
212+
`stopScreenShare()` - stops the screen share stream and removes it from the room
149213

150-
`setVolumeForAll(volume)`
214+
`testReadiness()` - tests that the connection is ready and that (if media is
215+
enabled) streams have started
151216

152-
`joinRoom(name, callback)`
217+
`createRoom(name, callback)` - emits the `create` event on the connection with
218+
`name` and (if provided) invokes `callback` on response
153219

154-
`getEl(idOrEl)`
220+
`joinRoom(name, callback)` - joins the conference in room `name`. Callback is
221+
invoked with `callback(err, roomDescription)` where `roomDescription` is yielded
222+
by the connection on the `join` event. See signalmaster for more details.
155223

156-
`startLocalVideo()`
224+
`startLocalVideo()` - starts the local media with the `media` options provided
225+
in the config passed to the constructor
157226

158-
`stopLocalVideo()`
227+
`stopLocalVideo()` - stops all local media streams
159228

160-
`getLocalVideoContainer()`
229+
`setVolumeForAll(volume)` - used to set the volume level for all peers
161230

162-
`getRemoteVideoContainer()`
231+
- `volume` - the volume level, between 0 and 1
163232

164-
`shareScreen(callback)`
233+
`handlePeerStreamAdded(peer)` - used internally to attach media stream to the
234+
DOM and perform other setup
165235

166-
`getLocalScreen()`
236+
`handlePeerStreamRemoved(peer)` - used internally to remove the video container
237+
from the DOM and emit `videoRemoved`
167238

168-
`stopScreenShare()`
239+
`getDomId(peer)` - used internally to get the DOM id associated with a peer
169240

170-
`testReadiness()`
241+
`getEl(idOrEl)` - helper used internally to get an element where `idOrEl` is
242+
either an element, or an id of an element
171243

172-
`createRoom(name, callback)`
244+
`getLocalVideoContainer()` - used internally to get the container that will hold
245+
the local video element
173246

174-
`sendFile()`
247+
`getRemoteVideoContainer()` - used internally to get the container that holds
248+
the remote video elements
175249

176250
### Connection
177251

178-
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:
252+
By default, SimpleWebRTC uses a [socket.io](http://socket.io/) connection to
253+
communicate with the signaling server. However, you can provide an alternate
254+
connection object to use. All that your alternate connection need provide are
255+
four methods:
179256

180257
- `on(ev, fn)` - A method to invoke `fn` when event `ev` is triggered
181258
- `emit()` - A method to send/emit arbitrary arguments on the connection

0 commit comments

Comments
 (0)