initial

config.toml.template

@@ -0,0 +1,266 @@
+# wl-webrtc Configuration Template
+#
+# This file serves as a template for configuring the wl-webrtc remote desktop backend.
+# Copy this file to 'config.toml' and modify the values as needed.
+#
+# Values can be overridden using command-line arguments:
+#   wl-webrtc --frame-rate 60 --width 1280 --height 720 --bitrate-mbps 4 --port 9000 start
+#
+# For detailed documentation, see:
+#   README.md - Project documentation
+#   DESIGN_CN.md - Technical design and architecture
+#
+# Configuration Philosophy:
+#   - Optimize for your use case (LAN vs WAN, quality vs performance)
+#   - Start with conservative settings, then adjust based on performance
+#   - Hardware encoders (VA-API/NVENC) provide better performance than software
+#   - Lower latency often requires trade-offs in quality or resource usage
+
+[capture]
+# Capture settings
+#
+# frame_rate: Target frames per second for screen capture
+#   Range: 1-144
+#   Default: 30
+#   Higher values provide smoother video but require more resources
+#   Recommended values:
+#     15-24: Acceptable for mostly static content, lower bandwidth
+#     30-60: Good balance for general use
+#     60-144: For gaming or highly dynamic content
+#   Note: Encoder frame_rate should match or be a divisor of this value
+frame_rate = 30
+
+# quality: Overall quality level for capture and encoding
+#   Options: low, medium, high, ultra
+#   Default: high
+#   Affects encoding parameters and resource usage
+#   This is a preset that adjusts multiple encoder parameters:
+#     low    - Fastest encoding, lowest quality, minimal CPU/bandwidth
+#     medium - Good balance for most scenarios
+#     high   - Better quality, moderate resource usage
+#     ultra  - Best quality, higher resource usage
+quality = "high"
+
+# screen_region: Optional region of screen to capture
+#   Format: { x = 0, y = 0, width = 1920, height = 1080 }
+#   Default: null (entire screen)
+#   Comment out to capture full screen
+#   Capturing a smaller region significantly reduces bandwidth and CPU
+#   Example: Capture only a specific application window
+# screen_region = { x = 0, y = 0, width = 1920, height = 1080 }
+
+[encoder]
+# Encoder settings
+#
+# encoder_type: Video encoder to use
+#   Options:
+#     h264_x264 - Software H.264 via x264 (best compatibility, higher CPU)
+#     h264_vaapi - Hardware H.264 via VA-API (Linux Intel/AMD GPU)
+#     h264_nvenc - Hardware H.264 via NVENC (NVIDIA GPU)
+#     vp9 - Software VP9 (better compression, higher CPU)
+#   Default: h264_x264
+#   Recommendation: Use hardware encoders (h264_vaapi or h264_nvenc) for lowest latency
+#   Zero-Copy Note: Hardware encoders can directly process DMA-BUF with no CPU copies
+encoder_type = "h264_x264"
+
+# width: Output video width
+#   Range: 320-7680
+#   Default: 1920
+#   Reducing width significantly lowers bandwidth and CPU usage
+width = 1920
+
+# height: Output video height
+#   Range: 240-4320
+#   Default: 1080
+#   Common resolutions: 1080, 720, 480
+height = 1080
+
+# frame_rate: Encoder frame rate
+#   Range: 1-144
+#   Default: 30
+#   Should match or be a divisor of capture frame rate
+frame_rate = 30
+
+# bitrate: Target video bitrate in bits per second
+#   Range: 100,000 to 50,000,000 (0.1 Mbps to 50 Mbps)
+#   Default: 4,000,000 (4 Mbps)
+#   Example values:
+#     500,000   (0.5 Mbps)  - Low quality, minimal bandwidth
+#     2,000,000 (2 Mbps)    - Good quality, moderate bandwidth
+#     4,000,000 (4 Mbps)    - High quality, typical bandwidth
+#     8,000,000 (8 Mbps)    - Very high quality, high bandwidth
+bitrate = 4000000
+
+# max_bitrate: Maximum allowed bitrate
+#   Range: 100,000 to 50,000,000
+#   Default: 8,000,000 (8 Mbps)
+#   Must be greater than min_bitrate
+#   Used for adaptive bitrate control
+max_bitrate = 8000000
+
+# min_bitrate: Minimum allowed bitrate
+#   Range: 100,000 to 50,000,000
+#   Default: 500,000 (0.5 Mbps)
+#   Must be less than max_bitrate
+#   Prevents quality degradation below this threshold
+min_bitrate = 500000
+
+# keyframe_interval: Keyframe (I-frame) interval in frames
+#   Range: 1-300
+#   Default: 60 (every 2 seconds at 30 fps)
+#   Smaller values increase keyframe frequency (better recovery, higher bitrate)
+#   Larger values reduce keyframe frequency (lower bitrate, slower recovery)
+keyframe_interval = 60
+
+# preset: Encoding speed vs quality tradeoff
+#   Options (fastest to slowest):
+#     ultrafast - Lowest latency, lowest quality (~10-15% CPU reduction vs veryfast)
+#     superfast  - Very low latency, low quality (~5% CPU reduction vs veryfast)
+#     veryfast   - Recommended for 15-25ms latency, good quality
+#     faster     - Slightly better quality, slight latency increase
+#     fast       - Good quality, moderate latency (30-40ms)
+#     medium     - Balanced quality and latency (40-60ms)
+#     slow       - Better quality, higher latency (60-80ms)
+#     slower     - Good quality, high latency (80-120ms)
+#     veryslow   - Highest quality, highest latency (120-200ms)
+#   Default: veryfast
+#   Latency Impact: Each step slower adds ~5-15ms to end-to-end latency
+#   Quality Impact: Each step slower improves compression by ~5-10%
+#   Recommendation: Use ultrafast/superfast for gaming, veryfast for general use
+preset = "veryfast"
+
+# tune: Encoder tuning parameter
+#   Options:
+#     zerolatency - Optimize for minimal latency (recommended)
+#     film - Optimize for film content
+#     animation - Optimize for animation
+#     stillimage - Optimize for static images
+#   Default: zerolatency
+tune = "zerolatency"
+
+[webrtc]
+# WebRTC transport settings
+#
+# port: Server listening port
+#   Range: 1-65535
+#   Default: 8443
+#   Ensure port is not blocked by firewall
+#   Note: This port needs to be accessible from client browsers
+#   For HTTPS/WSS, consider using 443 or 8443
+port = 8443
+
+# ice_servers: ICE servers for NAT traversal
+#   Format: Array of STUN/TURN server URLs
+#   Default: ["stun:stun.l.google.com:19302"]
+#   Google's public STUN server works for most scenarios
+#   For production, consider using your own STUN/TURN servers
+ice_servers = [
+    "stun:stun.l.google.com:19302"
+]
+
+# stun_servers: STUN servers specifically
+#   Format: Array of STUN server URLs
+#   Default: ["stun:stun.l.google.com:19302"]
+stun_servers = [
+    "stun:stun.l.google.com:19302"
+]
+
+# turn_servers: TURN servers for relay
+#   Required for networks that block direct UDP connections
+#   Format: Array of TURN server configurations
+#   Default: [] (no TURN servers)
+#
+# Example TURN configuration (uncomment to use):
+# [[webrtc.turn_servers]]
+# urls = ["turn:your-turn-server.com:3478?transport=udp"]
+# username = "your-username"
+# credential = "your-credential"
+
+# Network condition recommendations:
+#
+# Local network (LAN):
+#   - bitrate: 8-16 Mbps
+#   - frame_rate: 60
+#   - preset: veryfast
+#   - Expected latency: 15-25ms
+#
+# Remote network (good connection):
+#   - bitrate: 2-4 Mbps
+#   - frame_rate: 30
+#   - preset: veryfast
+#   - Expected latency: 50-100ms
+#
+# Remote network (poor connection):
+#   - bitrate: 0.5-1 Mbps
+#   - frame_rate: 15-24
+#   - preset: ultrafast
+#   - Expected latency: 100-200ms
+#
+# Low CPU requirements:
+#   - encoder_type: h264_vaapi or h264_nvenc (hardware)
+#   - preset: ultrafast or superfast
+#   - Reduce resolution (e.g., 1280x720)
+#   - Reduce frame rate (e.g., 15-24)
+
+# Hardware encoder selection guide:
+#
+# Intel/AMD GPU (Linux):
+#   - encoder_type: h264_vaapi
+#   - Requires: libva, vainfo, hardware with VAAPI support
+#
+# NVIDIA GPU:
+#   - encoder_type: h264_nvenc
+#   - Requires: NVIDIA drivers, NVENC-capable GPU
+#
+ # Software (fallback):
+ #   - encoder_type: h264_x264
+ #   - Works on any system but higher CPU usage
+ #
+ # Additional Performance Tuning:
+ #
+ # Zero-Copy Optimization (automatic):
+ #   - DMA-BUF frames are passed directly to hardware encoders
+ #   - No CPU memory copies from capture to encode
+ #   - Requires: Hardware encoder (h264_vaapi or h264_nvenc)
+ #   - Benefit: 10-15ms reduction in latency
+ #
+ # Buffer Pool Sizing:
+ #   - Too small: Frame drops, stutters
+ #   - Too large: Increased latency, higher memory usage
+ #   - Recommendation: 3-5 buffers for 30fps, 5-8 buffers for 60fps
+ #
+ # Jitter Buffer:
+ #   - Compensates for network latency variations
+ #   - Default is optimized for low-latency (10-20ms)
+ #   - Increase on unstable connections: 20-50ms
+ #   - Reduce on stable connections: 5-10ms
+ #
+ # Packet Size Tuning:
+ #   - Smaller packets (1200 bytes): Lower latency, higher overhead
+ #   - Larger packets (1400 bytes): Lower overhead, slight latency increase
+ #   - Default: 1200 bytes for optimal latency
+ #
+ # CPU Core Assignment:
+ #   - For best performance, dedicate cores to encoder:
+ #     taskset -c 2,3 ./target/release/wl-webrtc start
+ #   - Pinning reduces context switching overhead
+ #
+ # GPU Priority:
+ #   - Increase GPU priority for VA-API/NVENC:
+ #     sudo cpupower frequency-set -g performance
+ #   - Ensures encoder gets sufficient GPU resources
+ #
+ # Monitoring:
+ #   - Enable metrics collection to track performance:
+ #     RUST_LOG=info ./target/release/wl-webrtc start
+ #   - Watch for:
+ #     - Capture drops (indicates CPU bottleneck)
+ #     - Encode queue depth (should stay < 3)
+ #     - Network jitter (indicates network issues)
+ #
+ # Troubleshooting:
+ #   - High CPU: Use hardware encoder, reduce resolution/fps
+ #   - High latency: Check preset, frame rate, network conditions
+ #   - Poor quality: Increase bitrate, use slower preset
+ #   - Stuttering: Reduce frame rate, check network bandwidth
+