Skip to content

Commit be86b15

Browse files
xdumainexdumaine
committed
Merge pull request #371 from andyet/docs
Add API documentation
2 parents 0290ae3 + a9dba12 commit be86b15

File tree

1 file changed

+183
-7
lines changed

1 file changed

+183
-7
lines changed

‎README.md‎

Lines changed: 183 additions & 7 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,22 +58,30 @@ 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

76-
Join the SimpleWebRTC discussion list:
84+
Join the SimpleWebRTC discussion list:
7785

7886
http://lists.andyet.com/mailman/listinfo/simplewebrtc
7987

@@ -82,3 +90,171 @@ or the Gitter channel:
8290
https://gitter.im/HenrikJoreteg/SimpleWebRTC
8391

8492
## API
93+
94+
### Constructor
95+
96+
`new SimpleWebRTC(options)`
97+
98+
- `object options` - options object provided to constructor consisting of:
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 socketio` - *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
106+
- `bool debug` - *optional* flag to set the instance to debug mode
107+
- `[string|DomElement] locaVidelEl` - ID or Element to contain the local video
108+
element
109+
- `[string|DomElement] remoteVideosEl` - ID or Element to contain the
110+
remote video elements
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
120+
- `number peerVolumeWhenSpeaking` - *optional(=.0.25)* value used in
121+
conjunction with `adjustPeerVolume`. Uses values between 0 and 1.
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
131+
```javascript
132+
{
133+
autoplay: true, // automatically play the video stream on the page
134+
mirror: true, // flip the local video to mirror mode (for UX)
135+
muted: true // mute local video stream to prevent echo
136+
}
137+
```
138+
- `object logger` - *optional* alternate logger for the instance; any object
139+
that implements `log`, `warn`, and `error` methods.
140+
141+
### Fields
142+
143+
`capabilities` - the
144+
[`webrtcSupport`](https://github.com/HenrikJoreteg/webrtcsupport) object that
145+
describes browser capabilities, for convenience
146+
147+
`config` - the configuration options extended from options passed to the
148+
constructor
149+
150+
`connection` - the socket (or alternate) signaling connection
151+
152+
`webrtc` - the underlying WebRTC session manager
153+
154+
### Events
155+
156+
To set up event listeners, use the SimpleWebRTC instance created with the
157+
constructor. Example:
158+
159+
```javascript
160+
var webrtc = new SimpleWebRTC(options);
161+
162+
webrtc.on('connectionReady', function (sessionId) {
163+
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
197+
198+
- `videoEl` - the video element associated with the stream that was removed
199+
- `peer` - the peer associated with the stream that was removed
200+
201+
### Methods
202+
203+
`leaveRoom()` - leaves the currently joined room and stops local screen share
204+
205+
`disconnect()` - calls `disconnect` on the signaling connection and deletes it
206+
207+
`shareScreen(callback)` - initiates screen capture request to browser, then
208+
adds the stream to the conference
209+
210+
`getLocalScreen()` - returns the local screen stream
211+
212+
`stopScreenShare()` - stops the screen share stream and removes it from the room
213+
214+
`testReadiness()` - tests that the connection is ready and that (if media is
215+
enabled) streams have started
216+
217+
`createRoom(name, callback)` - emits the `create` event on the connection with
218+
`name` and (if provided) invokes `callback` on response
219+
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.
223+
224+
`startLocalVideo()` - starts the local media with the `media` options provided
225+
in the config passed to the constructor
226+
227+
`stopLocalVideo()` - stops all local media streams
228+
229+
`setVolumeForAll(volume)` - used to set the volume level for all peers
230+
231+
- `volume` - the volume level, between 0 and 1
232+
233+
`handlePeerStreamAdded(peer)` - used internally to attach media stream to the
234+
DOM and perform other setup
235+
236+
`handlePeerStreamRemoved(peer)` - used internally to remove the video container
237+
from the DOM and emit `videoRemoved`
238+
239+
`getDomId(peer)` - used internally to get the DOM id associated with a peer
240+
241+
`getEl(idOrEl)` - helper used internally to get an element where `idOrEl` is
242+
either an element, or an id of an element
243+
244+
`getLocalVideoContainer()` - used internally to get the container that will hold
245+
the local video element
246+
247+
`getRemoteVideoContainer()` - used internally to get the container that holds
248+
the remote video elements
249+
250+
### Connection
251+
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:
256+
257+
- `on(ev, fn)` - A method to invoke `fn` when event `ev` is triggered
258+
- `emit()` - A method to send/emit arbitrary arguments on the connection
259+
- `getSessionId()` - A method to get a unique session Id for the connection
260+
- `disconnect()` - A method to disconnect the connection

0 commit comments

Comments
 (0)