WebRTC Adapter

Common errors

• ReferenceError: adapter is not defined

  cause Attempting to access the `adapter` object without properly importing it in a module environment or before its script tag has executed in a global environment.
  fix If using a module system (ESM/CommonJS), ensure you have `import adapter from 'webrtc-adapter';` or `const adapter = require('webrtc-adapter');` at the top of your file. If using a `<script>` tag, ensure the adapter script is loaded before your code that references `adapter`.

• TypeError: navigator.mediaDevices is undefined

  cause Accessing `navigator.mediaDevices` in an older browser or a browser context where it's not yet defined, or when the `webrtc-adapter` shim has not been properly applied.
  fix Ensure `webrtc-adapter` is loaded and executed *before* any WebRTC API calls, especially `navigator.mediaDevices.getUserMedia`. The adapter polyfills `navigator.mediaDevices` for older browsers or contexts where it might be missing or prefixed. Also, check if the browser fundamentally supports WebRTC.

Warnings

• gotcha The package `webrtc-adapter-test` is an internal or deprecated testing package (version 0.2.10). For production use and active development, install and use the `webrtc-adapter` package (latest is 9.0.4).
  Fix: Use `npm install webrtc-adapter` and `import adapter from 'webrtc-adapter';`.
• breaking Major version updates of `webrtc-adapter` can introduce breaking changes, such as the removal of legacy shims (e.g., `navigator.getDisplayMedia` shim was removed) or modifications to API function signatures (`getStats`). These changes align with WebRTC specification evolution, but can break older applications.
  Fix: Always pin the exact version of `webrtc-adapter` in your `package.json` (e.g., `"webrtc-adapter": "^9.0.4"` to `"webrtc-adapter": "9.0.4"`) and thoroughly test when upgrading versions. Review release notes for breaking changes.
• gotcha When bundling for the browser, be aware of the different output files: `adapter.js` exposes the `adapter` object globally on `window.adapter`, while `adapter_no_global.js` does not. Choose the correct file based on whether you expect a global object or plan to import it as a module.
  Fix: If using a script tag and expecting global access, ensure you are loading `adapter.js`. If using a module bundler, typically `import adapter from 'webrtc-adapter';` is sufficient, and a global is not exposed unless explicitly configured by the bundler or the `adapter.js` variant.
• deprecated Direct browser prefix usage (e.g., `navigator.webkitGetUserMedia`) is deprecated. While the adapter historically handled these, modern WebRTC development should target the standard `navigator.mediaDevices.getUserMedia` and `RTCPeerConnection` APIs, letting the adapter manage subtle browser differences.
  Fix: Always use the standard, unprefixed WebRTC APIs. The adapter will apply necessary shims behind the scenes. Regularly update the adapter to ensure support for the latest browser behaviors.

Install

• npm install webrtc-adapter-test npm
• yarn add webrtc-adapter-test yarn
• pnpm add webrtc-adapter-test pnpm

Imports

• adapter (global)
  wrong:

  import adapter from 'webrtc-adapter'; // when using script tag

  correct:

  <!-- included via script tag -->

  When included via a `<script>` tag, the `adapter` object is typically exposed globally on `window.adapter`. This is often derived from `node_modules/webrtc-adapter/out/adapter.js`.
• adapter (ESM)
  wrong:

  const adapter = require('webrtc-adapter'); // For modern browser builds (ESM)

  correct:

  import adapter from 'webrtc-adapter';

  For module bundlers (Webpack, Rollup, Vite) or native ESM in browsers, import the default export. This approach does not expose a global `window.adapter` by default.
• adapter (CJS)
  wrong:

  import adapter from 'webrtc-adapter'; // In CommonJS environments (Node.js/older bundlers)

  correct:

  const adapter = require('webrtc-adapter');

  For CommonJS environments, `require` is the correct method. The adapter primarily shims browser APIs, so its direct use in Node.js might be limited to utility functions like `browserDetails`.
• adapter.browserDetails
  wrong:

  console.log(window.browserDetails.browser); // Not a direct global

  correct:

  console.log(adapter.browserDetails.browser);

  The `browserDetails` object, containing `browser` and `version` properties, is accessed via the `adapter` object to detect the WebRTC engine.

Quickstart

This quickstart demonstrates how to import and use the WebRTC Adapter, then acquire and display a local video and audio stream using `navigator.mediaDevices.getUserMedia` which the adapter may have shimmed. It also logs browser details detected by the adapter.

import adapter from 'webrtc-adapter';

const localVideo = document.createElement('video');
localVideo.autoplay = true;
localVideo.muted = true;
document.body.appendChild(localVideo);

console.log('WebRTC Adapter loaded. Browser:', adapter.browserDetails.browser, 'Version:', adapter.browserDetails.version);

const startMedia = async () => {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      video: true,
      audio: true
    });
    localVideo.srcObject = stream;
    console.log('Local stream acquired and displayed.');
  } catch (e) {
    console.error('Error accessing media devices:', e);
    alert(`Error accessing media: ${e.name} - ${e.message}`);
  }
};

startMedia();