> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meet media quality

> How Tuturuuu Meet chooses simulcast layers, prioritises speech and screen share, and adapts to network and CPU limits in large rooms.

These rules apply to web Meet and Parley calls on Cloudflare Realtime SFU. They
cover both the browser publisher and subscriber and the `meet-realtime` room
server. Bitrate ceilings and congestion handling for the sender are described in
[Meet calls](https://docs.tuturuuu.com/platform/features/meet-calls.md#bandwidth-and-cost-attribution).

## Simulcast layers

Cameras publish three RID simulcast layers: `f` (full), `h` (half) and `q`
(quarter resolution). Cloudflare Realtime falls back between layers in ASCII
order, so the RIDs sort from highest to lowest quality. Under receiver
congestion, or when the publisher pauses its full layer, a subscriber steps
down one layer instead of jumping to the smallest.

Publishers from older clients advertise `h`/`m`/`l`. The room server records
whichever scheme an offer carries, and subscribers address both by semantic
layer: high, mid or low.

The room server advertises `ascii-simulcast` and `layer-update` in its `ready`
message. Without them, a client publishes `h`/`m`/`l`, requests only legacy
RIDs and sends no layer updates. A rollback to an older room server therefore
keeps every subscription valid.

A connected client keeps the capabilities from its last `ready`. An older room
server drops a request it cannot parse without a correlated reply. So if a
subscription that requested `f` or `q` times out under the same advertisement,
the client treats that room server as legacy until the next join advertises
capabilities again. Other failures never downgrade it.

### Choosing a layer per tile

Each subscriber requests the smallest layer that fills its tile:

| Rendered tile height (device px) | Layer |
| - | - |
| 400 or more | high |
| 200 to 399 | mid |
| Under 200 | low |

Heights are measured in device pixels, with the pixel ratio capped at 2 and
rounded to 40 px steps. A spotlit camera never drops below mid on size alone.

Before a tile is measured, the layer depends on the camera window:

| Before measurement | Layer |
| - | - |
| Spotlit camera | high |
| Window of nine or more cameras | low |
| Any other camera | mid |

Cameras on another grid page are not subscribed at all.

### Receiver congestion ceiling

A receiver-wide ceiling caps every tile's layer. Any one of these counts as
congestion:

* At least 6% inbound video loss.
* Two new freezes in one 2-second sample.
* A round-trip time of 700 ms or more.
* A saturated receive estimate.

Congestion lowers the ceiling one layer at once, with a 4-second cooldown.
Recovery raises it one layer after five healthy samples (10 seconds). A recovery
that meets congestion within 15 seconds doubles the healthy run needed next
time, once per failed probe and up to 40 samples. Missing statistics never
upgrade.

Per tile, a downgrade applies immediately. An upgrade waits until it has been
wanted for two consecutive samples.

### Layer updates

Layer changes use the SFU's `PUT /sessions/{id}/tracks/update`, which needs no
renegotiation. They run in the same client queue as subscribe, close and
renegotiate, so a change never lands between a subscription's offer and its
answer. Each change is checked against the live receiver just before it is
sent. Only layers the SFU confirmed per MID are cached for the current receiving
peer.

The room server accepts a change only when all of these hold:

* The receiver MID belongs to the requesting socket's own session.
* The target is a current camera publication from another participant.
* That publication advertised the requested RID.
* The receiver has sent no more than 40 update batches in the past minute. The
  limit is charged once when the request arrives, before any provider call.
  Requests over it are refused without a durable write.

A receiver can therefore only re-layer a camera it could already subscribe to.
The client also checks that each receiver still carries the publication the
change was planned for. The SFU's track update can retarget a transceiver to
another publication. A modified client could use that only to show a camera it
may already watch in a different tile, so it crosses no permission boundary.

Layer switches never rewrite the durable room snapshot more than once every 15
seconds. If the Durable Object is evicted, the time accounting lost is bounded
by that interval. A switch that also changes tracks, presence, settings,
attendance or the room lifecycle is always persisted. That includes the
empty-room timer that starts when the last socket closes.

A rejected or failed update keeps the current layers and retries after 30
seconds. Only a matching per-MID success is cached. A plan made for one
visibility phase is discarded if the phase changes before it is sent. If the SFU
asks for immediate renegotiation after an update, the client rebuilds the
receiving peer. It then stops layer switching until a fresh join, so rebuilt
peers are not torn down again.

New subscriptions also start at or below the receiver's congestion ceiling. A
receiver that has just recovered from congestion therefore never reopens a
camera above the layer its link could carry. A rebuilt receiving peer inherits
that ceiling and must earn any upgrade with fresh healthy samples.

## Thumbnail mode

In thumbnail mode, every camera outside the spotlight is received on the lowest
layer. Publishers who have not spoken in the last 20 seconds also stop sending
their full layer. A recent speaker, the one most likely to be spotlit, keeps it.
Speech is measured from the microphone sender's own source; shared audio never
counts. A live microphone the browser does not measure keeps the full layer.
Audio and screen share are unaffected.

| Setting | Behaviour |
| - | - |
| Automatic (default) | On in rooms of 25 or more participants, and on a receiver whose congestion ceiling has reached the lowest layer |
| On | Always on |
| Off | Never on |

Participants choose the setting under **Settings → Media**. Each device
remembers its own choice. Network and CPU limits still apply on top of it.

## Audio-only fallback

When cameras stay congested for three consecutive samples after every one is
confirmed on the lowest layer, the receiver closes camera subscriptions. Speech, screen share and screen audio
continue. The stage shows that video is paused, with a control to resume it.

With no camera to measure, recovery is a timed probe on the lowest layer after
30 seconds. A probe that relapses within 30 seconds doubles the next pause, up
to four minutes. Resuming manually starts a fresh probe. The pause belongs to
the link rather than the receiving peer, so it and its probe deadline survive
a receiver rebuild. The probe runs even when no receiver exists, because
closing every camera can leave nothing to subscribe to.

## Hidden tab

Hiding the Meet tab lowers remote video in two steps. A Picture-in-Picture view
counts as visible.

| Hidden for | Remote video |
| - | - |
| 1.5 seconds | Every camera on its lowest layer, including the spotlight. Receiver stats sampling and speaker ordering pause. |
| 20 seconds | Camera and screen-share video subscriptions are closed. All remote audio, including screen audio, keeps playing. |

Returning to the tab applies at once. Subscriptions reopen immediately from the
current stage, even when a background close is still in flight, and layers
return without upgrade hysteresis. A quick tab switch therefore never closes
anything.

Opening or closing Picture-in-Picture while hidden is reconciled immediately.
This covers the standard, WebKit presentation-mode and document
Picture-in-Picture events. WebKit's per-video `webkitPresentationMode` is read
directly. Phases are derived from wall time, so a page the
browser suspended lands in the right phase when it resumes. iOS may suspend a
hidden page entirely, so its thresholds are best effort.

Visibility changes never change what this device sends. Only a thumbnail
preference change refreshes the publisher.

The participant's own camera, microphone and screen share keep publishing,
including a share of another tab. Under CPU pressure the existing CPU
adaptation lowers the send frame rate.

## Sender priority and screen share

Microphone senders carry high send and network priority, screen share and screen
audio carry medium priority, and cameras carry low priority. Browsers treat
these as allocation hints. Chromium and WebKit honour both fields; Firefox
exposes only `priority`.

Cameras hint `motion`, screens `detail`, speech `speech`, and screen audio
`music`. Screen senders prefer `maintain-resolution`, which the bandwidth
watcher applies after negotiation, so text stays legible while the frame rate
drops.

## Speech resilience

The publisher sets Opus in-band FEC on every audio section of the SFU's answer,
so a receiver can rebuild a lost frame from the next packet. Microphones,
identified by their `speech` hint, also get DTX, which sends almost nothing
during silence. Screen audio always has DTX off, so quiet passages of shared
media are not gated. Each audio section is rewritten on its own, because payload
numbers are scoped per media section.

## CPU adaptation

CPU adaptation depends on the browser reporting `qualityLimitationReason`.
Chromium and WebKit do; Firefox does not. When any active video encoder reports
`cpu`, the publisher sheds load at once:

* The camera drops its full layer and caps its frame rate at 15 fps.
* A single-encoding camera halves its resolution.
* A screen keeps its resolution and drops to 5 fps.

Only samples where every encoder reports `none` count toward recovery.
`bandwidth` and missing reports are neutral. Samples count at most every
2.5 seconds, so refreshes cannot rush recovery.

Recovery needs ten clean samples. That run doubles, up to 80 samples, when the
limit returns within a minute of recovering, and it resets after ten quiet
minutes.

## Stream quality by plan

Each participant's stream ceilings follow their own account plan:

| Plan | Camera | Screen share |
| - | - | - |
| Free, including guests | 720p · 24 fps · 0.9 Mbps | 720p · 15 fps · 1.8 Mbps |
| Plus, Pro and Enterprise | 1080p · 30 fps · 2.5 Mbps | 1440p · 60 fps · 6 Mbps |

The table is `MEET_STREAM_TIERS` in `packages/realtime/src/meet/stream-tiers.ts`.
Free allows HD resolution at a low frame rate.

The server resolves the plan when it issues the join token and signs the
ceilings into the token. A failed plan lookup falls back to free, and a guest
is always free. A token whose ceilings were altered fails signature
verification and is refused. The room server echoes the signed ceilings in
`ready` as `streamLimits`, and clients take them only from there.

The publisher clamps every encoding to its ceiling, from the first offer
onwards:

* A larger capture is downscaled to the height cap.
* Total bitrate is scaled down proportionally across simulcast layers.
* Frame rate is capped.

Ceilings never raise a limit that network or CPU adaptation already lowered,
and thumbnail mode still applies. Higher ceilings mainly benefit a spotlit
camera or a shared screen.

These are signed caps that the client applies, and the server only advises.
The SFU cannot enforce per-track resolution or bitrate. Beyond the client, the
room server detects drift:

* Each media health report carries the send rate and the largest active camera
  and screen send height and frame rate.
* The room server compares them with the signed ceilings. It allows 5% plus
  16 px of height, 3 fps, and a quarter of bitrate overshoot above the camera,
  screen and audio allowance.
* A publisher over its ceilings is counted under **Over plan limits** in room
  media health.
* When a publisher first drifts over, the reporting socket receives
  `stream.limits` as a reply, so an honest client clamps again. That reply
  needs no extra durable write.

A modified client can still send more than its plan, and misreport its stats.
Stopping that would need SFU-side per-track caps, which Cloudflare Realtime
does not offer.

The automatic budget uses the same targets on every plan: up to 1.4 Mbps and
24 fps for a spotlit camera, and 1.8 Mbps at 15 fps for a screen share. In the
current release, a paid plan therefore changes these things:

* A spotlit or higher-quality camera may use up to 1.4 Mbps, where the free
  ceiling holds it at 0.9 Mbps.
* A screen share is sent at its captured size up to 1440p, where a free one is
  downscaled to 720p.
* A camera track the browser delivers above 720p is sent at up to 1080p,
  where a free one is downscaled to 720p. The camera only requests 720p, so
  this applies only when the browser supplies more.

The higher paid frame rates, and bitrates beyond those targets, are headroom
for an upcoming stream quality picker. They are not reached automatically. The camera requests a 720p capture, an `ideal` constraint that
the browser may not meet.

The plan applies only to the web call for now. Mobile join tokens carry the
free ceilings, and the native publisher does not yet apply them.

The participant's plan is looked up alongside the host's meeting duration.
The lookup is bounded to two seconds and falls back to free.

## Media health diagnostics

Every device sends a `media.quality` report to the room every 30 seconds. It
holds counters and rates only, and never track IDs, addresses, SDP, names or
tokens:

* Send rate, available send estimate and camera receive rate.
* Round-trip time.
* Inbound and outbound loss.
* New freezes.
* How many tiles use each requested layer.
* Active send layers.
* CPU limitation, audio-only, thumbnail mode and visibility phase.

The numbers come from the publisher and subscriber loops above, so reporting
adds no `getStats()` call.

The room keeps the latest report per participant, at most 150, and drops
reports older than two minutes. Each device's reports beyond four a minute are
dropped before room processing. Manager reads are limited to ten a minute, and
excess reads get a correlated refusal.

Layer switches, reports, reads and refusals change only time accounting and
diagnostics. Together they cause at most one durable snapshot write every 15
seconds, and a refusal made at admission never causes one. Any other change to
room state is always persisted.

A camera that is not being measured reports no receive rate, loss or layers.
That covers a hidden tab, an audio-only pause and a receiver with no cameras.
Every reading also expires six seconds after it was last measured, so a closed
publisher or receiver never repeats an old value. A sample that resolves after
its receiver, session or camera set changed is discarded.

Participants who can manage the room see an anonymous room aggregate under
**Settings → Connection**. That includes the host, but not a classroom co-host
without participant management:

* Send and receive p50/p95.
* Devices measuring cameras, which the receive rates count.
* Devices measuring freezes: those whose browser also reports freeze counters.
  The freeze rate counts only these, and divides by the time each device
  actually measured, not by its report interval.
* Devices over plan limits.
* Loss and round-trip p95.
* Freezes per device-minute.
* Layer counts.
* Counts of CPU-limited, audio-only, hidden and thumbnail devices.

Other participants are refused. Load tests can read a device's latest numbers
from `globalThis.__meetMediaStats`.

The in-call connection diagnostics poll every 5 seconds while others are in the
room and every 15 seconds otherwise. Browsers pause this poll in a hidden tab.

## Device kill switches

Support can turn a behaviour off on one device. Set the browser storage key
`tumeet:media-flags` to a JSON object such as `{"layerSwitching":false}`.

| Flag | Turns off |
| - | - |
| `layerSwitching` | Layer switching |
| `opusDtx` | DTX, sent as `usedtx=0` |
| `cpuAdaptation` | CPU adaptation, clearing any active cap |
| `hiddenTabSaver` | Hidden-tab saving |

Denied or unreadable storage falls back to the shipped defaults.

## Known gaps

* The SFU gives publishers no feedback about which layers are subscribed.
  Publishers therefore pause the full layer from their own bandwidth and CPU
  budget rather than from audience demand.
* Cloudflare Realtime documents RID simulcast only. It has no SVC
  `scalabilityMode`.
* While a deployment rolls out, an older subscriber can misread a newer
  publisher's `h` as its high layer and receive half resolution in the
  spotlight until it reloads.
* DTX with the hosted SFU still needs live verification of silent joins and of
  mute and unmute across the SFU's 30-second inactivity timeout, including on
  iOS Safari.

## Regression coverage

* `packages/meet-core/src/features/call/lib/layer-policy.test.ts`
* `media-policy.test.ts`
* `media-health.test.ts`
* `packages/realtime/src/meet/room-media-quality.test.ts`
* `packages/realtime/src/meet/stream-tiers.test.ts`
* `stream-entitlement.test.ts`
* `subscriber-layers.test.tsx`
* `negotiation.test.ts`
* `sender-profile.test.ts`
* `bandwidth.test.ts`
* `packages/realtime/src/meet/simulcast-layers.test.ts`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.