Skip to content

Commit 819f1dd

Browse files
jhuckabyjhuckaby
committed
Initial checkin.
1 parent b336819 commit 819f1dd

18 files changed

+1990
-4
lines changed

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2014 Joseph Huckaby
3+
Copyright (c) 2012 - 2014 Joseph Huckaby
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy of
66
this software and associated documentation files (the "Software"), to deal in

‎README.md

+210-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,211 @@
1-
webcamjs
2-
========
1+
# WebcamJS
32

4-
HTML5 Webcam Image Capture Library with Flash Fallback
3+
## HTML5 Webcam Image Capture Library with Flash Fallback
4+
5+
WebcamJS is a small (~2K minified and gzipped) standalone JavaScript library for capturing still images from your computer's camera, and delivering them to you as JPEG or PNG [http://en.wikipedia.org/wiki/Data_URI_scheme](Data URIs). The images can then be displayed in your web page, rendered into a canvas, or submitted to your server via a standard form. WebcamJS uses [http://dev.w3.org/2011/webrtc/editor/getusermedia.html](HTML5 getUserMedia), but provides an automatic and invisible Flash fallback.
6+
7+
WebcamJS is based on my old [https://code.google.com/p/jpegcam/](JPEGCam) project, but has been redesigned for the modern web. Instead of relying on Flash and only being able to submit images directly to a server, WebcamJS delivers your images as client-side Data URIs, and it uses HTML5 getUserMedia where available. Flash is only used if your browser doesn't support getUserMedia, and the fallback is handled automatically.
8+
9+
[http://pixlcore.com/demos/webcamjs/basic.html](Check out a live demo here!)
10+
11+
## QuickStart Guide
12+
13+
Host the `webcam.js` and `webcam.swf` files on your web server, and drop in this HTML snippet:
14+
15+
```html
16+
<script src="webcam.js"></script>
17+
18+
<div id="my_camera" style="width:320px; height:240px;"></div>
19+
<div id="my_result"></div>
20+
21+
<script language="JavaScript">
22+
Webcam.attach( '#my_camera' );
23+
24+
function take_snapshot() {
25+
var data_uri = Webcam.snap();
26+
document.getElementById('my_result').innerHTML = '<img src="'+data_uri+'"/>';
27+
}
28+
</script>
29+
30+
<a href="javascript:void(take_snapshot())">Take Snapshot</a>
31+
```
32+
33+
This will create a live camera view in the `my_camera` DIV, and when the **Take Snapshot** link is clicked it will take a still snapshot, convert it to a JPEG, and deliver a Data URI which is inserted into the `my_result` DIV as a standard `<IMG SRC>` tag.
34+
35+
Data URIs may be passed around like any URL, and can be submitted to your server by stuffing them into a form field (see below for example of this).
36+
37+
## Configuration
38+
39+
If you want to override the default settings, just call `Webcam.set()` and pass in a hash with any of the following keys:
40+
41+
| Param Name | Default Value | Notes |
42+
--------------------------------------
43+
| `width` | (Auto) | Width of the live camera viewer in pixels, defaults to the actual size of the DOM element. |
44+
| `height` | (Auto) | Height of the live camera viewer in pixels, defaults to the actual size of the DOM element. |
45+
| `dest_width` | (Auto) | Width of the captured camera image in pixels, defaults to the live viewer size. |
46+
| `dest_height` | (Auto) | Height of the captured camera image in pixels, defaults to the live viewer size. |
47+
| `image_format` | jpeg | Desired image format of captured image, may be "jpeg" or "png". |
48+
| `jpeg_quality` | 90 | For JPEG images, this is the desired quality, from 0 (worst) to 100 (best). |
49+
50+
Here is an example of overriding some parameters. Remember to call this *before* you attach the viewer.
51+
52+
```javascript
53+
Webcam.set({
54+
width: 320,
55+
height: 240,
56+
dest_width: 640,
57+
dest_height: 480,
58+
image_format: 'jpeg',
59+
jpeg_quality: 90
60+
});
61+
62+
// Attach camera here
63+
```
64+
65+
## Initialization
66+
67+
WebcamJS is initialized and activated by "attaching" a live camera viewer to a DOM element. The DOM element must already be created and empty. Pass in a ID or CSS selector to the `Webcam.attach()` function. Example:
68+
69+
```javascript
70+
Webcam.attach( '#my_camera' );
71+
```
72+
73+
This will activate the user's webcam, ask for the appropriate permission, and begin showing a live camera image in the specified DOM element.
74+
75+
## Snapping a Picture
76+
77+
To snap a picture, just call the `Webcam.snap()` function. The image data will be returned as a Data URI, which you can then display in your web page, or submit to a server. Example:
78+
79+
```javascript
80+
var data_uri = Webcam.snap();
81+
82+
document.getElementById('my_result').innerHTML = '<img src="'+data_uri+'"/>';
83+
```
84+
85+
## Customizing Image Size
86+
87+
WebcamJS will automatically size the live camera viewer based on the DOM element it is attached to. However, you can override this by setting the `width` and/or `height` parameters:
88+
89+
```javascript
90+
Webcam.set({
91+
width: 320,
92+
height: 240
93+
});
94+
95+
// Attach camera here
96+
```
97+
98+
The size of the captured JPEG / PNG image is set to match the live camera viewer by default. However, you can override this by setting the `dest_width` and/or `dest_height`. Note that you can set the destination image size different than the viewer size. So you can have a small live viewer, but capture a large image. Example:
99+
100+
```javascript
101+
Webcam.set({
102+
width: 320,
103+
height: 240,
104+
dest_width: 640,
105+
dest_height: 480,
106+
});
107+
108+
// Attach camera here
109+
```
110+
111+
## Setting an Alternate SWF Location
112+
113+
By default WebcamJS looks for the SWF file in the same directory as the JS file. If you are hosting the SWF in a different location, please set it using the `Webcam.setSWFLocation()` function. Example:
114+
115+
```javascript
116+
Webcam.setSWFLocation("/path/to/the/webcam.swf");
117+
```
118+
119+
## Reset (Shutdown)
120+
121+
To shut down the live camera preview and reset the system, call `Webcam.reset()`. This removes any DOM elements we added, including a Flash movie if applicable, and resets everything in the library to the initial state. Example:
122+
123+
```javascript
124+
Webcam.reset();
125+
```
126+
127+
To use the library again after resetting, you must call `Webcam.attach()` and pass it your DOM element.
128+
129+
## Custom Events
130+
131+
WebcamJS fires a number of events you can intercept using a JavaScript hook system. Events are fired when the library is fully loaded, when the camera is live, and when an error occurs. To register an event listener, call the `Webcam.on()` function, passing an event name and callback function. Here is a table of the available event types:
132+
133+
| Event Name | Notes |
134+
--------------------------------------
135+
| `load` | Fires when the library finishes loading. |
136+
| `live` | Fires when the user's camera goes live (i.e. showing a live preview). |
137+
| `error` | Fires when an error occurs (your callback function is passed an error string). |
138+
139+
Example:
140+
141+
```javascript
142+
Webcam.on( 'load', function() {
143+
// library is loaded
144+
} );
145+
146+
Webcam.on( 'live', function() {
147+
// camera is live, showing preview image
148+
} );
149+
150+
Webcam.on( 'error', function(err) {
151+
// an error occurred (see 'err')
152+
} );
153+
```
154+
155+
By default the `error` event shows a JavaScript alert dialog, but if you register your own event handler this action is suppressed, and your function is called instead.
156+
157+
## Submitting Images to a Server
158+
159+
WebcamJS delivers your images by way of a client-side JavaScript Data URI. The binary image data is encoded with Base64 and stuffed into the URI. It is up to you to send this data to your server and decode it. There are many ways to do this, but here is the easiest.
160+
161+
First, add a hidden text element to a form:
162+
163+
```html
164+
<form id="myform" method="post" action="myscript.php">
165+
<input id="mydata" type="hidden" name="mydata" value=""/>
166+
</form>
167+
```
168+
169+
Then, when you snap your picture, stuff the Data URI into the form field value (minus the header), and submit the form:
170+
171+
```javascript
172+
var data_uri = Webcam.snap();
173+
var raw_image_data = data_uri.replace(/^data\:image\/\w+\;base64\,/, '');
174+
175+
document.querySelector('#mydata').value = raw_image_data;
176+
document.querySelector('#myform').submit();
177+
```
178+
179+
Finally, on your server, grab the form data as if it were a plain text field, decode the Base64, and you have your binary image file. Example here in PHP, assumes JPEG format:
180+
181+
```php
182+
$encoded_data = $_POST['mydata'];
183+
$binary_data = base64_decode( $encoded_data );
184+
185+
// save to server (beware of permissions)
186+
$result = file_put_contents( 'webcam.jpg', $binary_data );
187+
if (!$result) die("Could not save image! Check file permissions.");
188+
```
189+
190+
## License
191+
192+
The MIT License (MIT)
193+
194+
Copyright (c) 2012 - 2014 Joseph Huckaby
195+
196+
Permission is hereby granted, free of charge, to any person obtaining a copy of
197+
this software and associated documentation files (the "Software"), to deal in
198+
the Software without restriction, including without limitation the rights to
199+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
200+
the Software, and to permit persons to whom the Software is furnished to do so,
201+
subject to the following conditions:
202+
203+
The above copyright notice and this permission notice shall be included in all
204+
copies or substantial portions of the Software.
205+
206+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
207+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
208+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
209+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
210+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
211+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎htdocs/demos/basic.html

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<!doctype html>
2+
3+
<html lang="en">
4+
<head>
5+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6+
<title>WebcamJS Test Page</title>
7+
<style type="text/css">
8+
body { font-family: Helvetica, sans-serif; }
9+
h2, h3 { margin-top:0; }
10+
form { margin-top: 15px; }
11+
form > input { margin-right: 15px; }
12+
#results { float:right; margin:20px; padding:20px; border:1px solid; background:#ccc; }
13+
</style>
14+
</head>
15+
<body>
16+
<div id="results">Your captured image will appear here...</div>
17+
18+
<h1>WebcamJS Test Page</h1>
19+
<h3>Demonstrates simple capture &amp; display</h3>
20+
21+
<div id="my_camera" style="width:320px; height:240px;"></div>
22+
23+
<!-- First, include the Webcam.js JavaScript Library -->
24+
<script type="text/javascript" src="../webcam.js"></script>
25+
26+
<!-- Configure a few settings and attach camera -->
27+
<script language="JavaScript">
28+
Webcam.set({
29+
image_format: 'jpeg',
30+
jpeg_quality: 90
31+
});
32+
Webcam.attach( '#my_camera' );
33+
</script>
34+
35+
<!-- A button for taking snaps -->
36+
<form>
37+
<input type=button value="Take Snapshot" onClick="take_snapshot()">
38+
</form>
39+
40+
<!-- Code to handle taking the snapshot and displaying it locally -->
41+
<script language="JavaScript">
42+
function take_snapshot() {
43+
// take snapshot and get image data
44+
var data_uri = Webcam.snap();
45+
46+
// display results in page
47+
document.getElementById('results').innerHTML =
48+
'<h2>Here is your image:</h2>' +
49+
'<img src="'+data_uri+'"/>';
50+
}
51+
</script>
52+
53+
</body>
54+
</html>

‎htdocs/demos/hd.html

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<!doctype html>
2+
3+
<html lang="en">
4+
<head>
5+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6+
<title>WebcamJS Test Page - HD Capture</title>
7+
<style type="text/css">
8+
body { font-family: Helvetica, sans-serif; }
9+
h2, h3 { margin-top:0; }
10+
form { margin-top: 15px; }
11+
form > input { margin-right: 15px; }
12+
#results { margin:20px; padding:20px; border:1px solid; background:#ccc; }
13+
</style>
14+
</head>
15+
<body>
16+
<h1>WebcamJS Test Page - HD Capture</h1>
17+
<h3>Demonstrates 720p HD capture, if your camera supports it!</h3>
18+
19+
<div id="my_camera" style="width:1280px; height:720px;"></div>
20+
21+
<!-- First, include the Webcam.js JavaScript Library -->
22+
<script type="text/javascript" src="../webcam.js"></script>
23+
24+
<!-- Configure a few settings and attach camera -->
25+
<script language="JavaScript">
26+
Webcam.set({
27+
image_format: 'jpeg',
28+
jpeg_quality: 90
29+
});
30+
Webcam.attach( '#my_camera' );
31+
</script>
32+
33+
<!-- A button for taking snaps -->
34+
<form>
35+
<input type=button value="Take HD Snapshot" onClick="take_snapshot()">
36+
</form>
37+
38+
<!-- Code to handle taking the snapshot and displaying it locally -->
39+
<script language="JavaScript">
40+
function take_snapshot() {
41+
// take snapshot and get image data
42+
var data_uri = Webcam.snap();
43+
44+
// display results in page
45+
document.getElementById('results').innerHTML =
46+
'<h2>Here is your large image:</h2>' +
47+
'<img src="'+data_uri+'"/>';
48+
}
49+
</script>
50+
51+
<div id="results">Your captured image will appear here...</div>
52+
53+
</body>
54+
</html>

‎htdocs/demos/large.html

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
<!doctype html>
2+
3+
<html lang="en">
4+
<head>
5+
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6+
<title>WebcamJS Test Page - Large Capture</title>
7+
<style type="text/css">
8+
body { font-family: Helvetica, sans-serif; }
9+
h2, h3 { margin-top:0; }
10+
form { margin-top: 15px; }
11+
form > input { margin-right: 15px; }
12+
#results { float:right; margin:20px; padding:20px; border:1px solid; background:#ccc; }
13+
</style>
14+
</head>
15+
<body>
16+
<div id="results">Your captured image will appear here...</div>
17+
18+
<h1>WebcamJS Test Page - Large Capture</h1>
19+
<h3>Demonstrates large capture with small display</h3>
20+
21+
<div id="my_camera" style="width:320px; height:240px;"></div>
22+
23+
<!-- First, include the Webcam.js JavaScript Library -->
24+
<script type="text/javascript" src="../webcam.js"></script>
25+
26+
<!-- Configure a few settings and attach camera -->
27+
<script language="JavaScript">
28+
Webcam.set({
29+
dest_width: 640,
30+
dest_height: 480,
31+
image_format: 'jpeg',
32+
jpeg_quality: 90
33+
});
34+
Webcam.attach( '#my_camera' );
35+
</script>
36+
37+
<!-- A button for taking snaps -->
38+
<form>
39+
<input type=button value="Take Large Snapshot" onClick="take_snapshot()">
40+
</form>
41+
42+
<!-- Code to handle taking the snapshot and displaying it locally -->
43+
<script language="JavaScript">
44+
function take_snapshot() {
45+
// take snapshot and get image data
46+
var data_uri = Webcam.snap();
47+
48+
// display results in page
49+
document.getElementById('results').innerHTML =
50+
'<h2>Here is your large image:</h2>' +
51+
'<img src="'+data_uri+'"/>';
52+
}
53+
</script>
54+
55+
</body>
56+
</html>

0 commit comments

Comments
 (0)