The Capture API
HTML Media Capture

    
      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.
    
    
      
        An HTML Media Capture Proposed Recommendation was published on 28 November 2017, no further normative changes have been made since then.

        Errata for this document are recorded as issues.

        The implementation report produced for this version demonstrates there are two independent interoperable implementations.
      
    
    
      
        Introduction
      
      
        The HTML Media Capture specification extends the
        {{HTMLInputElement}} interface with a {{HTMLInputElement/capture}} attribute. The
        [^input/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.
      
    
    
      
        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.
      
    
    
      
        Terminology
      
      
        File
        Upload state, enumerated attribute,
        missing value
        default, invalid
        value default
        are defined in [[HTML]].
      
      
        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
        [^input/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.
      
    
    
      
        Security and privacy considerations
      
      
        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:
      
      
        select the exact media capture device to be used if there exist
        multiple devices of the same type (e.g. a front-facing camera in
        addition to a primary camera).
        
        disable sound capture when in the video capture mode.
        
      
      
        This specification builds upon the security and privacy protections
        provided by the <input type="file"> [[HTML]] 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.
      
    
    
      
        The capture IDL attribute
      
      
        When an [^input^] element's [^input/type^] attribute is in the File
        Upload state, and its [^input/accept^] attribute is specified, the
        rules in this section apply.
      
              partial interface HTMLInputElement {
            [CEReactions] attribute DOMString capture;
        };
      
      
        
          The capture content attribute is an enumerated attribute whose
          state specifies the preferred facing mode for the media
          capture mechanism.
        
        
          The attribute's keywords are user,
          environment, and the empty string, which map
          to the user, environment, and the
          implementation-specific state respectively. The semantics
          of the states user and environment mirror the
          similarly named enumeration values defined in
          {{VideoFacingModeEnum}}.
        
        
          The missing value default is the
          implementation-specific state. The invalid value
          default is also the implementation-specific state.
        
        
          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 {{HTMLInputElement/capture}} IDL attribute MUST [=Attr/reflect=] the respective
          content attribute of the same name.
        
        
          When the [^input/capture^] attribute is specified, the user agent
          SHOULD invoke a file picker of the specific capture control
          type.
        
        
          When the [^input/capture^] attribute is specified, the user agent
          MUST NOT save the captured media to any data storage, local or
          remote.
        
        
          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 [^input/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 [^input/capture^] attribute.
        
      
    
    
      
        Examples
      
      
        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 user-facing
        camera, and upload the picture taken using an HTML form:
                    <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>
        
        
        Or alternatively, to capture video using the device's local video
        camera facing the environment:
                    <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>
        
        
        Or alternatively, to capture audio using the device's local
        microphone (without preferred facing mode defined, falls back to
        the implementation-specific default facing mode):
                    <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 [^input/capture^] attribute in markup:
                    <input type="file" accept="image/*" capture>
          <canvas></canvas>
        And handle the file upload in script via `XMLHttpRequest`:
                    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:
        
                    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
          {{URL/createObjectURL()}} method and an [^img^] element:
        
                    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 [^input/accept^] attribute is set to
        image/* and the [^input/capture^] attribute is specified as
        in the [[[#example-1]]] or [[[#example-4]]], the file picker can be rendered as
        presented below:
      
      
        
      
      
        When the attribute is not specified, the file picker can be rendered
        as represented below:
      
      
        
      
    
  

