MediaStream Recording API
=========================

The **MediaStream Recording API**, sometimes referred to as the *Media Recording API* or the *MediaRecorder API*, is closely affiliated with the Media Capture and Streams API and the WebRTC API. The MediaStream Recording API makes it possible to capture the data generated by a `MediaStream` or `HTMLMediaElement` object for analysis, processing, or saving to disk. It's also surprisingly easy to work with.

Concepts and usage
------------------

The MediaStream Recording API is comprised of a single major interface, `MediaRecorder`, which does all the work of taking the data from a `MediaStream` and delivering it to you for processing. The data is delivered by a series of `dataavailable` events, already in the format you specify when creating the `MediaRecorder`. You can then process the data further or write it to file as desired.

### Overview of the recording process

The process of recording a stream is simple:

1. Set up a `MediaStream` or `HTMLMediaElement` (in the form of an `<audio>` or `<video>` element) to serve as the source of the media data.
2. Create a `MediaRecorder` object, specifying the source stream and any desired options (such as the container's MIME type or the desired bit rates of its tracks).
3. Set `ondataavailable` to an event handler for the `dataavailable` event; this will be called whenever data is available for you.
4. Once the source media is playing and you've reached the point where you're ready to record video, call `MediaRecorder.start()` to begin recording.
5. Your `dataavailable` event handler gets called every time there's data ready for you to do with as you will; the event has a `data` attribute whose value is a `Blob` that contains the media data. You can force a `dataavailable` event to occur, thereby delivering the latest sound to you so you can filter it, save it, or whatever.
6. Recording stops automatically when the source media stops playing.
7. You can stop recording at any time by calling `MediaRecorder.stop()`.

**Note:** Individual `Blob`s containing slices of the recorded media will not necessarily be individually playable. The media needs to be reassembled before playback.

If anything goes wrong during recording, an `error` event is sent to the `MediaRecorder`. You can listen for `error` events by setting up a `onerror` event handler.

Example here, we use an HTML Canvas as source of the `MediaStream`, and stop recording after 9 seconds.


```js
const canvas = document.querySelector("canvas");

// Optional frames per second argument.
const stream = canvas.captureStream(25);
const recordedChunks = [];

console.log(stream);
const options = { mimeType: "video/webm; codecs=vp9" };
const mediaRecorder = new MediaRecorder(stream, options);

mediaRecorder.ondataavailable = handleDataAvailable;
mediaRecorder.start();

function handleDataAvailable(event) {
  console.log("data-available");
  if (event.data.size > 0) {
    recordedChunks.push(event.data);
    console.log(recordedChunks);
    download();
  } else {
    // …
  }
}
function download() {
  const blob = new Blob(recordedChunks, {
    type: "video/webm",
  });
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  document.body.appendChild(a);
  a.style = "display: none";
  a.href = url;
  a.download = "test.webm";
  a.click();
  window.URL.revokeObjectURL(url);
}

// demo: to download after 9sec
setTimeout((event) => {
  console.log("stopping");
  mediaRecorder.stop();
}, 9000);
```

### Examining and controlling the recorder status

You can also use the properties of the `MediaRecorder` object to determine the state of the recording process, and its `pause()` and `resume()` methods to pause and resume recording of the source media.

If you need or want to check to see if a specific MIME type is supported, that's possible as well. Just call `MediaRecorder.isTypeSupported()`.

### Examining potential input sources

If your goal is to record camera and/or microphone input, you may wish to examine the available input devices before beginning the process of constructing the `MediaRecorder`. To do so, you'll need to call `navigator.mediaDevices.enumerateDevices()` to get a list of the available media devices. You can then examine that list and identify the potential input sources, and even filter the list based on desired criteria.

In this code snippet, `enumerateDevices()` is used to examine the available input devices, locate those which are audio input devices, and create `<option>` elements that are then added to a `<select>` element representing an input source picker.


```js
navigator.mediaDevices.enumerateDevices().then((devices) => {
  devices.forEach((device) => {
    const menu = document.getElementById("inputdevices");
    if (device.kind === "audioinput") {
      const item = document.createElement("option");
      item.textContent = device.label;
      item.value = device.deviceId;
      menu.appendChild(item);
    }
  });
});
```


Code similar to this can be used to let the user restrict the set of devices they wish to use.

### For more information

To learn more about using the MediaStream Recording API, see Using the MediaStream Recording API, which shows how to use the API to record audio clips. A second article, Recording a media element, describes how to receive a stream from an `<audio>` or `<video>` element and use the captured stream (in this case, recording it and saving it to a local disk).

Interfaces
----------

`BlobEvent`

Each time a chunk of media data is finished being recorded, it's delivered to consumers in `Blob` form using a `BlobEvent` of type `dataavailable`.

`MediaRecorder`

The primary interface that implements the MediaStream Recording API.

`MediaRecorderErrorEvent` 
Deprecated

Non-standard

The interface that represents errors thrown by the MediaStream Recording API. Its `error` property is a `DOMException` that specifies that error occurred.

Specifications
--------------

| Specification |
| --- |
| MediaStream Recording  |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Media Capture and Streams API landing page
* `MediaDevices.getUserMedia()`
* simpl.info MediaStream Recording demo, by Sam Dutton
* HTML5's Media Recorder API in Action on Chrome and Firefox
* MediaRecorder polyfill for Safari and Edge
* TutorRoom: HTML video capture/playback/download using getUserMedia and the MediaStream Recording API (source on GitHub)
* Simple video recording demo
* Advanced media stream recorder sample
* OpenLang: HTML video language lab web application using MediaDevices and the MediaStream Recording API for video recording (source on GitHub)
* MediaStream Recorder API Now Available in Safari Technology Preview 73