The Capture API

1.1 Usage Examples

The following code extracts illustrate how to work with a camera service in the hosting device:

function success(data) {
  var container = document.createElement("div");
  document.body.appendChild(container);
  
  for (var i in data) {
    var img = document.createElement("img");
    img.src = data[i].uri;
    container.appendChild(img);
  }
}
 
function error(err) {
  alert(err.message + " (" + err.code + ")"); 
}
 
navigator.device.captureImage(success, error, { maxNumberOfMediaFiles: 1 });

var summary,

formats = navigator.device.supportedImageFormats;

for (var key in formats) {
  summary += key + ": " + formats[key] + "\n";
}

alert(summary);

3.1 Capture interface

The Capture interface exposes an interface to the camera and microphone of the hosting device.

Objects implementing the NavigatorDevice interface (e.g. the window.navigator.device object in Web browsers [NAVIGATOR]) provide access to the Capture interface through the Capture interface. An instance of Capture would be then obtained by using binding-specific casting methods on an instance of NavigatorDevice.

[Supplemental, NoInterfaceObject]
interface Capture {
    readonly attribute FormatData[] supportedImageFormats;
    readonly attribute FormatData[] supportedVideoFormats;
    readonly attribute FormatData[] supportedAudioFormats;
    PendingOperation captureImage (in CaptureCB successCB, in optional CaptureErrorCB? errorCB, in optional CaptureImageOptions options);
    PendingOperation captureVideo (in CaptureCB successCB, in optional CaptureErrorCB? errorCB, in optional CaptureVideoOptions options);
    PendingOperation captureAudio (in CaptureCB successCB, in optional CaptureErrorCB? errorCB, in optional CaptureAudioOptions options);
    PendingOperation getViewFinder (in ViewFinderCB successCB, in optional ViewFinderErrorCB? errorCB);
};

3.2 MediaFile interface

MediaFile captures a single photo, video or sound captured by the device native capture application. It inherits from File [FILE-API]

[NoInterfaceObject]
interface MediaFile : File {
    attribute FormatData format;
};

3.3 FormatData interface

FormatData captures format information of a media file captured by the device native capture application.

[NoInterfaceObject]
interface FormatData {
    attribute DOMString     type;
    attribute unsigned long height;
    attribute double        duration;
    attribute unsigned long width;
};

3.4 CaptureCB interface

[Callback=FunctionOnly, NoInterfaceObject]
interface CaptureCB {
    void onSuccess (in MediaArray capturedMedia);
};

3.5 MediaArray typedef

The MediaArray typedef represents a sequence of MediaFile objects.

typedef sequence<MediaFile> MediaArray;

3.6 CaptureErrorCB interface

[Callback=FunctionOnly, NoInterfaceObject]
interface CaptureErrorCB {
    void onError (in CaptureError error);
};

3.7 ViewFinderCB interface

[Callback=FunctionOnly, NoInterfaceObject]
interface ViewFinderCB {
    void onSuccess (in ViewFinder viewfinder);
};

3.8 ViewFinderErrorCB interface

[Callback=FunctionOnly, NoInterfaceObject]
interface ViewFinderErrorCB {
    void onError (in CaptureError error);
};

3.9 CaptureError interface

The CaptureError interface encapsulates all errors in the Capture API.

More error codes to be defined here.

[NoInterfaceObject]
interface CaptureError {
    const unsigned short CAPTURE_INTERNAL_ERR = 0;
    readonly attribute unsigned short code;
};

3.10 CaptureImageOptions interface

The CaptureImageOptions interface encapsulates all image capture operation configuration options.

Additional attributes proposed: width and height.

[NoInterfaceObject]
interface CaptureImageOptions {
    attribute unsigned long maxNumberOfMediaFiles;
};

3.11 CaptureVideoOptions interface

[NoInterfaceObject]
interface CaptureVideoOptions {
    attribute unsigned long maxNumberOfMediaFiles;
    attribute double        duration;
};

3.12 CaptureAudioOptions interface

Additional attributes proposed: duration.

[NoInterfaceObject]
interface CaptureAudioOptions {
    attribute unsigned long maxNumberOfMediaFiles;
};

3.13 PendingOperation interface

This may be a general interface for use throughout all APIs. Included here for now for completion.

[NoInterfaceObject]
interface PendingOperation {
    void cancel ();
};

3.14 ViewFinder interface

This interface represents a camera viewfinder. It inherits from File [FILE-API] and provides a method to embed a viewfinder to web content.

[NoInterfaceObject]
interface ViewFinder : File {
    void startCapture (in Blob data);
    void stopCapture ();
};

4.1 Capture aware file-select control

This section is non-normative.

If input element in the File Upload state [HTML5] contains accept attribute with values image/*, sound/*, or video/*, the user agent can invoke a file picker that allows respectively the user to take a picture, record a sound file, or record a video in addition to selecting an existing file from the file system.

See the User Interface Examples appendix for the illustration.

In case the user chooses to capture video, audio, or image content, the user agent creates media files on the fly as specified in [HTML5].

<input id="cameraInput" type="file" accept="image/*"> 

In trusted environments the click event of file input element can be synthesised as follows:

<input id="cameraInput" onchange="successCB();" type="file" accept="image/*"> 

<script>

function successCB() {
  // Read the image using file-reader or submit the form
}

document.getElementById('cameraInput').click();

</script>

4.2 ViewFinder aware file-select control

Conforming user agents must provide the user a file picker from which it is possible to select any of the available capture devices in addition to possibility to select one or more files from the file system.

If a user selects camera device, the FileList object that represents the currently selected files in the input element in the File Upload state must contain one ViewFinder object instead of File objects as in [FILE-API].

<script>

  function getVideo () {
    var inp = document.createElement("input");
    inp.type = "file";
    inp.accept = "video/*";
    inp.onchange = function () { setupVideo(this.files[0]); };
    // this is only possible in trusted environments
    // the click event cannot be synthetized by default
    inp.click();
  }

  var blob;

  function setupVideo (vf) {
    document.getElementById("my-video").src = vf.URL;
	var bb = new BlobBuilder();
    blob = bb.getBlob();
    document.getElementById("start").onclick = function () { vf.startCapture(bb.getBlob()); }
    document.getElementById("stop").onclick = function () { vf.stopCapture(); }
    document.getElementById("send").onclick = function () { send(); }
  }

  function send () {
    if (!blob) {
       alert("You didn't capture anything!")
       return;
    }
    var xhr = new XMLHttpRequest();
    xhr.open("GET", "http://my-server/video-upload");
    xhr.onreadystatechange = function () {
      if (xhr.readyState == 4 && xhr.status == 200) alert("Video uploaded!");
    }
    xhr.send(blob);
  }
</script>

<button onclick='getVideo();'>Film your face!</button>
<video id='my-video'></video>
<button id='start'>Start</button>
<button id='stop'>Stop</button>
<button id='send'>Upload</button>