Avatar fails to start in Firefox on Android — LiveKit PeerConnection cannot establish (mDNS-obfuscated host candidates)

[trainexuspd]

Summary

The LiveAvatar streaming session reliably fails to establish a media connection in Firefox on Android (tested with Firefox Stable 150.0 on a Pixel 7). The signaling WebSocket connects, the SDK fires SESSION_STREAM_READY, but no media frames arrive and the underlying LiveKit RTCPeerConnection enters an endless reconnect loop across regions.

Chrome on the same device, same network, same account works flawlessly.

Root Cause (verified)

Firefox enables media.peerconnection.ice.obfuscate_host_addresses = true by default (per draft-ietf-mmusic-mdns-ice-candidates). Local ICE host candidates are sent as random <uuid>.local mDNS hostnames instead of LAN IPs, as a privacy-preserving feature.

The LiveKit SFU you use does not appear to resolve these mDNS hostnames. As a result, no host-candidate pair becomes nominated. Because Firefox publishes only mDNS host candidates (no plain IPs), the SFU never sees a usable peer-reflexive or relay path that would replace them — the connection times out and the SDK rotates to the next region, failing identically there.

Reproduction

1. Open any LiveAvatar-powered session in Firefox Stable on Android (Pixel 7, FF 150).
2. Trigger session start.
3. Observe console (via Firefox Remote Debugging over USB):

GET wss://heygen-feapbkvq.livekit.cloud/rtc?... [101 Switching Protocols]
Initial connection failed with ConnectionError: could not establish pc connection. Retrying with another region: https://heygen-feapbkvq.ofrankfurt1b.production.livekit.cloud
GET wss://...ofrankfurt1b... [101 Switching Protocols]
Initial connection failed with ConnectionError: could not establish pc connection. Retrying with another region: https://heygen-feapbkvq.omarseille1b...
GET wss://...omarseille1b... [101 Switching Protocols]
Initial connection failed with ConnectionError: could not establish pc connection. Retrying with another region: https://heygen-feapbkvq.olondon1b...

The pattern repeats indefinitely. Attempted regions in this session: frankfurt1b → marseille1b → london1b, all identical.

Verification of root cause

In Firefox Nightly for Android, set media.peerconnection.ice.obfuscate_host_addresses = false via about:config and reload — the avatar starts immediately and runs stably. This isolates the failure to mDNS handling.

This is not a fix path for end users: Firefox Stable on Android does not expose about:config, so users cannot toggle this themselves.

Why the application can't work around this

SessionConfig in @heygen/liveavatar-web-sdk (v0.0.10) currently exposes only voiceChat and apiUrl. There is no way to pass an RTCConfiguration (e.g. iceTransportPolicy: 'relay' to force TURN), no way to pass LiveKit RoomOptions, and no way to opt out of host candidates — all of which would mitigate the issue from the client side.

Suggested fixes (in order of preference)

1. Server-side mDNS resolution in the LiveKit SFU. This is the canonical fix for the spec; many SFU vendors (e.g. mediasoup, Janus) have implemented it. Once mDNS candidates are resolved into IPs locally on the SFU side, ICE pairing succeeds normally for Firefox clients.
2. Server-side TURN-only fallback when only mDNS host candidates are advertised. Detect Firefox-style ICE candidate sets and force the client through TURN as a backup.
3. SDK-level escape hatch: allow the application to pass iceTransportPolicy: 'relay' (or full RTCConfiguration) into SessionConfig. This wouldn't fix the root cause but would let app developers ship their own mitigation.

Impact

In our user base (German higher education, oral exam practice), Firefox Mobile is a non-trivial slice of users. Currently we have to ship a UA-detected warning telling them to switch browsers — not great UX, and we'd much rather not have that warning at all.

Environment

• @heygen/liveavatar-web-sdk 0.0.10
• livekit-client 2.15.7 (bundled via the SDK)
• Pixel 7, Android 14
• Firefox Stable 150.0 (Android)
• Confirmed cross-region: Frankfurt, Marseille, London
• Confirmed network-independent: tested over WLAN, mobile hotspot, USB tether — same failure pattern

