Troubleshooting: video room and call quality — WebRTC, recording QC, and SIP dial-out

A video-quality complaint is different from a video room that never connects: the room opens, participants join, and then the experience is broken — the video freezes while audio carries on, one participant drops out, the recording lands flagged as degraded, or a PSTN dial-out into the room never bridges. None of those are fixed by re-creating the room. Each quality class maps to a specific layer — WebRTC media negotiation, the participant’s network path, the track publish grant, the recording pipeline, or the SIP dial-out leg — and this page works each one as a decision path. Video rooms run over WebRTC on Orbit Media, not over SIP RTP like a trunk call: media setup is ICE/STUN/TURN election instead of SDP address advertisement, and the dominant codec family is H.264/H.265 video rather than telephone audio. That makes the diagnosis paths different from Troubleshooting: voice call quality — read that page only for the PSTN leg of a dial-out, never for the in-room media. For the create/join/record contract itself, start with the Video channel page and the Video API reference.

Symptom → layer index

Find the symptom row first, then go to the section below that works that layer.

Symptom	Layer that causes it	Go to
Degraded-recording QC verdict — a `video.recording.degraded` webhook arrives, or a completed recording is silent, black, or truncated	Recording pipeline — the quality scorer flagged the artifact after the room ended	Recording QC verdicts
Participant loss — one participant freezes, drops, or their tile goes dark mid-room	The participant’s network path — ICE path decay, or a firewall blocking the SFU ports	Participant loss and buffer stalls
Buffer stall — video freezes in bursts, audio keeps flowing	Bandwidth floor — the uplink or downlink cannot hold the video bitrate the simulcast ladder selected	Participant loss and buffer stalls
No video but audio present — the participant speaks and their tile shows nothing	Track publish — the video track was never published, was blocked by the grant, or the endpoint has no usable camera	No video but audio present
Echo — one side hears itself, or the PSTN dial-in participant feeds the room back	Far-end device or the bridged PSTN leg reflecting the stream	Echo
SIP dial-out failure — `POST /:id/dial-out` fails or a `video.dial_out.failed` webhook arrives	The SIP dial-out leg — softswitch trunk rejection, busy/unreachable callee, or ring timeout	SIP dial-out failures

Cause map

Every symptom above reduces to one of these causes. Work the symptom row first; the sections below give the fix path per cause.

Cause	Produces	Fix section
NAT without a working relay — the participant sits behind NAT and no STUN/TURN path completes	Participant loss, buffer stalls, or a join that connects and immediately decays	Participant loss and buffer stalls
STUN/TURN/ICE failure — a corporate firewall blocks the SFU ports or the UDP media path, or a SIP ALG mangles WebRTC-adjacent traffic	Same as above, plus rooms that never connect on one network but work everywhere else	Participant loss and buffer stalls
Bandwidth floor unmet — sustained throughput below what the selected video layer needs	Buffer stalls, frozen tiles, the active-speaker view never settling	Participant loss and buffer stalls
Unsent or blocked video track — camera permission denied, publish disabled at join, or the grant tier disallows publishing	No video but audio present	No video but audio present
Endpoint capability — a handset or browser with no usable camera, or one that cannot encode the negotiated codec	No video but audio present; poor picture on that participant only	No video but audio present
H.264/H.265 codec mismatch on the SIP leg — the dialled-in endpoint negotiates a video codec it cannot actually render	Dial-out connects with audio only, or a `video.dial_out.failed` on codec negotiation	SIP dial-out failures
SIP trunk rejection on the dial-out leg — the callee is busy, unreachable, or the ring timeout fires before answer	`video.dial_out.failed`	SIP dial-out failures

Recording QC verdicts

Orbit scores every completed recording after the room ends. When the artifact lands — or fails to — with an ambiguous quality signal, a video.recording.degraded webhook fires alongside video.recording.completed:

{
  "type": "video.recording.degraded",
  "data": {
    "room_id": "vroom_abc123",
    "session_id": "vsess_abc123",
    "status": "degraded",
    "reasons": ["short_duration"],
    "recording_url": null
  }
}

status is "missing" when no usable artifact was produced at all and "degraded" when an artifact exists but is suspect. The scorer is deliberately pessimistic — it prefers a false alarm over a silent loss. Read the reasons array first; it maps directly onto the fix:

