Added optional constraints custom parameter for user media, with docs.

jhuckaby · Aug 23, 2015 · 89afa2f · 89afa2f
1 parent bfd4d00
commit 89afa2f
Show file tree

Hide file tree

Showing 7 changed files with 110 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -387,11 +387,43 @@ Finally, in your server-side script, grab the form data as if it were a plain fo
 	if (!$result) die("Could not save image!  Check file permissions.");
 ```
 
+## Custom User Media Constraints (Advanced)
+
+The HTML5 getUserMedia API has a constraints system by which you can specify optional or mandatory requirements for the video stream.  These include things such a minimum or maximum resolution and/or framerate.  By default, WebcamJS will specify a mandatory minimum width and height, matching your `dest_width` and `dest_height` parameters.  However, if you want to customize this, you can set a `constraints` parameter using `Webcam.set()`, and pass in an object containing all the custom constraints you want.  Example:
+
+```javascript
+	Webcam.set( 'constraints', {
+		mandatory: {
+			minWidth: 1280,
+			minHeight: 720,
+			minFrameRate: 30
+		},
+		optional: [
+			{ minFrameRate: 60 }
+		]
+	} );
+```
+
+To remove the mandatory constraints and instead just specify the resolution you would prefer, you can set simple `width` and `height` properties like this:
+
+```javascript
+	Webcam.set( 'constraints', {
+		width: 1280,
+		height: 720
+	} );
+```
+
+Please call this this before calling `Webcam.attach()`.
+
+Note that some browsers may not support every possible constraint, so consult your browser's documentation and test in all your supported browsers before using this advanced feature.  For example, as of this writing Chrome 44 doesn't support framerate constraints.
+
+For more information see the [Media Capture Spec](http://w3c.github.io/mediacapture-main/getusermedia.html#idl-def-Constraints) and the [WebRTC Constraints Spec](http://tools.ietf.org/id/draft-alvestrand-constraints-resolution-00.html).
+
 ## License
 
 The MIT License (MIT)
 
-Copyright (c) 2012 - 2014 Joseph Huckaby
+Copyright (c) 2012 - 2015 Joseph Huckaby
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

diff --git a/bower.json b/bower.json
@@ -1,6 +1,6 @@
 {
   "name": "webcamjs",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "homepage": "https://github.com/jhuckaby/webcamjs",
   "authors": [
     "Joseph Huckaby <[email protected]>"

diff --git a/build.sh b/build.sh
@@ -3,4 +3,4 @@
 # Build Script for WebcamJS
 # Install uglifyjs first: sudo npm install uglify-js -g
 
-uglifyjs webcam.js -o webcam.min.js --mangle --reserved "Webcam" --preamble "// WebcamJS v1.0.3 - http://github.com/jhuckaby/webcamjs - MIT Licensed"
+uglifyjs webcam.js -o webcam.min.js --mangle --reserved "Webcam" --preamble "// WebcamJS v1.0.4 - http://github.com/jhuckaby/webcamjs - MIT Licensed"
diff --git a/demos/constraints.html b/demos/constraints.html
@@ -0,0 +1,66 @@
+<!doctype html>
+
+<html lang="en">
+<head>
+	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+	<title>WebcamJS Constraints Test Page</title>
+	<style type="text/css">
+		body { font-family: Helvetica, sans-serif; }
+		h2, h3 { margin-top:0; }
+		form { margin-top: 15px; }
+		form > input { margin-right: 15px; }
+		#results { float:right; margin:20px; padding:20px; border:1px solid; background:#ccc; }
+	</style>
+</head>
+<body>
+	<div id="results">Your captured image will appear here...</div>
+
+	<h1>WebcamJS Constraints Test Page</h1>
+	<h3>Demonstrates using the HTML5 user media constraints object</h3>
+
+	<div id="my_camera"></div>
+
+	<!-- First, include the Webcam.js JavaScript Library -->
+	<script type="text/javascript" src="../webcam.js"></script>
+
+	<!-- Configure a few settings and attach camera -->
+	<script language="JavaScript">
+		Webcam.set({
+			width: 320,
+			height: 240,
+			image_format: 'jpeg',
+			jpeg_quality: 90,
+			constraints: {
+				mandatory: {
+					minWidth: 320,
+					minHeight: 240
+					// minFrameRate: 30
+				},
+				optional: [
+					{ minFrameRate: 60 }
+				]
+			}
+		});
+		Webcam.attach( '#my_camera' );
+	</script>
+
+	<!-- A button for taking snaps -->
+	<form>
+		<input type=button value="Take Snapshot" onClick="take_snapshot()">
+	</form>
+
+	<!-- Code to handle taking the snapshot and displaying it locally -->
+	<script language="JavaScript">
+		function take_snapshot() {
+			// take snapshot and get image data
+			Webcam.snap( function(data_uri) {
+				// display results in page
+				document.getElementById('results').innerHTML = 
+					'<h2>Here is your image:</h2>' + 
+					'<img src="'+data_uri+'"/>';
+			} );
+		}
+	</script>
+
+</body>
+</html>
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "webcamjs",
-	"version": "1.0.3",
+	"version": "1.0.4",
 	"description": "HTML5 Webcam Image Capture Library with Flash Fallback",
 	"author": "Joseph Huckaby <[email protected]>",
 	"homepage": "https://github.com/jhuckaby/webcamjs",

diff --git a/webcam.js b/webcam.js
@@ -1,4 +1,4 @@
-// WebcamJS v1.0.3
+// WebcamJS v1.0.4
 // Webcam library for capturing JPEG/PNG images in JavaScript
 // Attempts getUserMedia, falls back to Flash
 // Author: Joseph Huckaby: http://github.com/jhuckaby
@@ -9,7 +9,7 @@
 (function(window) {
 
 var Webcam = {
-	version: '1.0.3',
+	version: '1.0.4',
 
 	// globals
 	protocol: location.protocol.match(/https/i) ? 'https' : 'http',
@@ -28,7 +28,8 @@ var Webcam = {
 		force_flash: false,   // force flash mode,
 		flip_horiz: false,    // flip image horiz (mirror mode)
 		fps: 30,              // camera frames per second
-		upload_name: 'webcam' // name of file in upload post data
+		upload_name: 'webcam', // name of file in upload post data
+		constraints: null     // custom user media constraints
 	},
 
 	hooks: {}, // callback hook functions
@@ -122,15 +123,11 @@ var Webcam = {
 			var self = this;
 			navigator.getUserMedia({
 				"audio": false,
-				"video": {
+				"video": this.params.constraints || {
 					mandatory: {
 						minWidth: this.params.dest_width,
 						minHeight: this.params.dest_height
-					}/* ,
-					frameRate: {
-						ideal: this.params.fps,
-						max: this.params.fps
-					} */
+					}
 				}
 			}, 
 			function(stream) {

diff --git a/webcam.min.js b/webcam.min.js