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. Start the test. 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

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 failures, so clients stop hitting it.
  • History retention — the tester keeps recent runs so you can compare before/after a config change.

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

The CLI wizard's "TV helper" mode includes a built-in 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.