-
Notifications
You must be signed in to change notification settings - Fork 9
/
module-rtc-tools.html
230 lines (207 loc) · 16.4 KB
/
module-rtc-tools.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="format-detection" content="telephone=no">
<meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width">
<title>rtc.io</title>
<link rel="stylesheet" type="text/css" href="css/reset.css">
<link rel="stylesheet" type="text/css" href="css/main.css">
<!-- responsive -->
<link rel="stylesheet" media="screen and (max-width: 960px)" href="css/tablet.css">
<link rel="stylesheet" media="screen and (max-width: 710px)" href="css/phone.css">
<link rel="stylesheet" type="text/css" href="fonts/source-sans/stylesheet.css">
<link rel="stylesheet" type="text/css" href="css/code.css">
</head>
<body>
<a class="scroll-point pt-top" name="top"></a>
<header>
<a href="https://github.com/rtc-io/rtc-tools"><img class="fork" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>
<a class="scroll-point pt-top" name="top"></a>
<div class="site">
<div class="mascot">
<img src="images/artsio.png">
</div>
<div class="logo" data-subtext="OpenSource WebRTC">
<a href="index.html">rtc.io</a>
</div>
<nav>
<ul>
<li><a href="index.html">About</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="modules.html">Modules</a></li>
</ul>
</nav>
</div>
<div class="shadow"></div>
</header>
<div class="main" role="content"><h1 id="rtc-tools">rtc-tools</h1>
<p>The <code>rtc-tools</code> module does most of the heavy lifting within the
<a href="http://rtc.io">rtc.io</a> suite. Primarily it handles the logic of coupling
a local <code>RTCPeerConnection</code> with it's remote counterpart via an
<a href="https://github.com/rtc-io/rtc-signaller">rtc-signaller</a> signalling
channel.</p>
<p><a href="https://nodei.co/npm/rtc-tools/"><img src="https://nodei.co/npm/rtc-tools.png" alt="NPM"></a></p>
<p><a href="https://travis-ci.org/rtc-io/rtc-tools"><img src="https://img.shields.io/travis/rtc-io/rtc-tools.svg?branch=master" alt="Build Status"></a> <a href="https://github.com/dominictarr/stability#unstable"><img src="https://img.shields.io/badge/stability-unstable-yellowgreen.svg" alt="unstable"></a>
<a href="https://gitter.im/rtc-io/discuss"><img src="https://badges.gitter.im/rtc-io/discuss.png" alt="Gitter chat"></a></p>
<h2 id="getting-started">Getting Started</h2>
<p>If you decide that the <code>rtc-tools</code> module is a better fit for you than either
<a href="https://github.com/rtc-io/rtc-quickconnect">rtc-quickconnect</a> or
<a href="https://github.com/rtc-io/rtc">rtc</a> then the code snippet below
will provide you a guide on how to get started using it in conjunction with
the <a href="https://github.com/rtc-io/rtc-signaller">rtc-signaller</a> (version 5.0 and above)
and <a href="https://github.com/rtc-io/rtc-media">rtc-media</a> modules:</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">messenger</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'rtc-switchboard-messenger'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">signaller</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'rtc-signaller'</span><span class="p">)(</span><span class="nx">messenger</span><span class="p">(</span><span class="s1">'https://switchboard.rtc.io/'</span><span class="p">));</span>
<span class="kd">var</span> <span class="nx">rtc</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'rtc-tools'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">getUserMedia</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'getusermedia'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">attachMedia</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'attachmediastream'</span><span class="p">);</span>
<span class="c1">// capture local media first as firefox</span>
<span class="c1">// will want a local stream and doesn't support onnegotiationneeded event</span>
<span class="nx">getUserMedia</span><span class="p">({</span> <span class="nx">video</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span> <span class="nx">audio</span><span class="o">:</span> <span class="kc">true</span> <span class="p">},</span> <span class="kd">function</span><span class="p">(</span><span class="nx">err</span><span class="p">,</span> <span class="nx">localStream</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">err</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">console</span><span class="p">.</span><span class="nx">error</span><span class="p">(</span><span class="s1">'could not capture media: '</span><span class="p">,</span> <span class="nx">err</span><span class="p">);</span>
<span class="p">}</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">body</span><span class="p">.</span><span class="nx">appendChild</span><span class="p">(</span><span class="nx">attachMedia</span><span class="p">(</span><span class="nx">localStream</span><span class="p">));</span>
<span class="c1">// look for friends</span>
<span class="nx">signaller</span><span class="p">.</span><span class="nx">on</span><span class="p">(</span><span class="s1">'peer:announce'</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">data</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">pc</span> <span class="o">=</span> <span class="nx">rtc</span><span class="p">.</span><span class="nx">createConnection</span><span class="p">();</span>
<span class="kd">var</span> <span class="nx">monitor</span> <span class="o">=</span> <span class="nx">rtc</span><span class="p">.</span><span class="nx">couple</span><span class="p">(</span><span class="nx">pc</span><span class="p">,</span> <span class="nx">data</span><span class="p">.</span><span class="nx">id</span><span class="p">,</span> <span class="nx">signaller</span><span class="p">);</span>
<span class="c1">// add the stream to the connection</span>
<span class="nx">pc</span><span class="p">.</span><span class="nx">addStream</span><span class="p">(</span><span class="nx">localStream</span><span class="p">);</span>
<span class="c1">// once the connection is active, log a console message</span>
<span class="nx">monitor</span><span class="p">.</span><span class="nx">once</span><span class="p">(</span><span class="s1">'connected'</span><span class="p">,</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
<span class="nx">console</span><span class="p">.</span><span class="nx">log</span><span class="p">(</span><span class="s1">'connection active to: '</span> <span class="o">+</span> <span class="nx">data</span><span class="p">.</span><span class="nx">id</span><span class="p">);</span>
<span class="nx">pc</span><span class="p">.</span><span class="nx">getRemoteStreams</span><span class="p">().</span><span class="nx">forEach</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">stream</span><span class="p">)</span> <span class="p">{</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">body</span><span class="p">.</span><span class="nx">appendChild</span><span class="p">(</span><span class="nx">attachMedia</span><span class="p">(</span><span class="nx">stream</span><span class="p">));</span>
<span class="p">});</span>
<span class="p">});</span>
<span class="nx">monitor</span><span class="p">.</span><span class="nx">createOffer</span><span class="p">();</span>
<span class="p">});</span>
<span class="c1">// announce ourself in the rtc-getting-started room</span>
<span class="nx">signaller</span><span class="p">.</span><span class="nx">announce</span><span class="p">({</span> <span class="nx">room</span><span class="o">:</span> <span class="s1">'rtc-getting-started'</span> <span class="p">});</span>
<span class="p">});</span>
</pre></div>
<p>This code definitely doesn't cover all the cases that you need to consider
(i.e. peers leaving, etc) but it should demonstrate how to:</p>
<ol>
<li>Capture video and add it to a peer connection</li>
<li>Couple a local peer connection with a remote peer connection</li>
<li>Deal with the remote steam being discovered and how to render
that to the local interface.</li>
</ol>
<h2 id="reference">Reference</h2>
<h3 id="createconnection">createConnection</h3>
<pre><code>createConnection(opts?, constraints?) => RTCPeerConnection</code></pre>
<p>Create a new <code>RTCPeerConnection</code> auto generating default opts as required.</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">conn</span><span class="p">;</span>
<span class="c1">// this is ok</span>
<span class="nx">conn</span> <span class="o">=</span> <span class="nx">rtc</span><span class="p">.</span><span class="nx">createConnection</span><span class="p">();</span>
<span class="c1">// and so is this</span>
<span class="nx">conn</span> <span class="o">=</span> <span class="nx">rtc</span><span class="p">.</span><span class="nx">createConnection</span><span class="p">({</span>
<span class="nx">iceServers</span><span class="o">:</span> <span class="p">[]</span>
<span class="p">});</span>
</pre></div>
<h3 id="rtc-tools-cleanup">rtc-tools/cleanup</h3>
<pre><code>cleanup(pc)</code></pre>
<p>The <code>cleanup</code> function is used to ensure that a peer connection is properly
closed and ready to be cleaned up by the browser.</p>
<h3 id="rtc-tools-couple">rtc-tools/couple</h3>
<h4 id="couple-pc-targetid-signaller-opts-">couple(pc, targetId, signaller, opts?)</h4>
<p>Couple a WebRTC connection with another webrtc connection identified by
<code>targetId</code> via the signaller.</p>
<p>The following options can be provided in the <code>opts</code> argument:</p>
<ul>
<li><p><code>sdpfilter</code> (default: null)</p>
<p>A simple function for filtering SDP as part of the peer
connection handshake (see the Using Filters details below).</p>
</li>
</ul>
<h5 id="example-usage">Example Usage</h5>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">couple</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'rtc/couple'</span><span class="p">);</span>
<span class="nx">couple</span><span class="p">(</span><span class="nx">pc</span><span class="p">,</span> <span class="s1">'54879965-ce43-426e-a8ef-09ac1e39a16d'</span><span class="p">,</span> <span class="nx">signaller</span><span class="p">);</span>
</pre></div>
<h5 id="using-filters">Using Filters</h5>
<p>In certain instances you may wish to modify the raw SDP that is provided
by the <code>createOffer</code> and <code>createAnswer</code> calls. This can be done by passing
a <code>sdpfilter</code> function (or array) in the options. For example:</p>
<div class="highlight"><pre><span class="c1">// run the sdp from through a local tweakSdp function.</span>
<span class="nx">couple</span><span class="p">(</span><span class="nx">pc</span><span class="p">,</span> <span class="s1">'54879965-ce43-426e-a8ef-09ac1e39a16d'</span><span class="p">,</span> <span class="nx">signaller</span><span class="p">,</span> <span class="p">{</span>
<span class="nx">sdpfilter</span><span class="o">:</span> <span class="nx">tweakSdp</span>
<span class="p">});</span>
</pre></div>
<h3 id="rtc-tools-detect">rtc-tools/detect</h3>
<p>Provide the <a href="https://github.com/rtc-io/rtc-core#detect">rtc-core/detect</a>
functionality.</p>
<h3 id="rtc-tools-generators">rtc-tools/generators</h3>
<p>The generators package provides some utility methods for generating
constraint objects and similar constructs.</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">generators</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'rtc/generators'</span><span class="p">);</span>
</pre></div>
<h4 id="generators-config-config-">generators.config(config)</h4>
<p>Generate a configuration object suitable for passing into an W3C
RTCPeerConnection constructor first argument, based on our custom config.</p>
<p>In the event that you use short term authentication for TURN, and you want
to generate new <code>iceServers</code> regularly, you can specify an iceServerGenerator
that will be used prior to coupling. This generator should return a fully
compliant W3C (RTCIceServer dictionary)[<a href="http://www.w3.org/TR/webrtc/#idl-def-RTCIceServer">http://www.w3.org/TR/webrtc/#idl-def-RTCIceServer</a>].</p>
<p>If you pass in both a generator and iceServers, the iceServers _will be
ignored and the generator used instead.</p>
<h4 id="generators-connectionconstraints-flags-constraints-">generators.connectionConstraints(flags, constraints)</h4>
<p>This is a helper function that will generate appropriate connection
constraints for a new <code>RTCPeerConnection</code> object which is constructed
in the following way:</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">conn</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">RTCPeerConnection</span><span class="p">(</span><span class="nx">flags</span><span class="p">,</span> <span class="nx">constraints</span><span class="p">);</span>
</pre></div>
<p>In most cases the constraints object can be left empty, but when creating
data channels some additional options are required. This function
can generate those additional options and intelligently combine any
user defined constraints (in <code>constraints</code>) with shorthand flags that
might be passed while using the <code>rtc.createConnection</code> helper.</p>
<h3 id="rtc-tools-monitor">rtc-tools/monitor</h3>
<pre><code>monitor(pc, targetId, signaller, parentBus) => mbus</code></pre>
<p>The monitor is a useful tool for determining the state of <code>pc</code> (an
<code>RTCPeerConnection</code>) instance in the context of your application. The
monitor uses both the <code>iceConnectionState</code> information of the peer
connection and also the various
<a href="https://github.com/rtc-io/rtc-signaller#signaller-events">signaller events</a>
to determine when the connection has been <code>connected</code> and when it has
been <code>disconnected</code>.</p>
<p>A monitor created <code>mbus</code> is returned as the result of a
<a href="https://github.com/rtc-io/rtc#rtccouple">couple</a> between a local peer
connection and it's remote counterpart.</p>
<h2 id="license-s-">License(s)</h2>
<h3 id="apache-2-0">Apache 2.0</h3>
<p>Copyright 2015 National ICT Australia Limited (NICTA)</p>
<p> Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</p>
<pre><code> http://www.apache.org/licenses/LICENSE-2.0</code></pre>
<p> Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</p>
</div>
<footer>
<p>
<a href="http://nicta.com.au">
<img src="images/nicta-logo.gif" alt="NICTA logo">
</a>© NICTA 2013 - 2014
</p>
<p class="license">Project source code is licensed under the <a href="https://github.com/rtc-io/rtc/blob/master/LICENSE">Apache 2.0</a>.</p>
<a class="closing" href="#top"></a>
</footer>
</body>
<script src="js/app.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-26567546-2', 'rtc.io');
ga('send', 'pageview');
</script>
</html>