← Lighthouse Briefings · analysis · 2026-06-25
analysis VoIP SDK · In-Call UX part2

VoIP In-Call User Notification Spec · v2

Real-time SDK-based quality detection with targeted, actionable user prompts during active calls. Peer-side issues inferred by elimination.
Design principle. Only surface problems the user can act on or needs to understand. Problems the user cannot perceive or act upon are suppressed. Similar issues are merged; no alert repeats within 30 seconds.

01 Action Prompts — user can act immediately

These alerts offer a clear user action. Delivered as dismissible banners.

ID Trigger condition User-facing message Suggested action Fire timing
T01 VPN active on device during call — VPN adds routing hops and encryption overhead, increasing latency and packet loss "VPN connection detected — this may affect call quality" Disconnect VPN On detection; may fire multiple times per call
T02 Local microphone initialisation failed — other party cannot hear any audio "Your microphone isn't working — the other party can't hear you" — On mic init failure only; fires once per call
T03 Local camera initialisation failed — other party sees no video "Your camera isn't working — the other party can't see you" — On camera init failure only; fires once per call
T05 Playback volume critically low (< threshold) — user can barely hear the other party "Volume too low — you may not be able to hear the other party" Increase system playback volume Checked at audio playback start; fires once per call

02 Informational Prompts — user needs context

These alerts explain what is happening so the user is not confused, even if they cannot fully resolve it.

Local network issues

ID Trigger condition User-facing message Suggested action Fire timing
T10 Local uplink packet loss > 5% or network quality score ≤ 2 — other party receives incomplete audio/video "Your network is unstable — the other party may not hear you clearly" Switch to a stronger Wi-Fi or move to better signal May fire multiple times per call
T11 Local downlink packet loss > 5% or network quality score ≤ 2 — received audio/video is incomplete, causing choppy playback "Unstable network — audio or video may be choppy" Switch to a stronger Wi-Fi May fire multiple times per call
T12 End-to-end RTT > 300 ms — noticeable conversation delay, risk of talking over each other "High call latency — conversation may feel out of sync" — (cross-region distance; may try disabling VPN) May fire multiple times per call
T22 Network type switched more than 3 times in one call — each switch causes a brief interruption and reconnect "Network is switching frequently — call quality may be unstable" Stay on one network (Wi-Fi or cellular) Once per call
T23 Video call over cellular data — video consumes ~3–5 MB/min "Using mobile data for video — this may consume significant data" Switch to Wi-Fi On call start over cellular, or on switch from Wi-Fi to cellular; once per call

Connection interruption

SDK Note. T15 and T16 already have a dedicated in-call UI indicator. Recommend not triggering an additional callback — the existing UI covers these states.
ID Trigger condition User-facing message Suggested action Fire timing
T15 Network connection dropped for > 10 seconds — SDK attempting to reconnect "Connection lost — trying to restore…" Wait for auto-recovery; if persistent, hang up and redial May fire multiple times per call
T16 Reconnect attempts still failing after 30 seconds — connection unlikely to self-recover "Failed to restore connection — try hanging up and calling again" Hang up and redial Once per call

SDK auto-handling

SDK Note. T21 involves no user action. Since the user cannot influence the outcome, recommend not triggering a callback — it adds noise without value.
ID Trigger condition User-facing message Suggested action Fire timing
T21 SDK proactively reduced video encoding quality (resolution / frame rate) due to bandwidth or CPU constraint — call remains connected "Poor network — switched to smooth mode automatically" None (SDK handles automatically) Triggered when resolution ≤ 240p; may fire multiple times per call

Peer-side issues — inferred by elimination

Inference logic. During a call, the SDK has no direct access to the peer's data. Peer issues are inferred by the rule: local network normal + anomalous experience = peer-side problem.
SDK Note. T17 and T19 share a very similar user signal ("other party sounds choppy / disconnected"). Recommend merging into a single prompt to reduce repetition.
ID Trigger condition User-facing message Suggested action Fire timing
T17 Local network normal, uplink normal, but no data received from peer for > 3 seconds — inferred: peer disconnected "The other party may have a network issue" Wait May fire multiple times per call
T19 Local network good (network_state ≥ 4), uplink loss normal, but downlink receive loss high (> 15%) — inferred: problem on peer's send side "The other party's network may be unstable — audio may be choppy" None (peer-side issue) May fire multiple times per call

Elimination logic reference

Prompt User perception Local signal Inference
T17 Suddenly can't hear / see peer network_state normal, send_loss_avg normal, but receive drops to 0 My network is fine + I'm receiving nothing → peer disconnected
T19 Peer audio choppy / video frozen receive_loss_avg high, but send_loss_avg normal and network_state ≥ 4 My network is good + receive quality poor → problem on peer's send side

03 Not Notified

These conditions are detected internally but produce no user-visible alert.

Condition Reason for suppression
Server-to-server packet lossUser cannot act; infrastructure issue
High CPU usageSDK auto-degrades (covered by T21); no direct user action
Low memoryNo direct user action available
Low-end deviceHardware constraint; cannot be changed
Video encode / decode latencySDK internal; user has no awareness or control
Encoder fallbackSDK handles automatically; T21 covers the user-visible outcome
FEC recovery failureTechnical detail; user cannot interpret or act
Poor peer device performancePeer-side issue; local user cannot act
Suboptimal media server selectionInfrastructure issue
Slow ICE establishmentAlready reflected in first-frame time metric; no additional action
Server timeout disconnectCall already ended; no opportunity to notify

04 Priority & Merge Rules

Priority tiers (high → low)

Priority Prompts Description
P0 T15 / T16 Connection interrupted / reconnect failed — call is unavailable or about to fail
P1 T02 / T03 Device capture failure — call missing a core function
P2 T05 / T10 / T11 Volume too low / uplink or downlink packet loss — call quality or function degraded
P3 T12 / T22 / T23 High latency / frequent network switching / cellular video — network status awareness
P4 T01 / T21 VPN warning / video downgrade notice — preventive or informational
P5 T17 / T19 Peer network issue (inferred) — informational only, no user action possible

Merge rules

Simultaneous triggers Merged message
T10 + T11 (uplink + downlink loss) "Your network is unstable — call quality may be affected"

Suppression rules