WebRTC getUserMedia: Access Camera and Mic Devices

Every WebRTC app starts by asking for the camera and microphone, and that first call is where a surprising number of support tickets begin. The API is small: navigator.mediaDevices has a handful of methods. The trouble is in the details, like constraints that fail on one laptop, device names that come back blank, and errors that each need a different message for the user.

The minimum getUserMedia call that works

The full API is defined in the W3C Media Capture and Streams spec, and MDN's getUserMedia reference tracks browser support. This is all you need to start:

const video = document.querySelector('video');

try {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: true,
    audio: true,
  });
  video.srcObject = stream;
  await video.play();
} catch (err) {
  console.error(err.name, err.message);
}

Three things have to be true for this to run at all:

• A secure context. navigator.mediaDevices only exists on HTTPS pages and http://localhost. On plain HTTP, even on your LAN, it is undefined.
• A user gesture is wise. Browsers allow the permission prompt without one, but prompting the moment a page loads gets denied far more often than prompting after a "Join" click.
• Permissions policy. Inside an iframe, the embedding page must allow it with allow="camera; microphone", which is the step people miss when embedding a meeting with something like the Jitsi Meet IFrame API.

When you are done, stop the tracks. Removing the video element is not enough; the camera light stays on until every track is stopped:

stream.getTracks().forEach((track) => track.stop());

WebRTC constraints without surprises

Constraints ask for a resolution, frame rate, camera direction or audio processing. The rule that matters: use ideal, not exact, min or max, unless failing is really what you want.

const stream = await navigator.mediaDevices.getUserMedia({
  video: {
    width: { ideal: 1280 },
    height: { ideal: 720 },
    frameRate: { ideal: 30 },
    facingMode: 'user',          // 'environment' for the rear camera
  },
  audio: {
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});

ideal means "get as close as you can". exact, min and max are hard requirements, and when a device can't meet them the promise rejects with OverconstrainedError. A min height of 720 works on your desk and fails on half your users' webcams.

Check what you actually got, because the browser may give you less than you asked for:

const [track] = stream.getVideoTracks();
console.log(track.getSettings());   // { width: 1280, height: 720, frameRate: 30, deviceId: ... }

navigator.mediaDevices.getSupportedConstraints() tells you which constraint names the browser understands, not what a particular camera can do. For device capabilities, use track.getCapabilities() after you have a track.

WebRTC device listing and switching with mediaDevices

const devices = await navigator.mediaDevices.enumerateDevices();
const cameras = devices.filter((d) => d.kind === 'videoinput');
const mics = devices.filter((d) => d.kind === 'audioinput');
const speakers = devices.filter((d) => d.kind === 'audiooutput');

If the labels come back as empty strings, that is by design. Browsers hide device names until the page has permission, so call getUserMedia first and enumerate again afterwards. Listen for hardware being plugged in or removed:

navigator.mediaDevices.addEventListener('devicechange', refreshDevicePicker);

To open a specific device, pass its deviceId. Inside a call, switch cameras without renegotiating by replacing the track on the existing sender:

const newStream = await navigator.mediaDevices.getUserMedia({
  video: { deviceId: { exact: selectedCameraId } },
});
const [newTrack] = newStream.getVideoTracks();

const sender = peerConnection.getSenders().find((s) => s.track && s.track.kind === 'video');
await sender.replaceTrack(newTrack);
oldVideoTrack.stop();

exact is correct here: the user picked that camera, and silently falling back to another one would be worse than an error.

Errors you must handle

A pattern worth copying: if video fails with NotFoundError or NotReadableError, retry with { audio: true, video: false } and let the user join without a camera. Far better than a dead end. When users report problems you can't reproduce, debugging WebRTC in Chrome, Firefox and Safari shows where the browser logs device and connection failures.

Screen capture

Screen sharing uses a sibling method on the same object. Note that it lives on navigator.mediaDevices, not on navigator directly, as some older examples show:

const screen = await navigator.mediaDevices.getDisplayMedia({
  video: true,
  audio: true,   // tab or system audio, where the browser supports it
});

It must be called from a user gesture, and the user always chooses what to share. WebRTC screen share and recording goes into capture options, sending it over a peer connection and recording it.

Testing without a camera

CI machines have no webcams, and a permission prompt blocks any automated test. Two approaches.

Browser flags, the easy one. Chromium can supply a fake device and accept the prompt automatically:

--use-fake-device-for-media-stream
--use-fake-ui-for-media-stream

In Playwright pass them in launchOptions.args; in Cypress add them in the before:browser:launch hook. You get a moving test pattern and a beep tone.

Cypress stub for navigator.mediaDevices.getUserMedia

Stubbing the API when you need control over the stream, for example to test how your UI handles a specific resolution or silence. Build a real MediaStream from a canvas and Web Audio:

function fakeStream() {
  const canvas = Object.assign(document.createElement('canvas'), { width: 640, height: 480 });
  const ctx = canvas.getContext('2d');
  setInterval(() => {
    ctx.fillStyle = '#' + Math.floor(Math.random() * 0xffffff).toString(16).padStart(6, '0');
    ctx.fillRect(0, 0, canvas.width, canvas.height);
  }, 100);
  const video = canvas.captureStream(10);

  const audioCtx = new AudioContext();
  const destination = audioCtx.createMediaStreamDestination();
  const osc = audioCtx.createOscillator();
  osc.connect(destination);
  osc.start();

  return new MediaStream([...video.getVideoTracks(), ...destination.stream.getAudioTracks()]);
}

// Cypress
cy.visit('/call', {
  onBeforeLoad(win) {
    cy.stub(win.navigator.mediaDevices, 'getUserMedia').callsFake(() => Promise.resolve(fakeStream()));
  },
});

Stubbing tests your code, not the browser. Keep at least one test that runs with the fake-device flags against the real API, so a change in permissions behaviour doesn't reach users first.

Once you have streams, the next steps are connecting them. Building a WebRTC signaling server covers exchanging offers and answers, and how WebRTC works puts the pieces together.

Related Articles

WebRTC Screen Share and Recording: Developer Guide (2026)

How to implement WebRTC screen share and desktop sharing, plus screen recording with getDisplayMedia and MediaRecorder: capture, security, and performance for real-time web apps.

By Kelum Sampath • Meetrix.io

How WebRTC Works: Architecture, Signaling, and Media Flow Explained

The WebRTC architecture explained: how signaling, SDP, and ICE connect two browsers, and where mesh, SFU, and MCU media flow diverge in production.

By Binuka Ranatunga • Meetrix.io

WebRTC Leaks: What They Are and How to Stop Them

A WebRTC leak exposes your real IP address even behind a VPN. Here's how the leak actually happens, how to test for it, and what fixes it without breaking your video calls.

By Kelum Sampath • Meetrix.io

STUN vs TURN vs ICE: WebRTC NAT Traversal Explained

STUN vs TURN vs ICE explained plainly: what each one actually does, why WebRTC calls fail behind NAT, and when you need your own TURN server.

By Binuka Ranatunga • Meetrix.io