WebRTC-Broadcast/README.md

WebRTC Broadcasting Application

A full-stack TypeScript application using Bun that enables one publisher to broadcast a stream to multiple subscribers using WebRTC.

Architecture

This application follows SOLID principles with clean separation of concerns:

Backend Services

• ClientManager: Manages connected clients and their roles
• SignalingService: Handles WebSocket signaling between publisher and subscribers
• Server: Bun-based HTTP/WebSocket server with routing

Frontend Services

• WebSocketClient: Manages WebSocket connections and messaging
• MediaHandler: Handles media capture and stream management
• UIController: Manages user interface updates and interactions
• PublisherRTCManager: Manages WebRTC peer connections for publishers
• SubscriberRTCManager: Manages WebRTC peer connections for subscribers

Features

• One-to-Many Broadcasting: Single publisher streams to multiple subscribers
• Real-time Signaling: WebSocket-based signaling for WebRTC negotiation
• Responsive UI: Clean, modern interface for both publisher and subscriber
• Connection Management: Automatic handling of client connections and disconnections
• Live Subscriber Count: Publisher can see how many subscribers are watching
• Error Handling: Robust error handling and user feedback

Getting Started

Prerequisites

• Bun runtime installed
• Modern web browser with WebRTC support
• Camera and microphone access (for publisher)

Installation

1. Install dependencies:

bun install

2. Choose your architecture:

Mesh Architecture (Simple)

bun run dev

• Best for: 1-10 subscribers
• Advantages: Lowest latency, simple setup
• Limitations: Publisher bandwidth scales linearly with subscribers

SFU Architecture (Scalable)

bun run sfu

• Best for: 10+ subscribers
• Advantages: Constant publisher bandwidth, server-side optimization
• Features: Adaptive bitrate, stream forwarding, scalable to hundreds

Usage

Mesh Version (http://localhost:3000)

1. Access the application:

   • Main page: http://localhost:3000
   • Publisher interface: http://localhost:3000/publisher
   • Subscriber interface: http://localhost:3000/subscriber

2. Publishing a stream:

   • Open the publisher interface
   • Click "Start Broadcasting"
   • Allow camera and microphone access
   • Direct peer-to-peer connections to subscribers

3. Subscribing to a stream:

   • Open the subscriber interface (can open multiple tabs/windows)
   • Click "Connect to Stream"
   • Direct connection to publisher

SFU Version (http://localhost:3001)

1. Access the SFU application:

   • Main page: http://localhost:3001
   • Publisher interface: http://localhost:3001/publisher
   • Subscriber interface: http://localhost:3001/subscriber
   • Live statistics: http://localhost:3001/stats

2. Publishing via SFU:

   • Open the publisher interface
   • Click "Start Broadcasting"
   • Stream goes to SFU server, then forwarded to all subscribers
   • Bandwidth stays constant regardless of subscriber count

3. Subscribing via SFU:

   • Open the subscriber interface (open many tabs to test scalability!)
   • Click "Connect to Stream"
   • Receive optimized stream from SFU server
   • Adaptive quality based on connection

Architecture Comparison

Feature	Mesh	SFU
Best Use Case	1-10 subscribers	10+ subscribers
Publisher Bandwidth	Scales with subscribers	Constant
Server Resources	Minimal	Medium
Latency	Lowest	Low
Scalability	Poor (max ~10)	Excellent (100s)
Setup Complexity	Simple	Moderate
Connection Type	Peer-to-peer	Server-mediated

When to Choose Each:

Choose Mesh When:

• Small audience (< 10 viewers)
• Lowest possible latency required
• Simple deployment preferred
• Publisher has excellent upload bandwidth

Choose SFU When:

• Large audience (10+ viewers)
• Publisher has limited upload bandwidth
• Need adaptive bitrate streaming
• Want server-side stream management
• Scaling to hundreds of viewers

Testing

Comprehensive test suites for both architectures:

Run All Tests

bun test

Architecture-Specific Tests

# Test Mesh Architecture (Basic)
bun run test:basic

# Test SFU Architecture 
bun run test:sfu

Test Coverage

• ✅ 41 Total Tests - All passing
• ✅ Mesh Architecture (5 tests) - Basic functionality, signaling, client management
• ✅ SFU Architecture (36 tests) - Client management, signaling service, integration tests
• ✅ Unit Tests - Individual service testing with mocks
• ✅ Integration Tests - Full message flow and scaling scenarios

Development

• Hot reload: Both servers run with hot reload enabled for development
• TypeScript: Full TypeScript support with proper type checking
• SOLID Principles: Codebase follows SOLID principles for maintainability
• Live Statistics: SFU version includes real-time performance monitoring
• Test-Driven: Comprehensive test coverage for all functionality

API Endpoints

• GET /: Main landing page
• GET /publisher: Publisher interface
• GET /subscriber: Subscriber interface
• WebSocket /?role=publisher|subscriber: WebSocket endpoint for signaling

Project Structure

├── src/
│   ├── interfaces/         # TypeScript interfaces
│   └── services/           # Backend services
├── public/
│   ├── js/
│   │   ├── interfaces/     # Frontend interfaces
│   │   └── services/       # Frontend services
│   ├── publisher.html      # Publisher interface
│   └── subscriber.html     # Subscriber interface
├── server.ts              # Main server file
└── package.json           # Project configuration

Technology Stack

• Runtime: Bun
• Backend: TypeScript, WebSockets
• Frontend: TypeScript, WebRTC API, HTML5 Media API
• Real-time Communication: WebRTC + WebSocket signaling
• Architecture: SOLID principles, dependency injection

Browser Support

• Chrome 60+
• Firefox 60+
• Safari 13+
• Edge 80+

License

MIT