Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document represents the early consensus of the group on the scope and features of the proposed Capture API. Issues and editors notes in the document highlight some of the points on which the group is still working and would particularly like to get feedback.
This document was published by the Device APIs and Policy Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
The Capture API defines a high-level interface for accessing the microphone and camera of a hosting device. It completes the HTML Form Based Media Capturing specification [HTMLMEDIACAPTURE] with a programmatic access to start a parametrized capture process.
The following code extracts illustrate how to work with a camera service in the hosting device:
Launching a camera application and retrieving the pictures taken.
function success(data) { var container = document.createElement("div"); for (var i in data) { var img = document.createElement("img"); img.src = data[i].url; container.appendChild(img); } document.body.appendChild(container); } function error(err) { if (err.code === err.CAPTURE_INTERNAL_ERR) { alert("The capture failed due to an internal error."); } else { alert("Other error occured."); } } navigator.device.capture.captureImage(success, error, { limit: 1 });
Example of retrieving image sizes and formats supported by hosting device camera.
var summary; formats = navigator.device.capture.supportedImageFormats; for (var key in formats) { summary += key + ": " + formats[key] + "\n"; } alert(summary);
The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made to this API to reflect requirements or support for privacy-related functionality.
The API defined in this specification launches the capture application which allows the user to take pictures, record voice or record video and provides a handle to the content. This information can potentially compromise user privacy and a conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism should ensure that such operations must not happen without user consent.
A conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism should ensure that privacy information is not revealed without user's informed consent.
Note that there is a minimization issue with EXIF headers. Implementations are assumed to avoid embeding information in the EXIF header which could be used for non-intended purposes (such as geolocation or device id).
DeviceCapture interfaceThe DeviceCapture interface is exposed on the navigator.device object, as defined in [CORE-DEVICE].
Device implements DeviceCapture;[NoInterfaceObject]
interface DeviceCapture {
readonly attribute Capture capture;
};
capture of type Capture, readonlyCapture interfaceThe Capture interface exposes an interface to the camera and microphone of the hosting device.
The MediaFileData Interface contains a duration attribute. What does it mean here? Is it the max recording length?.
Should the default audio, video, and image codec be defined that all implementations need to support? If yes, which codecs should be selected?
Duration and bitrate attributes of MediaFileData object make no sense in case of supportedImageFormats. Use of more well suited interface to be considered.
[Supplemental, NoInterfaceObject]
interface Capture {
readonly attribute MediaFileData[] supportedImageFormats;
readonly attribute MediaFileData[] supportedVideoFormats;
readonly attribute MediaFileData[] 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);
};
supportedAudioFormats of type array of MediaFileData, readonlysupportedImageFormats of type array of MediaFileData, readonlysupportedVideoFormats of type array of MediaFileData, readonlycaptureAudioLaunch audio recorder application for recording audio clip(s).
This method takes two or three arguments. When called, it
immediately returns a
PendingOperation object and then asynchronously
start a capture audio process defined as follows:
successCB
with a FileList [FILE-API]
argument. If the attempt fails, and the method was invoked with a
non-null errorCallback argument, this method must invoke
the errorCallback with a CaptureError object as
an argument.CaptureAudioOptions parameter was present,
and its limit attribute was defined,
successCB must be invoked after the user has
captured a number of audio clips defined in
limit. If user exited the audio recorder
application prematurely without recording any audio clips, errorCB must be invoked.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| successCB | | ✘ | ✘ | Function to call when the asynchronous operation completes |
| errorCB | | ✘ | ✔ | Function to call when the asynchronous operation fails. This parameter is optional. |
| options | | ✘ | ✔ | Audio capture options. This parameter is optional. |
PendingOperationcaptureImageLaunch camera application for taking image(s).
This method takes two or three arguments. When called, it
immediately returns a PendingOperation
object and then asynchronously start a capture image
process defined as follows:
successCB
with a FileList [FILE-API]
argument. If the attempt fails, and the method was invoked with a
non-null errorCallback argument, this method must
invoke the errorCallback with a CaptureError object
as an argument.CaptureImageOptions parameter was present,
and its limit attribute was defined,
successCB must be invoked after the user has
captured a number of images defined in limit. If
user exited the camera application without capturing any images,
errorCB must be invoked.| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| successCB | | ✘ | ✘ | Function to call when the asynchronous operation completes |
| errorCB | | ✘ | ✔ | Function to call when the asynchronous operation fails. This parameter is optional. |
| options | | ✘ | ✔ | Image capture options. This parameter is optional. |
PendingOperationcaptureVideoLaunch device camera application for recording video(s).
This method takes three or four arguments. When called, it
immediately returns a PendingOperation
object and then asynchronously start a capture video process
defined as follows:
successCB with a FileList
[FILE-API] argument. If
the attempt fails, and the method was invoked with a non-null
errorCallback argument, this method must invoke the
errorCallback with a CaptureError object as
an argument.CaptureVideoOptions parameter was present, and
its limit attribute was defined,
successCB must be invoked after the user has
captured a number of video clips defined in
limit. If user exited the camera
application without capturing any videos, errorCB must be invoked.CaptureVideoOptions parameter was present,
and its duration attribute was defined,
successCB must be invoked after the video has
been captured for the number of seconds defined in
duration. If user exited the camcorder
application without capturing any video clips, errorCB must be invoked.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| successCB | | ✘ | ✘ | Function to call when the asynchronous operation completes |
| errorCB | | ✘ | ✔ | Function to call when the asynchronous operation fails. This parameter is optional. |
| options | | ✘ | ✔ | Image capture options. This parameter is optional. |
PendingOperationCaptureCB interface[Callback=FunctionOnly, NoInterfaceObject]
interface CaptureCB {
void onSuccess (in FileList capturedMedia);
};
onSuccess| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| capturedMedia | FileList | ✘ | ✘ | Sequence of Files [FILE-API] (implementing the MediaFile [HTMLMEDIACAPTURE] interface) successfully captured by the device |
voidCaptureErrorCB interface[Callback=FunctionOnly, NoInterfaceObject]
interface CaptureErrorCB {
void onError (in CaptureError error);
};
onError| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| error | | ✘ | ✘ | The error object of an unsuccessful capture asynchronous operation. |
voidCaptureError interfaceThe 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;
const unsigned short CAPTURE_APPLICATION_BUSY = 1;
const unsigned short CAPTURE_INVALID_ARGUMENT = 2;
const unsigned short CAPTURE_NO_MEDIA_FILES = 3;
readonly attribute unsigned short code;
};
code of type unsigned short, readonlyCAPTURE_APPLICATION_BUSY of type unsigned shortCAPTURE_INTERNAL_ERR of type unsigned shortCAPTURE_INVALID_ARGUMENT of type unsigned shortCAPTURE_NO_MEDIA_FILES of type unsigned shortCaptureImageOptions interfaceThe CaptureImageOptions interface encapsulates all image
capture operation configuration options.
Additional attributes proposed: width
and height.
We might want to add format to give author control
over the capture format.
[NoInterfaceObject]
interface CaptureImageOptions {
attribute unsigned long limit;
};
limit of type unsigned longCaptureVideoOptions interfaceWe might want to add format to give author control
over the capture format.
[NoInterfaceObject]
interface CaptureVideoOptions {
attribute unsigned long limit;
attribute float duration;
};
duration of type floatlimit of type unsigned longCaptureAudioOptions interfaceAdditional attributes proposed: duration.
We might want to add format to give author control
over the capture format.
[NoInterfaceObject]
interface CaptureAudioOptions {
attribute unsigned long limit;
};
limit of type unsigned longPendingOperation interfaceThis may be a general interface for use throughout all APIs. Included here for now for completion.
[NoInterfaceObject]
interface PendingOperation {
void cancel ();
};
cancelThe effect of cancel method is currently under discussion in the working group. Is it necessary to delete files? Which callbacks (if any) should be invoked?
voidUser agents should discard the captured files only after the top-level browsing context [HTML5] related to the script is destroyed. In a special cases where the UA detects limited storage space, files may be deleted earlier.
Many thanks to Google, Nokia, and OMTP BONDI who provided the initial input into this specification.