Reason code	What the scorer saw	Where the problem sits	What to do
`no_file_results`	The recording pipeline ended without writing any file	Recording pipeline, or the room never had a publishable stream to capture	Check whether any participant actually published — a room of receive-only viewers produces no recordable composite. If publishers existed, capture the room per the checklist below and escalate
`empty_location`	An artifact entry was reported but its location was empty	Recording pipeline write step	Escalate — the pipeline acknowledged the recording but did not finish the write; nothing on the tenant side changes that
`egress_status_failed`	The recording job itself reported a failure tag	Recording job — aborted, failed, or hit its limit	Check `recording_enabled` vs. room duration: a room that hits its duration ceiling mid-recording can abort the job. Re-test in a short room; if the verdict repeats on every room, escalate with the room id
`no_participants_joined`	The session recorded zero join events	Room usage — recording started on an empty room (an auto-record race or a guest who never joined)	Confirm anyone published. If your flow starts recording at room create, gate the start on the first `video.participant.joined` instead
`short_duration`	The recorded session was under five seconds	Room usage — recording toggled on and off before anything meaningful was captured (a stale auto-record, or a participant who bounced immediately)	Treat as benign when it matches a quick join-leave; investigate only when full-length meetings flag it

One structural rule from the table: no_participants_joined and short_duration are usually room-usage signals, not platform faults — the platform exactly reported what happened. The first three reasons are different: they mean the recording pipeline said it would produce a file and did not. Those are the escalate cases. The QC verdict is also persisted on the room: fetch the room and read recording_qc off the completed session to see exactly what fired, with its score time — you do not need the webhook receiver to be live to audit a past meeting.

Participant loss and buffer stalls

A participant freezes, drops, or their tile darkens mid-room — or the video stalls in bursts while audio carries on. WebRTC recovers continuously, so a video freeze with live audio is almost always the network path, not a broken client: the video layers get shed first. Work the decision path in order:

Is it one participant, or everyone? One participant’s network is the cause when the rest of the room stays clean. Read the live per-participant QoS telemetry before changing anything: video.participant.qos fires when a participant’s connection quality crosses into a degraded bucket mid-session, and the same data is readable on demand at GET /api/v1/video/connection-quality/:name/participants/:identity/stats — each sample carries quality_label (excellent/good/poor/lost), quality_score (0–5), rtt_ms, and jitter_ms. A participant pinned at poor or lost with rising RTT is a network problem; everyone in the room degrading together points at the shared path.
Does it only happen on one network? A room that is fine everywhere except one corporate network is the classic firewall signature: UDP media blocked, the STUN/TURN election never completes to a workable path, and ICE either falls back to a slow path or dies. The NAT glossary entry covers why real-time media needs a reachable address after translation. Two tenant-side fixes close nearly every case: disable SIP ALG on the site firewall (it rewrites media-address information “to help” and breaks WebRTC-adjacent flows the same way it breaks SIP RTP — the same fix the voice page calls out for one-way audio), and allow the SFU’s published TCP/TLS fallback port so the client can relay when UDP is blocked. Forcing relay through TURN is the deliberate, correct fallback — a working relay path beats a broken direct path every time.
Does it stall exactly when the picture is busiest? Then the bandwidth floor is unmet: the simulcast ladder picked a video layer the link cannot hold, the queue backs up, and the video freezes while audio (which needs a fraction of the bitrate) keeps flowing. No rejoin fixes an undersized uplink — the participant needs the link, or a smaller send profile. The QoS sample’s quality_score dropping in step with the stalls confirms this before any platform change.
Is an ICE policy pinned in your client? If you embed with your own LiveKit client configuration rather than the prebuilt embed, an over-restrictive ICE election policy (relay-only when no relay is reachable, or a pinned candidate family the network blocks) produces rooms that connect in the test lab and fail in the field. Correct the ICE election policy to let the client contest all candidate types; the prebuilt <orbit-video-room> element ships defaults that already do.

No video but audio present

The participant speaks, everyone hears them, and their tile shows nothing. Unlike a stall, this is a track problem: the video track was never published, or the endpoint cannot produce it.

Check	Finding	Fix
Did the join token grant publishing?	The participant joined as a `viewer` tier, the lobby held them (`lobby_downgraded: true` on the join response), or a waiting-room admit was never run	The token’s `permissions.can_publish` is the source of truth — read it off the join response, not the requested tier. Admit the participant, or mint a token with a publishing tier. See the grant tiers on the Video channel page
Did the browser get camera permission?	Permission denied, or the camera is claimed by another application	The endpoint must grant capture; no token change fixes a denied permission
Can the endpoint actually encode?	A handset or virtualized browser with no usable camera, or a device that cannot encode the negotiated H.264/H.265 profile	Test on a known-good device. A participant who can only join audio-first stays useful — the room degrades them gracefully
On a SIP dial-in/dial-out leg, did the callee negotiate video?	The SIP endpoint accepted audio-only, or negotiated a video codec it cannot render	Pin the outbound leg’s encode profile (`video_fps`, `video_width`, `video_height`, `video_bitrate_kbps` on the dial-out body) to something the far end actually supports — see the next section

Echo

