Diagnosing WoWonder WebRTC livestream issues on iOS

An iPhone livestream failure can appear to be one bug while involving several systems: Safari media policy, camera permissions, TLS, the WebRTC signaling path, STUN/TURN reachability, the media server, and the surrounding WoWonder customization.

Reproduce the exact failing path

Record the iOS and Safari version, network type, stream direction, page route, and whether publishing or playback fails. Compare the same account and stream on another browser before changing code. A permission denial needs a different fix from a failed ICE negotiation.

Turn “it does not work” into a failure stage

• Page setup: the livestream interface or required script does not load.
• Permission: Safari does not grant camera or microphone access.
• Capture: a local media stream is missing, silent or uses an unexpected device.
• Signaling: the browser and media server do not exchange session information.
• ICE: candidates are gathered but no usable network path is selected.
• Media: a connection exists but codecs, tracks or playback policy prevent useful output.
• Application state: WoWonder shows the wrong status or does not clean up the session.

Record a timestamp for the attempt and use it across Safari diagnostics, reverse-proxy access logs, Ant Media logs and WoWonder records. Without a shared time window, messages from unrelated sessions can look like the cause.

Check the browser and transport boundary

Confirm a secure origin, valid certificate chain, explicit user interaction where playback requires it, and correct camera and microphone permissions. Inspect WebRTC statistics and media-server logs together so candidate selection, codec negotiation, and disconnect timing can be correlated.

Secure context and media policy

Camera and microphone APIs require a secure context outside the limited local-development exceptions. Test the complete certificate chain on the actual hostname and check that no iframe or permissions policy blocks capture. iOS playback may require a user gesture, muted start or inline playback attributes depending on the workflow. A desktop autoplay success does not prove the iPhone path is valid.

Permissions can be denied for the site, restricted by device settings or unavailable because another lifecycle path stopped the track. Display a useful recovery instruction without repeatedly prompting. When retrying, stop old tracks and event handlers before acquiring another stream so the UI does not accumulate competing sessions.

Read ICE state as evidence

Gathering host candidates proves little across mobile or carrier networks. A working deployment generally needs appropriate STUN and TURN coverage, reachable UDP/TCP/TLS paths and credentials that remain valid for the session. Inspect the selected candidate pair rather than assuming TURN is used because it is configured.

If connection works on Wi-Fi but not mobile data, compare selected candidate types, protocol and address family. Test through a restrictive network you control. Do not disable firewall protections broadly; open only the documented media-server and TURN ranges and verify them externally.

Correlate signaling, ICE and codec negotiation

Capture the signaling response and the media server's view of the same stream ID. Check whether the offer and answer contain compatible audio and video codecs, whether tracks are actually enabled, and when the peer connection changes through new, checking, connected, disconnected or failed states.

A black video can be a codec or track problem even when ICE is connected. An immediate ICE failure points toward network or credential issues. A connection that succeeds and then degrades after the app moves to the background may be an expected mobile lifecycle constraint that requires reconnection and UI state restoration.

Use bounded WebRTC statistics

Sample getStats() during the failing attempt and record selected candidate type, round-trip time, bytes sent or received, packet loss, frames encoded or decoded and the active codec. Avoid high-frequency permanent logging on customer devices. A short opt-in diagnostic snapshot is usually enough to distinguish no network path, no outgoing media and playback decode failure.

Separate WoWonder state from media state

Verify that the application creates the expected stream/session record and that cleanup occurs after a failed attempt. A successful media connection can still look broken when stale application state, an incorrect endpoint, or a JavaScript lifecycle error prevents the interface from updating.

Review customization boundaries

Compare customized templates and JavaScript with the installed WoWonder release before copying a vendor patch. Confirm configuration values are generated into the page correctly, endpoints use the current hostname and protocol, and cache layers are not serving an old bundle. Search for duplicate listeners introduced by app-like navigation or modal reopen behavior.

At the database layer, inspect the intended live-session record, ownership, status and cleanup timestamp. Do not edit production records until the expected state machine is understood. A repair should make abandoned sessions expire predictably rather than hiding them with a one-time manual delete.

Ant Media and reverse-proxy checks

Verify the media application name, stream ID rules, WebSocket or HTTP signaling endpoint, TLS termination and proxy upgrade headers. Confirm the media server advertises addresses reachable by the device rather than a private interface. Time synchronization matters when tokens or signed playback URLs expire.

Resource saturation can resemble a client bug. Check CPU, memory, network, active streams, encoder behavior and server-side exceptions during the test. Compare one publisher and one viewer before scaling the scenario. If adaptive streaming or transcoding is enabled, confirm the output is actually produced and the iOS playback path points to it.

Monitor after the fix

Retest publishing, viewing, reconnection, background/foreground transitions, and more than one network. The useful outcome is not a single successful call; it is a repeatable path with enough logging to understand the next failure.

Regression matrix

1. Publish from a current iPhone on Wi-Fi and mobile data.
2. View from iOS Safari with sound off and then enabled through user interaction.
3. Deny and later restore camera or microphone permission.
4. Switch device orientation and available cameras where supported.
5. Background and foreground the browser, then confirm the UI and server converge.
6. Interrupt Wi-Fi, recover on another network and verify bounded reconnect behavior.
7. End the stream from publisher and server paths and confirm records and tracks are cleaned up.

Document the WoWonder version, customization commit, iOS range, Ant Media version and relevant proxy configuration with the fix. That record is more valuable than a vague note that “WebRTC was updated,” because it gives the next investigation a known working baseline.