MediaRecorder.bs

<pre class="metadata">
Title: MediaStream Recording
Repository: w3c/mediacapture-record
Group: webrtc
Status: ED
ED: https://w3c.github.io/mediacapture-record/
TR: https://www.w3.org/TR/mediastream-recording/
Shortname: mediastream-recording
Level: none
Editor: Miguel Casas-Sanchez, w3cid 82825, Google Inc., mcasas@google.com
Former Editor: Jim Barnett, w3cid 34604, Genesis
Former Editor: Travis Leithead, w3cid 40117, Microsoft Corp., travis.leithead@microsoft.com
Abstract: This document defines a recording API for use with {{MediaStream}}s.
!Participate: <a href="https://lists.w3.org/Archives/Public/public-webrtc/">Mailing list</a>
!Participate: <a href="https://github.com/w3c/mediacapture-record">GitHub repo</a> (<a href="https://github.com/w3c/mediacapture-record/issues/new">new issue</a>, <a href="https://github.com/w3c/mediacapture-record/issues">open issues</a>)

!Implementation: <a href="http://caniuse.com/#feat=mediarecorder">Can I use Media Recording?</a>
!Implementation: <a href="https://github.com/miguelao/mediacapture-record-implementation-status/blob/master/chromium.md">Chromium Encode Acceleration Support</a>
Boilerplate: omit conformance
</pre>

<style>
table {
  border-collapse: collapse;
  border-left-style: hidden;
  border-right-style: hidden;
  text-align: left;
}
table caption {
  font-weight: bold;
  padding: 3px;
  text-align: left;
}
table td, table th {
  border: 1px solid black;
  padding: 3px;
}
</style>

# Overview # {#overview}

This API attempts to make basic recording very simple, while still allowing for
more complex use cases. In the simplest case, the application instantiates a
{{MediaRecorder}} object, calls {{start()}} and then calls {{stop()}} or waits
for the {{MediaStreamTrack}}(s) [[!GETUSERMEDIA]] to be ended. The contents of the recording will
be made available in the platform's default encoding via the {{ondataavailable}}
event.  Functions are available to query the platform's available set of
encodings, and to select the desired ones if the author wishes. The application
can also choose how much data it wants to receive at one time. By default a
{{Blob}} containing the entire recording is returned when the recording
finishes. However the application can choose to receive smaller buffers of data
at regular intervals.

# Media Recorder API # {#mediarecorder-api}

<pre class="idl">
[Exposed=Window]
interface MediaRecorder : EventTarget {
  constructor(MediaStream stream, optional MediaRecorderOptions options = {});
  readonly attribute MediaStream stream;
  readonly attribute DOMString mimeType;
  readonly attribute RecordingState state;
  attribute EventHandler onstart;
  attribute EventHandler onstop;
  attribute EventHandler ondataavailable;
  attribute EventHandler onpause;
  attribute EventHandler onresume;
  attribute EventHandler onerror;
  readonly attribute unsigned long videoBitsPerSecond;
  readonly attribute unsigned long audioBitsPerSecond;
  readonly attribute BitrateMode audioBitrateMode;

  undefined start(optional unsigned long timeslice);
  undefined stop();
  undefined pause();
  undefined resume();
  undefined requestData();

  static boolean isTypeSupported(DOMString type);
};
</pre>

## Constructors ## {#mediarecorder-constructor}

<dl class="domintro">
  <dt><dfn constructor for="MediaRecorder"><code>MediaRecorder(MediaStream stream, optional MediaRecorderOptions options = {})</code></dfn></dt>
  <dd>When the {{MediaRecorder()}}
  constructor is invoked, the User Agent MUST run the following steps:
  <ol>
    <li>Let |stream| be the constructor's first argument.</li>
    <li>Let |options| be the constructor's second argument.</li>
    <li>If invoking [$is type supported$] with |options|'
    {{MediaRecorderOptions/mimeType}} member as its argument returns false,
    throw a {{NotSupportedError}} {{DOMException}} and abort these steps.</li>
    <li>Let |recorder| be a newly constructed {{MediaRecorder}} object.</li>
    <li>Let |recorder| have a <dfn>\[[ConstrainedMimeType]]</dfn> internal slot,
    initialized to the value of |options|' {{MediaRecorderOptions/mimeType}}
    member.</li>
    <li>Let |recorder| have a <dfn>\[[ConstrainedBitsPerSecond]]</dfn> internal
    slot, initialized to the value of |options|'
    {{MediaRecorderOptions/bitsPerSecond}} member if it is present, otherwise
    <code>null</code>.</li>
    <li>Let |recorder| have a <dfn>\[[VideoKeyFrameIntervalDuration]]</dfn> internal
    slot, initialized to the value of |options|'
    {{MediaRecorderOptions/videoKeyFrameIntervalDuration}} member if it is present, otherwise
    <code>null</code>.</li>
    <li>Let |recorder| have a <dfn>\[[VideoKeyFrameIntervalCount]]</dfn> internal
    slot, initialized to the value of |options|'
    {{MediaRecorderOptions/videoKeyFrameIntervalCount}} member if it is present, otherwise
    <code>null</code>.</li>
    <li>Initialize |recorder|'s {{MediaRecorder/stream}} attribute to
    |stream|.</li>
    <li>Initialize |recorder|'s {{MediaRecorder/mimeType}} attribute to the
    value of |recorder|'s [=[[ConstrainedMimeType]]=] slot.</li>
    <li>Initialize |recorder|'s {{MediaRecorder/state}} attribute to
    {{inactive}}.</li>
    <li>Initialize |recorder|'s {{MediaRecorder/videoBitsPerSecond}} attribute to the value of
    |options|' {{MediaRecorderOptions/videoBitsPerSecond}} member, if it is
    present. Otherwise, choose a target value the User Agent deems reasonable
    for video.</li>
    <li>Initialize |recorder|'s {{MediaRecorder/audioBitsPerSecond}} attribute to the value of
    |options|' {{MediaRecorderOptions/audioBitsPerSecond}} member, if it is
    present. Otherwise, choose a target value the User Agent deems reasonable
    for audio.</li>
    <li>If |recorder|'s [=[[ConstrainedBitsPerSecond]]=] slot is not
    <code>null</code>, set |recorder|'s {{MediaRecorder/videoBitsPerSecond}} and
    {{MediaRecorder/audioBitsPerSecond}} attributes to values the User Agent deems reasonable
    for the respective media types, such that the sum of {{MediaRecorder/videoBitsPerSecond}}
    and {{MediaRecorder/audioBitsPerSecond}} is close to the value of |recorder|'s
    [=[[ConstrainedBitsPerSecond]]=] slot.</li>
    <li>If |recorder| supports the {{BitrateMode}} specified by the value of
    |options|' {{MediaRecorderOptions/audioBitrateMode}} member,
    then initialize |recorder|'s {{MediaRecorder/audioBitrateMode}} attribute to the value of
    |options|' {{MediaRecorderOptions/audioBitrateMode}} member,
    else initialize |recorder|'s {{MediaRecorder/audioBitrateMode}} attribute to the value
    "variable".</li>
    <li>Return |recorder|.</li>
  </ol></dd>