One side hears itself returned a moment after speaking. Echo is almost never introduced mid-path: a far-end device (speakerphone, handset, headset) or the bridged PSTN leg is reflecting the stream, and the SFU is passing it through faithfully. The dialled-in PSTN participant is the highest-echo suspect — a phone on speaker in the room behaves exactly like the speakerphone case on the voice side. Isolate by changing one endpoint variable at a time — headset instead of speakerphone, a different dialled-in number — and escalate with the room evidence below when echo follows one specific destination or device.

SIP dial-out failures

POST /api/v1/video/rooms-scheduled/:id/dial-out originates a PSTN or SIP leg and bridges the callee into the room. The failures divide cleanly: the request fails synchronously (a 4xx/503 response — read the error code on the Video channel page), or the leg starts and then fails asynchronously, firing video.dial_out.failed:

{
  "type": "video.dial_out.failed",
  "data": {
    "room_id": "550e8400-e29b-41d4-a716-446655440000",
    "destination_type": "sip",
    "sip_headers": { "X-Ticket-Id": "zd-48213" },
    "emitted_at": "2026-07-07T12:30:00Z"
  }
}

The three production failure shapes, per the event reference:

Trunk rejection — the softswitch rejected the INVITE. Work it with Troubleshooting: SIP trunk registration, health, and failover: an unregistered or failing trunk rejects every dial-out that routes over it, and a H.264/H.265 mismatch on a type: "sip" destination surfaces here too — the far end declines the offered video profile. Pin the video_* encode fields to a profile the destination accepts instead of retrying the same offer.
Callee busy or unreachable — the destination never answers into a bridgeable state. Verify the number by calling it directly; a busy or dead destination is not a room problem.
Ring timeout before answer — the ringing_timeout_sec budget ran out. Auto-answer chains (IVRs, call queues, voicemail) routinely outlast a short budget; raise ringing_timeout_sec when the callee is expected to take time to reach a human. When the callee answers and the room then feels downstream congestion, throttle the outbound leg with the video_bitrate_kbps profile rather than redialling.

If your dial-out request carried sip_headers, the failure webhook echoes the same map back unchanged — correlate the failure against your own ticket or account id from the event alone.

What not to do

Do not restart partial recordings in a loop. When a degraded verdict arrives, restarting the recording on the same ended room gains nothing — the session is over and the media is gone. Read the reasons array against the QC table, fix the named cause, and let the next room record cleanly.
Do not re-create the room for a media problem. A new room id changes nothing about ICE election, the participant’s uplink, or a firewall — the same join lands in the same network. Diagnose the one participant’s QoS sample instead.
Do not keep redialling a failed SIP leg against the same trunk state. A trunk that is rejecting INVITEs rejects the tenth dial the same as the first; fix the trunk or the codec profile, then dial once.
Do not paste raw SDP/ICE dumps into a first ticket. Escalate to the SDP and ICE traces only when the platform-side checks above come back clean — the QoS sample, QC verdict, and checklist below resolve most reports without a packet-level dive.

What to send support

Work the relevant section first; if the symptom persists, open a ticket with the full set below — it is what lets support pull the exact room and session without a back-and-forth:

Your tenant / organization ID (Settings → Organization, or organizationId from GET /api/v1/me).
Room id (room_id from the room — or off any video.* webhook) and the server-side room_sid from the join response or the video.room.started/video.room.ended payload.
The broken window in UTC — when the room ran and when the symptom appeared, so the session and QoS samples line up.
The participant identity (identity from the join token) of the affected participant, and their last-known quality_label from the QoS telemetry if you captured it.
Whether a SIP dial-out is involved — and if so, the video.dial_out.failed payload (the echoed sip_headers included), the type (pstn or sip), and the destination you dialled.
For recording complaints, the full video.recording.degraded payload — status, the reasons array, and the session_id.

Reference

Troubleshooting: video room and call quality — WebRTC, recording QC, and SIP dial-out

Troubleshooting: video room and call quality — WebRTC, recording QC, and SIP dial-out

Symptom → layer index

Cause map

Recording QC verdicts

Participant loss and buffer stalls

No video but audio present

Echo

SIP dial-out failures

What not to do

What to send support

See also

​Troubleshooting: video room and call quality — WebRTC, recording QC, and SIP dial-out

​Symptom → layer index

​Cause map

​Recording QC verdicts

​Participant loss and buffer stalls

​No video but audio present

​Echo

​SIP dial-out failures

​What not to do

​What to send support

​See also

Troubleshooting: video room and call quality — WebRTC, recording QC, and SIP dial-out

Symptom → layer index

Cause map

Recording QC verdicts

Participant loss and buffer stalls

No video but audio present

Echo

SIP dial-out failures

What not to do

What to send support

See also