Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Environment, Secure Contexts and Permissions

Set up for WebRTC: secure contexts (HTTPS and localhost), camera and microphone permission prompts, Permissions-Policy, feature detection and browser support.

WebRTC code is easy to write and surprisingly easy to see fail for reasons that have nothing to do with WebRTC: the page was loaded over plain HTTP, the user clicked "Block", an iframe lacked permission, or the browser lacked a feature. This lesson covers the environment rules so you recognise those failures immediately.

Secure contexts

Capturing the camera or microphone is only allowed in a secure context. A page is secure when it is served over HTTPS, or from http://localhost or 127.0.0.1 for development. On a plain http:// page on a real domain, navigator.mediaDevices is undefined, and calling navigator.mediaDevices.getUserMedia(...) throws a TypeError because mediaDevices does not exist.

RTCPeerConnection itself works on insecure pages, but real products need HTTPS anyway: browsers will not hand over the camera, and your signalling channel should be encrypted (wss://, not ws://).

You can ask the browser directly:

JavaScript
if (!window.isSecureContext) {
  console.warn('Camera and microphone need HTTPS or localhost.');
}

Permissions

The first call to getUserMedia shows a prompt such as "Allow this site to use your camera?". The returned promise stays pending until the user decides. The outcomes:

Error name Meaning
NotAllowedError The user (or a policy) denied access
NotFoundError No device matches the request
NotReadableError The device exists but is busy or failed (another app uses it)
OverconstrainedError A required constraint could not be met
SecurityError Not allowed in this context (for example an unsafe origin)
TypeError Bad constraints, or mediaDevices is missing

Handle each in the UI: tell the user what to do, not just that something failed.

You can query permission state without prompting:

JavaScript
const camera = await navigator.permissions.query({ name: 'camera' });
console.log(camera.state);          // 'granted' | 'denied' | 'prompt'
camera.onchange = () => console.log('Now', camera.state);

Support for camera and microphone in the Permissions API varies by browser (Firefox historically does not support them), so always wrap this in try/catch and still handle errors from getUserMedia.

Ask for access when the user clicks "Join" or "Turn on camera", not on page load. Users trust a prompt that follows an action they just took, and some browsers remember a "dismiss" and stop asking.

Permissions-Policy and iframes

If your page is embedded in an iframe, the parent must allow the capabilities:

HTML
<iframe src="https://meet.example.com" allow="camera; microphone; display-capture"></iframe>

The server can also send a Permissions-Policy: camera=(self), microphone=(self) header. If the policy forbids a feature, getUserMedia rejects even though the user never saw a prompt. The preview iframes used on this site do not grant camera or microphone, which is why the camera examples in this course use synthetic sources and show the real capture code as read-only.

Feature detection

Do not sniff user-agent strings. Test for the feature you need:

A feature detection report

Your results depend on your browser. Parameterless setLocalDescription() (used in perfect negotiation) cannot be detected with a property test, but every current browser supports it.

Browser support and quirks

All current Chrome, Edge, Firefox and Safari versions support the core API: peer connections, data channels, getUserMedia, getDisplayMedia. Differences you will actually hit:

  • Safari is strict about user gestures: video.play() for remote streams needs playsinline and muted or a click. Autoplay rules are stricter everywhere than for ordinary video.
  • Codec support differs: H.264 hardware paths vary, AV1 and VP9 are not universal, and Opus is universal.
  • Mobile browsers suspend capture when the tab goes into the background.
  • Firefox does not expose every getStats field Chrome does, and some newer features arrive later.

For older projects you may have used the adapter.js shim, which normalised vendor prefixes. Modern browsers no longer need it for the basics; add it only if you must support old versions and you have measured the need.

Autoplay and remote video

Even with permission, playing the remote video can fail until the user interacts with the page. The reliable markup is:

HTML
<video id="remote" autoplay playsinline></video>

autoplay plays when data arrives, playsinline stops iOS from forcing full screen. If the stream has audio and the page has had no user gesture, add a "Click to start" button that calls video.play().

A development checklist

  1. Use http://localhost while developing, or an HTTPS tunnel when testing on a phone.
  2. Test with at least two different browsers.
  3. Test the "denied" path: block the permission once and check your UI recovers.
  4. Test with the camera busy in another app (NotReadableError).
  5. Keep the browser console open; WebRTC logs useful warnings there.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. On http://example.com (not HTTPS), what is navigator.mediaDevices?

    mediaDevices is exposed only in secure contexts. Use HTTPS, or localhost during development.
  2. 2. Which error means the user clicked Block?

    NotAllowedError means permission was denied by the user or by a policy.
  3. 3. How does a parent page allow an embedded iframe to use the camera?

    The iframe needs the allow attribute (or a matching Permissions-Policy). Otherwise the capture request is rejected.
  4. 4. When is the best moment to call getUserMedia?

    A prompt that follows a clear user action is understood and trusted, and avoids autoplay and gesture restrictions.

Summary

  • Camera and microphone capture need a secure context (HTTPS or localhost).
  • Learn the capture errors: NotAllowedError, NotFoundError, NotReadableError, OverconstrainedError.
  • Iframes need allow="camera; microphone"; servers can set a Permissions-Policy.
  • Detect features instead of browsers, and use autoplay playsinline on remote video.

Next: The Offer/Answer Handshake