</dl>

## Attributes ## {#mediarecorder-attributes}

<dl class="domintro">
  <dt><dfn attribute for="MediaRecorder"><code>stream</code></dfn></dt>
  <dd>The {{MediaStream}} [[!GETUSERMEDIA]] to be recorded.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>mimeType</code></dfn></dt>
  <dd>The MIME type [[!RFC2046]] used by the {{MediaRecorder}} object.
  The User Agent SHOULD be able to play back any of the MIME types it supports
  for recording. For example, it should be able to display a video recording in
  the HTML &lt;video&gt; tag.

  <div class="note"> {{MediaRecorder/mimeType}} specifies the media type and
  container format for the recording via a type/subtype combination, with the
  codecs and/or profiles parameters [[RFC6381]] specified where ambiguity might
  arise. Individual codecs might have further optional specific parameters.
  </div></dd>

  <dt><dfn attribute for="MediaRecorder"><code>state</code></dfn></dt>
  <dd>The current state of the {{MediaRecorder}} object.
  </dd>

  <dt><dfn attribute for="MediaRecorder"><code>onstart</code></dfn></dt>
  <dd>Called to handle the <a event>start</a> event.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>onstop</code></dfn></dt>
  <dd>Called to handle the <a event>stop</a> event.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>ondataavailable</code></dfn></dt>
  <dd>Called to handle the <a event>dataavailable</a> event. The {{Blob}} of recorded
  data is contained in this event and can be accessed via its {{BlobEvent/data}}
  attribute.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>onpause</code></dfn></dt>
  <dd>Called to handle the <a event>pause</a> event.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>onresume</code></dfn></dt>
  <dd>Called to handle the <a event>resume</a> event.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>onerror</code></dfn></dt>
  <dd>Called to handle an {{ErrorEvent}}.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>videoBitsPerSecond</code></dfn></dt>
  <dd>The target bitrate used to encode video tracks.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>audioBitsPerSecond</code></dfn></dt>
  <dd>The target bitrate used to encode audio tracks.</dd>

  <dt><dfn attribute for="MediaRecorder"><code>audioBitrateMode</code></dfn></dt>
  <dd>The {{BitrateMode}} used to encode audio tracks.</dd>
</dl>

## Methods ## {#mediarecorder-methods}

  <div class="note">
    For historical reasons, the following methods alter {{state}} synchronously
    and fire events asynchronously.
  </div>
