wl-webrtc/examples/README.md

# wl-webrtc Examples

This directory contains example client applications for connecting to wl-webrtc servers.

## client.html

A simple web-based client that demonstrates how to connect to a wl-webrtc server using WebRTC.

### Usage

1. **Start the wl-webrtc server:**
   ```bash
   ./target/release/wl-webrtc start
   ```

2. **Open the client in a web browser:**
   - Directly open `examples/client.html` in a browser
   - Or serve it with a local web server:
     ```bash
     # Python 3
     python -m http.server 8000
     # Then navigate to http://localhost:8000/examples/client.html
     ```

3. **Connect to the server:**
   - Enter the server URL (default: `ws://localhost:8443`)
   - Click "Connect"
   - Grant screen capture permissions when prompted by PipeWire
   - The video stream will appear in the browser

### Features

- **WebRTC Connection**: Real-time video streaming via WebRTC
- **Status Monitoring**: Display connection status, bitrate, resolution, FPS, and latency
- **Fullscreen Mode**: Press `Alt+F` or click "Fullscreen" button
- **Error Handling**: Displays connection errors with helpful messages
- **Responsive Design**: Works on desktop and mobile browsers

### Configuration

The client connects to a wl-webrtc server via WebSocket. By default, it connects to:
- **Server URL**: `ws://localhost:8443`

To connect to a remote server:
- Change the server URL in the input field
- Ensure the server is accessible (firewall, NAT, etc.)
- Configure STUN/TURN servers in the wl-webrtc config if needed

### Limitations

This is a minimal example client. Production clients should include:
- Authentication and authorization
- Secure HTTPS/WSS connections
- Input event forwarding (mouse, keyboard)
- Clipboard sharing
- Audio support
- Multiple screen selection
- Connection quality indicators
- Automatic reconnection

### Browser Compatibility

Tested on modern browsers with WebRTC support:
- Chrome 88+
- Firefox 85+
- Safari 15+
- Edge 88+

### Troubleshooting

**Connection fails:**
- Verify wl-webrtc server is running
- Check server URL is correct
- Check firewall settings
- Review browser console for errors

**No video appears:**
- Grant screen capture permissions
- Check if PipeWire is running
- Verify encoder is configured correctly
- Check server logs for errors

**Poor quality:**
- Increase bitrate in server config
- Use hardware encoder (h264_vaapi or h264_nvenc)
- Check network bandwidth
- Reduce resolution or frame rate

**High latency:**
- Check network ping to server
- Use wired connection instead of WiFi
- Reduce frame rate in server config
- Use faster preset (ultrafast)
- Ensure hardware encoder is being used

## Advanced Usage

### Custom Client Implementation

To build your own client:

1. **Connect via WebSocket** to the signaling server
2. **Create WebRTC PeerConnection** with ICE servers
3. **Create Offer** and send to server via WebSocket
4. **Receive Answer** and set as remote description
5. **Exchange ICE candidates** with server
6. **Receive video track** and display in HTML video element

Example signaling flow:
```
Client                    Server
   |                        |
   |-------- WebSocket ----->|
   |                        |
   |------- Offer --------->|
   |<------ Answer ---------|
   |                        |
   |--- ICE Candidate ----->|
   |<--- ICE Candidate -----|
   |                        |
   |<---- Video Stream -----|
   |                        |
```

### Data Channel Usage

The server supports WebRTC data channels for bi-directional messaging:

```javascript
// Client side
const dataChannel = peerConnection.createDataChannel('control');

dataChannel.onopen = () => {
    console.log('Data channel opened');
};

dataChannel.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('Received:', message);
};

// Send control messages
dataChannel.send(JSON.stringify({
    type: 'mouse_move',
    x: 100,
    y: 200
}));
```

### Server-Side Events

The server sends events over the data channel:

- `connection_established`: Connection is ready
- `connection_failed`: Connection failed
- `stats_update`: Performance statistics
- `error`: Error occurred

## Security Considerations

For production use:

1. **Use HTTPS/WSS** instead of HTTP/WS
2. **Implement authentication** (tokens, certificates)
3. **Validate all input** from clients
4. **Rate limit** connections
5. **Monitor for abuse**
6. **Keep dependencies updated**
7. **Use firewall rules** to restrict access
8. **Enable TLS** for encryption

## Additional Resources

- [wl-webrtc README](../README.md) - Main project documentation
- [DESIGN_CN.md](../DESIGN_CN.md) - Technical design and architecture
- [config.toml.template](../config.toml.template) - Server configuration reference
- [WebRTC API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API) - Browser WebRTC documentation
- [webrtc-rs](https://webrtc.rs/) - WebRTC implementation in Rust

## Contributing

Contributions and improvements to the examples are welcome! Please follow the main project's [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines.