Voice Channels (LiveKit)

Spokes provides a seamless real-time voice and video experience by bundling an embedded instance of LiveKit (https://livekit.com/), a powerful, open-source WebRTC server.

This page explains how the LiveKit integration works under the hood and how to configure and troubleshoot it.

High-Level Architecture

When you deploy Spokes, the container automatically spins up an internal LiveKit server to handle all WebRTC media traffic (voice, video, and screen sharing).

• Embedded Service: LiveKit runs inside the exact same Docker container as the main Spokes application. A process manager (Supervisor) handles keeping both the Spokes Server and LiveKit running smoothly.
• Dynamic Configuration: Spokes dynamically configures LiveKit on every boot. It automatically provisions the necessary API keys, port ranges, and configuration files (livekit.yaml) so that you do not need to manually configure WebRTC settings.
• Client Connection: When a user joins a voice channel, the Spokes C# backend generates a secure token and passes it to the user’s browser. The browser then connects directly to the internal LiveKit instance using WebRTC.

Port Configuration

LiveKit requires specific ports to be exposed to allow peer-to-peer WebRTC traffic to flow.

• TCP Fallback Port: Used if UDP traffic is blocked. Configured via Spokes_Voice_Fallback_Port (Defaults to 7881).
• UDP Port Range: Used for high-performance media streaming. Configured via Spokes_Voice_UDP_Start_Port (Defaults to 50000) and Spokes_VOICE_UDP_PORT_COUNT (Defaults to 500).

Ensure that Docker host firewall allows traffic on these ports.

Why 1-to-1-to-1 mapping?

Spokes embeds the LiveKit engine for real-time communication. LiveKit explicitly advertises its internal bound port to external clients during the WebRTC handshake. Because of this, the port mapping must be identical across your entire network path: Router Port = Host Port = Container Port.

For example, for the TCP fallback port: 7881 on your Router’s WAN IP must be forwarded to 7881 on your Host IP, which must be mapped to 7881 on your Container.

If your router translates ports (e.g., forwarding WAN port 40000 to internal host port 50000), the voice and video connection will instantly fail.

Troubleshooting & Debugging

If you are experiencing connection drops or voice issues, it can be helpful to view the raw logs from the LiveKit server.

By default, LiveKit’s logs are merged into the main Spokes container logs (viewable via docker logs Spokes_Server), and the logging verbosity is set to info.

Enabling Debug Logs

If you need deeper insights, you can enable verbose debugging by setting an environment variable in your Docker or Unraid template:

1. Add a new environment variable: Spokes_LiveKit_Log_Level
2. Set the value to debug. (Other valid values are info, warn, or error).
3. Restart the container.

On the next boot, Spokes will inject this setting into the LiveKit configuration, and you will see highly detailed WebRTC connection logs stream directly into your main Docker console.

Filtering Logs

Because the LiveKit logs are multiplexed with the main .NET application logs, you can easily filter them out using grep: docker logs Spokes_Server | grep livekit