IPTV-Check v3.1

CLI tool for validating M3U playlists and keeping only usable video streams — online and fast enough for their resolution.

What it does

1. Checks each stream is reachable (ffprobe / optional OCR).
2. Drops audio/radio streams ([AUX]).
3. For online video streams, measures real download throughput for N seconds (default 10).
4. Compares measured Mbps against a resolution threshold (from ffprobe, else name, else assume 720p).
5. Drops under-threshold streams ([SLOW]); keeps usable ones ([ON]).
6. Corrects mismatched quality tags in titles (ffprobe wins), e.g. CNN (720p) → CNN (1080p).

Requirements

External tools on PATH:

ffmpeg ffprobe yt-dlp

Optional for --ocr:

tesseract
pip install Pillow pytesseract

Python deps:

pip install -r requirements.txt

Config (iptv_checker_config.ini)

[Settings]
workers = 6
timeout = 10
throughput_seconds = 15
min_mbps_480p = 2.0
min_mbps_720p = 4.0
min_mbps_1080p = 6.5
min_mbps_1440p = 10.0
min_mbps_2160p = 18.0
headroom = 1.0
low_res_group = Low Res

• workers / timeout — CLI defaults for -w / -t (flags still override when passed).
• throughput_seconds — how long to sample each online stream (raise toward 20–30 for stricter sustained checks).
• min_mbps_* — minimum measured Mbps required per resolution tier.
• headroom — multiplier on those mins (e.g. 1.25 requires 25% more).
• low_res_group — group-title used for usable streams below 720p (replaces the source group).

Tip: With throughput filtering, many parallel workers share your uplink and can falsely mark streams [SLOW]. Prefer workers = 4–8 for accurate Mbps; use 20 when you care more about wall-clock speed than measurement fairness.

Usage

# Check a remote or local playlist
python3 iptv_check.py -f "http://example.com/playlist.m3u"
python3 iptv_check.py -f "/path/to/playlist.m3u" -o "my_checked_list.m3u"

# Re-check an existing output file
python3 iptv_check.py -r "my_checked_list.m3u"

# Check all playlists in the links database
python3 iptv_check.py -d

# workers/timeout come from config; override only when needed
python3 iptv_check.py -f "https://github.com/<URL>"
python3 iptv_check.py -f "playlist.m3u" -w 5 --ocr

CLI arguments

  -f, --file FILE       Path or URL to the M3U playlist
  -d, --database        Use default links database
  -r, --recheck FILE    Re-check an existing output file
  -o, --output FILE     Output file (default: updated.m3u)
  -w, --workers N       Parallel workers 1–20 (default from config)
  -t, --timeout N       Network timeout seconds (default from config)
  --log-format {name,url}
  --ocr                 OCR frame check (optional deps)
  --no-skip             Do not skip URLs already in the output file

Log status tags

Tag	Meaning
ON	Online and throughput meets threshold → written to output
SLOW	Online but Mbps too low for resolution → dropped
AUX	Audio-only → dropped
OFF …	Unreachable / probe failure

Notes

• Adaptive HLS is tested as-served (no variant switching).
• Throughput is only measured after the stream passes the online check.
• GUI mode was removed in v3.1; this is CLI-only.