Introduction

WebRTC dropouts in a realtime avatar kiosk are usually not “the avatar stopped talking” problems. They’re often transport problems: ICE selection changed, the tab got throttled, the encoder got starved, the remote track was interrupted, or the app’s state machine drifted out of sync with the media pipeline.

This post walks through how to debug those failures in a Svelte-based kiosk that renders a talking avatar over WebRTC. By the end, you should be able to distinguish signaling issues from media issues, instrument the right browser events, reproduce the dropout class you’re seeing, and decide whether the fix belongs in the client, the network, or the realtime service.

Start by separating signaling, media, and rendering

A lot of debugging time gets wasted because all “blank video” symptoms are treated as one bug. In practice, there are three distinct layers:

• Signaling: offer/answer exchange, session setup, ICE candidate negotiation.

• Media transport: the RTP/RTCP path once peers are connected, including packet loss, jitter, and bitrate adaptation.

• Rendering/app state: whether Svelte still has the right track reference, whether the DOM node is mounted, and whether the browser is actually painting frames.

When a kiosk “drops out,” log each layer separately. If signaling failed, you never had a stable connection. If signaling succeeded but media froze, you’re looking at transport or encode/decode issues. If media is still flowing but the UI is black, the bug is in your app or browser rendering path.

Instrument the browser before you change code

For browser-side WebRTC, the most useful debugging tool is the peer connection itself. In a kiosk, you want periodic snapshots of connection state plus a way to dump statistics when the video stalls.

const pc = peerConnection;

}

const pc = peerConnection;

}

const pc = peerConnection;

}

What to look for:

• iceConnectionState goes to disconnected or failed: path problem, STUN/TURN/firewall issue, or tab suspend/reconnect behavior.

• connectionState remains connected but video freezes: packet loss, encoder starvation, or the remote sender stopped producing frames.

• Stats show rising packetsLost or flat framesDecoded: transport degradation before a visible freeze.

• Track events fire again: renegotiation or stream replacement happened; your UI may still be pointing at the old track.

Understand the common kiosk-specific failure modes

Realtimes kiosks fail differently from normal user sessions because they’re long-lived, often unattended, and frequently deployed in locked-down browsers or embedded environments.

1. Browser throttling and lifecycle events

If your kiosk is in a background tab, hidden iframe, or aggressive power-saving environment, the browser may throttle timers, suspend media, or reduce decoding work. Svelte can keep the component mounted while the browser quietly stops doing useful work.

Handle visibility changes explicitly. If the page becomes hidden, don’t assume media will continue unchanged; if it becomes visible again, verify the track is still live and rebind the UI if needed.

document.addEventListener('visibilitychange', () => {
});

document.addEventListener('visibilitychange', () => {
});

document.addEventListener('visibilitychange', () => {
});

2. Track replacement without UI rebinding

In WebRTC, a remote track can be replaced or renegotiated without the high-level app flow making that obvious. If your Svelte component stores a single MediaStream and assumes it never changes, a new track may arrive while the old element remains attached.

Make the stream assignment explicit. When you receive a track, attach the current track or stream to the video element and update reactive state if the peer sends a replacement.

function attachTrack(track, videoEl) {
}

function attachTrack(track, videoEl) {
}

function attachTrack(track, videoEl) {
}

3. ICE restarts and transient network changes

Kiosk deployments often move between Wi-Fi networks, use captive portals, or sit behind enterprise firewalls. A short network interruption can trigger an ICE restart or a full reconnect. If your app doesn’t tolerate that state transition, the user sees a permanent freeze even though the session could have recovered.

Watch for brief transitions to disconnected. If the connection recovers, don’t tear the UI down immediately. If it stays failed, reconnect deliberately and make sure the remote avatar session is still valid.

4. Media starvation from the sending side

Sometimes the browser is healthy, but the remote side stopped encoding frames. That can happen if the voice pipeline stalled, the avatar service stopped generating video, or the media worker hit a resource limit. From the client’s point of view, the video just stops advancing while ICE remains fine.

That’s why stats matter. If packet reception stays flat but framesDecoded stops increasing, the sender likely isn’t producing new frames. If packets still arrive but decode stalls, look for a decode bottleneck or corrupted stream.

Build the Svelte kiosk so reconnects are first-class

The most reliable pattern is to treat the WebRTC session as disposable and the kiosk UI as stateful. In other words: the avatar view should survive connection resets, but the peer connection should be recreated when the transport genuinely breaks.

In Svelte, that usually means separating “session state” from “media element state.” Keep the current connection status in a store, but rebind the video element whenever a new remote track appears. Avoid overfitting the UI to a single initial track event.

A useful mental model is:

1. Create the connection.

2. Attach the first remote track.

3. Continuously observe stats and connection state.

4. If the connection recovers after a short interruption, keep the session.

5. If it fails hard, recreate the connection and reattach media.

Use logs that answer one question: where did the failure happen?

When you collect logs, don’t just print “connected” or “error.” Record a short timeline with timestamps and the relevant state transitions. That lets you answer whether the dropout happened before media started, during a renegotiation, or after the stream was already live.

A minimal log set for production kiosks:

• Peer connection state changes.

• First remote track received.

• Stats snapshot every 5–10 seconds.

• Visibility changes.

• Reconnect attempts and their result.

Once you have that, you can usually classify the bug in minutes instead of guessing at browser behavior.

Where Protoface fits

If your kiosk is showing a realtime avatar, the cleanest way to reduce moving parts is to let the avatar session live behind a managed realtime surface instead of wiring every media primitive yourself. For example, if you’re using a browser embed, the iframe model keeps API keys out of the client and avoids pushing session-management complexity into the kiosk app. If you’re driving the avatar from a voice agent, the LiveKit plugin path is the relevant integration surface; the repo and examples are worth skimming if you need to understand how track lifecycle and session binding work in practice.

For setup details, check the documentation and the GitHub organization for the integration you’re using. The point isn’t to outsource debugging, but to reduce the number of custom moving parts you have to reason about when a WebRTC session gets flaky.

Practical triage checklist

If you’re on call for a kiosk dropout, use this order:

• Confirm whether signaling completed.

• Check connectionState and iceConnectionState.

• Verify a remote video track exists and is attached to the current element.

• Inspect stats for packet loss, jitter, and flat frame counters.

• Check page visibility and browser lifecycle events.

• Reproduce on the same device, browser version, and network class.

That sequence will usually tell you whether you need a reconnect strategy, a UI reattachment fix, or a network workaround.

Conclusion

WebRTC dropouts in a Svelte avatar kiosk are rarely mysterious once you instrument the right layers. Distinguish signaling from transport from rendering, watch peer-connection state and stats, and design your UI so reconnects and track replacement are expected rather than exceptional.

If you’re building on a realtime avatar platform and want fewer custom media edges to debug, start with the relevant integration surface, verify your session lifecycle, and then harden the kiosk around browser lifecycle and reconnect behavior. For deeper implementation details and quickstarts, see docs.protoface.com.