CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-webrtc-adapter

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

Overall
score

98%

Overview
Eval results
Files

common-shims.mddocs/

Common Shims

Common shims are universal WebRTC compatibility fixes applied across all browsers to handle differences in WebRTC specification implementations and ensure consistent behavior.

Capabilities

RTCIceCandidate Shimming

Normalizes RTCIceCandidate interface across browsers by parsing and augmenting candidate properties.

/**
 * Shims RTCIceCandidate to parse and augment candidate properties
 * Adds parsed fields from SDP candidate string to the candidate object
 * @param window - Browser window object
 */
function shimRTCIceCandidate(window: Window): void;

What it fixes:

  • Removes erroneous 'a=' prefix from candidate strings
  • Adds parsed candidate properties (foundation, component, priority, etc.)
  • Standardizes candidate serialization with toJSON method
  • Ensures consistent icecandidate event handling

Usage Examples:

import adapter from 'webrtc-adapter';

// RTCIceCandidate is automatically shimmed after import
const candidate = new RTCIceCandidate({
  candidate: 'candidate:1 1 UDP 2113667327 192.168.1.100 54400 typ host',
  sdpMid: '0',
  sdpMLineIndex: 0
});

// Parsed properties are automatically available
console.log(candidate.foundation); // '1'
console.log(candidate.component); // 1
console.log(candidate.priority); // 2113667327
console.log(candidate.address); // '192.168.1.100'
console.log(candidate.port); // 54400
console.log(candidate.type); // 'host'

RTCIceCandidate Relay Protocol Shimming

Adds relayProtocol property to relay-type ICE candidates based on priority values.

/**
 * Adds relayProtocol property to ICE candidates for relay connections
 * Maps libwebrtc priority values to protocol names
 * @param window - Browser window object
 */
function shimRTCIceCandidateRelayProtocol(window: Window): void;

What it fixes:

  • Adds missing relayProtocol property to relay candidates
  • Maps priority bits to protocol names: 'tls', 'tcp', 'udp'
  • Provides standard way to identify relay connection type

Max Message Size Shimming

Provides maxMessageSize property for SCTP data channels when not natively supported.

/**
 * Shims maxMessageSize property for SCTP data channels
 * Provides consistent way to query maximum message size limits
 * @param window - Browser window object
 * @param browserDetails - Browser detection information
 */
function shimMaxMessageSize(window: Window, browserDetails: IBrowserDetails): void;

What it fixes:

  • Adds maxMessageSize property to RTCPeerConnection.sctp
  • Provides browser-specific message size limits
  • Standardizes data channel size constraint queries

Usage Examples:

import adapter from 'webrtc-adapter';

const pc = new RTCPeerConnection();

// Check maximum message size (automatically shimmed)
if (pc.sctp && pc.sctp.maxMessageSize) {
  console.log('Max message size:', pc.sctp.maxMessageSize);
  
  // Send data respecting size limits
  const data = 'Large message content...';
  if (data.length <= pc.sctp.maxMessageSize) {
    dataChannel.send(data);
  }
}

Send Type Error Shimming

Ensures DataChannel.send() throws TypeError for invalid data types.

/**
 * Shims data channel send to throw TypeError for invalid data types
 * Standardizes error handling across browser implementations
 * @param window - Browser window object
 */
function shimSendThrowTypeError(window: Window): void;

What it fixes:

  • Ensures consistent TypeError for invalid send() parameters
  • Standardizes data channel error handling behavior
  • Provides predictable exception patterns

Connection State Shimming

Provides connectionState property for RTCPeerConnection when not natively available.

/**
 * Shims RTCPeerConnection connectionState property
 * Derives connection state from iceConnectionState when needed
 * @param window - Browser window object
 */
function shimConnectionState(window: Window): void;

What it fixes:

  • Adds missing connectionState property and events
  • Maps iceConnectionState values to connectionState
  • Provides consistent connection monitoring API

Usage Examples:

import adapter from 'webrtc-adapter';

const pc = new RTCPeerConnection();

// Connection state is automatically available
pc.addEventListener('connectionstatechange', () => {
  console.log('Connection state:', pc.connectionState);
  
  switch (pc.connectionState) {
    case 'connected':
      console.log('Peer connection established');
      break;
    case 'disconnected':
      console.log('Peer connection lost');
      break;
    case 'failed':
      console.log('Peer connection failed');
      break;
  }
});

Extmap Allow Mixed Removal

Removes problematic extmap-allow-mixed attribute from SDP.

/**
 * Removes extmap-allow-mixed attribute from SDP
 * Prevents compatibility issues with certain browsers
 * @param window - Browser window object  
 * @param browserDetails - Browser detection information
 */
function removeExtmapAllowMixed(window: Window, browserDetails: IBrowserDetails): void;

What it fixes:

  • Removes extmap-allow-mixed from offer/answer SDP
  • Prevents negotiation failures in mixed browser scenarios
  • Ensures wider browser compatibility

Add ICE Candidate Null/Empty Handling

Handles null or empty ICE candidate additions gracefully.

/**
 * Handles null or empty ICE candidate additions gracefully
 * Standardizes end-of-candidates signaling behavior
 * @param window - Browser window object
 * @param browserDetails - Browser detection information
 */
function shimAddIceCandidateNullOrEmpty(window: Window, browserDetails: IBrowserDetails): void;

What it fixes:

  • Allows null candidate to signal end of candidates
  • Handles empty candidate objects properly
  • Standardizes ICE gathering completion signaling

Parameterless SetLocalDescription

Enables parameterless setLocalDescription() calls.

/**
 * Supports parameterless setLocalDescription calls
 * Automatically uses last created offer/answer when no parameters provided
 * @param window - Browser window object
 * @param browserDetails - Browser detection information  
 */
function shimParameterlessSetLocalDescription(window: Window, browserDetails: IBrowserDetails): void;

What it fixes:

  • Enables modern parameterless setLocalDescription() usage
  • Automatically applies last created offer/answer
  • Simplifies WebRTC negotiation code patterns

Usage Examples:

import adapter from 'webrtc-adapter';

const pc = new RTCPeerConnection();

// Modern parameterless usage (automatically shimmed)
const offer = await pc.createOffer();
await pc.setLocalDescription(); // Uses created offer automatically

// Traditional explicit usage still works
await pc.setLocalDescription(offer);

Common Shim Interface

All common shims are available through the adapter object:

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;
}

These shims are automatically applied when importing webrtc-adapter, and are accessible via adapter.commonShim for manual application or testing purposes.

Install with Tessl CLI

npx tessl i tessl/npm-webrtc-adapter

docs

browser-detection.md

chrome-shims.md

common-shims.md

factory-configuration.md

firefox-shims.md

index.md

safari-shims.md

utility-functions.md

tile.json