mirror of
https://github.com/Vateron-Media/XC_VM.git
synced 2026-10-05 04:02:31 +02:00
Divarion_D
175198a902
Consolidate the two stream-check tools into a single master script with three subcommands: - check <url> verify one stream (or --live dashboard) - playlist <path|url> batch an .m3u list -> aggregate JSON (+ per-stream files) - graph <inputs...> render the JSON as SVG charts Shared helpers (HTTP, slugify, m3u/JSON handling) are now defined once. The old --playlist flag becomes the `playlist` subcommand and the bare-URL form becomes `check <url>`; the streamtest harness is updated accordingly. Also fix the per-stream SVG rendering black in viewers that do not support 8-digit #rrggbbaa hex: the bitrate area fill and not-PLAYING bands now use 6-digit hex plus a separate fill-opacity attribute. Docs (English + tools READMEs + STREAMTEST) updated to the new invocation. Removes stream_queue_check.py and stream_graph.py.
86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
# Stream check tool
|
|
|
|
A single dependency-free (pure Python 3 stdlib) tool to **verify** a live
|
|
stream's delivery and **visualise** the result. No ffmpeg/ffprobe needed — it
|
|
parses the bytes itself.
|
|
|
|
```text
|
|
tools/stream-check/
|
|
├── stream_check.py # verify a stream / playlist → JSON, and render JSON → SVG
|
|
└── README.md
|
|
```
|
|
|
|
Everything lives in one master script with three subcommands:
|
|
|
|
- **`check`** — verify one stream (or watch it live) → human/JSON report.
|
|
- **`playlist`** — test every stream in an `.m3u` channel list → aggregate JSON (+ per-stream files).
|
|
- **`graph`** — render the JSON from `check`/`playlist` as static SVG charts.
|
|
|
|
It pairs with `tools/test-stream-generator/` (a test source) and the e2e
|
|
harness in `tools/test-install/` (see `tools/test-install/STREAMTEST.md`).
|
|
|
|
## What it checks
|
|
|
|
Two independent queues are checked, depending on the stream type (auto-detected):
|
|
|
|
- **HLS** (`.m3u8`): media-playlist segment queue — `EXT-X-MEDIA-SEQUENCE` must
|
|
advance contiguously, no `EXT-X-DISCONTINUITY`, every new segment downloadable.
|
|
- **MPEG-TS** (`.ts`, e.g. an XC_VM `/play/<token>/ts`): per-PID
|
|
`continuity_counter`, sync loss and delivery stalls.
|
|
|
|
Health is judged per mode — TS fails on a delivery stall, HLS fails on real
|
|
buffer starvation (rebuffers), because HLS segment length is often intentionally
|
|
variable.
|
|
|
|
> **Quote URLs** that contain `&` (e.g. `…?output=hls&key=live`) — otherwise the
|
|
> shell splits the command on `&` and backgrounds it.
|
|
|
|
## `check` — single-stream checker
|
|
|
|
```bash
|
|
# one stream → report (exit 0 healthy / 2 problem)
|
|
python3 tools/stream-check/stream_check.py check 'http://host/stream.ts' --duration 120 --json
|
|
python3 tools/stream-check/stream_check.py check 'http://host/stream.m3u8' --live # ANSI dashboard
|
|
```
|
|
|
|
Key options: `--duration` (default 30), `--tolerance` (transient CC/sync breaks
|
|
allowed), `--stall-timeout` (TS), `--json`, `--live` (+ `--prebuffer`,
|
|
`--buffer-target`, `--no-color`). Run `check -h` for the full list.
|
|
|
|
Exit code: `0` healthy, `2` a queue/delivery problem, `1` usage error.
|
|
|
|
## `playlist` — batch checker
|
|
|
|
```bash
|
|
# a whole .m3u playlist → aggregate JSON (+ per-stream files)
|
|
python3 tools/stream-check/stream_check.py playlist 'url_or_path.m3u' --out-dir logs/
|
|
```
|
|
|
|
Tests each stream for `--duration` seconds (default 120), emits one JSON document
|
|
with a per-stream verdict and a per-second time-series ("the graph as JSON").
|
|
`--out-dir` also writes a separate `<NN>-<name>.json` per stream as it finishes.
|
|
Other options: `--tolerance`, `--stall-timeout`, `--prebuffer`, `--ua`.
|
|
|
|
An interactive terminal gets a short summary; redirected/piped stdout gets the
|
|
full JSON. Exit code: `0` all healthy, `2` a stream failed, `1` usage error.
|
|
|
|
## `graph` — static SVG charts
|
|
|
|
Turns the checker's JSON (per-stream files or an aggregate report) into
|
|
standalone **SVG** images for eyeballing and side-by-side comparison — throughput
|
|
over time, buffered-seconds curve, non-PLAYING bands, queue-break marks, and an
|
|
OK/FAIL header. `--combined` overlays every stream's bitrate on one chart with a
|
|
unique colour per stream.
|
|
|
|
```bash
|
|
# a folder of per-stream logs, plus a combined comparison
|
|
python3 tools/stream-check/stream_check.py graph logs/ --combined --out-dir graphs/
|
|
|
|
# individual files / an aggregate report (mix freely; duplicates de-duped)
|
|
python3 tools/stream-check/stream_check.py graph logs/01-*.json report.json
|
|
```
|
|
|
|
Input: any mix of `*.json` files and directories. Options: `--out-dir`
|
|
(default `graphs`), `--combined`, `--width`, `--height`. SVG opens in any
|
|
browser/IDE and converts to PNG with `rsvg-convert`/`inkscape` if needed.
|