Mediastream Image Capture

Table of Contents

• 1. Introduction
• 2. Image Capture API
  • 2.1 Attributes
  • 2.2 Methods
• 3. PhotoEvent
  • 3.1 Attributes
• 4. MediaSettingsRange
  • 4.1 Attributes
• 5. MediaSettingsItem
  • 5.1 Attributes
• 6. PhotoSettingsOptions
  • 6.1 Attributes
• 7. WhiteBalanceModeEnum
• 8. ExposureModeEnum
• 9. PhotoSettings
  • 9.1 Attributes
• 10. PhotoError
  • 10.1 Attributes
  • 10.2 Constants
• 11. Example: Taking a picture if Red Eye Reduction is activated
• A. References
  • A.1 Normative references

1. Introduction

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.

2. Image Capture API

interface ImageCapture : EventTarget {
    readonly attribute PhotoSettingsOptions photoSettingsOptions;
             attribute MediaStream          stream;
             attribute EventHandler         onphoto;
             attribute EventHandler         onphotoerror;
             attribute EventHandler         onphotosettingschange;
             attribute EventHandler         onphotosettingserror;
    void setPhotoSettings (PhotoSettings photoSettings);
    void takePhoto (optional DOMString trackID);
};

3. PhotoEvent

interface PhotoEvent : Event {
    readonly attribute Blob data;
};

4. MediaSettingsRange

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

5. MediaSettingsItem

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

interface MediaSettingsItem {
    readonly attribute any value;
};

6. PhotoSettingsOptions

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

7. WhiteBalanceModeEnum

enum WhiteBalanceModeEnum {
    "auto",
    "incandescent",
    "fluorescent",
    "warm-fluorescent",
    "daylight",
    "cloudy-daylight",
    "twilight",
    "shade"
};

8. ExposureModeEnum

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

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

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

10. PhotoError

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 DEVICE_UNAVAILABLE = 1;
};

11. Example: Taking a picture if Red Eye Reduction is activated

navigator.getUserMedia({video: true}, gotMedia, failedToGetMedia);

function gotMedia(mediastream) {
   var videoDevice = mediastream.videoTracks[0];
   // Check if this device supports a picture mode...
   var pictureDevice = new ImageCapture();
   if (pictureDevice) {
         pictureDevice.onphoto = showPicture;
         if (pictureDevice.photoSettingsOptions.redEyeReduction) {
            pictureDevice.setPhotoSettings({redEyeReductionSetting:true});
            }
         else
            console.log('No red eye reduction');
         pictureDevice.onphotosettingschange = function(){
            currentRedEye = new Boolean;
            currentRedEye = false;
            if (pictureDevice.photoSettingsOptions.redEyeReduction)
                currentRedEye = pictureDevice.photoSettingsOptions.redEyeReduction.value;
            if (currentRedEye == true)
                pictureDevice.takePhoto();
            }
         }
     }

 function showPicture(e) {
    var img = document.querySelector("img");
    img.src = URL.createObjectURL(e.data);
    }

 function failedToGetMedia{
    console.log('Stream failure');
    }