<dl class="domintro">
  <dt><dfn method for="MediaRecorder"><code>start(optional unsigned long timeslice)</code></dfn></dt>
  <dd>
  When a {{MediaRecorder}} object&#8217;s {{start()}} method is invoked, the UA
  MUST run the following steps:
  <ol>
    <li>Let |recorder| be the {{MediaRecorder}} object on which the method was
    invoked.</li>

    <li>Let <var>timeslice</var> be the method's first argument, if provided,
    or <code>undefined</code>. </li>

    <li>Let |stream| be the value of |recorder|'s {{MediaRecorder/stream}} attribute.</li>

    <li>Let |tracks| be the set of {{live}} tracks in |stream|'s
    [=track set=].</li>

    <li>If the value of |recorder|'s {{state}} attribute is not {{inactive}},
    throw an {{InvalidStateError}} {{DOMException}} and abort these steps.</li>

    <li>If the <a>isolation properties</a> of |stream| disallow access from
    |recorder|, throw a {{SecurityError}} {{DOMException}} and abort these
    steps.</li>

    <li>If |stream| is [=inactive=], throw a {{NotSupportedError}}
    {{DOMException}} and abort these steps.</li>

    <li>If the [=[[ConstrainedMimeType]]=] slot specifies a media type,
    container, or codec, then constrain the configuration of |recorder| to the
    media type, container, and codec specified in the [=[[ConstrainedMimeType]]=]
    slot.</li>

    <li>If |recorder|'s [=[[ConstrainedBitsPerSecond]]=] slot is not
    <code>null</code>, set |recorder|'s {{MediaRecorder/videoBitsPerSecond}} and
    {{MediaRecorder/audioBitsPerSecond}} attributes to values the User Agent deems reasonable
    for the respective media types, for recording all tracks in |tracks|, such
    that the sum of {{MediaRecorder/videoBitsPerSecond}} and {{MediaRecorder/audioBitsPerSecond}} is close
    to the value of |recorder|'s [=[[ConstrainedBitsPerSecond]]=] slot.</li>

    <li>Let |videoBitrate| be the value of |recorder|'s {{MediaRecorder/videoBitsPerSecond}}
    attribute, and constrain the configuration of |recorder| to target an
    aggregate bitrate of |videoBitrate| bits per second for all video tracks
    |recorder| will be recording. |videoBitrate| is a hint for the encoder and
    the value might be surpassed, not achieved, or only be achieved over a long
    period of time.</li>

    <li>Let |audioBitrate| be the value of |recorder|'s {{MediaRecorder/audioBitsPerSecond}}
    attribute, and constrain the configuration of |recorder| to target an
    aggregate bitrate of |audioBitrate| bits per second for all audio tracks
    |recorder| will be recording. |audioBitrate| is a hint for the encoder and
    the value might be surpassed, not achieved, or only be achieved over a long
    period of time.</li>

    <li>Let |videoKeyFrameIntervalDuration| be
    |recorder|.[=[[VideoKeyFrameIntervalDuration]]=], and let
    |videoKeyFrameIntervalCount| be
    |recorder|.[=[[VideoKeyFrameIntervalCount]]=]. The UA SHOULD constrain the
    configuration of |recorder| so that the video encoder follows the below rules:
    <ul>
    <li>If |videoKeyFrameIntervalDuration| is not <code>null</code> and |videoKeyFrameIntervalCount| is <code>null</code>,
    the video encoder produces a keyframe on the first frame arriving after |videoKeyFrameIntervalDuration|
    milliseconds elapsed since the last key frame.</li>

    <li>If |videoKeyFrameIntervalCount| is not <code>null</code> and |videoKeyFrameIntervalDuration| is <code>null</code>,
    the video encoder produces a keyframe on the first frame arriving after |videoKeyFrameIntervalCount|
    frames passed since the last key frame.</li>

    <li>If both |videoKeyFrameIntervalDuration| and |videoKeyFrameIntervalCount| are not <code>null</code>,
    then throw a {{NotSupportedError}} {{DOMException}} and abort these steps.</li>

    <li>If both |videoKeyFrameIntervalDuration| and |videoKeyFrameIntervalCount| are <code>null</code>,
    the User Agent may emit key frames as it deems fit.</li>
    </ul>

    Note that encoders will sometimes make independent decisions about when to
    emit key frames.</li>

    <li>Constrain the configuration of |recorder| to encode using the
    {{BitrateMode}} specified by the value of |recorder|'s {{MediaRecorder/audioBitrateMode}}
    attribute for all audio tracks |recorder| will be recording.</li>

    <li>For each track in |tracks|, if the User Agent cannot record the track
    using the current configuration, then throw a {{NotSupportedError}}
    {{DOMException}} and abort these steps.</li>

    <li>Set |recorder|'s {{state}} to {{recording}}, and run the following steps
    <a>in parallel</a>:
    <ol>
      <li>If the container and codecs to use for the recording have not yet been
      fully specified, the User Agent specifies them in |recorder|'s current
      configuration. The User Agent MAY take the sources of the tracks in
      |tracks| into account when deciding which container and codecs to
      use.
      <div class="note">
        By looking at the sources of the tracks in |tracks| when recording
        starts, the User Agent could choose a configuration that avoids
        re-encoding track content. For example, if the MediaStreamTrack is a
        remote track sourced from an RTCPeerConnection, the User Agent could
        pick the same codec as is used for the MediaStreamTrack's RTP stream,
        should it be known. However, if the codec of the RTP stream changes
        while recording, the User Agent has to be prepared to re-encode it to
        avoid interruptions.
      </div>
      </li>
      <li>Start recording all tracks in |tracks| using the |recorder|'s current
      configuration and gather the data into a {{Blob}} <var>blob</var>. Queue a
      task, using the DOM manipulation task source, to run the following steps:
      <ol>
        <li>Let |extendedMimeType| be the value of |recorder|'s
        [=[[ConstrainedMimeType]]=] slot.</li>
        <li>Modify |extendedMimeType| by adding media type, subtype and codecs
        parameter reflecting the configuration used by the MediaRecorder to
        record all tracks in |tracks|, if not already present. This MAY include
        the profiles parameter [[RFC6381]] or further codec-specific
        parameters.</li>
        <li>Set |recorder|'s {{MediaRecorder/mimeType}} attribute to |extendedMimeType|.</li>
        <li><a>Fire an event</a> named <a event>start</a> at |recorder|.</li>
      </ol>
      </li>

      <li>If at any point |stream|'s <a>isolation properties</a> change so
      that {{MediaRecorder}} is no longer allowed access to it, the UA MUST
      stop gathering data, discard any data that it has gathered,
      and queue a task, using the DOM manipulation task source, that runs the
      following steps:
      <ol>
        <li>[$Inactivate the recorder$] with |recorder|.</li>
        <li><a>Fire an error event</a> named {{SecurityError}} at
        <var>recorder</var>.</li>
        <li><a>Fire a blob event</a> named
        <a event>dataavailable</a> at <var>recorder</var> with <var>blob</var>.</li>
        <li><a>Fire an event</a> named <a event>stop</a> at <var>recorder</var>.</li>
      </ol>
      </li>

      <li>If at any point, a track is added to or removed from |stream|'s
      [=track set=], the UA MUST stop gathering data, and queue a task,
      using the DOM manipulation task source, that runs the following steps:
      <ol>
        <li>[$Inactivate the recorder$] with |recorder|.</li>
        <li><a>Fire an error event</a> named {{InvalidModificationError}} at
        <var>recorder</var>.</li>
        <li><a>Fire a blob event</a> named
        <a event>dataavailable</a> at <var>recorder</var> with <var>blob</var>.</li>
        <li><a>Fire an event</a> named <a event>stop</a> at <var>recorder</var>.</li>
      </ol>
      </li>

      <li>If the UA at any point is unable to continue gathering data for
      reasons other than <a>isolation properties</a> or |stream|'s
      [=track set=], it MUST stop gathering data, and queue a task, using the
      DOM manipulation task source, that runs the following steps:
      <ol>
        <li>[$Inactivate the recorder$] with |recorder|.</li>
        <li><a>Fire an error event</a> named {{UnknownError}} at
        <var>recorder</var>.</li>
        <li><a>Fire a blob event</a> named
        <a event>dataavailable</a> at <var>recorder</var> with <var>blob</var>.</li>
        <li><a>Fire an event</a> named <a event>stop</a> at <var>recorder</var>.</li>
      </ol>
      </li>

      <li>If <var>timeslice</var> is not <code>undefined</code>, then once a
      minimum of <var>timeslice</var> milliseconds of data have been collected,
      or some minimum time slice imposed by the UA, whichever is greater, start
      gathering data into a new {{Blob}} <var>blob</var>, and queue a task,
      using the DOM manipulation task source, that
      <a data-lt="fire a blob event">fires a blob event</a> named
      <a event>dataavailable</a> at <var>recorder</var> with <var>blob</var>.

      Note that an <code>undefined</code> value of <var>timeslice</var> will
      be understood as the largest <code>unsigned long</code> value.</li>

      <li>If all recorded tracks become {{ended}}, then stop gathering data, and
      queue a task, using the DOM manipulation task source, that runs the
      following steps:
      <ol>
        <li>[$Inactivate the recorder$] with |recorder|.</li>
        <li><a>Fire a blob event</a> named
        <a event>dataavailable</a> at <var>recorder</var> with <var>blob</var>.</li>
        <li><a>Fire an event</a> named <a event>stop</a> at
        <var>recorder</var>.</li>
      </ol>
      </li>

    </ol>
    </li>
  </ol>

  <p>Note that {{stop()}}, {{requestData()}}, and {{pause()}} also affect the
  recording behavior.</p>

  <p>The UA MUST record {{MediaRecorder/stream}} in such a way that the original
  Tracks can be retrieved at playback time. When multiple {{Blob}}s are returned
  (because of {{timeslice}} or {{requestData()}}), the individual Blobs need not
  be playable, but the combination of all the Blobs from a completed recording
  MUST be playable.</p>

  <p> If any Track within the {{MediaStream}} is {{muted}} or not {{enabled}} at
  any time, the UA will only record black frames or silence since that is the
  content produced by the Track.</p>

  <p>The <dfn abstract-op>Inactivate the recorder</dfn> algorithm given a
  |recorder|, is as follows:</p>
  <ol>
    <li>Set |recorder|'s {{MediaRecorder/mimeType}} attribute to the value of the
    [=[[ConstrainedMimeType]]=] slot.</li>
    <li>Set |recorder|'s {{state}} attribute to {{inactive}}.</li>
    <li>If |recorder|'s [=[[ConstrainedBitsPerSecond]]=] slot is not
    <code>undefined</code>, set |recorder|'s {{MediaRecorder/videoBitsPerSecond}} and
    {{MediaRecorder/audioBitsPerSecond}} attributes to values the User Agent deems reasonable
    for the respective media types, such that the sum of {{MediaRecorder/videoBitsPerSecond}}
    and {{MediaRecorder/audioBitsPerSecond}} is close to the value of |recorder|'s
    [=[[ConstrainedBitsPerSecond]]=] slot.</li>
  </ol>

  </dd>

  <dt><dfn method for="MediaRecorder"><code>stop()</code></dfn></dt>
  <dd>
  When a {{MediaRecorder}} object&#8217;s {{stop()}} method is invoked, the UA
  MUST run the following steps:
  <ol>
    <li>Let |recorder| be the {{MediaRecorder}} object on which the method was
    invoked.</li>
    <li>If |recorder|'s {{state}} attribute is {{inactive}}, abort these
    steps.</li>
    <li>[$Inactivate the recorder$] with |recorder|.</li>
    <li>Queue a task, using the DOM manipulation task source, that runs the
    following steps:
    <ol>
      <li>Stop gathering data.</li>
      <li>Let <var>blob</var> be the Blob of collected data so far, then
      <a>fire a blob event</a> named
      <a event>dataavailable</a> at <var>recorder</var> with <var>blob</var>.</li>
      <li><a>Fire an event</a> named <a event>stop</a> at <var>recorder</var>.</li>
    </ol>
    </li>
    <li>return <code>undefined</code>.</li>
  </ol>
  </dd>

  <dt><dfn method for="MediaRecorder"><code>pause()</code></dfn></dt>
  <dd>
  When a {{MediaRecorder}} object&#8217;s {{pause()}} method is invoked, the UA
  MUST run the following steps:
  <ol>
    <li>If {{state}} is {{inactive}}, throw an {{InvalidStateError}}
    {{DOMException}} and abort these steps.</li>

    <li>If {{state}} is {{paused}}, abort these steps.</li>

    <li>Set {{state}} to {{paused}}, and queue a
    task, using the DOM manipulation task source, that runs the following steps:
    <ol>
      <li>Stop gathering data into <var>blob</var> (but keep it
      available so that recording can be resumed in the future).</li>
      <li>Let <var>target</var> be the MediaRecorder context object.
      <a>Fire an event</a> named <a event>pause</a> at <var>target</var>.</li>
    </ol>
    </li>
    <li>return <code>undefined</code>.</li>
  </ol>
  </dd>

  <dt><dfn method for="MediaRecorder"><code>resume()</code></dfn></dt>
  <dd>
  When a {{MediaRecorder}} object&#8217;s {{resume()}} method is invoked, the
  UA MUST run the following steps:
  <ol>
    <li>If {{state}} is {{inactive}}, throw an {{InvalidStateError}}
    {{DOMException}} and abort these steps.</li>

    <li>If {{state}} is {{recording}}, abort these steps.</li>

    <li>Set {{state}} to {{recording}}, and queue a
    task, using the DOM manipulation task source, that runs the following steps:
    <ol>
      <li>Resume (or continue) gathering data into the current <var>blob</var>.
      </li>
      <li>Let <var>target</var> be the MediaRecorder context object. <a>Fire
      an event</a> named <a>resume</a> at <var>target</var>.</li>
    </ol>
    </li>
    <li>return <code>undefined</code>.</li>
  </ol>
  </dd>

  <dt><dfn method for="MediaRecorder"><code>requestData()</code></dfn></dt>
  <dd>
  When a {{MediaRecorder}} object&#8217;s {{requestData()}} method is invoked,
  the UA MUST run the following steps:
  <ol>
    <li>If {{state}} is {{inactive}} throw an {{InvalidStateError}}
    {{DOMException}} and terminate these steps. Otherwise the UA MUST queue a
    task, using the DOM manipulation task source, that runs the following steps:
    <ol>
      <li>Let <var>blob</var> be the {{Blob}} of collected data so far and
      let <var>target</var> be the {{MediaRecorder}} context object, then
      <a>fire a blob event</a> named
      <a event>dataavailable</a> at <var>target</var> with <var>blob</var>.
      (Note that <var>blob</var> will be empty if no data has been gathered
      yet.)</li>

      <li>Create a new Blob and gather subsequent data into it.</li>
    </ol>
    </li>
    <li>return <code>undefined</code>.</li>
  </ol>
  </dd>

  <dt><dfn method for="MediaRecorder"><code>isTypeSupported(DOMString type)
    </code></dfn></dt>
  <dd>
  Check to see whether a {{MediaRecorder}} can record in a specified MIME type.
  If true is returned from this method, it only indicates that the
  {{MediaRecorder}} implementation is capable of recording {{Blob}} objects for
  the specified MIME type. Recording may still fail if sufficient resources are
  not available to support the concrete media encoding. When this method is
  invoked, the User Agent must return the result of [$is type supported$],
  given the method's first argument.
  </dd>
  <dd algorithm="is type supported">The <dfn abstract-op>is type supported</dfn>
  algorithm consists of the following steps.
  <ol>
    <li>Let |type| be the algorithm's argument.</li>
    <li>If |type| is an empty string, then return true (note that this case is
    essentially equivalent to leaving up to the UA the choice of both container
    and codecs).</li>
    <li>If |type| does not contain a valid MIME type string, then return false.
    </li>
    <li>If |type| contains a media type or media subtype that the MediaRecorder
    does not support, then return false.</li>
    <li>If |type| contains a media container that the MediaRecorder does not
    support, then return false.</li>
    <li>If |type| contains more than one audio codec, or more than one video
    codec, then return false.</li>
    <li>If |type| contains a codec that the MediaRecorder does not support, then
    return false.</li>
    <li>If the MediaRecorder does not support the specified combination of media
    type/subtype, codecs and container then return false.</li>
    <li>Return true.</li>
  </ol>
  </dd>
