Quality / Stream Health

Quality / Stream Health measures the client-to-server connection quality. The panel runs a download/upload bandwidth test plus latency and jitter against the server, then distils the result into a green / amber / red traffic light (green = optimal, amber = fair, red = poor) graded against configurable thresholds.

Plugin id	quality
Category	tool
UI slot	panel
Needs worker	No

The test runs client-side. The configSchema is the server-side source of truth for the thresholds the tenant persists per app; the web panel mirrors the same keys/defaults so the traffic light classifies even before the backend responds.

Configuration

Field	Type	Default	Description
green_min_mbps	number	5	At or above this download speed (Mbps) the light is green (optimal). Min 0, max 10000.
yellow_min_mbps	number	1	Between this and the green threshold the light is amber; below it, red. Min 0, max 10000.
target_bitrate_kbps	number	2500	Expected stream bitrate (kbps). Measured reception bitrate is graded against it (green ≥ target, amber ≥ half). Min 0, max 100000.
max_green_rtt_ms	number	120	Round-trip time (and derived jitter) at or below this (ms) stays green. Min 0, max 10000.
download_url	string	/apple-touch-icon.png	Same-origin asset re-fetched (cache-busted) to measure download throughput. Point at a larger static file for steadier numbers.
download_target_mb	number	6	Total bytes (MB) to pull before computing the download speed. Min 1, max 200.
upload_url	string	`` (empty)	Optional endpoint that ACCEPTS a POST body (e.g. an S3 presigned URL). Leave blank to skip the upload leg — a browser-only test cannot measure upload without a server that reads the body.

Enable and configure

Dashboard: open the app’s Plugins tab → Install Quality / Stream Health → toggle Active → Configure to tune the thresholds.

API:

curl -X PATCH https://YOUR-DOMAIN/api/v1/apps/live/plugins/quality \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "config": {"green_min_mbps": 8, "target_bitrate_kbps": 3500}}'

Tip

The traffic light is a diagnostic aid for operators/viewers checking whether their connection can sustain the target bitrate — the upload leg is skipped unless you provide an upload_url that reads the POST body.