or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-detection.mdchrome-shims.mdcommon-shims.mdfactory-configuration.mdfirefox-shims.mdindex.mdsafari-shims.mdutility-functions.md
tile.json

tessl/npm-webrtc-adapter

A shim to insulate apps from WebRTC spec changes and browser prefix differences

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/webrtc-adapter@9.0.x

To install, run

npx @tessl/cli install tessl/npm-webrtc-adapter@9.0.0

index.mddocs/

WebRTC Adapter

WebRTC Adapter is a JavaScript shim library that provides WebRTC compatibility across different browsers by normalizing API differences and handling browser-specific quirks. It automatically detects the browser environment and applies appropriate polyfills to ensure consistent WebRTC behavior across Chrome, Firefox, Safari, and other WebRTC-enabled browsers.

Package Information

  • Package Name: webrtc-adapter
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install webrtc-adapter

Core Imports

import adapter from 'webrtc-adapter';

For CommonJS:

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

Factory function import:

import { adapterFactory } from 'webrtc-adapter/src/js/adapter_factory.js';

Basic Usage

import adapter from 'webrtc-adapter';

// Browser detection
console.log(adapter.browserDetails.browser); // 'chrome', 'firefox', 'safari'
console.log(adapter.browserDetails.version); // Browser version number

// WebRTC APIs are automatically shimmed after import
const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});

// Use WebRTC APIs normally - adapter handles browser differences
pc.createOffer().then(offer => {
  console.log('Offer created:', offer);
});

Architecture

WebRTC Adapter follows a modular architecture:

  • Main Adapter Object: Central interface providing browser detection and shim access
  • Browser Detection: Automatic identification of WebRTC engine and capabilities
  • Common Shims: Universal compatibility fixes applied across all browsers
  • Browser-Specific Shims: Targeted fixes for Chrome, Firefox, and Safari quirks
  • Utility Functions: Helper functions for stats processing, logging, and event handling
  • Factory Pattern: Configurable adapter creation with selective shim enabling

Capabilities

Browser Detection and Information

Provides comprehensive browser detection with version information and WebRTC capability assessment.

interface IBrowserDetails {
  browser: string;
  version: number | null;
  supportsUnifiedPlan?: boolean;
}

// Main adapter object properties
const adapter: {
  browserDetails: IBrowserDetails;
  extractVersion: (uastring: string, expr: string, pos: number) => number | null;
  disableLog: (disable: boolean) => string | Error;
  disableWarnings: (disable: boolean) => string | Error;
  sdp: any; // SDP utilities from sdp package
};

Browser Detection

Adapter Factory and Configuration

Factory function for creating customized adapter instances with selective shim enabling.

function adapterFactory(
  {window}?: {window?: Window}, 
  options?: {
    shimChrome?: boolean;
    shimFirefox?: boolean; 
    shimSafari?: boolean;
  }
): IAdapter;

interface IAdapter {
  browserDetails: IBrowserDetails;
  commonShim: ICommonShim;
  browserShim: IChromeShim | IFirefoxShim | ISafariShim | undefined;
  extractVersion: (uastring: string, expr: string, pos: number) => number | null;
  disableLog: (disable: boolean) => string | Error;
  disableWarnings: (disable: boolean) => string | Error;
  sdp: any; // SDP utilities from sdp package
}

Factory and Configuration

Common WebRTC Shims

Universal compatibility shims applied across all browsers to handle common WebRTC specification differences.

interface ICommonShim {
  shimRTCIceCandidate: (window: Window, browserDetails?: IBrowserDetails) => void;
  shimRTCIceCandidateRelayProtocol: (window: Window, browserDetails?: IBrowserDetails) => void;
  shimMaxMessageSize: (window: Window, browserDetails: IBrowserDetails) => void;
  shimSendThrowTypeError: (window: Window) => void;
  shimConnectionState: (window: Window, browserDetails?: IBrowserDetails) => void;
  removeExtmapAllowMixed: (window: Window, browserDetails: IBrowserDetails) => void;
  shimAddIceCandidateNullOrEmpty: (window: Window, browserDetails: IBrowserDetails) => void;
  shimParameterlessSetLocalDescription: (window: Window, browserDetails: IBrowserDetails) => void;
}

Common Shims

Chrome-Specific Shims

Compatibility fixes specifically for Chrome and Chromium-based browsers.

interface IChromeShim {
  shimGetUserMedia: (window: Window, browserDetails: IBrowserDetails) => void;
  shimMediaStream: (window: Window, browserDetails?: IBrowserDetails) => void;
  shimOnTrack: (window: Window, browserDetails?: IBrowserDetails) => void;
  shimGetSendersWithDtmf: (window: Window, browserDetails?: IBrowserDetails) => void;
  shimSenderReceiverGetStats: (window: Window, browserDetails?: IBrowserDetails) => void;
  shimAddTrackRemoveTrackWithNative: (window: Window, browserDetails?: IBrowserDetails) => void;
  shimAddTrackRemoveTrack: (window: Window, browserDetails: IBrowserDetails) => void;
  shimPeerConnection: (window: Window, browserDetails: IBrowserDetails) => void;
  fixNegotiationNeeded: (window: Window, browserDetails: IBrowserDetails) => void;
}

Chrome Shims

Firefox-Specific Shims

Compatibility fixes specifically for Firefox browsers.

interface IFirefoxShim {
  shimOnTrack: (window: Window) => void;
  shimPeerConnection: (window: Window, browserDetails: IBrowserDetails) => void;
  shimSenderGetStats: (window: Window) => void;
  shimReceiverGetStats: (window: Window) => void;
  shimRemoveStream: (window: Window) => void;
  shimRTCDataChannel: (window: Window) => void;
}

Firefox Shims

Safari-Specific Shims

Compatibility fixes specifically for Safari browsers.

interface ISafariShim {
  shimLocalStreamsAPI: (window: Window) => void;
  shimRemoteStreamsAPI: (window: Window) => void;
  shimCallbacksAPI: (window: Window) => void;
  shimGetUserMedia: (window: Window) => void;
  shimConstraints: (constraints: MediaStreamConstraints) => void;
  shimRTCIceServerUrls: (window: Window) => void;
  shimTrackEventTransceiver: (window: Window) => void;
  shimCreateOfferLegacy: (window: Window) => void;
}

Safari Shims

Utility Functions

Helper functions for WebRTC stats processing, event handling, and debugging.

// Logging and debugging utilities
function disableLog(bool: boolean): string | Error;
function disableWarnings(bool: boolean): string | Error;
function log(...args: any[]): void;
function deprecated(oldMethod: string, newMethod: string): void;

// Browser detection utilities  
function detectBrowser(window: Window): IBrowserDetails;
function extractVersion(uastring: string, expr: string, pos: number): number;

// WebRTC utilities
function wrapPeerConnectionEvent(
  window: Window, 
  eventNameToWrap: string, 
  wrapper: Function
): void;

function compactObject(data: any): any;
function walkStats(stats: Map<any, any>, base: any, resultSet: Map<any, any>): void;
function filterStats(result: Map<any, any>, track: MediaStreamTrack | null, outbound: boolean): Map<any, any>;

Utility Functions

SDP Utilities

Access to SDP (Session Description Protocol) parsing and manipulation utilities from the sdp dependency.

// Available as adapter.sdp
const sdp: {
  parseCandidate: (candidate: string) => any;
  writeCandidate: (candidate: any) => string;
  // Additional SDP utilities from sdp package
};

The SDP utilities are exposed through the main adapter object for convenience, providing direct access to Session Description Protocol parsing and manipulation functions.