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 https://www.w3.org/TR/.

Since Candidate Recommendation 04 May 2017, the capture IDL attribute was changed from an enumeration into a DOMString. This change aligns this specification with the HTML specification changes that removed the IDL enumeration reflection.

The CR exit criterion is two interoperable deployed implementations of each feature.

No features are marked as 'at-risk'.

This document was published by the Device and Sensors Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. 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 30 October 2017.

Please see the Working Group's implementation report.

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.

This document is governed by the 1 March 2017 W3C Process Document.

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 fine-grained author control may be met by using another specification, Media Capture and Streams [MEDIACAPTURE-STREAMS]. 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, and SHOULD 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-1], as this specification uses that specification and terminology.

3. Terminology

The input element, its type attribute, HTMLInputElement interface, accept attribute, File Upload state, enumerated attribute, missing value default, invalid value default, and reflect are defined in [HTML51].

The [CEReactions] WebIDL extended attribute is defined in [custom-elements].

The VideoFacingModeEnum enumeration is defined in [MEDIACAPTURE-STREAMS].

The FileList interface is defined in [FILE-API].

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 in its preferred facing mode.

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

The preferred facing mode is a hint for the direction of the device's media capture mechanism to be used.

4. Security and privacy considerations

This section is non-normative.

A User Agent implementation of this specification is advised to seek user consent before initiating capture of content by microphone or camera. This may be necessary to meet regulatory, legal and best practice requirements related to the privacy of user data. In addition, the User Agent implementation is advised to provide an indication to the user when an input device is enabled and make it possible for the user to terminate such capture. Similarly, the User Agent is advised to offer user control, such as to allow the user to:

This specification builds upon the security and privacy protections provided by the <input type="file"> [HTML51] 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 to prevent additional leakage of privacy-sensitive data from captured media. For instance, embedding the user’s location in the metadata of captured media (e.g. EXIF) might transmit more private data than the user is expecting.

5. The capture attribute

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 {
    [CEReactions]
    attribute DOMString capture;
};

The capture attribute is an enumerated attribute whose state specifies the preferred facing mode for the media capture mechanism.

The attribute's keywords are user and environment, which map to the respective states user and environment. The semantics of the states user and environment mirror the similarly named enumeration values defined in VideoFacingModeEnum.

In addition, there is a third state, the implementation-specific state.

The missing value default is the implementation-specific state. The invalid value default is also the implementation-specific state.

Note

If the user agent is unable to support the preferred facing mode, it can fall back to the implementation-specific default facing mode that maps to the implementation-specific state that indicates the implementation is to act according to its default behavior.

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.

When the capture attribute is specified, the user agent MUST NOT save the captured media to any data storage, local or remote.

Note
When scripts gain access to the files selected from the file picker (represented by a FileList object), they can use various mechanisms to store the captured media. These mechanisms are out of scope for this specification.

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.

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

B. References

B.1 Normative references

[FILE-API]
File API. Arun Ranganathan; Jonas Sicking. W3C. 21 April 2015. W3C Working Draft. URL: https://www.w3.org/TR/FileAPI/
[HTML51]
HTML 5.1 2nd Edition. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo. W3C. 3 August 2017. W3C Proposed Recommendation. URL: https://www.w3.org/TR/html51/
[MEDIACAPTURE-STREAMS]
Media Capture and Streams. Daniel Burnett; Adam Bergkvist; Cullen Jennings; Anant Narayanan; Bernard Aboba. W3C. 19 May 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mediacapture-streams/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL-1]
WebIDL Level 1. Cameron McCormack. W3C. 15 December 2016. W3C Recommendation. URL: https://www.w3.org/TR/2016/REC-WebIDL-1-20161215/
[custom-elements]
Custom Elements. Domenic Denicola. W3C. 13 October 2016. W3C Working Draft. URL: https://www.w3.org/TR/custom-elements/

B.2 Informative references

[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/