Copyright
©
2014
2017
W3C
®
(
MIT
,
ERCIM
,
Keio
,
Beihang
),
All
Rights
Reserved.
).
W3C
liability
,
trademark
and
document
use
rules
apply.
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.
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/.
https://www.w3.org/TR/.
There
Since
the
previous
Candidate
Recommendation
of
this
specification
,
the
following
changes
have
been
no
substantive
changes
since
brought
to
the
W3C
W3C
Last
Call
Working
Draft
19
June
2014
.
document:
capture
attribute
has
been
changed
from
a
boolean
to
an
enumerated
value
representing
the
facing
mode
of
capture
attribute
has
been
annotated
with
a
[CEReactions]
extended
attribute
since
it
can
change
the
DOM
in
ways
that
may
impact
custom
elements
This
document
was
published
by
the
Device
APIs
and
Sensors
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.
The
CR
exit
criterion
is
two
interoperable
deployed
implementations
of
each
feature.
No
features
are
marked
as
'at-risk'.
This
Candidate
Recommendation
is
expected
to
advance
to
Proposed
Recommendation
no
earlier
than
12
November
2014.
6
July
2017.
All
comments
are
welcome.
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
14
October
2005
1
March
2017
W3C
Process
Document
.
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
[
GETUSERMEDIA
MEDIACAPTURE-STREAMS
].
For
example,
access
to
real-time
media
streams
from
the
hosting
device
is
out
of
scope
for
this
specification.
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
SHOULD
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
WEBIDL-1
],
as
this
specification
uses
that
specification
and
terminology.
The
input
element,
its
element
,
type
HTMLInputElement
attribute,
HTMLInputElement
interface,
accept
attribute
,
and
attribute,
File
Upload
state,
enumerated
attribute
state
,
missing
value
default
,
invalid
value
default
,
and
reflect
are
defined
in
[
HTML5
HTML51
].
The
term
boolean
attribute
VideoFacingModeEnum
and
the
concept
reflect
enumeration
is
defined
in
[
MEDIACAPTURE-STREAMS
are
].
The
FileList
interface
is
defined
in
[
HTML5
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.
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">
[
HTML5
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.
capture
attribute
This
section
is
normative.
When
an
input
element's
type
attribute
is
in
the
File
Upload
state
,
state,
and
its
accept
attribute
is
specified,
the
rules
in
this
section
apply.
enumCaptureFacingMode
{ "user", "environment" }; partial interfaceHTMLInputElement
{ [CEReactions] attributeCaptureFacingMode
capture
; };
The
enumeration
is
used
to
express
the
preferred
facing
mode
.
The
semantics
of
capture
CaptureFacingMode
type
boolean
,
its
keywords
mirror
the
similarly
named
keywords
defined
in
.
VideoFacingModeEnum
If the user agent is unable to support the preferred facing mode , it can fall back to the implementation-specific default facing mode.
The
capture
attribute
is
a
boolean
an
enumerated
attribute
that,
if
specified,
indicates
that
specifies
the
capture
of
media
directly
from
preferred
facing
mode
for
the
device's
environment
using
a
media
capture
mechanism
.
The
attribute's
keywords
are
user
and
environment
,
which
map
to
the
respective
states
user
and
environment
.
In
addition,
there
is
a
third
state,
the
implementation-specific
state.
The
missing
value
default
is
preferred.
the
implementation-specific
state.
The
invalid
value
default
is
also
the
implementation-specific
state.
The implementation-specific state 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
.
If
When
the
capture
attribute
is
specified,
the
user
agent
MUST
NOT
save
the
captured
media
to
any
data
storage,
local
or
remote.
FileList
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.
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.
<form action="server.cgi" method="post" enctype="multipart/form-data">
<input type="file" name="image" accept="image/*" capture="user">
<input type="submit" value="Upload">
</form>
<form action="server.cgi" method="post" enctype="multipart/form-data">
<input type="file" name="video" accept="video/*" capture="environment">
<input type="submit" value="Upload">
</form>
<form action="server.cgi" method="post" enctype="multipart/form-data">
<input type="file" name="audio" accept="audio/*" capture>
<input type="submit" value="Upload">
</form>
capture
attribute
in
markup:
<input type="file" accept="image/*" capture>
<canvas></canvas>
XMLHttpRequest
:
var input = document.querySelector('input[type=file]'); // see Example 4
input
input.onchange = function () {
var file = input.files[0];
upload
drawOnCanvas
displayAsImage
upload(file);
drawOnCanvas(file); // see Example 6
displayAsImage(file); // see Example 7
};
xhr
function upload(file) {
var form = new FormData(),
xhr = new XMLHttpRequest();
form
xhr
xhr
form.append('image', file);
xhr.open('post', 'server.php', true);
xhr.send(form);
}
FileReader
and
a
canvas
element:
function drawOnCanvas(file) {
var reader = new FileReader();
reader
c
ctx
img
reader.onload = function (e) {
var dataURL = e.target.result,
c = document.querySelector('canvas'), // see Example 4
ctx = c.getContext('2d'),
img = new Image();
img
c
c
ctx
img.onload = function() {
c.width = img.width;
c.height = img.height;
ctx.drawImage(img, 0, 0);
};
img
img.src = dataURL;
};
reader
reader.readAsDataURL(file);
}
createObjectURL()
method
and
an
img
element:
function displayAsImage(file) {
var imgURL = URL.createObjectURL(file),
img = document.createElement('img');
img
URL
img.onload = function() {
URL.revokeObjectURL(imgURL);
};
img
document
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.