wl-webrtc/examples

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:

   ./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:

     # 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:

// 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 - Main project documentation
• DESIGN_CN.md - Technical design and architecture
• config.toml.template - Server configuration reference
• WebRTC API - Browser WebRTC documentation
• webrtc-rs - WebRTC implementation in Rust

Contributing

Contributions and improvements to the examples are welcome! Please follow the main project's CONTRIBUTING.md guidelines.