Skip to content

Stream Health Tests

The stream tester probes channels asynchronously and reports back what's playable, what's flaky, and what's broken — before your users notice.

What it tests

Protocol How it's detected What's probed
HLS .m3u8 extension / application/vnd.apple.mpegurl Manifest parse, resolution extraction, bandwidth, codec hints
MPEG-TS .ts extension / TS payload sniff Container parsing (PAT/PMT), resolution extraction, codec hints
MP4 .mp4 extension Container parsing (moov), resolution extraction, codec hints
Matroska .mkv, .webm Container parsing (EBML), resolution extraction, codec hints

Detection logic lives in stream_protocol.go and uses fast, allocation-light comparisons — running a sweep against a large catalog is practical.

Shallow Probing Constraint

To keep tests fast and practical across large catalogs, the stream tester performs shallow metadata extraction. It fetches up to 512KB of the stream URL to verify the initial 2xx HTTP status and parse container headers. It does not perform deep stream integrity checks (such as HLS segment reachability, sync-byte alignment, or packet payload integrity). A passing test means the stream is online and valid at the container level, not that its deeper contents are uncorrupted.

When to run it

  • After importing channels from iptv-org.
  • After enabling WireGuard egress on a proxy — confirms the tunnel actually reaches your upstreams.
  • After enabling MediaFlow — verifies the bridge handles your stream mix.
  • On a recurring schedule, to catch upstream rot without manual sampling.

Run a sweep from the dashboard

Stream health tests

  1. Open the proxy or Xtream service.
  2. Choose Stream Health Tests.
  3. Pick the scope: all channels, one category, or one channel.
  4. Create the test. It is created and waits: the summary shows how many streams it holds and the least time Start will take (it requests every stream, no faster than one every 0.5 s, so 5,000 streams take at least 42 minutes). Press Start, or tick Start immediately to skip the pause. Progress and per-stream results stream in live.

Each completed probe records:

  • HTTP status of the stream URL
  • Detected protocol and basic metadata (resolution, bandwidth, codecs when available)
  • Round-trip time
  • Pass / fail verdict against your thresholds

The JSON and CSV buttons download the report of the selected test. Stream addresses and error messages in it have the provider's password in them replaced with dots, so the file can be attached to a bug report.

Configurable behavior

  • Timeout — how long to wait per probe before declaring failure.
  • Retry on client error — re-probe once on a transient 4xx/5xx.
  • Auto-disable after N failures — flip channel.enabled to false in the underlying Xtream service after N consecutive failed checks, so clients stop hitting it. A run checks each stream once, so the failures are counted across runs (in memory, until tunlx restarts): a passing check starts the count again, and so does disabling the stream. The dashboard's Disable failures switch is off by default and uses N = 3: the third run in a row in which a stream fails disables it, and one bad moment at the provider takes nothing out. Set autoDisableAfter to another number over the API; 1 disables on the first failure, which a short provider outage can turn into an empty lineup.
  • History retention — the tester keeps recent runs so you can compare before/after a config change. Clear History removes them, and the bulk Enable and Disable buttons act on the selected streams, after asking you to confirm.

Endpoints (Advanced UI / scripting):

Method Path Purpose
GET /xtreme-service/tests List running and recent tests
GET /xtreme-service/tests/history Past results
GET /xtreme-service/tests/{testID} Status of a specific test
POST /xtreme-service/tests/{testID} Pause / resume / stop

See Architecture for where the tester sits in the request pipeline.

Composite catalogs

When testing a composite proxy, tunlx automatically routes each test through the originating standard proxy for that stream — so egress mode, MediaFlow, and credentials match a real client request.

Wizard-driven testing

Both setup wizards (the dashboard's service wizard and the CLI one) include a pass that probes a sample of the imported channels and tells you up-front which ones to drop.

Wizard — select test channels

Workflow tips

  • Run a small sample first. A 20-channel sweep tells you fast whether routing/credentials are correct before you fire a 2,000-channel sweep.
  • Pair with auto-disable. Manual triage doesn't scale on large catalogs; let the tester do the first pass.
  • Re-run after every routing change. Switching a proxy from system to vpn can break access patterns you didn't anticipate.