1. Introduction

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.

2. Image Capture API

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 ();
};

3. ImageCaptureError

[NoInterfaceObject]
interface ImageCaptureError {
    readonly        attribute DOMString? errorDescription;
};

4. 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:

1. White balance mode is a setting that cameras use to adjust for different color temperatures. Color temperature is the temperature of background light (measured in Kelvin normally). This setting can also be automatically determined by the implementation. If 'automatic' mode is selected, then the Kelvin setting for White Balance Mode may be overridden. Typical temprature ranges for different modes are provided below:

   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

2. Exposure is the amount of light allowed to fall on the photographic medium. Auto-exposure mode is a camera setting where the exposure levels are automatically adjusted by the implementation based on the subject of the photo.
3. Exposure Compensation is a numeric camera setting that adjusts the exposure level from the current value used by the implementation. This value can be used to bias the exposure level enabled by auto-exposure.
4. The ISO setting of a camera describes the sensistivity of the camera to light. It is a numeric value, where the lower the value the greater the sensitivity. This setting in most implementations relates to shutter speed, and is sometimes known as the ASA setting.
5. Red Eye Reduction is a feature in cameras that is designed to limit or prevent the appearance of red pupils ("Red Eye") in photography subjects due prolonged exposure to a camera's flash.
6. Brightness refers to the numeric camera setting that adjusts the perceived amount of light emitting from the photo object. A higher brightness setting increases the intensity of darker areas in a scene while compressing the intensity of brighter parts of the scene.
7. Contrast is the numeric camera setting that controls the difference in brightness between light and dark areas in a scene. A higher contrast setting reflects an expansion in the difference in brightness.
8. Saturation is a numeric camera setting that controls the intensity of color in a scene (i.e. the amount of gray in the scene). Very low saturation levels will result in photo's closer to black-and-white.
9. Sharpness is a numeric camera setting that controls the intensity of edges in a scene. Higher sharpness settings result in higher edge intensity, while lower settings result in less contrast and blurrier edges (i.e. soft focus).
10. Zoom is a numeric camera setting that controls the focal length of the lens. The setting usually represents a ratio, e.g. 4 is a zoom ratio of 4:1. The minimum value is usually 1, to represent a 1:1 ratio (i.e. no zoom).
11. Fill light mode describes the flash setting of the capture device.
12. Focus mode describes the focus setting of the capture device.

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;
};

5. 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;
};

6. MediaSettingsRange

interface MediaSettingsRange {
    readonly        attribute unsigned long max;
    readonly        attribute unsigned long min;
    readonly        attribute unsigned long current;
};

7. MediaSettingsItem

The MediaSettingsItem interface is now defined, which allows for a single setting to be managed.

interface MediaSettingsItem {
    readonly        attribute any value;
};

8. ExposureMode

enum ExposureMode {
    "frame-average",
    "center-weighted",
    "spot-metering"
};

9. FillLightMode

enum FillLightMode {
    "unavailable",
    "auto",
    "off",
    "flash",
    "on"
};

10. FocusMode

enum FocusMode {
    "unavailable",
    "auto",
    "manual"
};

11. Examples

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>