0
# WebRTC Adapter
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: webrtc-adapter
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install webrtc-adapter`
10

11
## Core Imports
12

13
```javascript
14
import adapter from 'webrtc-adapter';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const adapter = require('webrtc-adapter');
21
```
22

23
Factory function import:
24

25
```javascript
26
import { adapterFactory } from 'webrtc-adapter/src/js/adapter_factory.js';
27
```
28

29
## Basic Usage
30

31
```javascript
32
import adapter from 'webrtc-adapter';
33

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

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

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

49
## Architecture
50

51
WebRTC Adapter follows a modular architecture:
52

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

60
## Capabilities
61

62
### Browser Detection and Information
63

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

66
```javascript { .api }
67
interface IBrowserDetails {
68
  browser: string;
69
  version: number | null;
70
  supportsUnifiedPlan?: boolean;
71
}
72

73
// Main adapter object properties
74
const adapter: {
75
  browserDetails: IBrowserDetails;
76
  extractVersion: (uastring: string, expr: string, pos: number) => number | null;
77
  disableLog: (disable: boolean) => string | Error;
78
  disableWarnings: (disable: boolean) => string | Error;
79
  sdp: any; // SDP utilities from sdp package
80
};
81
```
82

83
[Browser Detection](./browser-detection.md)
84

85
### Adapter Factory and Configuration
86

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

89
```javascript { .api }
90
function adapterFactory(
91
  {window}?: {window?: Window}, 
92
  options?: {
93
    shimChrome?: boolean;
94
    shimFirefox?: boolean; 
95
    shimSafari?: boolean;
96
  }
97
): IAdapter;
98

99
interface IAdapter {
100
  browserDetails: IBrowserDetails;
101
  commonShim: ICommonShim;
102
  browserShim: IChromeShim | IFirefoxShim | ISafariShim | undefined;
103
  extractVersion: (uastring: string, expr: string, pos: number) => number | null;
104
  disableLog: (disable: boolean) => string | Error;
105
  disableWarnings: (disable: boolean) => string | Error;
106
  sdp: any; // SDP utilities from sdp package
107
}
108
```
109

110
[Factory and Configuration](./factory-configuration.md)
111

112
### Common WebRTC Shims
113

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

116
```javascript { .api }
117
interface ICommonShim {
118
  shimRTCIceCandidate: (window: Window, browserDetails?: IBrowserDetails) => void;
119
  shimRTCIceCandidateRelayProtocol: (window: Window, browserDetails?: IBrowserDetails) => void;
120
  shimMaxMessageSize: (window: Window, browserDetails: IBrowserDetails) => void;
121
  shimSendThrowTypeError: (window: Window) => void;
122
  shimConnectionState: (window: Window, browserDetails?: IBrowserDetails) => void;
123
  removeExtmapAllowMixed: (window: Window, browserDetails: IBrowserDetails) => void;
124
  shimAddIceCandidateNullOrEmpty: (window: Window, browserDetails: IBrowserDetails) => void;
125
  shimParameterlessSetLocalDescription: (window: Window, browserDetails: IBrowserDetails) => void;
126
}
127
```
128

129
[Common Shims](./common-shims.md)
130

131
### Chrome-Specific Shims
132

133
Compatibility fixes specifically for Chrome and Chromium-based browsers.
134

135
```javascript { .api }
136
interface IChromeShim {
137
  shimGetUserMedia: (window: Window, browserDetails: IBrowserDetails) => void;
138
  shimMediaStream: (window: Window, browserDetails?: IBrowserDetails) => void;
139
  shimOnTrack: (window: Window, browserDetails?: IBrowserDetails) => void;
140
  shimGetSendersWithDtmf: (window: Window, browserDetails?: IBrowserDetails) => void;
141
  shimSenderReceiverGetStats: (window: Window, browserDetails?: IBrowserDetails) => void;
142
  shimAddTrackRemoveTrackWithNative: (window: Window, browserDetails?: IBrowserDetails) => void;
143
  shimAddTrackRemoveTrack: (window: Window, browserDetails: IBrowserDetails) => void;
144
  shimPeerConnection: (window: Window, browserDetails: IBrowserDetails) => void;
145
  fixNegotiationNeeded: (window: Window, browserDetails: IBrowserDetails) => void;
146
}
147
```
148

149
[Chrome Shims](./chrome-shims.md)
150

151
### Firefox-Specific Shims
152

153
Compatibility fixes specifically for Firefox browsers.
154

155
```javascript { .api }
156
interface IFirefoxShim {
157
  shimOnTrack: (window: Window) => void;
158
  shimPeerConnection: (window: Window, browserDetails: IBrowserDetails) => void;
159
  shimSenderGetStats: (window: Window) => void;
160
  shimReceiverGetStats: (window: Window) => void;
161
  shimRemoveStream: (window: Window) => void;
162
  shimRTCDataChannel: (window: Window) => void;
163
}
164
```
165

166
[Firefox Shims](./firefox-shims.md)
167

168
### Safari-Specific Shims
169

170
Compatibility fixes specifically for Safari browsers.
171

172
```javascript { .api }
173
interface ISafariShim {
174
  shimLocalStreamsAPI: (window: Window) => void;
175
  shimRemoteStreamsAPI: (window: Window) => void;
176
  shimCallbacksAPI: (window: Window) => void;
177
  shimGetUserMedia: (window: Window) => void;
178
  shimConstraints: (constraints: MediaStreamConstraints) => void;
179
  shimRTCIceServerUrls: (window: Window) => void;
180
  shimTrackEventTransceiver: (window: Window) => void;
181
  shimCreateOfferLegacy: (window: Window) => void;
182
}
183
```
184

185
[Safari Shims](./safari-shims.md)
186

187
### Utility Functions
188

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

191
```javascript { .api }
192
// Logging and debugging utilities
193
function disableLog(bool: boolean): string | Error;
194
function disableWarnings(bool: boolean): string | Error;
195
function log(...args: any[]): void;
196
function deprecated(oldMethod: string, newMethod: string): void;
197

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

202
// WebRTC utilities
203
function wrapPeerConnectionEvent(
204
  window: Window, 
205
  eventNameToWrap: string, 
206
  wrapper: Function
207
): void;
208

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

214
[Utility Functions](./utility-functions.md)
215

216
### SDP Utilities
217

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

220
```javascript { .api }
221
// Available as adapter.sdp
222
const sdp: {
223
  parseCandidate: (candidate: string) => any;
224
  writeCandidate: (candidate: any) => string;
225
  // Additional SDP utilities from sdp package
226
};
227
```
228

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