Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Browser and Web APIs

MediaDevices.getUserMedia()

Reference for navigator.mediaDevices.getUserMedia(): constraints, permissions, MediaStream tracks, enumerateDevices(), error names and stopping the camera.

navigator.mediaDevices.getUserMedia(constraints) asks the user for access to a camera, a microphone or both. It returns a promise that fulfills with a MediaStream, which you can show in a <video> element, record with MediaRecorder, process with Web Audio, or send over WebRTC.

Because this exposes private devices, the browser always asks for permission, the page must be served from a secure context, and an indicator stays on while the device is in use. The constraints object says which kinds of media you want and, optionally, preferences such as resolution or which camera.

JavaScript
const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
document.querySelector("video").srcObject = stream;

Try it

The sandboxed editors on this site do not allow camera or microphone access, so the request is expected to be rejected here. The examples show how to ask and how to react to each kind of failure.

JS Requesting a camera, handling failure

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Turning error names into messages

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
const stream = await navigator.mediaDevices.getUserMedia(constraints)
const devices = await navigator.mediaDevices.enumerateDevices()
Name Description
constraints.video true, false, or an object with constraints such as width, height, frameRate, facingMode ("user" or "environment") and deviceId.
constraints.audio true, false, or an object with echoCancellation, noiseSuppression, autoGainControl, deviceId.
Constraint values A plain value, or an object with ideal, exact, min and max. ideal is a preference; exact makes the request fail if it cannot be met.

Return value: a promise for a MediaStream. Useful members: getTracks(), getVideoTracks(), getAudioTracks(), and on each track kind, label, enabled, readyState, stop(), getSettings().

Exceptions (promise rejections): NotAllowedError (denied by the user or policy), NotFoundError, NotReadableError, OverconstrainedError, SecurityError, and TypeError when neither audio nor video is requested.

Usage notes

  • Ask only when needed, ideally after a click on a clear button such as "Start camera".
  • Stop tracks when done. Call track.stop() for every track, or the camera light stays on. Removing the <video> element does not release the device.
  • Use muted and playsinline on the <video> element, plus autoplay, so the preview starts inside mobile browsers.
  • enumerateDevices() shows device kinds, but labels stay empty until permission has been given once.
  • Prefer ideal over exact. Exact constraints fail on devices that cannot match them.
  • Secure contexts only, and embedded iframes need allow="camera; microphone".
  • Permissions memory. Browsers may remember the choice per site, so handle both a silent success and a silent failure.
  • Screen capture is a separate API: navigator.mediaDevices.getDisplayMedia().

Browser support

getUserMedia() is supported in all current browsers on secure origins. Details such as supported constraints, resolutions and device labels differ between browsers and devices, so test on real hardware.