[trainexuspd]

Second, independent repro of the same SDK limitation — enterprise firewall, Chromium desktop

We've now hit the exact blocker described under "Why the application can't work around this" in a completely different scenario: no Firefox, no mDNS, no mobile. This suggests the missing escape hatch is a general gap rather than a Firefox-specific one, so I wanted to add the data here rather than open a duplicate.

The case

An enterprise customer on a managed corporate network (Chromium-based desktop browser) cannot start any avatar session. Console output:

Initial connection failed with ConnectionError: could not establish pc connection.
Retrying with another region: https://<project>.ofrankfurt1b.production.livekit.cloud
websocket closed · signal disconnected · reconnecting, attempt: 0 / 1
Received leave request while trying to (re)connect
skipping incoming track as it already ended

Identical failure signature to the Firefox case — signaling succeeds, media never establishes, the client rotates regions and fails identically in each.

What we could isolate:

Layer	Status	Evidence
DNS / HTTPS	works	region failover resolves and connects
WebSocket signaling	works	room IDs and participant IDs are assigned, so the signal connection is fully established
WebRTC PeerConnection	fails	could not establish pc connection

Root cause here is the network, not the browser: outbound UDP is blocked, and the TURN relay over TCP 443 offered by LiveKit Cloud does not get through either — consistent with an explicit HTTP proxy that only passes genuine HTTPS on 443 and drops TURN payload.

So: two unrelated root causes (mDNS obfuscation / blocked UDP), same dead end — the application has no way to influence ICE behaviour.

The fix is smaller than it may look

livekit-client already honours an application-supplied ICE configuration. From the shipped bundle (livekit-client.esm.mjs, makeRTCConfiguration()):

const rtcConfig = Object.assign({}, this.rtcConfig);
...
if (serverResponse.iceServers && !rtcConfig.iceServers) {   // ← only when NOT already provided

Server-provided ICE servers are applied only if the app hasn't supplied its own. RoomOptions.rtcConfig therefore takes precedence and already does the right thing.

The only thing standing in the way is the SDK: LiveAvatarSession constructs its Room with a hardcoded options object, so nothing can be passed through —

new Room({
  adaptiveStream: supportsAdaptiveStream() ? { pauseVideoInBackground: false } : false,
  dynacast: supportsDynacast(),
  videoCaptureDefaults: { resolution: VideoPresets.h720.resolution },
  ...
})

(The other new Room(options.roomOptions) in the bundle belongs to LiveKit's bundled ConnectionCheck class, not to LiveAvatarSession.)

So suggestion 3 in the original post appears to be a pass-through change rather than new functionality — livekit-client supports it today, LiveAvatarSession just doesn't forward it.

Concrete API request

new LiveAvatarSession(token, {
  voiceChat: false,
  // either of these would unblock both cases:
  rtcConfig: { iceServers: [...], iceTransportPolicy: 'relay' },
  // or, more generally:
  roomOptions: { rtcConfig: { ... } },
})

For our case this would let us route media through our own self-hosted coturn instance on EU infrastructure, which we already operate for a different WebRTC path in the same product and which is reachable on TCP 443. We'd only enable it for affected customers, precisely because replacing your distributed relays with a single-region one would be a regression for everyone else — which is also why a server-side option alone wouldn't fit our case as well as a client-side opt-in.

One correction on environment

Our tree resolves livekit-client 2.19.2 (bundled via @heygen/liveavatar-web-sdk 0.0.10), not 2.15.7 as stated in the original post. The makeRTCConfiguration() behaviour quoted above was read from 2.19.2, so the precedence logic still holds in the current release.

Workaround we're evaluating meanwhile

Patching the internal Room instance after construction but before start(). That reaches into SDK internals and we'd rather not ship it long-term — which is the whole reason for asking for the supported option.

Happy to test a pre-release build against both scenarios if that helps — we can reproduce the enterprise-network case on demand with the affected customer.