webrtc2-peer
Version:
WebRTC2 Peer - Low-level WebRTC peer connection management for cross-platform real-time communication with signaling, ICE handling, and media streaming
334 lines (247 loc) • 8.31 kB
Markdown
# @webrtc2/peer - WebRTC Peer Connection Management
[](https://www.npmjs.com/package/@webrtc2/peer)
[](https://typescriptlang.org/)
[](https://webrtc.org/)
**Low-level WebRTC peer connection management** - Handle RTCPeerConnection, ICE candidates, signaling, and media streaming for cross-platform real-time communication.
## 🚀 WebRTC Peer Connection Made Easy
@webrtc2/peer provides the foundational layer for WebRTC applications:
- **🔗 RTCPeerConnection Management**: Create, configure, and manage peer connections
- **🧊 ICE Handling**: Automatic ICE candidate gathering and exchange
- **📡 Signaling Client**: WebSocket-based signaling for connection establishment
- **🎥 Media Manager**: Stream management and media device handling
- **⚡ Event-Driven**: EventEmitter-based architecture for real-time updates
- **🌐 Cross-Platform**: Works in browsers, React Native, and Electron
## 📦 Installation
```bash
npm install @webrtc2/peer
```
## 🎯 Quick Start
### Basic Peer Connection
```typescript
import { PeerConnection } from '@webrtc2/peer';
const peer = new PeerConnection({
iceServers: [
{ urls: 'stun:stun.l.google.com:19302' },
{
urls: 'turn:your-turn-server.com:3478',
username: 'user',
credential: 'password'
}
]
});
// Handle connection events
peer.on('connected', () => {
console.log('Peer connected!');
});
peer.on('stream', (stream) => {
console.log('Received remote stream:', stream);
});
peer.on('disconnected', () => {
console.log('Peer disconnected');
});
// Connect to remote peer
await peer.connect('remote-peer-id');
```
### Signaling Client
```typescript
import { SignalingClient } from '@webrtc2/peer';
const signaling = new SignalingClient('wss://your-signaling-server.com');
signaling.on('offer', async (offer, peerId) => {
await peer.handleOffer(offer, peerId);
});
signaling.on('answer', async (answer, peerId) => {
await peer.handleAnswer(answer, peerId);
});
signaling.on('ice-candidate', async (candidate, peerId) => {
await peer.addIceCandidate(candidate, peerId);
});
await signaling.connect();
```
### Media Manager
```typescript
import { MediaManager } from '@webrtc2/peer';
const mediaManager = new MediaManager();
// Get user media
const localStream = await mediaManager.getUserMedia({
video: { width: 1280, height: 720 },
audio: true
});
// Add stream to peer connection
peer.addStream(localStream);
// Handle device changes
mediaManager.on('device-change', (devices) => {
console.log('Available devices:', devices);
});
```
## 🔧 Advanced Features
### Custom ICE Configuration
```typescript
import { PeerConnection, ICEConfiguration } from '@webrtc2/peer';
const iceConfig: ICEConfiguration = {
iceServers: [
{ urls: 'stun:stun.l.google.com:19302' },
{ urls: 'stun:stun1.l.google.com:19302' }
],
iceCandidatePoolSize: 10,
bundlePolicy: 'max-bundle',
rtcpMuxPolicy: 'require'
};
const peer = new PeerConnection(iceConfig);
```
### Data Channel Support
```typescript
// Create data channel
const dataChannel = peer.createDataChannel('messages', {
ordered: true,
maxRetransmits: 3
});
dataChannel.onopen = () => {
console.log('Data channel opened');
dataChannel.send('Hello from peer!');
};
dataChannel.onmessage = (event) => {
console.log('Received message:', event.data);
};
// Handle incoming data channels
peer.on('datachannel', (channel) => {
console.log('Received data channel:', channel.label);
});
```
### Connection Statistics
```typescript
// Get connection stats
const stats = await peer.getStats();
console.log('Connection stats:', {
bitrate: stats.bitrate,
packetLoss: stats.packetLoss,
latency: stats.roundTripTime,
jitter: stats.jitter
});
// Monitor stats continuously
peer.on('stats', (stats) => {
if (stats.packetLoss > 0.05) {
console.warn('High packet loss detected:', stats.packetLoss);
}
});
```
## 🌐 Cross-Platform Usage
### React Native Integration
```typescript
import { PeerConnection } from '@webrtc2/peer';
import { mediaDevices } from 'react-native-webrtc';
// React Native specific media constraints
const peer = new PeerConnection({
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});
// Get camera stream for React Native
const stream = await mediaDevices.getUserMedia({
video: {
width: 640,
height: 480,
frameRate: 30,
facingMode: 'user'
},
audio: true
});
peer.addStream(stream);
```
### Electron Desktop
```typescript
// Electron main process
import { PeerConnection } from '@webrtc2/peer';
const peer = new PeerConnection({
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});
// Desktop screen sharing
const screenStream = await navigator.mediaDevices.getDisplayMedia({
video: { mediaSource: 'screen' },
audio: true
});
peer.addStream(screenStream);
```
## 🔧 API Reference
### PeerConnection Class
```typescript
class PeerConnection extends EventEmitter {
constructor(config: RTCConfiguration);
// Connection management
connect(peerId: string): Promise<void>;
disconnect(): void;
// Media handling
addStream(stream: MediaStream): void;
removeStream(stream: MediaStream): void;
// Data channels
createDataChannel(label: string, options?: RTCDataChannelInit): RTCDataChannel;
// Statistics
getStats(): Promise<RTCStatsReport>;
// Events
on('connected', callback: () => void): this;
on('disconnected', callback: () => void): this;
on('stream', callback: (stream: MediaStream) => void): this;
on('datachannel', callback: (channel: RTCDataChannel) => void): this;
}
```
### SignalingClient Class
```typescript
class SignalingClient extends EventEmitter {
constructor(url: string);
connect(): Promise<void>;
disconnect(): void;
sendOffer(offer: RTCSessionDescriptionInit, peerId: string): void;
sendAnswer(answer: RTCSessionDescriptionInit, peerId: string): void;
sendIceCandidate(candidate: RTCIceCandidateInit, peerId: string): void;
// Events
on('offer', callback: (offer: RTCSessionDescriptionInit, peerId: string) => void): this;
on('answer', callback: (answer: RTCSessionDescriptionInit, peerId: string) => void): this;
on('ice-candidate', callback: (candidate: RTCIceCandidateInit, peerId: string) => void): this;
}
```
### MediaManager Class
```typescript
class MediaManager extends EventEmitter {
getUserMedia(constraints: MediaStreamConstraints): Promise<MediaStream>;
getDisplayMedia(constraints?: DisplayMediaStreamConstraints): Promise<MediaStream>;
enumerateDevices(): Promise<MediaDeviceInfo[]>;
// Events
on('device-change', callback: (devices: MediaDeviceInfo[]) => void): this;
}
```
## 🐛 Troubleshooting
### Common ICE Connection Issues
```typescript
// Debug ICE connection state
peer.on('ice-connection-state-change', (state) => {
console.log('ICE connection state:', state);
if (state === 'failed') {
console.error('ICE connection failed - check TURN servers');
}
});
// Monitor ICE candidates
peer.on('ice-candidate', (candidate) => {
console.log('ICE candidate:', candidate);
});
```
### Signaling Connection Problems
```typescript
signaling.on('error', (error) => {
console.error('Signaling error:', error);
// Attempt reconnection
setTimeout(() => {
signaling.connect();
}, 5000);
});
signaling.on('disconnect', () => {
console.warn('Signaling disconnected - attempting reconnection');
});
```
## 📚 Related Packages
- [@webrtc2/client](../client) - React hooks and components
- [@webrtc2/types](../types) - TypeScript definitions
- [@webrtc2/utils](../utils) - Utility functions
- [@webrtc2/config](../config) - Configuration management
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
## 📄 License
MIT License - see [LICENSE](../../LICENSE) for details.
---
**Keywords**: WebRTC peer connection, RTCPeerConnection, WebRTC signaling, ICE candidates, STUN TURN servers, WebRTC media streaming, peer-to-peer connection, WebRTC JavaScript, WebRTC TypeScript, cross-platform WebRTC