</dl>

## Data handling ## {#data-handling}

To <dfn>fire a blob event</dfn>  with a {{Blob}} <var>blob</var> means to
<a>fire an event</a> at <var ignore=''>target</var> using a {{BlobEvent}} with
its {{BlobEvent/data}} attribute initialized to <var>blob</var>.

<div class="note">
  Usually <var>blob</var> will be the data gathered by the UA after the
  last transition to {{recording}} {{state}}.
</div>


## MediaRecorderOptions ## {#mediarecorderoptions-section}

<pre class="idl">
dictionary MediaRecorderOptions {
  DOMString mimeType = "";
  unsigned long audioBitsPerSecond;
  unsigned long videoBitsPerSecond;
  unsigned long bitsPerSecond;
  BitrateMode audioBitrateMode = "variable";
  DOMHighResTimeStamp videoKeyFrameIntervalDuration;
  unsigned long videoKeyFrameIntervalCount;
};
</pre>

### Members ### {#mediarecorderoptions-members}

<dl class="domintro">
  <dt><dfn dict-member for="MediaRecorderOptions"><code>mimeType</code></dfn></dt>
  <dd>The container and codec format(s) [[!RFC2046]] for the recording, which
  may include any parameters that are defined for the format.

  <div class="note"> {{MediaRecorderOptions/mimeType}} specifies the media
  type and container format for the recording via a type/subtype
  combination, with the codecs and/or profiles parameters [[RFC6381]]
  specified where ambiguity might arise. Individual codecs might have
  further optional or mandatory specific parameters. </div></dd>

  <dt><dfn dict-member for="MediaRecorderOptions"><code>audioBitsPerSecond</code></dfn></dt>
  <dd>Aggregate target bits per second for encoding of the Audio track(s), if
  any.</dd>

  <dt><dfn dict-member for="MediaRecorderOptions"><code>videoBitsPerSecond</code></dfn></dt>
  <dd>Aggregate target bits per second for encoding of the Video track(s), if
  any.</dd>

  <dt><dfn dict-member for="MediaRecorderOptions"><code>bitsPerSecond</code></dfn></dt>
  <dd> Aggregate target bits per second for encoding of all Video and Audio
  Track(s) present. This member overrides either
  {{MediaRecorderOptions/audioBitsPerSecond}} or
  {{MediaRecorderOptions/videoBitsPerSecond}} if present, and might be
  distributed among the present track encoders as the UA sees fit.</dd>
  
  <dt><dfn dict-member for="MediaRecorderOptions"><code>audioBitrateMode</code></dfn></dt>
  <dd>Specifes the {{BitrateMode}} that should be used to encode the Audio track(s).</dd>

  <dt><dfn dict-member for="MediaRecorderOptions"><code>videoKeyFrameIntervalDuration</code></dfn></dt>
  <dd>Specifies the nominal interval in time between key frames in the encoded video stream.
  The UA controls key frame generation considering this dictionary member as well as 
  {{MediaRecorderOptions/videoKeyFrameIntervalCount}}.</dd>

  <dt><dfn dict-member for="MediaRecorderOptions"><code>videoKeyFrameIntervalCount</code></dfn></dt>
  <dd>Specifies the interval in number of frames between key frames in the encoded video stream.
  The UA controls key frame generation considering this dictionary member as well as 
  {{MediaRecorderOptions/videoKeyFrameIntervalDuration}}.</dd>
