initial
This commit is contained in:
182
examples/README.md
Normal file
182
examples/README.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user