-
Notifications
You must be signed in to change notification settings - Fork 9
/
module-rtc-captureconfig.html
251 lines (229 loc) · 16.8 KB
/
module-rtc-captureconfig.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
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
<!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-captureconfig"><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-captureconfig">rtc-captureconfig</h1>
<p>This is a simple parser that takes a string of text and determines what
that means in the context of WebRTC.</p>
<p><a href="https://nodei.co/npm/rtc-captureconfig/"><img src="https://nodei.co/npm/rtc-captureconfig.png" alt="NPM"></a></p>
<p><a href="https://travis-ci.org/rtc-io/rtc-captureconfig"><img src="https://img.shields.io/travis/rtc-io/rtc-captureconfig.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="why-">Why?</h2>
<p>It provides a simple, textual way of describing your requirements for
media capture. Trying to remember the structure of the constraints object
is painful.</p>
<h2 id="how">How</h2>
<p>A simple text string is converted to an intermediate JS object
representation, which can then be converted to a getUserMedia constraints
data structure using a <code>toConstraints()</code> call.</p>
<p>For example, the following text input:</p>
<pre><code>camera min:1280x720 max:1280x720 min:15fps max:25fps</code></pre>
<p>Is converted into an intermedia representation (via the <code>CaptureConfig</code>
utility class) that looks like the following:</p>
<div class="highlight"><pre><span class="p">{</span>
<span class="nx">camera</span><span class="o">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nx">microphone</span><span class="o">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nx">res</span><span class="o">:</span> <span class="p">{</span>
<span class="nx">min</span><span class="o">:</span> <span class="p">{</span> <span class="nx">w</span><span class="o">:</span> <span class="mi">1280</span><span class="p">,</span> <span class="nx">h</span><span class="o">:</span> <span class="mi">720</span> <span class="p">},</span>
<span class="nx">max</span><span class="o">:</span> <span class="p">{</span> <span class="nx">w</span><span class="o">:</span> <span class="mi">1280</span><span class="p">,</span> <span class="nx">h</span><span class="o">:</span> <span class="mi">720</span> <span class="p">}</span>
<span class="p">},</span>
<span class="nx">fps</span><span class="o">:</span> <span class="p">{</span>
<span class="nx">min</span><span class="o">:</span> <span class="mi">15</span><span class="p">,</span>
<span class="nx">max</span><span class="o">:</span> <span class="mi">25</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
<p>Which in turn is converted into the following media constraints for
a getUserMedia call:</p>
<div class="highlight"><pre><span class="p">{</span>
<span class="nx">audio</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="nx">video</span><span class="o">:</span> <span class="p">{</span>
<span class="nx">mandatory</span><span class="o">:</span> <span class="p">{},</span>
<span class="nx">optional</span><span class="o">:</span> <span class="p">[</span>
<span class="p">{</span> <span class="nx">minFrameRate</span><span class="o">:</span> <span class="mi">15</span> <span class="p">},</span>
<span class="p">{</span> <span class="nx">maxFrameRate</span><span class="o">:</span> <span class="mi">25</span> <span class="p">},</span>
<span class="p">{</span> <span class="nx">frameRate</span><span class="o">:</span> <span class="p">{</span> <span class="nx">min</span><span class="o">:</span> <span class="mi">15</span><span class="p">,</span> <span class="nx">max</span><span class="o">:</span> <span class="mi">25</span> <span class="p">}</span> <span class="p">},</span>
<span class="p">{</span> <span class="nx">minWidth</span><span class="o">:</span> <span class="mi">1280</span> <span class="p">},</span>
<span class="p">{</span> <span class="nx">maxWidth</span><span class="o">:</span> <span class="mi">1280</span> <span class="p">},</span>
<span class="p">{</span> <span class="nx">width</span><span class="o">:</span> <span class="mi">1280</span> <span class="p">},</span>
<span class="p">{</span> <span class="nx">minHeight</span><span class="o">:</span> <span class="mi">720</span> <span class="p">},</span>
<span class="p">{</span> <span class="nx">maxHeight</span><span class="o">:</span> <span class="mi">720</span> <span class="p">},</span>
<span class="p">{</span> <span class="nx">height</span><span class="o">:</span> <span class="mi">720</span> <span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
<h3 id="experimental-targeted-device-capture">Experimental: Targeted Device Capture</h3>
<p>While the <code>rtc-captureconfig</code> module itself doesn't contain any media
identification logic, it is able to the sources information from a
<code>MediaStreamTrack.getSources</code> call to generate device targeted constraints.</p>
<p>For instance, the following example demonstrates how we can request
<code>camera:1</code> (the 2nd video device on our local machine) when we are making
a getUserMedia call:</p>
<div class="highlight"><pre><span class="c1">// load in capture config</span>
<span class="kd">var</span> <span class="nx">capture</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'rtc-captureconfig'</span><span class="p">);</span>
<span class="c1">// pull in the getusermedia helper module</span>
<span class="c1">// see: https://github.com/HenrikJoreteg/getUserMedia</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="c1">// get the sources</span>
<span class="nx">MediaStreamTrack</span><span class="p">.</span><span class="nx">getSources</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">sources</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">var</span> <span class="nx">constraints</span> <span class="o">=</span> <span class="nx">capture</span><span class="p">(</span><span class="s1">'camera:1'</span><span class="p">).</span><span class="nx">toConstraints</span><span class="p">({</span> <span class="nx">sources</span><span class="o">:</span> <span class="nx">sources</span> <span class="p">});</span>
<span class="cm">/* here is an example of what the generated constraints actually look like</span>
<span class="cm"> var constraints = {</span>
<span class="cm"> audio:true,</span>
<span class="cm"> video: {</span>
<span class="cm"> mandatory: {},</span>
<span class="cm"> optional: [</span>
<span class="cm"> { sourceId: '30a3f6408175c22df739bcbf9573d841d9f99289' }</span>
<span class="cm"> ]</span>
<span class="cm"> }</span>
<span class="cm"> };</span>
<span class="cm"> */</span>
<span class="c1">// get user media</span>
<span class="nx">getUserMedia</span><span class="p">(</span><span class="nx">constraints</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">stream</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">log</span><span class="p">(</span><span class="s1">'Could not capture stream: '</span><span class="p">,</span> <span class="nx">err</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">'captured stream: '</span><span class="p">,</span> <span class="nx">stream</span><span class="p">);</span>
<span class="p">});</span>
<span class="p">});</span>
</pre></div>
<p>It's worth noting that if the requested device does not exist on the
machine (in the case above, if your machine only has a single webcam - as
is common) then no device selection constraints will be generated (i.e.
the standard <code>{ video: true, audio: true }</code> constraints will be returned
from the <code>toConstraints</code> call).</p>
<h3 id="experimental-screen-capture">Experimental: Screen Capture</h3>
<p>If you are working with chrome and serving content of a HTTPS connection,
then you will be able to experiment with experimental getUserMedia screen
capture.</p>
<p>In the simplest case, screen capture can be invoked by using the capture
string of:</p>
<pre><code>screen</code></pre>
<p>Which generates the following contraints:</p>
<div class="highlight"><pre><span class="p">{</span>
<span class="nx">audio</span><span class="o">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nx">video</span><span class="o">:</span> <span class="p">{</span>
<span class="nx">mandatory</span><span class="o">:</span> <span class="p">{</span>
<span class="nx">chromeMediaSource</span><span class="o">:</span> <span class="s1">'screen'</span>
<span class="p">},</span>
<span class="nx">optional</span><span class="o">:</span> <span class="p">[]</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
<h2 id="reference">Reference</h2>
<h3 id="captureconfig">CaptureConfig</h3>
<p>This is a utility class that is used to update capture configuration
details and is able to generate suitable getUserMedia constraints based
on the configuration.</p>
<h4 id="camera-index-">camera(index)</h4>
<p>Update the camera configuration to the specified index</p>
<h4 id="microphone-index-">microphone(index)</h4>
<p>Update the microphone configuration to the specified index</p>
<h4 id="screen-target-">screen(target)</h4>
<p>Specify that we would like to capture the screen</p>
<h4 id="max-data-">max(data)</h4>
<p>Update a maximum constraint. If an fps constraint this will be directed
to the <code>maxfps</code> modifier.</p>
<h4 id="maxfps-data-">maxfps(data)</h4>
<p>Update the maximum fps</p>
<h4 id="min-data-">min(data)</h4>
<p>Update a minimum constraint. This can be either related to resolution
or FPS.</p>
<h4 id="minfps-data-">minfps(data)</h4>
<p>Update the minimum fps</p>
<h4 id="toconstraints-opts-">toConstraints(opts?)</h4>
<p>Convert the internal configuration object to a valid media constraints
representation. In compatible browsers a list of media sources can
be passed through in the <code>opts.sources</code> to create contraints that will
target a specific device when captured.</p>
<div class="highlight"><pre><span class="kd">var</span> <span class="nx">media</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'rtc-media'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">capture</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">'rtc-captureconfig'</span><span class="p">);</span>
<span class="c1">// get the sources</span>
<span class="nx">MediaStreamTrack</span><span class="p">.</span><span class="nx">getSources</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">sources</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// get the cameras</span>
<span class="kd">var</span> <span class="nx">cameras</span> <span class="o">=</span> <span class="nx">sources</span><span class="p">.</span><span class="nx">filter</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">info</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">info</span> <span class="o">&&</span> <span class="nx">info</span><span class="p">.</span><span class="nx">kind</span> <span class="o">===</span> <span class="s1">'video'</span><span class="p">;</span>
<span class="p">});</span>
<span class="c1">// create videos</span>
<span class="kd">var</span> <span class="nx">videos</span> <span class="o">=</span> <span class="nx">cameras</span><span class="p">.</span><span class="nx">map</span><span class="p">(</span><span class="kd">function</span><span class="p">(</span><span class="nx">info</span><span class="p">,</span> <span class="nx">idx</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">media</span><span class="p">(</span><span class="nx">capture</span><span class="p">(</span><span class="s1">'camera:'</span> <span class="o">+</span> <span class="nx">idx</span><span class="p">).</span><span class="nx">toConstraints</span><span class="p">({</span> <span class="nx">sources</span><span class="o">:</span> <span class="nx">sources</span> <span class="p">}));</span>
<span class="p">});</span>
<span class="c1">// render the videos</span>
<span class="nx">videos</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">vid</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">vid</span><span class="p">.</span><span class="nx">render</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="p">});</span>
<span class="p">});</span>
</pre></div>
<h3 id="-internal-methods">"Internal" methods</h3>
<h4 id="_parseres-data-">_parseRes(data)</h4>
<p>Parse a resolution specifier (e.g. 1280x720) into a simple JS object
(e.g. { w: 1280, h: 720 })</p>
<h2 id="license-s-">License(s)</h2>
<h3 id="apache-2-0">Apache 2.0</h3>
<p>Copyright 2014 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>