</dl>

## BitrateMode ## {#bitratemode}

<pre class="idl">
enum BitrateMode {
  "constant",
  "variable"
};
</pre>

### Values ### {#bitratemode-values}

<dl class="domintro">
  <dt><dfn enum-value for="BitrateMode"><code>constant</code></dfn></dt>
  <dd>Encode at a constant bitrate.</dd>

  <dt><dfn enum-value for="BitrateMode"><code>variable</code></dfn></dt>
  <dd>Encode using a variable bitrate, allowing more space to be used for complex signals
  and less space for less complex signals.</dd>
</dl>

## RecordingState ## {#recordingstate}

<pre class="idl">
enum RecordingState {
  "inactive",
  "recording",
  "paused"
};
</pre>

### Values ### {#recordingstate-values}

<dl class="domintro">
  <dt><dfn enum-value for="RecordingState"><code>inactive</code></dfn></dt>
  <dd>Recording is not occuring: Either it has not been started or it has been
  stopped.</dd>

  <dt><dfn enum-value for="RecordingState"><code>recording</code></dfn></dt>
  <dd>Recording has been started and the UA is capturing data.</dd>

  <dt><dfn enum-value for="RecordingState"><code>paused</code></dfn></dt>
  <dd>Recording has been started, then paused, and not yet stopped or resumed.</dd>
