JPEGCam v1.0.11

LICENCE

Webcam library for capturing JPEG images and submitting to a server Copyright (c) 2008 - 2009 Joseph Huckaby jhuckaby@goldcartridge.com Copyright (c) 2011 - 2012 Matt Clements matt@mattclements.co.uk Licensed under the GNU Lesser Public License http://www.gnu.org/licenses/lgpl.html

CONTRIBUTIONS

Original Version: Joseph Huckaby
Ongoing Support: Matt Clements
onAllow Functionality: Liyan Chang
Additional Changes: Richard Nicholls

OVERVIEW

JPEGCam is a simple, JavaScript and Flash library that allows you to enable your users to submit Webcam snapshots to your server in JPEG format. The Flash movie is variable-sized, and has no visible user interface controls. All commands sent to the movie are done so from JavaScript, so you can implement your own look & feel on your site, create your own buttons, and tell the Flash movie what to do from your own code.

REQUIREMENTS

JavaScript-enabled browser
Flash Player 9+

EMBEDDING IN YOUR PAGE

(For a working example, see "test.html" in the htdocs folder.)

First, copy the following files to your web server:

webcam.js
webcam.swf
shutter.mp3

Next, edit your HTML and load the JavaScript library:

<script type="text/javascript" src="webcam.js"></script>

Configure a few settings (see API CALLS for complete list):

<script language="JavaScript">
	webcam.set_api_url( 'test.php' );
	webcam.set_quality( 90 ); // JPEG quality (1 - 100)
	webcam.set_shutter_sound( true ); // play shutter click sound
</script>

Load the movie into the page. If you want to load the movie immediately, simply use document.write() as shown below. If you are designing a DHTML application, you can call webcam.get_html(...) at any time to dynamically populate a DIV or other element after the page is finished loading.

<script language="JavaScript">
	document.write( webcam.get_html(320, 240) );
</script>

Add some controls for sending commands to the movie (see API CALLS):

<br/><form>
	<input type=button value="Configure..." onClick="webcam.configure()">
	&nbsp;&nbsp;&nbsp;
	<input type=button value="Take Snapshot" onClick="webcam.snap()">
</form>

Finally, add some code for handling the server response:

<script language="JavaScript">
	webcam.set_hook( 'onComplete', 'my_callback_function' );
	function my_callback_function(response) {
		alert("Success! PHP returned: " + response);
	}
</script>

That's it! See the following sections for a complete list of all the available API calls, and how to write the server-side code.

API CALLS

Here are all the available API calls for the JPEGCam JavaScript library. Everything is under a top-level global 'webcam' namespace.

webcam.set_hook( HOOK_NAME, USER_FUNCTION );

This allows you to set a user callback function that will be fired for
various events in the JPEGCam system.  Here are all the events you 
can hook:

onLoad
	Fires when the Flash movie is loaded on the page.  This is useful
	for knowing when the movie is ready to receive scripting calls. Your 
	functions will be passed the initial allow state.

onAllow
	Fires when the 'Allow' option has been selected.
	
onComplete
	Fires when the JPEG upload is complete.
	Your function will be passed the raw output from the API script 
	that received the file upload, as the first argument.

onError
	Fires when an error occurs.  If this hook is not defined, the library
	will display a simple JavaScript alert dialog.  Your function will be
	passed the error text as the first argument.

webcam.set_api_url( URL );

This allows you to set the URL to your server-side script that will 
receive the JPEG uploads from the Flash movie. Beware of cross-domain 
restrictions in Flash.

webcam.set_swf_url( URL );

This allows you to set the URL to the location of the "webcam.swf" Flash
movie on your server.  It is recommended to keep this file in the same
directory as your HTML page, but if that is not possible, set the path
using this function.  Beware of cross-domain restrictions in Flash.
The default is the current directory that your HTML page lives in.

webcam.set_quality( QUALITY );

This allows you to adjust the JPEG compression quality of the images 
taken from the camera.  The range is 1 - 100, with 1 being the lowest
quality (but smallest size files), to 100 being the highest quality
(but largest files).  This does NOT control the resolution of the images,
only the JPEG compression.  The default is 90.

webcam.set_shutter_sound( ENABLED, [ URL ] );

This allows you to enable or disable the "shutter" sound effect that 
the Flash movie makes when a snapshot is taken.  Pass in a boolean
true or false to the function.  It defaults to true.  If set to false
the sound effect will not even be loaded.

