HTML Media Capture

Abstract

The HTML Media Capture specification defines an HTML form extension that facilitates user access to a device's media capture mechanism, such as a camera, or microphone, from within a file upload control.

Status of This Document

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

The only change made since the 26 March 2013 W3C Last Call Working Draft has been to update the Web IDL reference and to make the File API reference informative, as the referenced Security Considerations section is informative in that document (diff).

The Device APIs Working Group expects to request that the Director advance this document to Proposed Recommendation once the Working Group has verified two interoperable deployed implementations of each feature. The Device APIs Working Group does not have an estimate of when this will be achieved.

No features have been marked as "at risk".

This document was published by the Device APIs Working Group as a Candidate Recommendation. 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). W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 18 July 2013. All comments are welcome.

Publication as a Candidate Recommendation 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.

1. Introduction

This section is non-normative.

The HTML Media Capture specification extends the HTMLInputElement interface with a capture attribute. The capture attribute allows authors to declaratively request use of a media capture mechanism, such as a camera or microphone, from within a file upload control, for capturing media on the spot.

This extension is specifically designed to be simple and declarative, and covers a subset of the media capture functionality of the web platform. Specifically, the extension does not provide detailed author control over capture. Use cases requiring more file-grained author control may be met by using another specification, Media Capture and Streams [GETUSERMEDIA]. For example, access to real-time media streams from the hosting device is out of scope for this specification.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3. Terminology

The input element, HTMLInputElement interface, accept attribute, and File Upload state are defined in [HTML5].

The term boolean attribute and the concept reflect are defined in [HTML5].

In this specification, the term capture control type refers to a specialized type of a file picker control that is optimized, for the user, for directly capturing media of a MIME type specified by the accept attribute, using a media capture mechanism.

The term media capture mechanism refers to a device's local media capture device, such as a camera or microphone.

4. Security and privacy considerations

The user agent SHOULD NOT enable any device for media capture, such as a microphone or camera, until a user interaction giving implicit consent is completed. A user agent SHOULD also provide an indication when such an input device is enabled and make it possible to terminate such capture. Similarly, the user agent SHOULD allow the user:

to select the exact media capture device to be used if there exists multiple devices of the same type (e.g. a front-facing camera in addition to a primary camera).
to disable sound capture when in the video capture mode.

This specification builds upon the security and privacy protections provided by the <input type="file"> [HTML5] and the [FILE-API] specifications; in particular, it is expected that any offer to start capturing content from the user’s device would require a specific user interaction on an HTML element that is entirely controlled by the user agent.

Implementors SHOULD take care of additional leakage of privacy-sensitive data from captured media. For instance, embedding the user’s location in a captured media metadata (e.g. EXIF) might transmit more private data than the user might be expecting.

5. The capture attribute

This section is normative.

When an input element's type attribute is in the File Upload state, and its accept attribute is specified, the rules in this section apply.

partial interface HTMLInputElement {
                attribute boolean capture;
};

5.1 Attributes

capture of type boolean,

The capture attribute is a boolean attribute that, if specified, indicates that the capture of media directly from the device's environment using a media capture mechanism is preferred.

The capture IDL attribute MUST reflect the respective content attribute of the same name.

When the capture attribute is specified, the user agent SHOULD invoke a file picker of the specific capture control type.

If the accept attribute's value is set to a MIME type that has no associated capture control type, the user agent MUST act as if there was no capture attribute.

A. Examples

This section is non-normative.

The following examples demonstrate how to give hints that it is preferred for the user to capture media of a specific MIME type using the media capture capabilities of the hosting device. Both a simple declarative example using an HTML form, as well as a more advanced example including scripting, are presented.

To take a picture using the device's local still image capture device, such as a camera, and upload the picture taken using an HTML form:

Example 1

<form action="server.cgi" method="post" enctype="multipart/form-data">
  <input type="file" name="image" accept="image/*" capture>
  <input type="submit" value="Upload">
</form>

Or alternatively, to capture video using the device's local video camera:

Example 2

<form action="server.cgi" method="post" enctype="multipart/form-data">
  <input type="file" name="video" accept="video/*" capture>
  <input type="submit" value="Upload">
</form>

Or alternatively, to capture audio using the device's local microphone:

Example 3

<form action="server.cgi" method="post" enctype="multipart/form-data">
  <input type="file" name="audio" accept="audio/*" capture>
  <input type="submit" value="Upload">
</form>

For more advanced use cases, specify the capture attribute in markup:

Example 4

<input type="file" accept="image/*" capture>
<canvas></canvas>

And handle the file upload in script via XMLHttpRequest:

Example 5

var input = document.querySelector('input[type=file]'); // see Example 4

input.onchange = function () {
  var file = input.files[0];

  upload(file);
  drawOnCanvas(file);   // see Example 6
  displayAsImage(file); // see Example 7
};

function upload(file) {
  var form = new FormData(),
      xhr = new XMLHttpRequest();

  form.append('image', file);
  xhr.open('post', 'server.php', true);
  xhr.send(form);
}

The image can also be displayed on the client-side without uploading it e.g. for client-side image editing purposes, using the FileReader and a canvas element:

Example 6

function drawOnCanvas(file) {
  var reader = new FileReader();

  reader.onload = function (e) {
    var dataURL = e.target.result,
        c = document.querySelector('canvas'), // see Example 4
        ctx = c.getContext('2d'),
        img = new Image();

    img.onload = function() {
      c.width = img.width;
      c.height = img.height;
      ctx.drawImage(img, 0, 0);
    };

    img.src = dataURL;
  };

  reader.readAsDataURL(file);
}

Or alternatively, to just display the image, using the createObjectURL() method and an img element:

Example 7

function displayAsImage(file) {
  var imgURL = URL.createObjectURL(file),
      img = document.createElement('img');

  img.onload = function() {
    URL.revokeObjectURL(imgURL);
  };

  img.src = imgURL;
  document.body.appendChild(img);
}

When an input element's accept attribute is set to image/* and the capture attribute is specified as in the Example 1 or Example 4, the file picker may render as presented on the right side. When the attribute is not specified, the file picker may render as represented on the left side.

A File picker control in the File Upload (left) and Image
Capture state (right).

HTML Media Capture

W3C Candidate Recommendation 09 May 2013

Abstract

Status of This Document

Table of Contents