</dl>

# Blob Event # {#blobevent-section}

<pre class="idl">
  [Exposed=Window]
  interface BlobEvent : Event {
    constructor(DOMString type, BlobEventInit eventInitDict);
    [SameObject] readonly attribute Blob data;
    readonly attribute DOMHighResTimeStamp timecode;
  };
</pre>

## Constructors ## {#blobevent-constructor}

<dl class="domintro">
  <dt><dfn constructor for="BlobEvent"><code>BlobEvent(DOMString type, BlobEventInit eventInitDict)</code></dfn></dt>
  <dd></dd>
</dl>

## Attributes ## {#blobevent-attributes}

<dl class="domintro">
  <dt><dfn attribute for="BlobEvent"><code>data</code></dfn></dt>
  <dd>The encoded {{Blob}} whose {{Blob/type}} attribute indicates the
  encoding of the blob data.

  <dt><dfn attribute for="BlobEvent"><code>timecode</code></dfn></dt>
  <dd>The difference between the timestamp of the first chunk in
  {{BlobEvent/data}} and the timestamp of the first chunk in the first
  {{BlobEvent}} produced by this recorder as a {{DOMHighResTimeStamp}} [[!HR-TIME]].  Note that the {{BlobEvent/timecode}}
  in the first produced {{BlobEvent}} does not need to be zero.
  </dd>