You can optionally pass a second argument to this function, which 
should be a URL (relative to page or fully qualified) to an MP3
sound effect for the shutter sound.  This defaults to 'shutter.mp3'
in the current directory relative to the HTML page.

These values cannot be changed after get_html() is called (see below).

webcam.get_html( WIDTH, HEIGHT, [SERVER_WIDTH, SERVER_HEIGHT] );

This returns the necessary HTML code to embed the Flash movie into your
page.  Pass in the desired pixel width & height, which not only controls
the visual size of the movie, but also the JPEG image width & height.
Standard sizes are 320x240 and 640x480.

You can optionally pass a desired server image width and height.  If 
these differ from the video width and height, the captured images will 
be resized to match just prior to upload.

webcam.snap();

This instructs the Flash movie to take a snapshot and upload the JPEG
to the server.  Make sure you set the URL to your API script using 
webcam.set_api_url(), and have a callback function ready to receive
the results from the server, using webcam.set_hook().

webcam.configure( PANEL );

This launches one of Flash's configuration panels, used to setup camera
devices, privacy settings, and more.  Pass in one of the following strings
which sets the default panel "tab" in the settings dialog:
"camera", "privacy", "default", "localStorage", "microphone", or 
"settingsManager".  Example:

webcam.configure( 'camera' );

webcam.freeze();

Optional, new in v1.0.4.  This is not required if you use webcam.snap(),
described above.

This captures an image from the webcam but does NOT upload it.
Instead, the image is displayed "frozen" in the Flash movie, and the user 
may take further action.  For example, you may provide separate "Upload"
and "Reset" buttons to upload the frozen image and/or reset the camera.

webcam.upload();

Optional, new in v1.0.4.  This is not required if you use webcam.snap(),
described above.

This uploads the captured image to the server, previously frozen with
webcam.freeze().  This is provided as its own function so you can
have separate "Capture" and "Upload" buttons for the user.

webcam.reset();

Optional, new in v1.0.4.  This resets the frozen image, previously captured
with webcam.freeze(), and restores the live webcam feed for further
capturing.

SERVER-SIDE CODE

The Flash movie makes a HTTP POST to your server-side script, using the Content-Type 'image/jpeg'. This is a NON-STANDARD method which is unlike submitting a form from a web page. If you are using PHP, the JPEG data will NOT be in the normal $_POST variable. Instead, you should read it from the special PHP file wrapper 'php://input'. For example:

$jpeg_data = file_get_contents('php://input');

You can write this raw, binary JPEG data to a file handle using the PHP function file_put_contents():

$filename = "my_file.jpg";
$result = file_put_contents( $filename, $jpeg_data );

Any output from your script is passed back through the Flash movie to the JavaScript code, which in turn passes it to your onComplete callback function.

For example, if you want your script to pass back a URL to the JPEG image, save the file where you want it, and construct a URL to the file. Then simply print the URL to the output like this:

(This assumes you are saving the files to the current working directory)

$url = 'http://' . $_SERVER['HTTP_HOST'] . dirname($_SERVER['REQUEST_URI'])
 	. '/' . $filename;
print "$url\n";

(See "test.php" for a working example.)

FAQ

Q. I cannot see the image from my camera! What am I doing wrong?

A. You probably have to setup the camera device in the Flash Camera settings dialog first. Often Flash doesn't auto-detect the right device.

	webcam.configure( 'camera' );

It is always a good idea to provide a "Configure..." button on your page which calls this function, so users can easily get to it.

Q. What is this ugly permission dialog? Can't I just make it remember me?

A. Yes, you certainly can! In the Flash setup dialogs, click on the 2nd icon from the left (i.e. Privacy Settings), and you can click "Allow", then check the "Remember" checkbox.

You can send your users directly to the Privacy config panel by calling: webcam.configure( 'privacy' );

A cool trick is to detect "new" users (via a cookie) and register an onLoad handler to send them directly to the Privacy settings.

webcam.set_hook( 'onLoad', 'my_load_handler' );
function my_load_handler() {
	if (is_new_user())
		webcam.configure( 'privacy' );
}
	
Of course, you have to write the is_new_user() function yourself.
I no wanna be settin' no cookies on your domain.

Q. How can you detect when a user has allowed access?

A. You can detect whether webcam access has been allowed as below: