DEV Community: AiLaoHuYu

Jitsi is the right default for meetings. Here is the narrower case where it is not

AiLaoHuYu — Wed, 21 Oct 2026 07:24:49 +0000

Disclosure: I sell Low-Latency Kit, a commercial WebRTC source kit. This post compares it honestly with Jitsi Meet, an Apache-2.0 project. I do not earn anything from a Jitsi deployment.

Jitsi Meet is the stronger default when the product you are building is a meeting.

It has multi-party rooms, mature browser and mobile clients, authentication integrations, recording and streaming options, and an established deployment ecosystem. If users need to join a room, see a grid of participants, mute each other, share a screen, and use the same experience on desktop and mobile, adopting Jitsi is usually the shorter path.

Low-Latency Kit solves a narrower problem: one phone or screen publisher to one or many browser viewers. The camera is effectively a remote pair of eyes. The important parts are the media path, what happens when frames stop, and whether an operator can see why the session failed.

I wrote a fuller comparison here: Jitsi Meet vs Low-Latency Kit. This post is about the engineering decision behind that comparison, not the feature count.

The failure that makes the two products diverge

In a meeting, the room is the unit of the product. In a remote inspection or field-support workflow, the camera session is the unit. That changes the failure model.
A conferencing UI can show a participant tile, a connection state, a mute icon, and a device selector. A field-support UI usually needs to answer different questions:

Is the publisher still sending new frames, or is the last frame frozen?
Is the selected candidate pair direct or relayed through TURN?
Did the WebSocket reconnect, and did the publisher rejoin the correct session?
Is the failure packet loss, bandwidth limitation, CPU pressure, or no picture at all?
Can the session recover without asking the technician to reload the page?

These questions matter because iceConnectionState === "connected" does not prove that video is moving. A track can remain live while the displayed frame is stale. Browser APIs commonly report the connection as connected during exactly the kind of mobile-network transition that makes a support call useless.

The recovery chain I use has three steps:

Detect a frame-level stall with requestVideoFrameCallback, falling back to currentTime when needed.
Try an ICE restart on the existing peer connection.
Rejoin the session only if the restart does not produce frames.

The order is deliberate. An ICE restart is cheaper and preserves the existing media tracks. A full rejoin is the fallback for stale server-side session state, a signaling reconnect, or a republished track. Repeated rejoins need jittered exponential backoff so a tower coming back online does not cause a retry storm.

You can try the failure path in a browser with no account or installation: the 18-second freeze and recovery demo.

Where Jitsi is the better engineering choice

Choose Jitsi if any of these statements describes the product:

Users need more than one participant to publish media.
The primary interface is a meeting room.
You need the Jitsi mobile applications, meeting UI, or authentication integrations.
Your team already operates the Java, web, and supporting services in a Jitsi deployment.
You need the Apache-2.0 licence path and not a commercial source licence.

Those are not small advantages. Rebuilding a meeting product around a small kit would be worse engineering, even if the kit has better diagnostics for a frozen viewer.

Jitsi is also the safer choice when procurement or legal requires a well-known open-source project and an established licence model. Verify the current project and deployment requirements before deciding because licences and supported topologies can change.

Where a one-publisher kit makes sense

Consider a smaller kit when the workflow is closer to this:

A technician points a phone camera at a machine, asset, or fault.
One or more experts watch in a browser.
The expert does not need to publish video or manage a meeting.
The application owns the buttons, branding, session IDs, and business workflow.
The media path must stay on infrastructure the buyer controls.

That is a different product from a conference room. The buyer usually has an existing field-service app, inspection workflow, teleoperation dashboard, or IoT camera interface. The missing piece is the reliable camera session and its operational details, not another meeting application.

The kit is source code, not a hosted service. It includes a Go signalling server, a Pion SFU, a browser publisher and viewer, reconnect logic, diagnostics, Docker and Caddy deployment examples, TURN wiring, and notes on the failure modes that showed up in practice.

A deployment mistake worth checking first

One of the most common cloud failures has nothing to do with JavaScript. The server has a private network interface, while the public address is supplied by the provider NAT. If the server advertises its private address in SDP, a remote browser may never reach the media path. On a TURN server, the equivalent setting is external-ip. In a Go server, the deployment needs a public IP flag or a relay-only policy. The symptom is easy to miss: two machines on the same office network connect instantly, while an outside browser never receives frames.

Another common case is the phone moving from Wi-Fi to cellular. The old five-tuple is gone, so the old candidate pair cannot be revived. The connection object may keep saying connected while the viewer is looking at a still image. The application needs frame health, ICE restart, a full-rejoin fallback, and useful diagnostics. This is exactly the gap between a WebRTC demo and a support product.

What I would decide from

If the product needs a meeting, choose Jitsi. You will spend your time on the workflow instead of rebuilding rooms and mobile clients.

If the product needs one camera publisher, many viewers, a self-hosted media path, and visible recovery behavior, the narrower kit is worth evaluating. Start with the live demo, then read the implementation notes and pricing:

The source package is a one-time purchase with a seven-day refund window. A lower-priced copy is also available through Codester.

If you are deciding between these paths, the useful question is not which project has more features. It is whether your users need a conference room or a remote pair of eyes.

Your WebRTC viewer says connected. The picture is frozen.

AiLaoHuYu — Mon, 19 Oct 2026 02:57:34 +0000

There is a failure mode in WebRTC that looks healthy from almost every angle:

pc.iceConnectionState === "connected";
pc.connectionState === "connected";
video.readyState === HTMLMediaElement.HAVE_ENOUGH_DATA;

The signaling socket is open. The peer connection has a candidate pair. The video
element is attached. And the frame on screen has not moved for three minutes.

That last sentence is the problem. connected describes the transport, not the
picture. A media track can be live while no new frames are rendered.

Try the freeze-and-recovery demo in your browser. It freezes a real media stream, shows Transport: connected throughout the outage, then walks through ICE restart and full rejoin. No install and no account.

Frames are the health check

If the audience is watching video, the useful health signal is not a connection state.
It is an advancing frame.

requestVideoFrameCallback gives us that signal. It fires when the browser has a new
video frame to present, and its metadata includes the presentation time:

video.requestVideoFrameCallback((now, metadata) => {
  console.log(metadata.presentationTime, metadata.width, metadata.height);
});

That one callback can drive both recovery and observability: the viewer is healthy when
frames are arriving, and it is frozen when they stop.

Older browsers may not implement the callback. There, a timer can watch
video.currentTime. It is less precise, but it still distinguishes playback from a
still image.

Recover in the cheapest order

When frames stop, the instinct is to tear down and reconnect everything. That works,
but it is the most expensive option: a new socket, a new offer, a new answer and a new
peer connection. Most interruptions do not require all of that.

I use a three-step recovery ladder:

ICE restart. Reuse the current session and negotiate new candidates. This is usually enough after a Wi-Fi change or a network path failure.
Full rejoin. Replace the signaling session and peer connection. This covers server-side sessions that went stale or a publisher that republished.
Backoff and retry. Repeating full rejoins without a delay can turn one broken client into a retry storm.

The deadlines matter. A restart that has not produced a new frame in five seconds is
not a successful restart. A rejoin that has not produced a new frame in eight seconds
is not a successful rejoin. The transition should be driven by rendered frames, not by
the fact that a connection event fired.

A compact implementation

I published the recovery logic as webrtc-recovery. It contains no signaling or media
server code; you provide restart() and rejoin() for your own stack.

import { createRecoveryLadder, watchFrames } from "webrtc-recovery";

const ladder = createRecoveryLadder({
  restart: () => signaling.send({ type: "restart" }),
  rejoin: () => {
    pc.close();
    pc = null;
    signaling.reconnect();
  },
});

watchFrames(video, {
  onStall: () => ladder.onIceState("failed"),
  onResume: () => ladder.markHealthy(),
});

video.requestVideoFrameCallback(function tick() {
  ladder.markHealthy("frame");
  video.requestVideoFrameCallback(tick);
});

The important part is the invariant: only a rendered frame clears the recovery
deadline. A successful setRemoteDescription or an iceConnectionState transition is
not evidence that somebody can see the stream.

The package is ESM-only, has zero runtime dependencies, and the state machine accepts
an injected clock, so the timeout branches can be tested without real waits. The
current release is available from GitHub while the npm listing is being prepared:

npm install https://github.com/AiLaoHuYu/webrtc-recovery/archive/refs/tags/v0.1.1.tar.gz

Repository:
https://github.com/AiLaoHuYu/webrtc-recovery

Diagnose one thing, not ten numbers

getStats() can return dozens of numbers at once. A viewer does not need a dashboard;
it needs the first useful explanation.

Check the highest-severity condition first:

Is the transport failed or closed?
Is the frame watchdog reporting a stall?
Is packet loss already bad enough to explain poor quality?
Is the jitter buffer growing?
Is the sender capped by bandwidth or CPU?
Is signaling up but no frame dimensions arriving?

That ordering avoids the common mistake of telling a user about 3% packet loss while
the real problem is that the peer connection is dead.

The same package exposes sampleConnection() to flatten a stats report and
diagnose() to turn the first actionable condition into one sentence.

What this does not solve

Client recovery cannot fix a server that is down, a publisher that stopped sending
media, or a TURN service with no capacity. It also cannot make an expired signaling
session valid.

What it can do is stop a viewer from sitting on a frozen frame while every status badge
says everything is fine. In a live video product, that difference is the whole user
experience.

If you are assembling the rest of the stack yourself, the library and source are here:

https://github.com/AiLaoHuYu/webrtc-recovery

If you would rather start from the full self-hosted WebRTC video server, including
signaling, the SFU, the publisher and the viewer, see https://lowlatencykit.com.
The complete source package is also available through
Codester.

Testing WebRTC without a camera: a loopback self-test that proves the whole path

AiLaoHuYu — Tue, 13 Oct 2026 08:50:51 +0000

The hardest part of testing a WebRTC pipeline is that the real one needs a camera, a microphone, a user who clicks allow, and HTTPS. On a build machine none of that exists, so the pipeline tests get skipped and the first honest test is a human on a laptop.

There is a better fixture. Put a canvas on one end and a <video> element on the other, and send the canvas through the actual stack — publisher, signaling, SFU, viewer — so what the test exercises is the real path and not a mock.

The whole thing in one line: a canvas is an acceptable substitute for a camera, a timer is a better driver than an animation frame, and a moving timestamp is what proves the picture is live rather than merely present.

Replace the camera with a canvas

canvas.captureStream() returns a MediaStream with the same shape as a camera's, so everything downstream is unchanged:

const stream = cv.captureStream(30);
for (const track of stream.getVideoTracks()) {
  pc.addTrack(track, stream);
}

No permission prompt, no device enumeration, no browser variation in which camera it picked. The test runs headless, on a server, in CI, and on a machine whose only camera is already in use by a call.

Draw something that can only be live

A static image is a trap. If the encoder dies and the last frame stays on screen, a static test pattern passes. Draw motion and a clock:

function draw() {
  const t = performance.now();
  ctx.fillStyle = '#101418';
  ctx.fillRect(0, 0, cv.width, cv.height);

  const x = ((t / 8) % (cv.width + 80)) - 80;   // a moving block
  ctx.fillStyle = '#5b8cff';
  ctx.fillRect(x, 120, 80, 80);

  ctx.fillStyle = '#e6e9ef';
  ctx.font = '20px monospace';
  ctx.fillText(new Date().toLocaleTimeString() + '.' + String(Math.floor(t % 1000)).padStart(3, '0'), 16, 34);
}

The timestamp is the assertion. A frozen stream shows a stopped clock, and a stream that is alive shows a clock that keeps moving, so the test can tell "connected and carrying video" from "connected and showing the last frame forever" without a human looking at it.

Drive the canvas on a timer, not on `requestAnimationFrame`

This is the detail that costs an afternoon if you get it wrong. A background tab gets no animation frames, so a requestAnimationFrame draw loop stops the moment the tab is not visible — and the self-test then fails with a black or frozen viewer that has nothing to do with the network:

// Timer-driven, not requestAnimationFrame: a background tab gets no animation
// frames, which would silently stop the source and make the test look broken.
draw();
setInterval(draw, 33);

A 33 ms interval is roughly 30 fps and keeps producing frames while the tab is hidden, which is exactly when people leave a test running.

Count liveness two ways, because one of them stops in a hidden tab

requestVideoFrameCallback is the most accurate way to count painted frames, and it also stops firing when the tab is backgrounded. So count both painted frames and decoded frames, and let the test pass if either one is advancing:

if (video.requestVideoFrameCallback) {
  video.requestVideoFrameCallback(function tick() {
    painted += 1;            // frames the user could actually see
    video.requestVideoFrameCallback(tick);
  });
}

// getStats framesDecoded keeps advancing in a background tab.
setInterval(async () => {
  const s = await sample(pc, prev);
  prev = s;
  decoded = s.framesDecoded || 0;
}, 1000);

One counter answers "can the user see it", the other answers "is the decoder still receiving". Using only the first produces a test that fails whenever it is not being watched, which trains everyone to ignore it.

Give every run its own room

If the server enforces one publisher per room — and the simple SFU design does — then two concurrent self-tests collide: the second publisher evicts the first, and both tests report a failure that is really a scheduling coincidence.

Derive the room name per visit instead of hardcoding it:

const ROOM = 'selftest-' + (
  globalThis.crypto?.randomUUID?.() ||
  Math.random().toString(36).slice(2, 10)
);

That one line makes the test safe to run in parallel across browser tabs, machines and CI jobs with no coordination.

Mirror the state so automation can assert it

A test whose only output is pixels cannot be automated. Publish the state on a global object and assert on numbers:

const st = {
  publisher: 'connecting',
  viewer: 'connecting',
  frames: 0,      // frames painted, via requestVideoFrameCallback
  decoded: 0,     // frames decoded, via getStats - works in a background tab
  w: 0,
  h: 0,
  kbps: null,
  ice: '',
};
window.__st = st;

Now the assertion is boring and reliable: wait for ice to be connected, wait for decoded to exceed a threshold, and confirm the resolution is what you asked for. A driver script can do that in a few lines, and a failure tells you which of the three did not happen.

What this test does and does not prove

It proves the path end to end: track creation, offer/answer through the server, the SFU's fan-out, decoding, and the resolution and bitrate the session settled on. It catches the majority of regressions, because most of them break the path rather than a corner of it.

It does not prove TURN works from outside your network — that needs a host with a different NAT, which is why the relay probe is a separate test. It does not prove camera or microphone behaviour, because there is no camera. And it does not prove quality under loss; for that you need a network emulator, not a loopback.

Those boundaries are worth stating in the test itself. A self-test that claims to cover everything gets trusted for everything and then quietly lies.

The fixture, in order

Source from a canvas, not a camera — headless, no permissions, no HTTPS requirement.
Draw a moving element and a monotonic timestamp so a frozen frame cannot pass.
Drive the canvas with a timer, because a hidden tab stops animation frames.
Count painted frames and decoded frames, and accept either as liveness.
Give each run a unique room so parallel tests cannot evict each other.
Expose the state on a global so assertions are numeric, not visual.
Be explicit about what the test does not cover, and keep the relay and loss tests separate.

This loopback test ships with the self-hosted WebRTC kit — canvas publisher, server relay, viewer, and the same stats panel the production viewer uses — so the whole path can be verified before a camera or a network is involved:

https://lowlatencykit.com/

The free relay probe, which covers the one thing the loopback test cannot, needs no account:

https://lowlatencykit.com/test/turn/

The six getStats numbers that actually tell you what broke

AiLaoHuYu — Tue, 13 Oct 2026 08:49:17 +0000

getStats() returns a few hundred fields across dozens of records, and almost all of them are useless for diagnosis. The problem is not that the data is missing. It is that the numbers which matter only mean something in combination, and a dashboard that prints all of them tells you nothing.

These are the six worth putting on a screen, in the order I would look at them.

The whole thing in one line: the selected candidate pair tells you the path, the inbound counters tell you whether media arrived, and the outbound reason tells you why the encoder is holding back.

1. The selected candidate pair, and the candidate types behind it

This is the one everyone gets wrong, because getStats() reports many candidate-pair records and only one of them is the path your media is actually on. Print the wrong pair and you will confidently announce a direct connection while the session is relayed, or the reverse:

stats.forEach((r) => {
  if (r.type === 'local-candidate' || r.type === 'remote-candidate') cands[r.id] = r;
  if (r.type === 'candidate-pair' && (r.selected || r.state === 'succeeded') && r.currentRoundTripTime != null) {
    pair = r;
  }
});

Note the extra condition. Requiring currentRoundTripTime != null filters out pair records that exist but never carried a round trip — which is most of them on a NAT-heavy session. Without it, a "succeeded" pair with no measured RTT can win and you report a path that was never used.

The types are not on the pair. They live in separate records that the pair refers to by id, so you have to join them:

const l = cands[pair.localCandidateId];
const rm = cands[pair.remoteCandidateId];
out.localType = l ? l.candidateType : null;   // host | srflx | prflx | relay
out.remoteType = rm ? rm.candidateType : null;

host → host means a direct path on the same network. relay → relay means both sides are going through TURN, which is the expected state behind a carrier NAT and the first thing to verify when someone says the relay is broken. Skipping the join is why people conclude "it is always relayed" or "it is never relayed".

2. Inbound bitrate, which requires two samples

bytesReceived is a cumulative counter. You cannot read a rate out of a single snapshot, which is why so many quick debugging scripts print a number that keeps growing and call it bitrate:

// Pass the previous sample in; the delta is the rate.
if (prev && prev.bytes != null && r.bytesReceived != null && now > prev.t) {
  out.bitrateKbps = Math.round(((r.bytesReceived - prev.bytes) * 8) / (now - prev.t));
}
out.bytes = r.bytesReceived;

One unit trap lives in that line: (bytes delta * 8) / milliseconds is kilobits per second only because the division by a duration in milliseconds yields bits per millisecond — which is bits per second divided by a thousand. Get the units wrong here and your numbers are off by 1000, which looks like a codec problem.

3. `framesPerSecond` and resolution

These tell you whether the stream is alive at the quality you asked for. A stream that negotiated 1280×720 and settles at 320×180 is not broken; it is being told to back off, and the next two numbers say by what.

Read frameWidth/frameHeight from the inbound video record rather than from the video element's videoWidth. The element reports the decoded frame, which lags behind a change and is zero until the first frame decodes — the exact moment you most need a number.

4. `qualityLimitationReason` on the outbound side

This is the single most underused field in WebRTC diagnostics. When the encoder reduces resolution or frame rate, it says why:

if (r.type === 'outbound-rtp' && r.kind === 'video') {
  out.qlr = r.qualityLimitationReason || null;   // bandwidth | cpu | other | none
  ...
}

bandwidth means the estimator decided the path cannot carry more, and the fix is the network or the bitrate ceiling. cpu means the sender could not encode fast enough, and the fix is on the machine — resolution, hardware encoding, or too many tabs doing the same thing. other is usually a screen-share capture path that cannot keep up. Those are three different investigations, and without this field you are guessing between them.

5. `framesDecoded` versus `framesReceived`

This pair is how you separate transport from decode. Packets arriving while decoded frames stay flat means the media reached you and could not be turned into pictures — codec parameters, a missing keyframe, or a hardware decoder that gave up.

out.freezeCount = r.freezeCount != null ? r.freezeCount : null;
out.framesDecoded = r.framesDecoded != null ? r.framesDecoded : null;

freezeCount is the browser's own opinion that the picture stopped, which is a useful cross-check on your own frame-gap detection. If your 2-second frame-gap timer says "frozen" and freezeCount is still rising while framesDecoded is not, you are looking at decode, not at the network. If framesDecoded is climbing and the user still reports a frozen tile, the problem is downstream of the decoder — rendering, the element, or the application.

6. Jitter and the jitter buffer

Jitter on its own is a poor number to alarm on, because a jitter buffer exists precisely to absorb it. The informative value is the average time a frame spent waiting in that buffer, which you compute from two counters:

if (r.jitterBufferDelay != null && r.jitterBufferEmittedCount) {
  out.jbufMs = Math.round((r.jitterBufferDelay / r.jitterBufferEmittedCount) * 1000);
}

That is total buffer delay divided by frames emitted, scaled to milliseconds: the average per-frame hold. A buffer sitting in the tens of milliseconds is doing its job. A buffer climbing into the hundreds means the network is delivering frames unevenly enough that latency is the price being paid to keep the picture smooth — and for a live support call, that trade is often the wrong one.

The table that fits on one screen

The rendering that is actually useful is thirteen rows and no graphs:

const rows = [
  ['Connection',     (s.connState || '-') + ' / ' + (s.iceState || '-')],
  ['Bitrate in',     s.bitrateKbps != null ? s.bitrateKbps + ' kbps' : '-'],
  ['Resolution',     s.w ? s.w + ' x ' + s.h : '-'],
  ['FPS in',         s.fps != null ? s.fps + ' fps' : '-'],
  ['Packets lost',   s.loss != null ? s.loss : '-'],
  ['Jitter',         s.jitterMs != null ? s.jitterMs + ' ms' : '-'],
  ['Jitter buffer',  s.jbufMs != null ? s.jbufMs + ' ms' : '-'],
  ['RTT',            s.rttMs != null ? s.rttMs + ' ms' : '-'],
  ['Path',           s.localType ? s.localType + ' -> ' + s.remoteType : '-'],
  ['Freezes',        s.freezeCount != null ? s.freezeCount : '-'],
  ['Bitrate out',    s.outKbps != null ? s.outKbps + ' kbps' : '-'],
  ['FPS out',        s.outFps != null ? s.outFps + ' fps' : '-'],
  ['Quality limit',  s.qlr != null ? s.qlr : '-'],
];

Sampled once a second, that table answers the questions support actually asks: is there a path, is media arriving, at what quality, and if it is degraded, is the encoder blaming the network or the CPU.

How to read it in one pass

Path shows the candidate types. relay -> relay on a cellular session is correct, not a bug.
Bitrate in and FPS in flat or zero with Connection connected is a media problem, not a signaling problem.
Frames received climbing while Frames decoded stays flat means the media arrived and could not be decoded.
Quality limit: bandwidth and Quality limit: cpu are different bugs with different owners.
A jitter buffer in the hundreds of milliseconds is the latency you are paying for smoothness.
Freezes rising is the browser agreeing with your own freeze detection.

I built this sampling and rendering into the diagnostics panel of a self-hosted WebRTC kit, next to the recovery ladder that acts on it — ICE restart first, full rejoin when that fails — so the numbers are visible while the failure is happening rather than reconstructed from a log afterwards:

https://lowlatencykit.com/

The guide that covers the network layers these numbers are measuring is here:

https://lowlatencykit.com/guides/remote-field-assist-mobile-webrtc/

Coturn and Kurento in Docker Compose: the three addresses that decide everything

AiLaoHuYu — Tue, 13 Oct 2026 08:47:17 +0000

A containerised TURN and media stack fails in a way that is genuinely confusing: every container is running, the logs look clean, the ports are published, and no remote peer can get media. The cause is almost always that three different addresses were treated as one.

They are not interchangeable. Each one answers a different question, and mixing them up produces silent failure rather than an error.

The whole thing in one line: realm is for authentication, external-ip is for relay candidates, and the advertised media address is for SDP — a stack that works needs all three correct, and none of them is a synonym for the others.

Address 1: the realm

realm is not an address at all in the transport sense. It is the authentication realm coturn sends in its TURN challenge, and it participates in long-term credential authentication. A stable hostname is easier to operate than an IP:

realm=turn.example.com

Leave it empty and every request is challenged with nothing, the client retries forever, and you get a wall of 401 Unauthorized with a client-side 701 timeout. The startup log says so once — Default realm: followed by nothing — and then never mentions it again. Read the ten lines before the first client request, not the hundred after it.

Address 2: `external-ip`

This is the address that appears in relay candidates. On a cloud VM, coturn usually sees only a private interface while the public address is attached by the provider's NAT, so it must be told:

external-ip=203.0.113.10/10.0.0.4

The paired form is the one people miss. 203.0.113.10 is the public address, and 10.0.0.4 must be the address coturn actually sees on the host. Get the second half wrong and coturn does not map the interface, the relay candidates stay private, and remote peers try to reach an address that only exists inside the VPC.

Address 3: the media address Kurento advertises

Media servers have their own version of this problem, made worse by containers. A containerised Kurento is happy to advertise the 172.x address of its Docker interface in SDP, and no remote peer can route to it:

  kurento:
    image: kurento/kurento-media-server:7.1.0
    restart: unless-stopped
    expose:
      - "8888"
    environment:
      KMS_STUN_IP: turn.example.com
      KMS_STUN_PORT: "3478"
      KMS_TURN_URL: "turn:turn.example.com:3478?transport=udp"
      KMS_EXTERNAL_IPV4: "203.0.113.10"
    networks:
      - server

KMS_EXTERNAL_IPV4 is the public address Kurento puts in its SDP. Without it you get a session that negotiates, reports connected, and carries nothing — the classic "works locally, dead from a remote browser" shape.

Two related traps in the same file. KMS_STUN_IP has to be reachable from inside the Kurento container, so 127.0.0.1 and localhost are wrong there. And ws://kurento:8888/kurento is correct for your application service on the Compose network, but it is not a public endpoint and it is not a browser URL — that mistake looks like a firewall problem and is not one.

Give coturn host networking, and then drop the `ports:` block

On a Linux VPS, network_mode: host is the least surprising option for coturn, because the relay range is a wide UDP span that bridged networking handles badly:

services:
  coturn:
    image: coturn/coturn:4.6.3
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./turnserver.conf:/etc/coturn/turnserver.conf:ro
    command: ["-c", "/etc/coturn/turnserver.conf"]

With host networking the container shares the host network namespace, so a ports: block is not just redundant — it is misleading, because it suggests Docker is publishing something that is already directly exposed. Remove it and let the config file own the port and range.

Choose one credential mode, not two

The other recurring mistake is layering both credential mechanisms and then wondering which one the client used:

Development: lt-cred-mech with an explicit user=.
Production: use-auth-secret with short-lived timestamp:label usernames and HMAC-SHA1 passwords.

If you move to use-auth-secret, remove the static user= lines unless you have deliberately created a separate path for an internal client.

username = <unix-expiry>:<label>
password = base64(HMAC-SHA1(secret, username))

And keep the browser's credential out of the browser. The browser should receive credentials from your signaling backend, minted per session, because a long-lived credential embedded in JavaScript is a credential you cannot rotate.

Note that KMS_TURN_URL is used by Kurento itself, not by the browser. If Kurento needs a fixed URL, give it its own tightly scoped credential, rotate it deliberately, and do not reuse it for browser clients.

The relay range is a capacity number, not a formality

Each concurrent TURN allocation consumes a relay port, and retries or multiple allocations can consume more than one. A ten-port range is a test configuration:

min-port=49152
max-port=65535

That default is safe and large. A small production deployment can run a few hundred ports once you have measured concurrency — but open the range in both firewalls, the provider firewall and the host firewall. A control port that answers while the relay range is closed produces a srflx candidate and no relay candidate, which the browser reports as a generic failure with no hint about which of the two is blocked.

Do not match Kurento's internal RTP range to coturn's. They are different pools with different owners.

Transport order, and what Nginx should not do

Prefer UDP, then add fallbacks deliberately: TCP on 3478, and TLS on 5349 or 443 if you have certificates, for networks that block UDP.

turn:turn.example.com:3478?transport=udp

Do not put TURN behind an HTTP reverse proxy. TURN is not HTTP. Nginx can terminate HTTPS/WSS for your application and proxy Kurento's WebSocket over the private Compose network, but the TURN listeners must remain direct UDP/TCP services, and Kurento's port 8888 should stay unexposed to the internet.

The verification order worth following exactly

Confirm the host is listening on 3478/UDP and on the configured relay range.
Confirm the provider firewall and host firewall allow that same range.
Run a Trickle ICE check and confirm a relay candidate actually appears — not just an srflx one.
Set iceTransportPolicy: "relay" in a test browser and confirm a call still connects. That proves the relay path end to end.
Inspect the Kurento SDP and confirm it advertises KMS_EXTERNAL_IPV4, not a Docker address.

Step three and step four are the ones people skip, and they are the only two that distinguish "TURN is running" from "TURN works". A relay that answers STUN and refuses allocations passes every health check you would think to write.

If you want to run that check without setting up a browser test, the relay test on my site takes a TURN URL and credentials and reports which candidate types came back, and it is free and needs no account:

https://lowlatencykit.com/test/turn/

The longer-lived version of this article, with the complete Compose file, lives as a guide here:

https://lowlatencykit.com/guides/coturn-kurento-docker/

And the self-hosted WebRTC kit this came out of — Go signaling server, SFU, browser clients and the coturn configuration — is here:

https://lowlatencykit.com/

One camera, many viewers: the fan-out details that decide whether viewer #2 works

AiLaoHuYu — Tue, 13 Oct 2026 08:45:34 +0000

The first viewer is easy. You put a TrackLocalStaticRTP on the server, you write the publisher's packets into it, and the tile lights up. Then a second viewer joins and you find out that "forward the RTP" was never a complete design.

The single-viewer case hides five decisions. Each one is small, and each one is the difference between a demo and a session that behaves the same way for viewer number two.

The whole thing in one line: the publisher sends one stream, the server's egress scales with viewers, and every viewer needs its own negotiation plus its own keyframe request.

The publisher's uplink does not grow, and that is the entire point

In a mesh, three viewers means the publisher encodes and uploads three streams. In an SFU it uploads one. The server reads each incoming packet once and writes it to a local track that is bound to every viewer's sender:

local, err := webrtc.NewTrackLocalStaticRTP(codec.RTPCodecCapability, remote.ID(), remote.StreamID())
if err != nil {
    return
}

// One reader for the upstream, one local track, N senders bound to it.
go func() {
    for {
        pkt, _, readErr := remote.ReadRTP()
        if readErr != nil {
            break
        }
        if writeErr := local.WriteRTP(pkt); writeErr != nil {
            break
        }
    }
}()

The consequence people miss is where the bandwidth lands. The field technician on a phone keeps a single modest uplink no matter how many people are watching, and the server pays the multiplication. That is the right trade for a support call — the person on site has the worst connection in the system, and the server has the best one.

It is also the number you have to watch when you plan capacity: egress, not ingress, and it grows linearly with viewers per session.

The new viewer's black tile is a keyframe problem

The first viewer connects while the encoder is producing frames, so a keyframe arrives quickly. A viewer that joins ten minutes into a session receives inter-frames that reference a keyframe it never saw. RTP flows, framesReceived climbs, and the tile is black until the publisher's encoder happens to emit the next keyframe — which, for a long GOP, can be many seconds.

The fix is to relay the viewer's feedback upstream. Browsers already send a Picture Loss Indication when they cannot decode; the server's job is to carry it to the publisher. But a PLI carries the SSRC it is about, and a PLI that arrives from a viewer is about the server's local track, not the publisher's upstream track:

ssrc := uint32(t.remote.SSRC())
for _, p := range pkts {
    switch pkt := p.(type) {
    case *rtcp.PictureLossIndication:
        pkt.MediaSSRC = ssrc
    case *rtcp.FullIntraRequest:
        pkt.MediaSSRC = ssrc
    case *rtcp.TransportLayerNack:
        pkt.MediaSSRC = ssrc
    }
}
if err := t.pubPC.WriteRTCP(pkts); err != nil {
    return
}

Forward the packet unchanged and the publisher sees feedback about an SSRC it does not own, ignores it, and the new viewer waits out the GOP. Rewrite MediaSSRC to the publisher's value and the keyframe arrives in milliseconds. This one line is the difference between "the second viewer is broken" and "the second viewer is instant", and nothing in the browser tells you which one you are looking at.

Negotiate all the tracks in one offer, not one offer per track

A publisher's ontrack fires once per track. Audio and video often arrive within milliseconds of each other, and a naive implementation answers each one immediately, which puts two setLocalDescription cycles in flight for the same viewer. That is offer glare on your own connection, and the symptoms are intermittent in the way that wastes an afternoon.

Batch them. A short timer that coalesces whatever arrived into a single offer per viewer is enough:

func (r *Room) scheduleNegotiateLocked() {
    if r.negTimer != nil {
        return
    }
    r.negTimer = time.AfterFunc(250*time.Millisecond, func() {
        r.mu.Lock()
        defer r.mu.Unlock()
        r.negTimer = nil
        for v := range r.viewers {
            r.negotiateViewerLocked(v)
        }
    })
}

Two details make it safe: the timer is stored per room so a burst of track arrivals collapses into one callback, and the callback re-takes the lock and re-checks the state, because 250 milliseconds is plenty of time for a viewer to leave.

RTCP reads need a real buffer

The control channel looks trivial until it does not. Read it with a buffer sized for the largest datagram you can receive, not for the packet you expect:

buf := make([]byte, 1500)
for {
    n, _, err := sender.Read(buf)
    if err != nil {
        return
    }
    pkts, err := rtcp.Unmarshal(buf[:n])
    if err != nil {
        continue
    }
    // ...
}

An undersized buffer turns into a short read, Unmarshal fails, and the feedback is silently dropped — which surfaces as poor quality that only appears on networks sending large compound RTCP packets.

When the publisher changes, every viewer is stale

If the publisher disconnects or republishes, the viewers' PeerConnections are holding transceivers that belong to a session that no longer exists. Patching them is not worth it; tear them down so the next negotiation starts clean:

// resetViewersLocked tears down every viewer's PeerConnection so the next
// negotiation starts from scratch. Caller must hold r.mu.

This pairs with the client-side ladder: the viewer's full-rejoin fallback exists precisely because the server rebuilt its side, and a viewer that reuses its old connection negotiates successfully and receives nothing.

The honest limits of this design

Being explicit about the edges is more useful than pretending they are not there:

One publisher per room. Multiple publishers and stream mixing are a different product; this fan-out assumes a single source that everyone watches.
The codec is forwarded as-is. The server does not transcode, so if the publisher switches codec mid-session, viewer connections have to be rebuilt.
No simulcast or SVC in this version. Every viewer receives the same encoding, which is right for a support call with a handful of viewers and wrong for a 500-person webinar.

Knowing which of those you need is most of the architecture decision. For one technician showing a fault to two or three people, the simple version is not a compromise.

The six things that make viewer #2 work

Read the upstream once; bind the same local track to every viewer's sender.
Budget server egress, not publisher uplink, for capacity.
Relay viewer PLI/NACK upstream with the publisher's SSRC so a late joiner gets a keyframe immediately.
Batch track arrivals into one offer per viewer instead of one offer per track.
Give RTCP reads a full-size buffer and handle unmarshal failures explicitly.
Rebuild viewer connections when the publisher's session ends, and let the client escalate to a full rejoin.

I built this fan-out, the batched negotiation, the RTCP relay and the client-side recovery ladder into a self-hosted WebRTC kit in Go — signaling server, SFU and browser clients in one binary, with a diagnostics panel that shows the selected candidate path and per-leg stats:

https://lowlatencykit.com/

The field-assist guide, which is the deployment this design is tuned for, is here:

https://lowlatencykit.com/guides/remote-field-assist-mobile-webrtc/

A frozen video tile and a working ICE state: the three-tier recovery ladder

AiLaoHuYu — Tue, 13 Oct 2026 08:42:19 +0000

The support call starts the same way every time: "it says connected but the picture is stuck." pc.iceConnectionState is connected. The signaling socket is open. Nothing in the logs is an error.

That is the failure this article is about, because the fix is not a config value. It is a recovery ladder: three tiers of escalating repair, each with a different cost, and a detection method that does not trust the connection state at all.

The whole thing in one line: connected describes the network path, not the picture, so a frozen tile and a healthy ICE state are entirely compatible.

Tier 0: detect on frames, never on ICE state

ICE state tells you whether a candidate pair was selected. It does not tell you whether frames are still arriving. A path that stops carrying media can sit in connected indefinitely, and a UI that renders a status dot from ICE state will happily show green over a black rectangle.

Ask the video element instead. requestVideoFrameCallback fires once per delivered frame, which makes it the cheapest possible liveness probe — no decoding, no stats parsing, and it is exactly the thing that stops happening when the picture freezes:

if (video.requestVideoFrameCallback) {
  video.requestVideoFrameCallback(function tick(now) {
    lastFrame = now;
    video.requestVideoFrameCallback(tick);
  });
}

setInterval(() => {
  const frozen = video.srcObject && performance.now() - lastFrame > 2000;
  // surface it; do not silently wait
}, 1000);

Two seconds is a deliberate choice: long enough that a normal keyframe interval or a momentary loss spike does not trip it, short enough that a user notices the recovery instead of giving up.

This is also the reason getStats() is a second opinion rather than the primary signal. It is the right tool for the cause — framesReceived climbing while framesDecoded stays flat means codec or keyframe, a climbing packetsLost means bandwidth — but polling it for liveness costs more and reports later than a frame callback.

Tier 1: an ICE restart, with a deadline

A restart is the cheapest repair, because it re-gathers candidates without tearing down the PeerConnection, the tracks, or the application state:

function tryRestart() {
  if (restarting) return;
  restarting = true;
  sig.send({ type: 'restart' });
  setTimeout(() => {
    restarting = false;
    if (pc && pc.iceConnectionState === 'failed') fullRejoin();
  }, 5000);
}

Two details in those nine lines are the whole lesson.

The restarting flag is what keeps a restart from stacking on top of itself while a previous attempt is still in flight. Without it, a 5-second timer that fires every second produces a restart storm, and the storm is worse than the original fault because now the server is doing new offers for a client that is still falling over.

The 5-second deadline is what stops the ladder from looping forever at tier 1. A restart fixes a path that changed — a phone that moved from Wi-Fi to cellular, a NAT mapping that expired, a route that shifted. It cannot fix a remote peer that is gone, and if you do not escalate, a client whose publisher has disappeared will retry restarts until the tab is closed.

Tier 2: the full rejoin, and why the old PeerConnection must die

When the server rebuilds its side — the publisher went away, or republished as a new session — the next offer is not a continuation of the session you were in. It is a new one. Reusing the old PeerConnection at that point produces the worst possible outcome: a connection that negotiates successfully, reports connected, and carries nothing, because the transceivers and the media state belong to a session the server has already discarded.

So the second tier is an explicit teardown, then a fresh socket:

function teardown() {
  if (pc) { pc.close(); pc = null; }
  video.srcObject = null;
}

function fullRejoin() {
  teardown();
  sig.reconnect();
}

Closing the PeerConnection is not cosmetic. It releases ICE agents and transceivers, and it makes the next createOffer a genuinely new negotiation instead of a delta against stale state.

The signaling layer needs two guards of its own

The ladder above is client-side recovery, but it depends on the socket underneath it behaving. Two guards matter, and both are absent from naive reconnect logic.

An epoch counter. A socket that closes after a newer socket has already connected would, without a guard, trigger a second reconnect and you end up with two live sockets and duplicated messages. Increment an epoch on every connect and let the handlers from stale sockets return early:

connect() {
  this.epoch += 1;
  const myEpoch = this.epoch;
  const ws = new WebSocket(this.url);
  ws.onclose = () => {
    if (myEpoch !== this.epoch) return;   // a newer socket already owns the state
    if (!this.closedByUser) this.retry();
  };
}

A send queue for the connecting window. The self-test path builds its offer during page load, before the socket has necessarily finished opening. A send() that returns false in that window silently drops the offer, and the symptom on the other side is "the server never answered" — a client bug that looks exactly like a server bug. Queue while readyState === CONNECTING and flush on open.

The retry itself is exponential with a ceiling, min(500 * 2^n, 8000), because a reconnecting client that hammers a server which is already struggling is a self-inflicted second outage.

What not to do

Do not keep the session alive with a client-side heartbeat timer. Hidden tabs throttle timers, and the tab is hidden precisely when a technician has put the phone in a pocket. Keepalives belong on the server, over the socket, for the reasons in the earlier article on reverse proxies.

Do not treat a restart as free and fire it on every hint of trouble. A restart re-gathers candidates and produces a new offer/answer; doing that on a loss spike turns a mild network blip into a visible glitch.

And do not hide the ladder from the user. A frozen tile with no indication is what makes someone close the tab. "Reconnecting" for two seconds, followed by a picture, is a product that looks like it is working.

The ladder, in order

Detect on frames, not on iceConnectionState. A 2-second frame gap is a freeze.
Try an ICE restart first, guarded by an in-flight flag.
Give the restart a hard deadline. If it is still failed, escalate.
Escalate to a full rejoin: close the PeerConnection, then reconnect fresh. A rebuilt server session needs a new negotiation.
Guard the socket with an epoch counter and queue sends during CONNECTING.
Back off exponentially to a ceiling, and keep keepalives on the server.

I built this ladder into the browser clients of a self-hosted WebRTC kit, together with the diagnostics panel that shows the selected candidate path, the freeze counter and the per-leg stats, so each tier can be watched failing and recovering on a real network instead of being taken on faith:

https://lowlatencykit.com/

The remote field-assist write-up, which walks the four network failure layers this ladder is designed to survive, is here:

https://lowlatencykit.com/guides/remote-field-assist-mobile-webrtc/

TURN returns 401 forever: the one config line nobody reads

AiLaoHuYu — Tue, 13 Oct 2026 08:38:44 +0000

A TURN server that answers every request with 401 Unauthorized looks like a credentials problem. Most of the time it is a missing realm, and the reason it is hard to find is that the startup log tells you once and then never mentions it again.

The pattern is always the same. The relay was configured with use-auth-secret, the shared secret matches on both sides, the client sends a valid REST credential, and the log fills with this:

Default realm:
WARNING: ... you did not specify the default realm option
realm <> user <>: ... error 401: Unauthorized

That empty <> in realm <> user <> is the whole bug.

The whole thing in one line: use-auth-secret still needs a realm, and coturn will not remind you twice.

Why an empty realm breaks authentication

use-auth-secret is the long-term credential mechanism with a shared secret. The client is expected to be challenged once and then retry with a proper credential — a first 401 is normal and healthy.

What is not normal is the stream. The challenge carries the realm, the client hashes username:realm:password for the REST scheme, and if the realm is empty the two sides are not answering the same question. The client retries, gets challenged with the same nothing, retries again, and eventually dies with a client-side 701 timeout. From the browser it looks like the relay simply refuses you.

Fix it with one line:

realm=turn.example.com

A normal stable hostname is the right choice. If the server is only reachable by IP, use that IP consistently. A hostname pays off later when you add TLS certificates, and it keeps the realm readable in a packet capture.

The startup log is the actual debugging tool

This is the part worth internalising: read the ten lines before the first client request, not the hundred identical 401s after it.

A misspelled option, a wrong -c path, or a config file coturn cannot read all produce the same symptom — your edits do not exist. Start with an absolute path so there is no ambiguity about which file won:

turnserver -c /root/turnserver.conf

Then confirm the startup output prints a non-empty Default realm. If it prints nothing, stop debugging credentials; nothing you do to the client will matter.

Realm is a deployment setting, not a knob

Once it is set, treat it as fixed. Changing the realm changes the authentication context clients see, so every cached or pre-generated credential has to be retested after the change. This is the kind of setting that silently invalidates a working integration during an otherwise harmless config edit.

Verify the shared secret with coturn's exact bytes

After the realm is in place, check the secret the same way coturn will. The password is base64(HMAC-SHA1(secret, username)) — not a direct HMAC of the password, and not an MD5 hash:

SECRET='mysecret'
EXP=$(($(date +%s) + 3600))
USER="$EXP:bob"
PASS=$(printf '%s' "$USER" | openssl dgst -binary -sha1 -hmac "$SECRET" | openssl base64)

printf 'username=%s\npassword=%s\n' "$USER" "$PASS"

Two traps live in that command. A trailing newline or a set of quotes that got included in the secret value will produce a credential that is wrong by one or two bytes and looks perfect. And an expiry in the past produces a credential that is well-formed and rejected.

Paste the result into the Trickle ICE page against:

turn:12.34.567.89:3478?transport=udp

The second config gap that looks identical

If the realm is correct and credentials verify but the client still cannot relay, check external-ip. When the machine has a private interface and the public address is attached by the provider's NAT, the relayed candidate must contain the public address:

external-ip=12.34.567.89/10.0.0.4

Replace 10.0.0.4 with the actual local address coturn listens on. And open the UDP relay range in both places — the provider firewall and the host firewall. A control port that answers while the relay range is closed gives you a srflx candidate and no relay candidate, which the browser reports as a generic failure.

For a server-side check that removes the browser entirely:

turnutils_uclient -v \
  -u "$USER" \
  -w "$PASS" \
  -p 3478 \
  12.34.567.89

If that allocates, the server is fine and the problem is in the client's credential or the network path.

The check order that saves time

Read the startup log for Default realm. Empty means stop and fix the config.
Start coturn with an absolute config path and confirm your file is the one loaded.
Expect one 401, then an allocation. An endless 401 stream with a client 701 is the realm failure, not a wrong secret.
Generate the REST credential with coturn's exact algorithm and check for stray whitespace or quotes.
Verify external-ip whenever the host interface is private.
Open the relay port range in both firewalls, not just the control port.
Prove it with turnutils_uclient so you are not debugging TLS, browsers and JavaScript at the same time.

None of this is complicated. All of it is invisible until you know that the one line above the 401s is the line that matters.

I packaged a working self-hosted WebRTC stack — the Go signaling server and SFU, the browser publisher and viewer, the ICE restart and rejoin chain, the coturn configuration and a two-probe relay test that separates "port unreachable" from "allocation refused" — as a source kit you run on your own server:

https://lowlatencykit.com/

If you only want to know whether your own TURN server allocates, that test page is free and needs no account:

https://lowlatencykit.com/test/turn/

Audio works, video is black: debugging a layered WebRTC SFU in Go

AiLaoHuYu — Tue, 13 Oct 2026 08:29:25 +0000

Audio connects instantly, the viewer hears everything, and the video tile stays black. The publisher side looks fine. ReplaceTrack returns nil, which the code logs as success.

That nil is where most of these debugging sessions go wrong. ReplaceTrack returning nil means one thing: the track was bound to a sender that already existed. It does not mean the negotiated SDP allows that m-line to send, it does not mean both legs agreed on a codec, and it does not mean a single video RTP packet ever reached the downstream leg. Three separate failures that produce the same black rectangle.

This is the order that separates them, cheapest check first.

The whole thing in one line: audio and video travel the same connection but not the same negotiated path, so a working audio leg proves nothing about video.

First, read the negotiated direction, not the code

Direction in SDP is not a preference. It is the answer both sides ended up with, and it is what controls the RTP path.

The sending leg's video m-section must be sendonly or sendrecv. The receiving leg must be recvonly or sendrecv. ReplaceTrack does not renegotiate direction. You can add a track to a sender that the remote side accepted as inactive and get a perfectly fine nil back.

m=video ...
a=mid:<same mid on both sides>
a=sendrecv | a=sendonly   # sender side
a=recvonly | a=sendrecv   # receiver side
a=rtpmap:<pt> <matching video codec>

If the video m-line has no usable a=ssrc from the sender, or the remote direction is recvonly/inactive, stop. That is a negotiation fault, and no amount of buffering or async handling will fix it. Setting direction on one side only is not enough — the negotiated answer is the one that matters.

Second, the codec has to match across the boundary

A TrackLocalStaticRTP rewrites the SSRC and the payload type when it writes into a sender. It does not transcode, and it does not rewrite codec parameters.

So forwarding H.264 between two legs that negotiated different profiles, or writing VP8 packets into a sender that negotiated H.264, gives you a track object that exists, accepts writes, and never decodes. The mime type looking similar is not the same as the codec being compatible.

remoteTrack.Codec().RTPCodecCapability on the inbound side and the negotiated codec on the outbound sender are not interchangeable just because both say video/H264. Pin the same codec on both legs, or transcode at the boundary. Pick one deliberately.

Third, find out whether RTP arrived at all

Before touching the forwarding loop, get evidence. Two log lines split the problem in half: packets that never arrived, versus packets that arrived and were not used.

// After negotiation, before the forwarding loop starts.
for _, encoding := range subSFU.videoRTPTransceiver.Sender().GetParameters().Encodings {
    log.Printf("sub video sender ssrc=%d pt=%d", encoding.SSRC, encoding.PayloadType)
}

// In the master forwarding loop.
if err := localTrack.WriteRTP(packet); err != nil {
    log.Printf("sub video write failed: %v", err)
}

On the receiving side, log the track handed to OnTrack, then read pc.GetStats() for the inbound RTP stream and check whether packetsReceived moves.

If the downstream leg never receives the first video packet, the fault is in negotiation or sending. If it receives packets and the decoder never produces frames, the fault is codec compatibility or keyframes. Those are different bugs.

Fourth, a forwarding loop that hides its own death

The classic version of this loop:

for {
    packet, _, err := remoteTrack.ReadRTP()
    if err != nil {
        log.Printf("upstream video read failed: %v", err)
        return
    }

    if err := localTrack.WriteRTP(packet); err != nil {
        log.Printf("sub video write failed: %v", err)
        return
    }
}

Both exits matter. A single failed binding must not be mistaken for a successful fan-out, and a read that returns an error must not kill the goroutine silently — the symptom of a dead forwarding goroutine is exactly "audio works, video disappeared" on the leg it was feeding.

One more trap in the same loop: ReadRTP() allocates to Pion's receive MTU. If you keep a fixed byte slice and reuse it, handle io.ErrShortBuffer explicitly instead of letting the goroutine exit. The failure looks identical to a network problem and costs an afternoon.

Fifth, flowing RTP with a black tile is a keyframe problem

Packets can arrive continuously while the viewer stays black, because the first decodable frame never arrived. Send a PLI on the inbound video receiver and then confirm that framesReceived and framesDecoded actually advance in GetStats(). If framesReceived climbs and framesDecoded stays flat, you are looking at codec parameters or a missing keyframe, not transport.

Keep that check separate from the previous one. Transport and decode fail with the same pixels on screen.

The pattern that avoids the whole renegotiation dance

Instead of adding video late and hoping the negotiation cooperates: create the video transceiver with a placeholder TrackLocalStaticRTP before the very first offer/answer, negotiate it as sendrecv, and only then swap in the real upstream track once the initial negotiation is stable.

The placeholder costs one unused m-line and removes an entire class of "the sender exists but the direction does not allow media" failures. Each downstream leg gets its own binding of the same local track, and every write is checked — one failed binding must not be mistaken for a successful fan-out.

The check order that saves time

Read the negotiated direction on both legs. No sendrecv/sendonly on the sender means it is a negotiation bug.
Confirm the same codec on both legs. Similar mime types are not proof.
Log the sender SSRC and payload type, then check packetsReceived on the inbound leg.
Handle every error in the forwarding loop; a dead goroutine looks like a network fault.
If packets flow but frames do not decode, request a keyframe and compare framesReceived with framesDecoded.
Prefer a placeholder transceiver negotiated up front over adding video mid-session.

None of this is exotic. All of it is invisible when the publisher and the viewer happen to agree by accident, which is why demos pass and production does not.

I packaged the working version of all of this — the Go signaling server and SFU, the browser publisher and viewer, the ICE restart and rejoin chain, and the diagnostics panel that shows the selected candidate path and the per-leg counters — as a self-hosted source kit, so you can prove each layer on your own server instead of inferring it from a black box:

https://lowlatencykit.com/

If you only want to know whether your own TURN server allocates, the relay test page is free and needs no account:

https://lowlatencykit.com/test/turn/

Remote video support that survives a technician's phone network

AiLaoHuYu — Tue, 13 Oct 2026 05:46:50 +0000

Remote visual assistance demos well on office Wi-Fi and fails the first time a technician climbs into a van. I have watched this happen with a working demo and a confused buyer, and the failure is almost never the codec. It is the network underneath it: the phone changes address mid-session, it sits behind a carrier NAT that no direct candidate can reach, and the server does not know its own public address.

This is the write-up I wanted when I started. Symptoms first, because that is what you search for when a field session has gone dark and the customer is waiting.

The whole thing in one line: field video fails in four different layers, and they look identical from the UI.

It works in the office and fails on cellular

ICE finds a path by gathering candidates. A host candidate is the device's own address. An srflx candidate is the address a STUN server saw after NAT. A relay candidate is an address on a TURN server that both sides send to when nothing direct works.

Consumer Wi-Fi is usually cone NAT, so two peers discover each other with STUN alone and the session connects with no infrastructure at all. A phone on cellular is frequently behind a carrier-grade NAT whose mapping is not reusable. The srflx candidate is still gathered, still looks valid, and every packet sent to it is dropped, because the mapping was opened for a different destination.

Symptom: on Wi-Fi the connection establishes in under a second; on cellular it never leaves checking.

What to look at: log the selected candidate pair. If it is never relay when the call fails, you need TURN before you debug anything else.

pc.oniceconnectionstatechange = () => {
  if (pc.iceConnectionState === 'failed') {
    // which pair did we actually end up on?
    pc.getStats().then((s) => s.forEach((r) => {
      if (r.type === 'candidate-pair' && r.state === 'failed') {
        console.log('failed pair', r.localCandidateId, r.remoteCandidateId);
      }
    }));
  }
};

The relay port answers but the allocation is refused

"No video through the relay" has two causes that are indistinguishable from the browser: the UDP port is unreachable, or the port is fine and the relay declined the allocation. Different fixes, so test them separately.

First, a STUN probe against the same host and port as your TURN server. If it returns an srflx candidate, the port is open and something is listening. Then a real allocation with the real credentials. A relay candidate coming back means TURN works and the problem is elsewhere. A refusal with the port open means credentials or the allocation range — usually a 401 in the coturn log, or a relay port range that was never opened even though the control port was.

# coturn: open the control port AND the relay range
listening-port=3478
min-port=49152
max-port=65535

# a cloud VM must be told its own public address
external-ip=203.0.113.10

The relay range is the part people forget. The control port on 3478 answers, the credentials are perfect, and the allocation still fails because the media ports coturn wanted are closed in the security group. This is the trap that makes a TURN config look correct while every cellular session dies.

Video freezes when the technician walks to the van

A WebRTC transport is bound to a 5-tuple: source address, source port, destination address, destination port, protocol. When the phone moves from Wi-Fi to cellular it gets a new source address and the 5-tuple the session was using is gone. The old candidate pair cannot be revived. On screen this is a freeze with no error, because the connection object has not given up yet.

The recovery is an ICE restart, which renegotiates connectivity on the existing peer connection instead of tearing the session down. A restart is not always enough after a long outage or a carrier change, so the practical chain is: ICE restart first, full rejoin as fallback, jittered backoff between attempts so a fleet of devices does not hammer the server at once when a tower comes back up.

Do not trust the connection state alone. A connection can read connected while frames have stopped. Watch the frame callbacks instead, and treat a missing frame as frozen even while ICE still says connected:

let last = performance.now();
video.requestVideoFrameCallback(function tick() {
  last = performance.now();
  video.requestVideoFrameCallback(tick);
});
setInterval(() => {
  if (performance.now() - last > 3000) restartChain(); // stalled, not disconnected
}, 1000);

ICE connects but no frame ever decodes

On a cloud VM the network interface usually has a private address and the public address is attached by the provider's NAT. If the server gathers candidates from its own interface it advertises something like 172.16.x.x in SDP, and the remote browser tries a private address it can never reach. ICE can even report connected on a local path while the media never leaves the host.

Tell the server its public address, or force the relay path. In coturn that is external-ip; in a Go server it is a -public-ip flag or an ICE transport policy of relay. If a session connects instantly between two machines on the same office network and fails from outside, check this first.

The tab says connected but nothing arrives

Signaling runs over a WebSocket and reverse proxies reap idle WebSockets, often around 60 seconds. The socket closes, the application does not notice, and the UI keeps saying connected because nothing told it otherwise.

The fix is a protocol-level ping from the server, not a JavaScript heartbeat. Background tabs throttle timers aggressively, so a client timer that fires every 20 seconds in the foreground can fire far less often when the tab is hidden — which is exactly when a technician has put the phone in a pocket.

The check order that saves time

Log the selected candidate pair. Never relay on a cellular failure means you need TURN first.
Probe the relay in two steps: STUN on the control port, then a real allocation. It separates "port unreachable" from "allocation refused".
Confirm the relay media port range is open, not just the control port.
Set the public address explicitly on any host whose interface is private.
Trigger an ICE restart on a freeze and fall back to a full rejoin, with jittered backoff.
Keep the signaling socket alive from the server, not from a client timer.

None of this is exotic once it is written down, and all of it is invisible in a demo on good Wi-Fi. The failure modes only show up in the field, which is where a field-assist product actually runs.

I packaged the working version of all of this — the Go signaling server and SFU, the browser publisher and viewer, the ICE restart and rejoin chain, the diagnostics panel that shows the selected candidate path, the coturn config and the two-probe relay test — as a self-hosted source kit, so you can prove each layer on your own server instead of inferring it from a black box:

https://lowlatencykit.com/field-assist/

The relay test page is free and needs no account, if you just want to check whether your own TURN server allocates:

https://lowlatencykit.com/test/turn/

What breaks when you self-host a TURN server (coturn — symptom, cause, fix)

AiLaoHuYu — Sun, 20 Sep 2026 03:53:34 +0000

The first article in this series was the traps inside the code. The second was the layer underneath — the candidates that lie, the UDP firewall nobody looks at, the reverse proxy that reaps an idle socket. This one is about the piece people reach for when those two are not enough: the relay.

TURN is the part of WebRTC that gets configured last, in a hurry, by copying a config off a blog post. That is exactly how you end up with a relay that passes every "is it running?" check and still produces no video.

The failures below are all coturn behaviours you can read in the config and the log. What makes them expensive is not that they are subtle — it is that most of them fail without an error message anywhere near where you are looking.

First: is TURN even your problem?

It often is not. Adding a relay to a system whose real fault is elsewhere hides the fault and makes the next debugging session worse.

Three checks, in this order.

Look at which candidate type won. In chrome://webrtc-internals (or about:webrtc in Firefox), find the selected candidate pair and read the local candidate's type. If it says relay, TURN is in the path and working, and your problem is somewhere else entirely. If it says srflx or host while the connection fails, TURN is not being used at all — which is a different bug from TURN being broken, and it lives in your ICE configuration.

Force the relay. In a test page, build the peer connection with iceTransportPolicy: 'relay'. Now TURN is the only permitted path. If this connects while your normal config does not, your relay is fine. If this also fails, you are actually debugging TURN.

Check the two failures from the last article first. A server advertising an unroutable address and a closed UDP media range both produce the same visible symptom as a dead relay: signaling green, ICE stuck checking, then failed. They cost nothing to rule out and they are far more common than a broken coturn.

It says it started and is bound to nothing

Symptom. systemctl start coturn returns success. systemctl status coturn says active. Nothing works.

Cause. On Debian and Ubuntu the package ships /etc/default/coturn with the enable switch commented out, and the start path honours that file. Depending on the version and how the package was installed, that gate is either the init script or a unit that wraps it — and either way you get a clean exit with no error message. A service that declined to start and a service that started and could not bind look identical from systemctl.

This is also where a config file mismatch hides: coturn reads /etc/turnserver.conf by default, but if something passes -c to a different path, your edits are being ignored and nothing tells you.

Check. Do not ask whether the service is running. Ask whether anything is bound.

ss -lunp | grep -E '3478|5349'
journalctl -u coturn -n 50 --no-pager

If the ports are not in the ss output, it is not running in any sense that matters. Note that curl is useless here — TURN is not HTTP, so an HTTP request to 3478 will connect and then produce something unhelpful. It proves nothing either way.

Fix. TURNSERVER_ENABLED=1 in /etc/default/coturn, restart, re-run the check. If it is still not bound, you are now looking at a real startup error and the log will have it.

The relay address points inward

Symptom. The allocation succeeds. The client gets a relayed candidate. The candidate is a 10.x or 172.16–31.x address. ICE never gets past checking, from the outside it looks like the relay is broken, and on the server everything is green.

Cause. A cloud VM's network interface has a private address and the public IP exists in the provider's NAT layer in front of it. The machine has no idea what its public address is. coturn advertises the address it is bound to, so it advertises the private one, and nobody outside can route to it.

This is the same class of bug as the host candidates in the previous article, one layer up: the service is telling the truth about an interface that is a lie.

Fix. Both halves of the mapping:

external-ip=203.0.113.10/10.0.0.4

Public first, private second, slash between them. Setting only the public address is a common half-fix that works until coturn needs to bind locally.

Verify. Re-read the relayed candidate. It should now be the public address, and it should be reachable — which is a different claim, and the next section is why.

You opened the control port and called it done

Symptom. Allocation succeeds. The relayed candidate is correct and public. Media still never flows. Or: it works for one client and not another, with nothing different about them.

Cause. 3478 is the control port. The media does not go over it. coturn allocates a relay port per client from a range — min-port to max-port, default 49152 to 65535 — and the actual RTP flows there, over UDP.

This one is worse than the others because the successful allocation proves your firewall work is partly right, which is exactly the wrong amount of right. You conclude the network is fine and go looking in your application code.

Fix. Open the relay range in both firewalls: the provider's security group and the host's own ufw/iptables. On most cloud providers the security group is the one that actually decides whether a packet arrives and the host firewall is a red herring; on a VPS with a full iptables ruleset it is the reverse. Open UDP. Opening only TCP gets you nothing, because browsers will use UDP for TURN whenever it is available.

Do not narrow the range "for security." This is the trap hidden in a reasonable-sounding hardening step. Each client using the relay takes a port out of the range, and one page can open more than one allocation. A forty-port range is a lab with a handful of users and nothing else, and the way you find out is under load, months later, as an intermittent failure that does not reproduce.

Keep the default range, and if you must narrow it, size it against the number of concurrent clients you expect rather than the number of streams you are picturing.

Nobody can authenticate, and only the log will say why

Symptom. Every allocation is refused. The client retries, or gives up and reports ICE failure. The relay is bound, reachable, and simply will not talk to you.

Cause. coturn has two credential modes and they are alternatives, not layers:

lt-cred-mech is static long-term credentials, with users created through turnadmin. If you enable it and never create a user, every request is refused and there is nothing wrong with your configuration as such.

use-auth-secret with a static-auth-secret is the time-limited REST scheme. The client generates a username of <unix-expiry-timestamp>:<any-label> and a password of base64(HMAC-SHA1(secret, username)). Every part of that has to be exact — the HMAC variant, the encoding, the units of the expiry. Get any of it slightly wrong and you get a refusal that looks exactly like a wrong password, because it is one.

A config that sets neither is, in effect, an unauthenticated relay. That is not a neutral default: it is an open relay, someone will find it, and their traffic will be on your bill and your IP's reputation.

Fix. Pick one mode, set it explicitly, and turn on verbose so the log shows you the request instead of leaving you to infer it. Then generate the credential the way the server expects:

# username = <unix expiry>:<label>;  password = base64(hmac-sha1(secret, username))
EXP=$(( $(date +%s) + 3600 ))
USER="$EXP:demo"
PASS=$(printf '%s' "$USER" | openssl dgst -binary -sha1 -hmac "$SECRET" | openssl base64)
printf 'username=%s\npassword=%s\n' "$USER" "$PASS"

Read the response code, not the symptom. TURN tells you exactly what is wrong if you look at the code in the log:

401 — the challenge. On a first request this is normal and expected; the client is supposed to retry with credentials. Seeing 401s is not itself a fault, and treating it as one sends people down a long road.
441 — wrong credentials. Your HMAC or your expiry is off.
438 — stale nonce. The client cached a nonce past its lifetime; a conforming client retries and you should not see it persist.
403 — forbidden, including a denied peer. See the blocklist section.
486 — allocation quota reached. See the last section.

coturn ships with turnutils_uclient, which does a real allocation against your server and prints what came back. It is the fastest way to test the relay without a browser in the loop at all — check turnutils_uclient -h for the current flags.

The certificate is valid and coturn still cannot read it

Symptom. turn: on 3478 works. turns: on 5349 does not. Or coturn fails to start with a message about a file that definitely exists.

Cause. turns: needs a certificate, coturn runs as its own unprivileged user, and Let's Encrypt's /etc/letsencrypt/live/ directory is symlinks into archive/ behind permissions that user does not have. The certificate is valid, your path is correct, and the process cannot open it.

Fix. Give the turnserver user read access to the cert tree, or have the renewal hook copy the pair somewhere readable with the right ownership. Both work; the second survives a permissions change on the original.

And the part worth more than the fix: turn: on 3478 does not need TLS at all. If what you need is UDP relay for browsers, you can leave turns: out entirely and this whole failure mode stops existing.

There is a second assumption worth killing while you are here: UDP TURN from an HTTPS page is not mixed content. The browser will not block it, and you do not need turns: to satisfy a security policy. It is a common reason people add a certificate they did not need and then spend an evening on permissions.

The blocklist is doing exactly what it was designed to do

Symptom. Allocation succeeds, the candidate is right, the ports are open, and media still does not flow. The log mentions the peer.

Cause. coturn ships with denied-peer-ip entries covering loopback, the private ranges, link-local, multicast and reserved space. This is deliberate and good: it is what stops your relay being used to reach things it should not reach.

But if your peers legitimately live on a private network — a corporate deployment, an internal lab, anything over a VPN — the relay is correctly refusing to talk to them, and it is not going to tell you that it thinks it is protecting you.

Fix. Allow the specific range you need:

allowed-peer-ip=10.20.0.0-10.20.255.255

Be precise about it. The default list is aggressive because a relay will happily connect to whatever it is told to, and you are the one removing that guard for a case where you actually want it removed.

It works until it does not: quotas, TTLs and the bill

Symptom. Clean in testing, degrades in production. Allocations start failing under load. Or the bandwidth graph shows relay traffic far larger than the number of relayed sessions should account for.

Three things, in the order they usually turn out to be:

No quota. coturn's defaults let a single client hold a great deal. total-quota and user-quota cap concurrent allocations, and max-bps caps throughput per session. Without them, one misbehaving client is a capacity incident for everyone else.

Relay traffic is real traffic. Every relayed stream passes through your server, and you pay for it. This is worth watching as a ratio, not a total: what fraction of your sessions needed relay candidates. If it is most of them, you do not have a TURN problem, you have a NAT-traversal problem that you are paying to route around. Treat a rising relay ratio as a defect in your ICE configuration, not as a reason to buy more bandwidth.

Allocation lifetime. Allocations are refreshed by the client. A client that stops refreshing — a throttled tab, a suspended mobile app — loses its allocation at the TTL, and the user experiences that as "it disconnects after a while," which sounds like a media problem and is not one.

The order I would check these in

When a relayed session fails, in this order, cheapest first:

ss -lunp | grep 3478 — is anything actually bound, or did the service decline to start?
Read the relayed candidate's address — public, or a private address nobody can route to?
Confirm the relay UDP range is open in both the provider firewall and the host firewall.
Put verbose in the config, reproduce, and read the TURN response code — 401 on the first request is normal, 441 and 486 are not.
Force iceTransportPolicy: 'relay' in a test page — does it connect when relay is the only permitted path?
Watch the relay ratio — if most sessions relay, the relay is a symptom and not the cure.

One more, and it is the same one as last time because it is the one that keeps being true: test from a network that is not your development machine. Your laptop and your server are often close enough that a path which cannot work anywhere else still works for you. Wifi off, cellular on, open the page on a phone. That is a genuinely different NAT and a genuinely different path, and it is the only test that answers the question you are actually asking.

The kit

I put what I learned into a starter kit: the signaling server and SFU in Go (Pion v4), the browser publisher and viewer, the auto-reconnect chain, the diagnostics panel, deploy files for systemd, Caddy and Docker, and the pitfalls doc with symptom, cause and fix.

There is a live demo you can open without an account, and a canvas self-test page that exercises the whole path and needs no camera: https://lowlatencykit.com

It is paid (early access, Basic $99 / Pro $199 / Team $499, with an early-bird code on the landing page). This article is free, and so are the other two — that part is not a teaser, it is the actual content.

WebRTC works on your laptop. Here is what breaks when you put it on a server.

AiLaoHuYu — Sat, 19 Sep 2026 06:53:11 +0000

The first article in this series covered the traps inside the code — the Pion v4 API changes, the SSRC rewrites, the renegotiation timing. This one is about the layer underneath it, where the failures look identical and have completely different causes.

Everything below happened to me deploying a real-time streaming server to a cloud VM. None of it was a bug in my code, and all of it took longer to find than it should have.

The split that explains most "it connects but there's no video"

Signaling and media take different paths, and only one of them goes through the infrastructure you configured.

Signaling is a WebSocket. It goes out on 443, it is plain TCP, your reverse proxy terminates TLS for it, your tunnel carries it, your certificate covers it, and every tool you already know how to debug applies to it.

Media is RTP over UDP. It goes browser-to-server directly, carrying the actual audio and video. No part of your reverse proxy, your CDN or your tunnel touches it. Not by misconfiguration — by design. A WebSocket connection is not a suitable transport for a 30fps media stream and no proxy is going to turn into one.

So the moment you see a session where the WebSocket is healthy and there is no picture, you are not looking at a bug in your web stack. You are looking at the media path, and the web stack is a red herring. That single distinction has saved me more time than any debugging tool.

The candidate list in your SDP is the whole story of that second path. It is a list of "here is where I might be reachable", and most of the deployment failures below are about that list being wrong.

Trap 1: your ICE candidates are lies

A cloud VM's network interface has a private address. Mine had a 172.31.x.x on the NIC; the public IP exists in the provider's NAT layer in front of it. The machine itself has no idea what its public address is.

So when your server gathers ICE candidates the honest way, it reports what it can see: a private address nobody on the internet can route to. Signaling completes perfectly. ICE checks go out to an unreachable address. You get a connection that never connects, and nothing in any log says why.

There are two ways out, and they are not equivalent:

Use a STUN server. The server asks a public STUN server "what address did this request appear to come from?" and advertises the answer. This is the standard solution and it works — right up until the NAT in front of your VM is the kind that assigns a different external port per destination, at which point the port you advertise is not the port that reaches you, and you are back to failing checks with no explanation.

Tell the server its public IP. If your provider gives you a one-to-one mapping — public IP forwards directly to the instance, same ports — then you can skip the guessing entirely and configure the advertised address explicitly. The candidate your server hands out is then a statement of fact rather than an inference, and it holds regardless of what the NAT is doing.

In Pion that is a setting engine call, made once before you build the API:

se := webrtc.SettingEngine{}
se.SetNAT1To1IPs([]string{opts.PublicIP}, webrtc.ICECandidateTypeHost)
api := webrtc.NewAPI(webrtc.WithSettingEngine(se))

The second is what I ended up using, and the difference on the wire is not subtle. Before, checks that never completed. After, a usable pair with a 7ms round trip and a steady 30fps of decoded frames with zero freezes over a six-second test.

If you take one thing from this section: the fact that your server is behind NAT is not a detail, it is a first-class configuration input you have to handle deliberately. Decide which of the two approaches fits your provider and set it. Do not assume the default gathering will figure it out.

Trap 2: the firewall that has nothing to do with your app

Cloud providers give you two firewalls and only one of them is the one you think of as a firewall.

The one on the machine — ufw, iptables, firewalld — is the one everybody checks. The one at the provider level, usually called a security group, sits in front of the instance and is what actually decides whether a packet arrives. It defaults to closed. On the VM I used, exactly one port was open out of the box: 22.

Now the part that makes this expensive: your web setup gives you no warning at all. You open 443, you get a certificate, the site loads, the signaling connects, and you conclude the networking is done. Almost all of it is done. All of it that runs over TCP is done.

Your media ports are UDP and they are in a range that is not 443, so nothing about a working HTTPS setup tells you anything about them.

The symptom is the one from the previous section and it is maddening: signaling green, ICE stuck in "checking", then failed. Same visible outcome as wrong candidates, completely different fix.

Here is how to tell trap 1 and trap 2 apart, because from the outside they look the same:

Open the browser's WebRTC internals page (chrome://webrtc-internals in Chromium browsers; about:webrtc in Firefox) and look at the candidate list, not the connection state.

If the only candidates you see are private addresses and no public one, you have trap 1 — your server never learned where it really is. If you see a sensible public candidate but the connectivity checks to it are the ones failing, you have trap 2 — the address is right and something is eating the packets.

That is a two-minute check that tells you which of two very different afternoons you are about to have. Learn it before you need it.

Trap 3: your reverse proxy reaps the idle socket

This one is a different failure shape and it is worse, because everything works first.

The WebSocket carries signaling, and signaling is idle most of the time. Two peers agree on parameters, media flows, and then nothing needs to be said for a while. Your reverse proxy has an idle timeout, usually around 60 seconds, and an idle WebSocket looks exactly like an abandoned connection. It closes it.

The tab, meanwhile, has no idea. From the user's perspective the stream is running, the UI says connected, and then something that needed signaling — a reconnection, a new viewer, a track change — goes into a socket that has been dead for a minute.

The fix everyone reaches for first is a heartbeat from the browser: a small message every 30 seconds to keep the socket warm. Do not do this. Background tabs throttle timers, aggressively, and the tab that has been in the background for ten minutes is exactly the one whose heartbeat has stopped. You have built a keepalive that fails precisely when it is needed.

Send the ping from the server instead, at the protocol level rather than the application level. The WebSocket spec defines ping and pong frames, browsers answer pings automatically, and that answer is not subject to the timer throttling that hits your JavaScript. Pair it with a read deadline on the server and you also get something a browser-side heartbeat never gives you: you find out about dead connections within a bounded time instead of discovering them when a room mysteriously gets stuck as busy.

Making the server responsible for liveness also removes a category of bug entirely. There is no client-side code to get wrong, no clock to drift, no timer to be throttled.

The shape of it in gorilla/websocket, with the browser side handling pongs for you with no code at all:

const (
    writeWait  = 10 * time.Second
    pongWait   = 60 * time.Second
    pingPeriod = 25 * time.Second // under pongWait, and under the proxy's own idle limit
)

func (c *Client) writeLoop() {
    ticker := time.NewTicker(pingPeriod)
    defer ticker.Stop()
    for {
        select {
        case msg := <-c.send:
            if err := c.conn.WriteJSON(msg); err != nil { c.close(); return }
        case <-ticker.C:
            if err := c.conn.WriteControl(websocket.PingMessage, nil, time.Now().Add(writeWait)); err != nil {
                c.close(); return
            }
        case <-c.closed:
            return
        }
    }
}

func (c *Client) readLoop() {
    defer c.close()
    _ = c.conn.SetReadDeadline(time.Now().Add(pongWait))
    c.conn.SetPongHandler(func(string) error {
        return c.conn.SetReadDeadline(time.Now().Add(pongWait))
    })
    for {
        var m clientMsg
        if err := c.conn.ReadJSON(&m); err != nil { return }
        _ = c.conn.SetReadDeadline(time.Now().Add(pongWait))
        c.handle(m)
    }
}

Two things worth noticing in that pair. The deadline is refreshed by any inbound frame, not just pongs, so an active connection is never falsely declared dead. And a missed pong closes the client and frees the room, which is why a crashed publisher does not leave the room stuck as busy for the next viewer.

The order I would do this in from scratch

Start with the media path, not the app. Before writing a line of signaling code, answer two questions: which UDP ports will carry media, and are they reachable from the open internet. Both answers come from your provider, not from your code, and finding out later means unpicking an assumption you have built on top of.

Configure the advertised address deliberately, as covered above. Treat "what address does my server claim to be" as a required setting, not something to leave to defaults and hope about.

Test from a network that is not your development machine. This is not a formality. Your laptop and your server are often on networks close enough that a candidate that cannot work anywhere else still works for you. Open the test page on a phone with wifi off and the cellular radio on, and you are testing something genuinely different: a different carrier, a different NAT, and a different path to your server. If it works there, it works.

Only then build reconnection. Reconnection logic on top of a media path that does not work is untestable — every failure looks the same and you cannot tell whether you are debugging your retry logic or the network underneath it.

The kit

There is a live demo you can open without an account, and a canvas self-test page that exercises the whole path and needs no camera: https://lowlatencykit.com

It is paid (early access, Basic $99 / Pro $199 / Team $499, with an early-bird code on the landing page). This article is free, and so is the first one — that part is not a teaser, it is the actual content.

DEV Community: AiLaoHuYu

Jitsi is the right default for meetings. Here is the narrower case where it is not

The failure that makes the two products diverge

Where Jitsi is the better engineering choice

Where a one-publisher kit makes sense

A deployment mistake worth checking first

What I would decide from

Your WebRTC viewer says connected. The picture is frozen.

Frames are the health check

Recover in the cheapest order

A compact implementation

Diagnose one thing, not ten numbers

What this does not solve

Testing WebRTC without a camera: a loopback self-test that proves the whole path

Replace the camera with a canvas

Draw something that can only be live

Drive the canvas on a timer, not on requestAnimationFrame

Count liveness two ways, because one of them stops in a hidden tab

Give every run its own room

Mirror the state so automation can assert it

What this test does and does not prove

The fixture, in order

The six getStats numbers that actually tell you what broke

1. The selected candidate pair, and the candidate types behind it

2. Inbound bitrate, which requires two samples

3. framesPerSecond and resolution

4. qualityLimitationReason on the outbound side

5. framesDecoded versus framesReceived

6. Jitter and the jitter buffer

The table that fits on one screen

How to read it in one pass

Coturn and Kurento in Docker Compose: the three addresses that decide everything

Address 1: the realm

Address 2: external-ip

Address 3: the media address Kurento advertises

Give coturn host networking, and then drop the ports: block

Choose one credential mode, not two

The relay range is a capacity number, not a formality

Transport order, and what Nginx should not do

The verification order worth following exactly

One camera, many viewers: the fan-out details that decide whether viewer #2 works

The publisher's uplink does not grow, and that is the entire point

The new viewer's black tile is a keyframe problem

Negotiate all the tracks in one offer, not one offer per track

RTCP reads need a real buffer

When the publisher changes, every viewer is stale

The honest limits of this design

The six things that make viewer #2 work

A frozen video tile and a working ICE state: the three-tier recovery ladder

Tier 0: detect on frames, never on ICE state

Tier 1: an ICE restart, with a deadline

Tier 2: the full rejoin, and why the old PeerConnection must die

The signaling layer needs two guards of its own

What not to do

The ladder, in order

TURN returns 401 forever: the one config line nobody reads

Why an empty realm breaks authentication

The startup log is the actual debugging tool

Realm is a deployment setting, not a knob

Verify the shared secret with coturn's exact bytes

The second config gap that looks identical

The check order that saves time

Audio works, video is black: debugging a layered WebRTC SFU in Go

First, read the negotiated direction, not the code

Second, the codec has to match across the boundary

Third, find out whether RTP arrived at all

Fourth, a forwarding loop that hides its own death

Fifth, flowing RTP with a black tile is a keyframe problem

The pattern that avoids the whole renegotiation dance

The check order that saves time

Remote video support that survives a technician's phone network

It works in the office and fails on cellular

The relay port answers but the allocation is refused

Video freezes when the technician walks to the van

ICE connects but no frame ever decodes

The tab says connected but nothing arrives

The check order that saves time

What breaks when you self-host a TURN server (coturn — symptom, cause, fix)

First: is TURN even your problem?

It says it started and is bound to nothing

Drive the canvas on a timer, not on `requestAnimationFrame`

3. `framesPerSecond` and resolution

4. `qualityLimitationReason` on the outbound side

5. `framesDecoded` versus `framesReceived`

Address 2: `external-ip`

Give coturn host networking, and then drop the `ports:` block