</dl>

## BlobEventInit ## {#blobeventinit}

<pre class="idl">
dictionary BlobEventInit {
  required Blob data;
  DOMHighResTimeStamp timecode;
};
</pre>

### Members ### {#blobeventinit-members}

<dl class="domintro">
  <dt><dfn dict-member for="BlobEventInit"><code>data</code></dfn></dt>
  <dd>A {{Blob}} object containing the data to deliver via {{BlobEvent}}.</dd>

  <dt><dfn dict-member for="BlobEventInit"><code>timecode</code></dfn></dt>
  <dd>The timecode to be used in initializing {{BlobEvent}}.</dd>
</dl>

# Error handling # {#error-handling}

## General principles ## {#error-handling-principles}
<em>This section is non-normative.</em>

The UA will throw a {{DOMException}} when the error can be detected at the time
that the call is made. In all other cases the UA will <a>fire an error event</a>.  If recording has been started and not yet stopped
when the error occurs, let <var>blob</var> be the {{Blob}} of collected data so
far; after raising the error, the UA will <a data-lt="fire a blob event">fire a
dataavailable event</a> with <var>blob</var>; immediately after the UA will then
<a>fire an event</a> named <a event>stop</a>.
The UA may set platform-specific limits, such as those for the minimum and
maximum {{Blob}} size that it will support, or the number of
{{MediaStreamTrack}}s it will record at once.
It will signal a fatal error if these limits are exceeded.

## Error events ## {#errorevent-section}

To <dfn>fire an error event</dfn> means to [= fire an event =] using {{ErrorEvent}} as <var ignore>eventConstructor</var>.

## Exception Summary ## {#exception-summary}

Each of the exceptions defined in this document is a {{DOMException}} with a
specific type.

<table class="vert">
  <thead>
    <tr>
      <th>Name</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{InvalidStateError}}</td>
      <td>An operation was called on an object on which it is not allowed
      or at a time when it is not allowed, or if a request is made on a
      source object that has been deleted or removed.</td>
    </tr>
    <tr>
      <td>{{NotSupportedError}}</td>
      <td>An operation could not be performed because the MIME type was not
      supported or the set of tracks could not be recorded by the MIME type.
      User agents should provide as much additional information as possible in
      the <code>message</code> attribute.</td>
    </tr>
    <tr>
      <td>{{SecurityError}}</td>
      <td>The <a>isolation properties</a> of the {{MediaStream}} do not allow the
      MediaRecorder access to it.</td>
    </tr>
    <tr>
      <td>{{InvalidModificationError}}</td>
      <td>The set of {{MediaStreamTrack}}s of the recoded {{MediaStream}} has
      changed, preventing any further recording.</td>
    </tr>
  </tbody>
</table>


# Event summary # {#event-summary}

The following additional events fire on {{MediaRecorder}} objects:

<table class="vert">
  <thead>
    <tr>
      <th>Event name</th>
      <th>Interface</th>
      <th><a href="https://dom.spec.whatwg.org/#concept-event-fire">Fired
      </a> when...</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><dfn event for=MediaRecorder>start</dfn></td>
      <td>{{Event}}</td>
      <td>The UA has started recording data from the MediaStream.</td>
    </tr>
    <tr>
      <td><dfn event for=MediaRecorder>stop</dfn></td>
      <td>{{Event}}</td>
      <td>The UA has stopped recording data from the MediaStream.</td>
    </tr>
    <tr>
      <td><dfn event for=MediaRecorder>dataavailable</dfn></td>
      <td>{{BlobEvent}}</td>
      <td>The UA generates this event to return data to the application. The
      {{BlobEvent/data}} attribute of this event contains a {{Blob}} of recorded
      data.</td>
    </tr>
    <tr>
      <td><dfn event for=MediaRecorder>pause</dfn></td>
      <td>{{Event}}</td>
      <td>The UA has paused recording data from the MediaStream.</td>
    </tr>
    <tr>
      <td><dfn event for=MediaRecorder>resume</dfn></td>
      <td>{{Event}}</td>
      <td>The UA has resumed recording data from the MediaStream.</td>
    </tr>
    <tr>
      <td><dfn event for=MediaRecorder>error</dfn></td>
      <td>{{ErrorEvent}}</td>
      <td>An error has occurred, e.g. out of memory or a modification to
      the {{MediaRecorder/stream}} has occurred that makes it impossible to
      continue recording (e.g. a Track has been added to or removed from
      the said {{MediaRecorder/stream}} while recording is occurring).</td>
    </tr>
  </tbody>
</table>

# Privacy and Security Considerations # {#privacy-and-security}

<em>This section is non-normative</em>.

Given that the source of data for {{MediaRecorder}} is always going to be a
{{MediaStream}}, a large part of the security is essentially offloaded onto the
[[GETUSERMEDIA]] and its "Privacy and Security Consideration" Section. In
particular, the source {{MediaStream}} is assumed to be coming from a
<a>secure context</a>.

## Resource exhaustion ## {#resource-exhaustion}

Video and audio encoding can consume a great deal of resources. A malicious
website could try to block or bring down the UA by configuring too large a
workload, e.g. encoding large frame resolutions and/or framerates.

{{MediaRecorder}} can be configured to hold on to the encoded data for a certain
period of time upon {{start()}} by means of the {{timeslice}} parameter. Too
large a time slice parameter can force the UA to buffer a large amount of data,
causing jankiness and otherwise memory exhaustion.

