0
# Simple Peer
1
2
Simple Peer provides a concise, Node.js-style API for WebRTC that enables simple peer-to-peer connections for video, voice, and data channels. It offers cross-platform compatibility, working in both browser and Node.js environments, with built-in support for duplex streams and advanced WebRTC features like trickle ICE candidates and transceivers.
3
4
## Package Information
5
6
- **Package Name**: simple-peer
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install simple-peer`
10
11
## Core Imports
12
13
```javascript
14
const Peer = require('simple-peer');
15
```
16
17
ES modules:
18
19
```javascript
20
import Peer from 'simple-peer';
21
```
22
23
Browser script tag:
24
25
```html
26
<script src="simplepeer.min.js"></script>
27
<!-- Creates global SimplePeer constructor -->
28
```
29
30
## Basic Usage
31
32
```javascript
33
const Peer = require('simple-peer');
34
35
// Create peers
36
const peer1 = new Peer({ initiator: true });
37
const peer2 = new Peer();
38
39
// Handle signaling
40
peer1.on('signal', data => {
41
// Send signaling data to peer2 somehow (websocket, etc.)
42
peer2.signal(data);
43
});
44
45
peer2.on('signal', data => {
46
// Send signaling data to peer1 somehow
47
peer1.signal(data);
48
});
49
50
// Handle connection
51
peer1.on('connect', () => {
52
peer1.send('Hello from peer1!');
53
});
54
55
peer2.on('data', data => {
56
console.log('Received:', data.toString());
57
});
58
59
// Don't forget to clean up
60
peer1.destroy();
61
peer2.destroy();
62
```
63
64
## Architecture
65
66
Simple Peer is built around several key components:
67
68
- **Peer Class**: Main WebRTC connection class extending Node.js Duplex streams
69
- **Signaling System**: Event-based signaling for offer/answer/ICE candidate exchange
70
- **Data Channels**: Automatic data channel setup for text/binary communication
71
- **Media Streams**: Built-in support for audio/video stream handling
72
- **Stream Interface**: Full Node.js duplex stream compatibility for data channels
73
74
## Capabilities
75
76
### Peer Connection Management
77
78
Core WebRTC peer connection functionality with automatic negotiation, signaling, and connection lifecycle management.
79
80
```javascript { .api }
81
class Peer extends Duplex {
82
constructor(opts?: PeerOptions);
83
signal(data: SignalData): void;
84
destroy(err?: Error): void;
85
}
86
87
interface PeerOptions {
88
initiator?: boolean;
89
channelConfig?: RTCDataChannelInit;
90
channelName?: string;
91
config?: RTCConfiguration;
92
offerOptions?: RTCOfferOptions;
93
answerOptions?: RTCAnswerOptions;
94
sdpTransform?: (sdp: string) => string;
95
stream?: MediaStream;
96
streams?: MediaStream[];
97
trickle?: boolean;
98
allowHalfTrickle?: boolean;
99
iceCompleteTimeout?: number;
100
wrtc?: WebRTCImplementation;
101
objectMode?: boolean;
102
allowHalfOpen?: boolean;
103
}
104
```
105
106
[Connection Management](./connection.md)
107
108
### Data Communication
109
110
Send and receive text or binary data through WebRTC data channels with automatic buffering and backpressure handling.
111
112
```javascript { .api }
113
// Direct data sending
114
peer.send(data: string | Buffer | ArrayBufferView | ArrayBuffer | Blob): void;
115
116
// Stream interface
117
peer.write(chunk: any, encoding?: string, callback?: Function): boolean;
118
peer.read(size?: number): any;
119
```
120
121
[Data Communication](./data.md)
122
123
### Media Stream Handling
124
125
Add, remove, and manage audio/video streams with support for track-level operations and dynamic stream modification.
126
127
```javascript { .api }
128
peer.addStream(stream: MediaStream): void;
129
peer.removeStream(stream: MediaStream): void;
130
peer.addTrack(track: MediaStreamTrack, stream: MediaStream): void;
131
peer.removeTrack(track: MediaStreamTrack, stream: MediaStream): void;
132
peer.replaceTrack(oldTrack: MediaStreamTrack, newTrack: MediaStreamTrack, stream: MediaStream): void;
133
peer.addTransceiver(kind: string, init?: RTCRtpTransceiverInit): void;
134
```
135
136
[Media Streams](./media.md)
137
138
### Connection Information
139
140
Access connection details, statistics, and peer addressing information.
141
142
```javascript { .api }
143
// Connection properties
144
peer.connected: boolean;
145
peer.bufferSize: number;
146
peer.destroyed: boolean;
147
148
// Address information
149
peer.localAddress: string;
150
peer.localPort: number;
151
peer.localFamily: string;
152
peer.remoteAddress: string;
153
peer.remotePort: number;
154
peer.remoteFamily: string;
155
156
// Methods
157
peer.address(): AddressInfo;
158
peer.getStats(callback: (err: Error | null, stats: RTCStats[]) => void): void;
159
```
160
161
[Connection Info](./info.md)
162
163
## Static Properties
164
165
```javascript { .api }
166
// WebRTC support detection
167
Peer.WEBRTC_SUPPORT: boolean;
168
169
// Default configurations
170
Peer.config: RTCConfiguration;
171
Peer.channelConfig: RTCDataChannelInit;
172
```
173
174
## Events
175
176
Simple Peer emits events following the Node.js EventEmitter pattern:
177
178
- **'signal'** - Signaling data ready to send to remote peer
179
- **'connect'** - Peer connection established and ready
180
- **'data'** - Data received from remote peer
181
- **'stream'** - Remote media stream received
182
- **'track'** - Remote media track received
183
- **'close'** - Connection closed
184
- **'error'** - Fatal error occurred
185
- **'iceStateChange'** - ICE connection state changed
186
- **'signalingStateChange'** - WebRTC signaling state changed
187
- **'negotiated'** - Peer connection negotiation completed
188
189
## Types
190
191
```javascript { .api }
192
interface SignalData {
193
type?: 'offer' | 'answer' | 'renegotiate' | 'transceiverRequest' | 'candidate';
194
sdp?: string;
195
candidate?: RTCIceCandidateInit;
196
renegotiate?: boolean;
197
transceiverRequest?: {
198
kind: string;
199
init?: RTCRtpTransceiverInit;
200
};
201
}
202
203
interface AddressInfo {
204
address: string;
205
family: string;
206
port: number;
207
}
208
209
interface WebRTCImplementation {
210
RTCPeerConnection: typeof RTCPeerConnection;
211
RTCSessionDescription: typeof RTCSessionDescription;
212
RTCIceCandidate: typeof RTCIceCandidate;
213
}
214
```