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.

interface ImageCapture: EventTarget

readonly attribute PhotoOptions photoOptions

Describes current photo settings

readonly attribute VideoStreamTrack videoStreamTrack

The MediaStream passed into the constructor

attribute EventHandler onphoto

Register/unregister for photo events of type BlobEvent. The handler should expect to get a BlobEvent object as its first parameter.

attribute EventHandler onerror

Register/unregister for Image Capture error events of type ImageCaptureErrorEvent. The handler should expect to get an ImageCaptureError object as its first parameter.

attribute EventHandler onoptions

Register/unregister for photo settings change events of type SettingsChangeEvent.

attribute EventHandler onframe

Register/unregister for frame capture events of type FrameGrabEvent. The handler should expect to get a FrameGrabEvent object as its first parameter.

void 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. If the UA can successfully apply the settings, then the UA must fire a SettingsChangeEvent event at the onoptions event handler (if specified). If the UA cannot successfully apply the settings, then the UA must fire an ImageCaptureErrorEvent at the ImageCapture object whose code is set to OPTIONS_ERROR.

void takePhoto ()

When the takePhoto() method of an ImageCapture object is invoked, then if the readyState of the VideoStreamTrack provided in the constructor is not "live", the UA must fire an ImageCaptureErrorEvent event at the ImageCapture object with a new ImageCaptureError object whose code 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 fire an ImageCaptureErrorEvent event at the ImageCapture object with a new ImageCaptureError 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:

1. Gather data from the VideoStreamTrack 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. Raise a BlobEvent event containing the Blob to the onphoto event handler (if specified).

void grabFrame()

When the grabFrame() method of an ImageCapture object is invoked, then if the readyState of the VideoStreamTrack provided in the contructor is not "live", the UA must fire an ImageCaptureErrorEvent event at the ImageCapture object with a new ImageCaptureError object whose code is set to INVALID_TRACK. If the UA is unable to execute the grabFrame() method for any other reason, then the UA must fire an ImageCaptureErrorEvent event at the ImageCapture object with a new ImageCaptureError object whose code 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 VideoStreamTrack 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 VideoStreamTrack.
2. Raise a FrameGrabEvent event containing the ImageData to the onframe event handler (if specified). {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 code 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.

const unsigned short FRAME_ERROR=1

An ImageCaptureError object must set its code value to this constant if an error occurred upon invocation of the grabFrame() method of the ImageCapture interface.

const unsigned short OPTIONS_ERROR=2

An ImageCaptureError object must set its code value to this constant if an error occurred upon invocation of the setOptions() method of the ImageCapture interface.

const unsigned short PHOTO_ERROR=3

An ImageCaptureError object must set its code value to this constant if an error occurred upon invocation of the takePhoto() method of the ImageCapture interface.

const unsigned short ERROR_UNKNOWN=4

An ImageCaptureError object must set its code value to this constant if an error occurred due to indeterminate cause upon invocation of any method of the ImageCapture interface.

readonly attribute unsigned short code

The code attribute returns the appropriate code for the error event, derived from the constants defined in the ImageCaptureError interface.

readonly attribute DOMString message

The message attribute must return an error message describing the details of the error encountered.

    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 captureDevice = new ImageCapture(videoDevice);
          if (captureDevice) {
                captureDevice.onphoto = showPicture;
                if (captureDevice.photoOptions.redEyeReduction) {
                   captureDevice.setOptions({redEyeReductionSetting:true});
                   }
                else
                   console.log('No red eye reduction');
                captureDevice.onoptions = function(){
                   if (captureDevice.photoOptions.redEyeReduction.value)
                       captureDevice.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 captureDevice = new ImageCapture(videoDevice);
          if (captureDevice) {
                captureDevice.onframe = processFrame;
                captureDevice.grabFrame();
                }
            }

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

    <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.getTrackByID()[0];
          // Check if this device supports a picture mode...
          var captureDevice = new ImageCapture(videoDevice);
          var frameVar;
          if (captureDevice) {
                captureDevice.onframe = processFrame;
                frameVar = setInterval(captureDevice.grabFrame(), 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>