Copyright © 2012-2013 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document specific the takePhoto() method and corresponding camera settings or use with MediaStreams 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 Media Capture Task Force as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-media-capture@w3.org (subscribe, archives). All feedback is welcome.
Publication as an Editor's 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 a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes 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.
FrameGrabEventFrameGrabErrorEventBlobEventPhotoErrorEventSettingsChangeEventSettingsErrorEventMediaSettingsRangeMediaSettingsItemPhotoSettingsOptionsWhiteBalanceModeEnumExposureModeEnumPhotoSettingsFrameErrorPhotoErrorThe API defined in this document taks a valid MediaStream and returns an encoded image in the form of a Blob (as defined in [FILE-API]). The image is
provided by the capture device that provides the MediaStream. Moreover,
picture-specific settings can be optionally provided as arguments that can be applied to the image being captured.
[Constructor(MediaStreamTrack track)]
interface ImageCapture : EventTarget {
readonly attribute PhotoSettingsOptions photoSettingsOptions;
readonly attribute MediaStreamTrack videoStreamTrack;
attribute EventHandler onphoto;
attribute EventHandler onphotoerror;
attribute EventHandler onphotosettingschange;
attribute EventHandler onphotosettingserror;
attribute EventHandler onframegrab;
attribute EventHandler onframegraberror;
void setPhotoSettings (PhotoSettings? photoSettings);
void takePhoto ();
void clearFrameGrabber ();
void getFrame ();
void frameGrabber ();
};onframegrab of type EventHandlerFrameGrabEvent. The handler should expect to get a FrameGrabEvent object as its first parameter.onframegraberror of type EventHandlerFrameGrabErrorEvent.onphoto of type EventHandlerBlobEvent. The handler should expect to get a BlobEvent object as its first parameter.onphotoerror of type EventHandlerPhotoErrorEvent. The handler should expect to get a PhotoError object as its first parameter.onphotosettingschange of type EventHandlerSettingsChangeEvent.onphotosettingserror of type EventHandlerSettingsErrorEvent.photoSettingsOptions of type PhotoSettingsOptions, readonlyvideoStreamTrack of type MediaStreamTrack, readonlyclearFrameGrabberframeGrabber() method has been successfully invoked previously, the UA must
immediately terminate the corresponding process. Otherwise the method must immediately return without further action taking
place.voidframeGrabberframeGrabber() method of an ImageCapture object is invoked, then if the MediaStreamTrack provided in the contructor does not have the
kind attribute set to "video" or if the MediaStreamTrack's readyState is not "live", the UA must fire a FrameGrabErrorEvent event at the ImageCapture object with a
new FrameError object whose code is set to INVALID_TRACK. If the UA is unable to execute the frameGrabber() method for any
other reason, then the UA must fire a FrameGrabErrorEvent event at the ImageCapture object with a
new FrameError object whose code is set to FRAME_GRAB_ERROR. Otherwise it must
queue a task, using the DOM manipulation task source, that starts a process
where the following steps are executed every time a new frame of image data is available:
MediaStreamTrack into a ImageData object (as defined in [CANVAS-2D]) containing a single still frame in RGBA format. The width and height of the
ImageData object are derived from the constraints of the MediaStreamTrack. FrameGrabEvent event containing the ImageData to the onframegrab event handler (if specified).voidgetFramegetFrame() method of an ImageCapture object is invoked, then if the MediaStreamTrack provided in the contructor does not have the
kind attribute set to "video" or if the MediaStreamTrack's readyState is not "live", the UA must fire a FrameGrabErrorEvent event at the ImageCapture object with a
new FrameError object whose code is set to INVALID_TRACK. If the UA is unable to execute the getFrame() method for any
other reason, then the UA must fire a FrameGrabErrorEvent event at the ImageCapture object with a
new FrameError object whose code is set to FRAME_GRAB_ERROR. Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
MediaStreamTrack into a ImageData object (as defined in [CANVAS-2D]) containing a single still frame in RGBA format. The width and height of the
ImageData object are derived from the constraints of the MediaStreamTrack. FrameGrabEvent event containing the ImageData to the onframegrab event handler (if specified). {Note: Unlike frameGrabber(), getFrame() returns data only once upon being invoked.}voidsetPhotoSettingssetPhotoSettings() method of an ImageCapture object is invoked, then
then a valid PhotoSettings object must be passed in the method to the
ImageCapture object. If the UA can successfully apply the settings, then the UA must fire a SettingsChangeEvent event at the
onphotosettingschange event handler (if specified). If the UA cannot successfully apply the settings, then the UA
must fire a SettingsErrorEvent at the ImageCapture object. | Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| photoSettings | | ✔ | ✘ |
voidtakePhototakePhoto() method of an ImageCapture object is invoked,
then if the MediaStreamTrack provided in the contructor does not have the
kind attribute set to "video" or if the MediaStreamTrack's readyState is not "live", the UA must fire a PhotoErrorEvent event at the ImageCapture object with a
new PhotoError object whose code is set to INVALID_TRACK. If the UA is unable to execute the takePhoto() method for any
other reason, then the UA must fire a PhotoErrorEvent event at the ImageCapture object with a
new PhotoError object whose code is set to PHOTO_ERROR.
Otherwise it must
queue a task, using the DOM manipulation task source, that runs the following steps:
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. BlobEvent event containing the Blob to the onphoto event handler (if specified).voidFrameGrabEvent[Constructor(DOMString type, optional FrameGrabEventInit frameGrabInitDict)]
interface FrameGrabEvent : Event {
readonly attribute ImageData imageData;
};imageData of type ImageData, readonlyImageData object whose length and height attributes indicates the dimensions of the captured frame. FrameGrabEventInit Dictionarydictionary FrameGrabEventInit : EventInit {
ImageData imageData;
};FrameGrabEventInit MembersimageData of type ImageDataImageData object containing the data to deliver via this event.FrameGrabErrorEvent[Constructor(DOMString type, optional FrameGrabErrorEventInit frameGrabErrorInitDict)]
interface FrameGrabErrorEvent : Event {
readonly attribute FrameError frameError;
};frameError of type FrameError, readonlyFrameError object whose code attribute indicates the type of error occurrence. FrameGrabErrorEventInit Dictionarydictionary FrameGrabErrorEventInit : EventInit {
FrameError frameError;
};FrameGrabErrorEventInit MembersframeError of type FrameErrorFrameError object containing the data to deliver via this event.BlobEvent[Constructor(DOMString type, optional BlobEventInit blobInitDict)]
interface BlobEvent : Event {
readonly attribute Blob data;
};data of type Blob, readonlyBlob object whose type attribute indicates the encoding of the blob data. An implementation must return a Blob in a format that is capable of being viewed in an HTML <img> tag. BlobEventInit Dictionarydictionary BlobEventInit : EventInit {
Blob data;
};BlobEventInit Membersdata of type BlobBlob object containing the data to deliver via this event.PhotoErrorEvent[Constructor(DOMString type, optional PhotoErrorEventInit photoErrorInitDict)]
interface PhotoErrorEvent : Event {
readonly attribute PhotoError photoError;
};photoError of type PhotoError, readonlyPhotoError object whose code attribute indicates the type of error occurrence. PhotoErrorEventInit Dictionarydictionary PhotErrorEventInit : EventInit {
PhotoError photoError;
};PhotErrorEventInit MembersphotoError of type PhotoErrorphotoError object containing the data to deliver via this event.SettingsChangeEvent[Constructor(DOMString type, optional SettingsChangeEventInit photoSettingsInitDict)]
interface PhotoSettingsEvent : Event {
readonly attribute PhotoSettings photoSettings;
};photoSettings of type PhotoSettings, readonlyPhotoSettings object whose type attribute indicates the current photo settings. SettingsChangeEventInit Dictionarydictionary SettingsChangeEventInit : EventInit {
PhotoSettings photoSettings;
};SettingsChangeEventInit MembersphotoSettings of type PhotoSettingsPhotoSettings object containing the data to deliver via this event.SettingsErrorEvent[Constructor(DOMString type, optional SettingsErrorEventInit photoSettingsInitDict)]
interface SettingsErrorEvent : Event {
readonly attribute PhotoSettings photoSettings;
};photoSettings of type PhotoSettings, readonlyPhotoSettings object whose type attribute indicates the current photo settings. SettingsErrorEventInit Dictionarydictionary SettingsErrorEventInit : EventInit {
PhotoSettings photoSettings;
};SettingsErrorEventInit MembersphotoSettings of type PhotoSettingsPhotoSettings object containing the data to deliver via this event.MediaSettingsRangeinterface MediaSettingsRange {
readonly attribute unsigned long max;
readonly attribute unsigned long min;
readonly attribute unsigned long initial;
};initial of type unsigned long, readonlymax of type unsigned long, readonlymin of type unsigned long, readonlyMediaSettingsItemThe MediaSettingsItem interface is now defined, which allows for a single setting to be managed.
interface MediaSettingsItem {
readonly attribute any value;
};value of type any, readonlyPhotoSettingsOptionsThe PhotoSettingsOptions attribute of the ImageCapture object provides
the photo-specific settings options and current settings values.
interface PhotoSettingsOptions {
attribute MediaSettingsItem whiteBalanceMode;
attribute MediaSettingsItem autoExposureMode;
attribute MediaSettingsRange exposureCompensation;
attribute MediaSettingsRange iso;
attribute MediaSettingsItem redEyeReduction;
attribute MediaSettingsRange brightness;
attribute MediaSettingsRange constrast;
attribute MediaSettingsRange saturation;
attribute MediaSettingsRange sharpness;
attribute MediaSettingsRange imageHeight;
attribute MediaSettingsRange imageWidth;
};autoExposureMode of type MediaSettingsItemExposureModeEnum.brightness of type MediaSettingsRangeconstrast of type MediaSettingsRangeexposureCompensation of type MediaSettingsRangeimageHeight of type MediaSettingsRangeimageWidth of type MediaSettingsRangeiso of type MediaSettingsRangeredEyeReduction of type MediaSettingsItemsaturation of type MediaSettingsRangesharpness of type MediaSettingsRangewhiteBalanceMode of type MediaSettingsItemWhiteBalanceModeEnum.WhiteBalanceModeEnumenum WhiteBalanceModeEnum {
"auto",
"incandescent",
"fluorescent",
"warm-fluorescent",
"daylight",
"cloudy-daylight",
"twilight",
"shade"
};| Enumeration description | |
|---|---|
auto | auto |
incandescent | 2500-3500 Kelvin |
fluorescent | 4000-5000 Kelvin |
warm-fluorescent | 5000-5500 Kelvin |
daylight | 5000-6500 Kelvin |
cloudy-daylight | 6500-8000 Kelvin |
twilight | 8000-9000 Kelvin |
shade | 9000-10000 Kelvin |
ExposureModeEnumenum ExposureModeEnum {
"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 |
PhotoSettings
The PhotoSettings object is optionally passed into the ImageCapture.setPhotoSettings() method
in order to modify capture device settings specific to still imagery. Each of the attributes in this object
are optional.
dictionary PhotoSettings {
attribute any whiteBalanceModeSetting;
attribute any autoExposureModeSetting;
attribute unsigned long exposureCompensationSetting;
attribute unsigned long isoSetting;
attribute boolean redEyeReductionSetting;
attribute unsigned long brightnessSetting;
attribute unsigned long constrastSetting;
attribute unsigned long saturationSetting;
attribute unsigned long sharpnessSetting;
attribute unsigned long imageHeightSetting;
attribute unsigned long imageWidthSetting;
};PhotoSettings MembersautoExposureModeSetting of type attribute anyExposureModeEnum.brightnessSetting of type attribute unsigned longconstrastSetting of type attribute unsigned longexposureCompensationSetting of type attribute unsigned longimageHeightSetting of type attribute unsigned longimageWidthSetting of type attribute unsigned longisoSetting of type attribute unsigned longredEyeReductionSetting of type attribute booleansaturationSetting of type attribute unsigned longsharpnessSetting of type attribute unsigned longwhiteBalanceModeSetting of type attribute anyWhiteBalanceModeEnum.FrameError
The FrameError object is passed to an onframegraberror event handler of an
ImageCapture object if an error occurred when the getFrame() method was invoked.
interface FrameError {
readonly attribute unsigned short code;
const unsigned short FRAME_GRAB_ERROR = 0;
const unsigned short INVALID_TRACK = 1;
};code of type unsigned short, readonlyFRAME_GRAB_ERROR of type unsigned shortcode for when an error occurred while capturing the frameINVALID_TRACK of type unsigned shortcode for when the MediaStreamTrack is not suitable for frame capturePhotoError
The PhotoError object is passed to an onphotoerror event handler of an
ImageCapture object if an error occurred when the takePhoto() method was invoked.
interface PhotoError {
readonly attribute unsigned short code;
const unsigned short PHOTO_ERROR = 0;
const unsigned short INVALID_TRACK = 1;
};code of type unsigned short, readonlyINVALID_TRACK of type unsigned shortcode for when the MediaStreamTrack is not suitable for image capturePHOTO_ERROR of type unsigned shortcode for when an error occurred while capturing the imagenavigator.getUserMedia({video: true}, gotMedia, failedToGetMedia);
function gotMedia(mediastream) {
//Extract video track. 'kind' attribute not checked because stream was created with video option only.
var videoDevice = mediastream.getTrackByID()[0];
// Check if this device supports a picture mode...
var pictureDevice = new ImageCapture(videoDevice);
if (pictureDevice) {
pictureDevice.onphoto = showPicture;
if (pictureDevice.photoSettingsOptions.redEyeReduction) {
pictureDevice.setPhotoSettings({redEyeReductionSetting:true});
}
else
console.log('No red eye reduction');
pictureDevice.onphotosettingschange = function(){
if (pictureDevice.photoSettingsOptions.redEyeReduction.value)
pictureDevice.takePhoto();
}
}
}
function showPicture(e) {
var img = document.querySelector("img");
img.src = URL.createObjectURL(e.data);
}
function failedToGetMedia{
console.log('Stream failure');
}navigator.getUserMedia({video: true}, gotMedia, failedToGetMedia);
function gotMedia(mediastream) {
//Extract video track. 'kind' attribute not checked because stream was created with video option only.
var videoDevice = mediastream.getTrackByID()[0];
// Check if this device supports a picture mode...
var pictureDevice = new ImageCapture(videoDevice);
if (pictureDevice) {
pictureDevice.onframegrab = processFrame;
pictureDevice.getFrame();
}
}
function processFrame(e) {
imgData = e.imageData;
width = imgData.width;
height = imgData.height;
for (j=3; j < imgData.length; 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.length; j++)
{
newImg.data[j] = imgData.data[j];
}
// ... and do something with the modified image ...
}
function failedToGetMedia{
console.log('Stream failure');
}