WebRTC streamer

The WebRTC Streamer microservice is an important component of a system that is used for live video streaming over WebRTC. It is responsible for receiving MPEG-TS video streams over multicast UDP and sending them out over WebRTC, either as a h264 passthrough payload or transcoded to VP8/VP9. One of the key features of the WebRTC Streamer microservice is its ability to provide low latency video, allowing users to view live video with minimal delay. To accomplish this, the WebRTC Streamer microservice uses a combination of hardware acceleration and software optimization techniques. This allows it to efficiently process and transmit video streams, even at high resolutions and frame rates. The microservice also provides transcoding capabilities, allowing it to convert video streams to the VP8 format for transmission over WebRTC. This ensures that the video stream is compatible with a wide range of devices and web browsers, while also providing high-quality video with minimal latency. Overall, the WebRTC Streamer microservice is a critical component of any system that requires live video streaming over WebRTC. By providing low-latency video with efficient encoding and transmission, it helps to ensure that users are able to view high-quality video in real-time, making it ideal for use in applications such as video conferencing, online gaming, and more.

WebRTC Server Network Flags.

This section explains the WebRTC networking flags and gives tested recipes for common deployment scenarios. It’s written for the server that exposes the following CLI flags:

--fullIce
--forceRelay
--nat1to1Enabled
--publicIp <ip>
--keepHostCandidates
--loopbackIceCandidate
--udpStreamTimeout  
--udpStreamOffline  
--klvSampling

If running in Docker, here are the equivalent .env variables:

WEBRTC_FULL_ICE
WEBRTC_FORCE_RELAY 
WEBRTC_NAT_1TO1_ENABLED 
WEBRTC_PUBLIC_IP
WEBRTC_KEEP_HOST_CANDIDATES 
WEBRTC_LOOPBACK_ICE_CANDIDATE 
WEBRTC_TEST_PAGE
STREAM_TIMEOUT
STREAM_OFFLINE
KLV_SAMPLING

What each flag does

--fullIce

(bool, default: false → ICE-Lite)

Switch the server to Full ICE (controlling/controlled ICE agent that can gather STUN/TURN candidates).
If false, the server runs ICE‑Lite (answers connectivity checks but does not gather its own candidates).

  • Enable when you need STUN/TURN on the server side, or when you use NAT 1:1 with server‑reflexive (srflx) candidates.
  • Disable (ICE-Lite) for simple LAN or public IP environments where the client does the heavy lifting.

When to use: Cloud or NATed environments where server needs to advertise public reachability beyond local hosts.

--forceRelay

(bool, default: false)

Force the server’s ICETransportPolicy to relay (TURN‑only). All media/data must go via TURN.
This is the most firewall‑friendly, but adds latency/cost.

When to use: Highly restricted networks or when direct P2P paths routinely fail.

Tip: Pair with a TURN config on the client as well (the client must also have TURN URLs).

--nat1to1Enabled

(bool, default: false)

Enable NAT 1:1 advertising on the server. The server replaces or augments host candidates with a publicly reachable IP.
Two modes are possible internally:

  • Host‑mapped NAT1to1: Replace private hosts with the public IP (works with ICE‑Lite; best for Internet‑only deployments that don’t need LAN discovery).
  • Srflx NAT1to1 (requires --fullIce=true and STUN): Keep local host candidates and add a server‑reflexive (public) candidate. Good when you want both LAN and Internet reachability.

When to use: Cloud/public deployments; also mixed LAN/Internet if combined with --keepHostCandidates=true and --fullIce=true (srflx).

--publicIp <ip>

(string, default: empty)

Set a public IP that the server should advertise. Used together with --nat1to1Enabled.
If omitted and --nat1to1Enabled=true, the server tries to auto‑detect a public IP (e.g., via ipify).

When to use: Server has a single, stable public IP (bare‑metal or cloud VM with public interface).

--keepHostCandidates

(bool, default: true)

If true, the server keeps its local/LAN host candidates in SDP. If false, private/loopback hosts are not signaled (only public/TURN/srflx).

  • Keep true when clients might connect over LAN.
  • Set false to avoid leaking private IPs and to simplify candidate lists for Internet‑only or TURN‑only cases.

--loopbackIceCandidate

(bool, default: false)

If enabled, the server will also advertise a loopback (127.0.0.1) ICE candidate.
Useful for local testing on the same machine (browser and server on one host) or when the service should work on local machine.
Leave off in normal deployments.

When to use: Dev/testing only, single machine.

--testPage

(bool, default: false)

If enabled, the test page will be available.

Set false in normal deployments.

--udpStreamTimeout

(uint, default: 2000)

Specifies the UDP stream timeout in milliseconds. If the stream resumes, the pipeline continues to operate normally.

Note: The resumed stream must use the same MPEG-TS profile - otherwise, the processing pipeline or decoder may become stuck.

--udpStreamOffline

(uint, default: 10000)

Defines the duration (in milliseconds) after which, if the stream is unavailable, the sensor is considered offline. The pipeline is then restarted, allowing the server to accept an MPEG-TS stream with different parameters.

--klvSampling

(uint, default: 0)

Defines the KLV packet sampling frequency. A value of 0 disables sampling, meaning all packets are processed.

Ready‑to‑use configurations (recipes)

Below are practical combinations of flags and why they’re recommended. Replace <BIND> with your listen address as needed (e.g., 0.0.0.0:8080).

Local machine (same host)

Browser and server on the same computer.

# simplest
--loopbackIceCandidate=true \
--fullIce=false \
--nat1to1Enabled=false \
--keepHostCandidates=true \
--forceRelay=false

Why: ICE‑Lite is enough; loopback makes the browser connect immediately. No public IP needed.

Local network (LAN only)

Multiple machines on the same LAN, no Internet requirement.

--fullIce=false \
--nat1to1Enabled=false \
--keepHostCandidates=true \
--forceRelay=false

Why: Host candidates on the LAN are sufficient, and ICE‑Lite keeps server lightweight.

If some clients sit behind strict local firewalls, you may enable --fullIce=true so the server can also gather STUN/TURN as needed, but usually not required for LAN.

Local machine & local network (mixed)

You want same‑host access and LAN access simultaneously.

--loopbackIceCandidate=true \
--fullIce=false \
--nat1to1Enabled=false \
--keepHostCandidates=true \
--forceRelay=false

Why: Loopback for same‑host, host candidates for LAN. Still ICE‑Lite.

Cloud server with public IP (directly reachable or NAT1to1 host‑mapped)

VM with a stable public IP (or 1:1 NAT from public IP), and you serve Internet clients. Prefer not to leak private IPs.

--fullIce=false \
--nat1to1Enabled=true \
--publicIp=<PUBLIC_IP> \
--keepHostCandidates=false \
--forceRelay=false

Why: ICE‑Lite + NAT1to1(host) advertises the public IP as host candidate, omits private hosts. Efficient and simple for public Internet clients.

If you also want to support LAN/side‑car access inside the same VPC/VNet, set --keepHostCandidates=true and consider --fullIce=true to allow srflx + host (see next recipe).

Cloud server behind NAT (need both LAN + Internet reachability)

Server sits behind a NAT, and you want both local/private and Internet clients to connect.

--fullIce=true \
--nat1to1Enabled=true \
--publicIp=<PUBLIC_IP>     # or leave empty to auto-detect
--keepHostCandidates=true  \
--forceRelay=false

Why: Full ICE + NAT1to1(srflx) lets the server publish both local host and public srflx candidates. Great for mixed LAN + Internet access. Clients can choose the best path.

If networks are extremely locked down, add TURN on clients and optionally --forceRelay=true to make all paths go through TURN (higher latency).

Quick decision guide

  • Only me, same computer? → Use loopback, ICE‑Lite.
  • Same LAN only? → ICE‑Lite, keep host candidates.
  • Public Internet only, clean candidate list? → ICE‑Lite + NAT1to1(host), no host candidates.
  • Public Internet + also LAN (mixed)? → Full ICE + NAT1to1(srflx) + keep host.
  • Corporate firewalls everywhere? → TURN on clients, possibly --forceRelay=true.

TURN transport notes

TURN URLs you provide to clients can influence connectivity and latency. Typical set:

"urls": [
  "turn:turn.example.com:3478?transport=udp",
  "turn:turn.example.com:80?transport=tcp",
  "turns:turn.example.com:443"       // TLS-over-TCP
]
  • Prefer UDP for best media latency.
  • Keep TCP/TLS fallbacks for restrictive firewalls (but expect higher RTT/latency).
  • If you set --forceRelay=true on the server, make sure clients also know TURN URLs; otherwise they can’t reach the relay.

Troubleshooting checklist

  • Remote works, local doesn’t (or vice versa):
  • Check whether you need Full ICE (set --fullIce=true) so the server can produce srflx candidates.
  • Confirm --nat1to1Enabled and --publicIp are correct for Internet use.
  • Connected but no media:
  • Verify browser logs for ontrack firing and codecs (e.g., VP8/H264).
  • Ensure the server actually sends media (check encoder is running).
  • Data channels open, but no video:
  • Check TURN policy. TURN‑only paths (relay) increase delay; try allowing direct paths or enable UDP on TURN.
  • Leak of private IPs in SDP not desired:
  • Set --keepHostCandidates=false (Internet‑only deployments).
  • Or use Full ICE + NAT1to1(srflx) to include public srflx and sanitize hosts if needed.
  • Browser shows only host candidates on remote cloud server:
  • Likely running ICE‑Lite without NAT1to1. For Internet clients, prefer NAT1to1(host) or enable Full ICE to advertise srflx/relay.

Security & privacy

  • Advertising host candidates may reveal private IPs. Use --keepHostCandidates=false for public deployments if this is a concern.
  • TURN credentials should be scoped/rotated. Avoid embedding long‑lived secrets in public pages.
  • For relay‑only operation (--forceRelay=true), ensure your TURN service has sufficient capacity and TLS where needed.