UAs should take measures to avoid the encoding and buffering process from
exhausting the resources.

## Fingerprinting ## {#fingerprinting}

{{MediaRecorder}} provides information regarding the supported video and audio
MIME types via the {{isTypeSupported()}} method. It will also select the most
appropriate codec and bandwidth allocation combination when these are not
defined in the {{MediaRecorderOptions}}, and make this information available via
the {{Blob/type}} attribute of the <code>event</code>'s' <code>data</code>
received in {{ondataavailable}}. It will also try to honour the
{{MediaRecorderOptions}} if specified.

A malicious website could try to use this information for <a>active
fingerprinting</a> in a number of ways, e.g. it might try to

- Infer the device and hardware characteristics or determine the operating
    system vendor and/or version differences by means of identifying the user
    agent capabilities: a UA might provide use of a certain codec and/or hardware
    encoding accelerator only on a given platform (or generation thereof), or
    those might have a resolution/frame rate limit, making it vulnerable to
    fingerprinting.

- Infer any of the above by statistical measurements of system performance: e.g.
    the UA might provide different by-default bandwidth allocations depending on
    the hardware capabilities, or the UA could try measuring the system load when
    encoding different resolutions of certain input vectors.

The UAs should take measures to mitigate this <a>fingerprinting surface</a>
increase by e.g. implementing broad support for a given codec or MIME type and
not making it dependent on e.g. architecture or hardware revisions nor OS/
version support, to prevent device/hardware characteristics inference through
browser functionality. The UA should also take steps for making the default
values that limit the amount and identifiability of the UA capabilities.

# Examples # {#examples}

<div class="note">
Slightly modified versions of these examples can be found in e.g. <a
 href="https://codepen.io/collection/XjkNbN/">this codepen collection</a>.
</div>

## Check for {{MediaRecorder}} and content types ## {#example1}

This example checks if the implementation supports a few popular codec/container
combinations.

<div class="note">
The following example can also be found in e.g. <a
  href="https://codepen.io/miguelao/pen/edqNab?editors=0010">this codepen</a>
with minimal modifications.
</div>

<div class="example" highlight="javascript">
  <pre>
  if (window.MediaRecorder == undefined) {
    console.error('MediaRecorder not supported, boo');
  } else {
    var contentTypes = ["video/webm",
                        "video/webm;codecs=vp8",
                        "video/x-matroska;codecs=avc1",
                        "audio/webm",
                        "video/mp4;codecs=avc1",
                        "video/invalid"];
    contentTypes.forEach(contentType => {
      console.log(contentType + ' is '
          + (MediaRecorder.isTypeSupported(contentType) ?
              'supported' : 'NOT supported '));
    });
  }
  </pre>
</div>


## Recording webcam video and audio ## {#example2}

This example captures an video+audio {{MediaStream}} using {{MediaDevices/getUserMedia()}},
plugs it into a <code>&lt;video&gt;</code> tag and tries to record it,
retrieving the recorded chunks via the {{ondataavailable}} event.  Note that the
recording will go on forever until either MediaRecorder is {{stop()}}ed or all
the {{MediaStreamTrack}}s of the recorded {{MediaStream}} are {{ended}}.

<div class="note">
The following example can also be found in e.g. <a
 href="https://codepen.io/miguelao/pen/wzVMJb?editors=0010">this codepen</a>
with minimal modifications.
</div>

<div class="example" highlight="javascript">
  <pre>
  &lt;html>
  &lt;body>
  &lt;video autoplay/>
  &lt;script>
    var recordedChunks = [];

    function gotMedia(stream) {
      // |video| shows a live view of the captured MediaStream.
      var video = document.querySelector('video');
      video.src = URL.createObjectURL(stream);

      var recorder = null;
      try {
        recorder = new MediaRecorder(stream, {mimeType: "video/webm"});
      } catch (e) {
        console.error('Exception while creating MediaRecorder: ' + e);
        return;
      }

      recorder.ondataavailable = (event) => {
        console.log(' Recorded chunk of size ' + event.data.size + "B");
        recordedChunks.push(event.data);
      };

      recorder.start(100);
    }

    navigator.mediaDevices.getUserMedia({video: true, audio: true})
        .then(gotMedia)
        .catch(e => { console.error('getUserMedia() failed: ' + e); });
  &lt;/script>
  &lt;/body>
  &lt;/html>
  </pre>
</div>

<div class="note">
The <code>recordedChunks</code> can be saved to a file using e.g. the function
  <code>download()</code> in the <a
  href="https://developers.google.com/web/updates/2016/01/mediarecorder">
  MediaRecorder Web Fundamentals article</a>.
</div>


<pre class="anchors">
urlPrefix: https://www.w3.org/TR/mediacapture-streams/#; type: dfn; text: inactive; url: stream-inactive
urlPrefix: https://www.w3.org/TR/webrtc-identity/#; type: dfn; text: isolation properties; url: isolated-media-streams
urlPrefix: https://www.w3.org/TR/fingerprinting-guidance/#
    type: dfn
        text: active fingerprinting; url: dfn-active-fingerprinting
</pre>

<pre class="link-defaults">
spec:mediacapture-streams; type:enum-value; text:ended
spec:mediacapture-streams; type:attribute; text:muted
spec:mediacapture-streams; type:attribute; text:enabled
</pre>