# 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