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:
```bash
bun install
```

2. Choose your architecture:

#### **Mesh Architecture (Simple)**
```bash
bun run dev
```
- **Best for:** 1-10 subscribers
- **Advantages:** Lowest latency, simple setup
- **Limitations:** Publisher bandwidth scales linearly with subscribers

#### **SFU Architecture (Scalable)**
```bash
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**
```bash
bun test
```

### **Architecture-Specific Tests**
```bash
# 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