The 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.

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 an exception will be thrown.

interface ImageCapture

readonly attribute PhotoCapabilities photoCapabilities

Describes current photo settings

readonly attribute MediaStreamTrack videoStreamTrack

The MediaStreamTrack passed into the constructor

readonly attribute MediaStream previewStream

The MediaStream that provides a camera preview

Promise setOptions(PhotoSettings? photoSettings)

When the setOptions() method of an ImageCapture object is invoked, then a valid PhotoSettings object must be passed in the method to the ImageCapture object. In addition, a new Promise object is returned. If the UA can successfully apply the settings, then the UA must return a SettingsChangeEvent event to the resolver object's resolve() method. If the UA cannot successfully apply the settings, then the UA must return an ImageCaptureErrorEvent to the resolver object's reject() method whose errorDescription is set to OPTIONS_ERROR.

Promise takePhoto ()

When the takePhoto() method of an ImageCapture object is invoked, a new Promise object is returned. If the readyState of the VideoStreamTrack provided in the constructor is not "live", the UA must return an ImageCaptureErrorEvent event to the resolver object's reject() method with a new ImageCaptureError object whose errorDescription is set to INVALID_TRACK. If the UA is unable to execute the takePhoto() method for any other reason (for example, upon invocation of multiple takePhoto() method calls in rapid succession), then the UA must return an ImageCaptureErrorEvent event to the resolver object's reject() method with a new ImageCaptureError object whose errorDescription is set to PHOTO_ERROR. Otherwise it must queue a task, using the DOM manipulation task source, that runs the following steps:

1. Gather data from the 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.
2. Return a BlobEvent event containing the Blob to the resolver object's resolve() method.

Promise grabFrame()

When the grabFrame() method of an ImageCapture object is invoked, a new Promise object is returned. If the readyState of the MediaStreamTrack provided in the contructor is not "live", the UA must return an ImageCaptureErrorEvent event to the resolver object's reject() method with a new ImageCaptureError object whose errorDescription is set to INVALID_TRACK. If the UA is unable to execute the grabFrame() method for any other reason, then the UA must return an ImageCaptureErrorEvent event to the resolver object's reject() method with a new ImageCaptureError object whose errorDescription is set to FRAME_ERROR. Otherwise it must queue a task, using the DOM manipulation task source, that runs the following steps:

1. Gather data from the MediaStreamTrack into an 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. The method of doing this will depend on the underlying device. Devices may temporarily stop streaming data, reconfigure themselves with the appropriate photo settings (which may be a subset of the settings provided in photoCapabilities), take the photo (and convert to an ImageData object), 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.
2. Return a FrameGrabEvent event containing the ImageData to the resolver object's resolve() method. {Note: grabFrame() returns data only once upon being invoked.}

readonly attribute ImageData imageData

Returns an ImageData object whose width and height attributes indicates the dimensions of the captured frame.

ImageData imageData

An ImageData object containing the data to deliver via this event.

readonly attribute ImageCaptureError imageCaptureError

Returns an ImageCaptureError object whose errorDescription attribute indicates the type of error occurrence.

ImageCaptureError imageCaptureError

an ImageCaptureError object containing the data to deliver via this event.

readonly attribute Blob data

Returns a Blob 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.

Blob data

A Blob object containing the data to deliver via this event.

readonly attribute PhotoSettings photoSettings

Returns a PhotoSettings object whose type attribute indicates the current photo settings.

PhotoSettings photoSettings

A PhotoSettings object containing the data to deliver via this event.

The ImageCaptureError object is passed to an onerror event handler of an ImageCapture object if an error occurred when the object was created or any of its methods were invoked.

readonly attribute DOMString? errorDescription

The errorDescription attribute returns the appropriate DOMString for the error event. Acceptable values are FRAME_ERROR, OPTIONS_ERROR, PHOTO_ERROR, and ERROR_UNKNOWN.

    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) {
                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>