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.
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.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
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
mutedandplaysinlineon the<video>element, plusautoplay, so the preview starts inside mobile browsers. enumerateDevices()shows device kinds, but labels stay empty until permission has been given once.- Prefer
idealoverexact. 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.