Copyright © 2012-2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This document specifies the takePhoto() and grabFrame() methods, and corresponding camera settings for use with MediaStreamTracks as defined in Media Capture and Streams [GETUSERMEDIA].
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
Comments on this document are welcomed.
This document was published by the Device and Sensors Working Group and the Web Real-Time Communications Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-media-capture@w3.org (subscribe, archives). All comments are welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (Device and Sensors Working Group) and a public list of any patent disclosures (Web Real-Time Communications Working Group) made in connection with the deliverables of each group; these pages also include instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
The API defined in this document captures images from a valid MediaStreamTrack. The produced image can be in the form of a Blob
(as defined in [FILE-API]) or as an ImageBitmap
(as defined in [HTML51])). The source image is provided by the capture device that provides the MediaStreamTrack. Moreover, picture-specific settings can be optionally provided as arguments that can be applied to the device for the capture.
The User Agent must support Promises in order to implement the Image Capture API. Any Promise object is assumed to have resolver object, with resolve() and reject() methods associated with it. The MediaStreamTrack
passed to the constructor must have its kind
attribute set to "video
" otherwise a DOMException
of type NotSupportedError
will be thrown.
[Constructor(MediaStreamTrack track)]
interface ImageCapture {
readonly attribute MediaStreamTrack videoStreamTrack;
readonly attribute MediaStream previewStream;
[Throws]
Promise<PhotoCapabilities
> getPhotoCapabilities ();
[Throws]
Promise<void> setOptions (PhotoSettings
? photoSettings);
[Throws]
Promise<Blob> takePhoto ();
[Throws]
Promise<ImageBitmap> grabFrame ();
};
previewStream
of type MediaStream, readonly videoStreamTrack
of type MediaStreamTrack, readonly getPhotoCapabilities
getPhotoCapabilities()
ImageCapture
PromisegetPhotoCapabilities()
MediaStreamTrack
mustImageCaptureError
errorDescription
must
MediaStreamTrack
into a PhotoCapabilities
object containing the available capabilities of the device, including ranges where appropriate. The resolved PhotoCapabilities
will also include the current conditions in which the capabilities of the device are found. The method of doing this will depend on the underlying device. PhotoCapabilities
object.Promise<PhotoCapabilities
>
grabFrame
grabFrame()
ImageCapture
PromisereadyState
MediaStreamTrack
mustImageCaptureError
errorDescription
grabFrame()
mustImageCaptureError
errorDescription
must
MediaStreamTrack
into an ImageBitmap
object (as defined in [HTML51]). The width
and height
of the ImageBitmap
object are derived from the constraints of the MediaStreamTrack
. ImageBitmap
object. (Note: grabFrame()
returns data only once upon being invoked).Promise<ImageBitmap>
setOptions
setOptions()
ImageCapture
PhotoSettings
mustImageCapture
PromisemustmustImageCaptureError
errorDescription
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
photoSettings |
|
✔ | ✘ |
Promise<void>
takePhoto
takePhoto()
ImageCapture
PromisereadyState
VideoStreamTrack
mustImageCaptureError
errorDescription
takePhoto()
mustImageCaptureError
errorDescription
must
MediaStreamTrack
into a Blob
containing a single still image. The method of doing this will depend on the underlying device. Devices may temporarily stop streaming data, reconfigure themselves with the appropriate photo settings, take the photo, and then resume streaming. In this case, the stopping and restarting of streaming should cause mute
and unmute
events to fire on the Track in question. Promise<Blob>
ImageCaptureError
[NoInterfaceObject]
interface ImageCaptureError {
readonly attribute DOMString? errorDescription;
};
errorDescription
of type DOMString, readonly , nullableerrorDescription
PhotoCapabilities
The PhotoCapabilities
interface provides the photo-specific settings options and current settings values. The following definitions are assumed for individual settings and are provided for information purposes:
Mode | Kelvin range |
---|---|
incandescent | 2500-3500 |
fluorescent | 4000-5000 |
warm-fluorescent | 5000-5500 |
daylight | 5500-6500 |
cloudy-daylight | 6500-8000 |
twilight | 8000-9000 |
shade | 9000-10000 |
interface PhotoCapabilities {
attribute Boolean autoWhiteBalanceMode;
attribute MediaSettingsRange
whiteBalanceMode;
attribute ExposureMode
autoExposureMode;
attribute MediaSettingsRange
exposureCompensation;
attribute MediaSettingsRange
iso;
attribute Boolean redEyeReduction;
attribute MediaSettingsRange
brightness;
attribute MediaSettingsRange
contrast;
attribute MediaSettingsRange
saturation;
attribute MediaSettingsRange
sharpness;
attribute MediaSettingsRange
imageHeight;
attribute MediaSettingsRange
imageWidth;
attribute MediaSettingsRange
zoom;
attribute FillLightMode
fillLightMode;
attribute FocusMode
focusMode;
};
autoExposureMode
of type ExposureMode
ExposureMode
autoWhiteBalanceMode
of type Booleanbrightness
of type MediaSettingsRange
contrast
of type MediaSettingsRange
exposureCompensation
of type MediaSettingsRange
fillLightMode
of type FillLightMode
FillLightMode
focusMode
of type FocusMode
FocusMode
imageHeight
of type MediaSettingsRange
imageWidth
of type MediaSettingsRange
iso
of type MediaSettingsRange
redEyeReduction
of type Booleansaturation
of type MediaSettingsRange
sharpness
of type MediaSettingsRange
whiteBalanceMode
of type MediaSettingsRange
WhiteBalanceModeEnum
zoom
of type MediaSettingsRange
PhotoSettings
The PhotoSettings
object is optionally passed into the ImageCapture.setOptions()
method in order to modify capture device settings specific to still imagery. Each of the attributes in this object are optional.
dictionary PhotoSettings {
boolean autoWhiteBalanceMode;
unsigned long whiteBalanceMode;
ExposureMode
autoExposureMode;
unsigned long exposureCompensation;
unsigned long iso;
boolean redEyeReduction;
unsigned long brightness;
unsigned long contrast;
unsigned long saturation;
unsigned long sharpness;
unsigned long zoom;
unsigned long imageHeight;
unsigned long imageWidth;
FillLightMode
fillLightMode;
FocusMode
focusMode;
};
PhotoSettings
MembersautoExposureMode
of type ExposureMode
ExposureMode
.autoWhiteBalanceMode
of type booleanbrightness
of type unsigned longcontrast
of type unsigned longexposureCompensation
of type unsigned longfillLightMode
of type FillLightMode
FillLightMode
.focusMode
of type FocusMode
FocusMode
.imageHeight
of type unsigned longimageWidth
of type unsigned longiso
of type unsigned longredEyeReduction
of type booleansaturation
of type unsigned longsharpness
of type unsigned longwhiteBalanceMode
of type unsigned longzoom
of type unsigned longMediaSettingsRange
interface MediaSettingsRange {
readonly attribute unsigned long max;
readonly attribute unsigned long min;
readonly attribute unsigned long current;
};
current
of type unsigned long, readonly max
of type unsigned long, readonly min
of type unsigned long, readonly MediaSettingsItem
The MediaSettingsItem
interface is now defined, which allows for a single setting to be managed.
interface MediaSettingsItem {
readonly attribute any value;
};
value
of type any, readonly ExposureMode
enum ExposureMode {
"frame-average",
"center-weighted",
"spot-metering"
};
Enumeration description | |
---|---|
frame-average |
Average of light information from entire scene |
center-weighted |
Sensitivity concentrated towards center of viewfinder |
spot-metering |
Spot-centered weighting |
FillLightMode
enum FillLightMode {
"unavailable",
"auto",
"off",
"flash",
"on"
};
Enumeration description | |
---|---|
unavailable |
This source does not have an option to change fill light modes (e.g., the camera does not have a flash) |
auto |
The video device's fill light will be enabled when required (typically low light conditions). Otherwise it will be off. Note that auto does not guarantee that a flash will fire when takePhoto is called. Use flash to guarantee firing of the flash for the takePhoto() or getFrame() methods. |
off |
The source's fill light and/or flash will not be used. |
flash |
This value will always cause the flash to fire for the takePhoto() or getFrame() methods. |
on |
The source's fill light will be turned on (and remain on) while the source MediaStreamTrack is active |
FocusMode
enum FocusMode {
"unavailable",
"auto",
"manual"
};
Enumeration description | |
---|---|
unavailable |
This source does not have an option to change focus modes. |
auto |
Auto-focus mode is enabled. |
manual |
Manual focus mode is enabled. |
navigator.mediaDevices.getUserMedia({video: true}).then(gotMedia, failedToGetMedia);
function gotMedia(mediastream) {
//Extract video track.
var videoDevice = mediastream.getVideoTracks()[0];
// Check if this device supports a picture mode...
var captureDevice = new ImageCapture(videoDevice);
if (captureDevice) {
captureDevice.grabFrame().then(processFrame(imgData));
}
}
function processFrame(e) {
imgData = e.imageData;
width = imgData.width;
height = imgData.height;
for (j=3; j < imgData.width; j+=4)
{
// Set all alpha values to medium opacity
imgData.data[j] = 128;
}
// Create new ImageObject with the modified pixel values
var canvas = document.createElement('canvas');
ctx = canvas.getContext("2d");
newImg = ctx.createImageData(width,height);
for (j=0; j < imgData.width; j++)
{
newImg.data[j] = imgData.data[j];
}
// ... and do something with the modified image ...
}
}
function failedToGetMedia{
console.log('Stream failure');
}
navigator.getUserMedia({video: true}, gotMedia, failedToGetMedia);
function gotMedia(mediastream) {
//Extract video track.
var videoDevice = mediastream.getVideoTracks()[0];
// Check if this device supports a picture mode...
var captureDevice = new ImageCapture(videoDevice);
if (captureDevice) {
if (captureDevice.photoCapabilities.redEyeReduction) {
captureDevice.setOptions({redEyeReductionSetting:true})
.then(captureDevice.takePhoto()
.then(showPicture(blob),function(error){alert("Failed to take photo");}));
}
else
console.log('No red eye reduction');
}
}
function showPicture(e) {
var img = document.querySelector("img");
img.src = URL.createObjectURL(e.data);
}
function failedToGetMedia{
console.log('Stream failure');
}
<html>
<body>
<p><canvas id="frame"></canvas></p>
<button onclick="stopFunction()">Stop frame grab</button>
<script>
var canvas = document.getElementById('frame');
navigator.getUserMedia({video: true}, gotMedia, failedToGetMedia);
function gotMedia(mediastream) {
//Extract video track.
var videoDevice = mediastream.getVideoTracks()[0];
// Check if this device supports a picture mode...
var captureDevice = new ImageCapture(videoDevice);
var frameVar;
if (captureDevice) {
frameVar = setInterval(captureDevice.grabFrame().then(processFrame()), 1000);
}
}
function processFrame(e) {
imgData = e.imageData;
canvas.width = imgData.width;
canvas.height = imgData.height;
canvas.getContext('2d').drawImage(imgData, 0, 0,imgData.width,imgData.height);
}
function stopFunction(e) {
clearInterval(myVar);
}
</script>
</body>
</html>