or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

connection.mddata.mdindex.mdinfo.mdmedia.md
tile.json

tessl/npm-simple-peer

Simple one-to-one WebRTC video/voice and data channels

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/simple-peer@9.11.x

To install, run

npx @tessl/cli install tessl/npm-simple-peer@9.11.0

index.mddocs/

Simple Peer

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.

Package Information

  • Package Name: simple-peer
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install simple-peer

Core Imports

const Peer = require('simple-peer');

ES modules:

import Peer from 'simple-peer';

Browser script tag:

<script src="simplepeer.min.js"></script>
<!-- Creates global SimplePeer constructor -->

Basic Usage

const Peer = require('simple-peer');

// Create peers
const peer1 = new Peer({ initiator: true });
const peer2 = new Peer();

// Handle signaling
peer1.on('signal', data => {
  // Send signaling data to peer2 somehow (websocket, etc.)
  peer2.signal(data);
});

peer2.on('signal', data => {
  // Send signaling data to peer1 somehow  
  peer1.signal(data);
});

// Handle connection
peer1.on('connect', () => {
  peer1.send('Hello from peer1!');
});

peer2.on('data', data => {
  console.log('Received:', data.toString());
});

// Don't forget to clean up
peer1.destroy();
peer2.destroy();

Architecture

Simple Peer is built around several key components:

  • Peer Class: Main WebRTC connection class extending Node.js Duplex streams
  • Signaling System: Event-based signaling for offer/answer/ICE candidate exchange
  • Data Channels: Automatic data channel setup for text/binary communication
  • Media Streams: Built-in support for audio/video stream handling
  • Stream Interface: Full Node.js duplex stream compatibility for data channels

Capabilities

Peer Connection Management

Core WebRTC peer connection functionality with automatic negotiation, signaling, and connection lifecycle management.

class Peer extends Duplex {
  constructor(opts?: PeerOptions);
  signal(data: SignalData): void;
  destroy(err?: Error): void;
}

interface PeerOptions {
  initiator?: boolean;
  channelConfig?: RTCDataChannelInit;
  channelName?: string;
  config?: RTCConfiguration;
  offerOptions?: RTCOfferOptions;
  answerOptions?: RTCAnswerOptions;
  sdpTransform?: (sdp: string) => string;
  stream?: MediaStream;
  streams?: MediaStream[];
  trickle?: boolean;
  allowHalfTrickle?: boolean;
  iceCompleteTimeout?: number;
  wrtc?: WebRTCImplementation;
  objectMode?: boolean;
  allowHalfOpen?: boolean;
}

Connection Management

Data Communication

Send and receive text or binary data through WebRTC data channels with automatic buffering and backpressure handling.

// Direct data sending
peer.send(data: string | Buffer | ArrayBufferView | ArrayBuffer | Blob): void;

// Stream interface  
peer.write(chunk: any, encoding?: string, callback?: Function): boolean;
peer.read(size?: number): any;

Data Communication

Media Stream Handling

Add, remove, and manage audio/video streams with support for track-level operations and dynamic stream modification.

peer.addStream(stream: MediaStream): void;
peer.removeStream(stream: MediaStream): void;
peer.addTrack(track: MediaStreamTrack, stream: MediaStream): void;
peer.removeTrack(track: MediaStreamTrack, stream: MediaStream): void;
peer.replaceTrack(oldTrack: MediaStreamTrack, newTrack: MediaStreamTrack, stream: MediaStream): void;
peer.addTransceiver(kind: string, init?: RTCRtpTransceiverInit): void;

Media Streams

Connection Information

Access connection details, statistics, and peer addressing information.

// Connection properties
peer.connected: boolean;
peer.bufferSize: number;
peer.destroyed: boolean;

// Address information
peer.localAddress: string;
peer.localPort: number;
peer.localFamily: string;
peer.remoteAddress: string;
peer.remotePort: number;
peer.remoteFamily: string;

// Methods
peer.address(): AddressInfo;
peer.getStats(callback: (err: Error | null, stats: RTCStats[]) => void): void;

Connection Info

Static Properties

// WebRTC support detection
Peer.WEBRTC_SUPPORT: boolean;

// Default configurations
Peer.config: RTCConfiguration;
Peer.channelConfig: RTCDataChannelInit;

Events

Simple Peer emits events following the Node.js EventEmitter pattern:

  • 'signal' - Signaling data ready to send to remote peer
  • 'connect' - Peer connection established and ready
  • 'data' - Data received from remote peer
  • 'stream' - Remote media stream received
  • 'track' - Remote media track received
  • 'close' - Connection closed
  • 'error' - Fatal error occurred
  • 'iceStateChange' - ICE connection state changed
  • 'signalingStateChange' - WebRTC signaling state changed
  • 'negotiated' - Peer connection negotiation completed

Types

interface SignalData {
  type?: 'offer' | 'answer' | 'renegotiate' | 'transceiverRequest' | 'candidate';
  sdp?: string;
  candidate?: RTCIceCandidateInit;
  renegotiate?: boolean;
  transceiverRequest?: {
    kind: string;
    init?: RTCRtpTransceiverInit;
  };
}

interface AddressInfo {
  address: string;
  family: string;
  port: number;
}

interface WebRTCImplementation {
  RTCPeerConnection: typeof RTCPeerConnection;
  RTCSessionDescription: typeof RTCSessionDescription;
  RTCIceCandidate: typeof RTCIceCandidate;
}