mirror of
https://github.com/Vateron-Media/XC_VM.git
synced 2026-10-19 04:03:00 +02:00
Divarion_D
c982bb2f1e
Verify every dev-doc claim against src/ and fix factual drift: wrong method signatures/return types, wrong enum casing (BootContext cases are PascalCase), stale paths (M3u parsers are Composer deps under vendor/, MobileDetect is mobiledetect/mobiledetectlib v4.9.0 \Detection\MobileDetect, NotFoundException lives in XcVm\Core\Container\Psr), a fictional `stream:check` command/class, reversed migration-failure semantics ([FAIL] = not recorded, retried), inverted isStreamRunning/isStreamAlive descriptions, findProcessPIDs ANY-not-ALL, acquireCronLock has no shutdown callback, and nonexistent make targets. Split oversized pages and fix nav + cross-links: - modules.md -> module-authoring / module-lifecycle / module-extension-points - cli-tools.md -> cli-tools + database-migrations - streaming-subsystem.md -> + streaming-diagnostics - geoip-and-device-detection.md -> geoip-isp-and-geo-routing + device-detection-and-stb-locking Add development/core-wiring.md: how the core assembles itself at boot (container population, ServiceContainer reference, bootAll orchestration, CLI command auto-discovery, end-to-end Admin/CLI boot walkthroughs). Only docs/en + mkdocs.yml touched; docs/ru is regenerated before release.
63 lines
3.4 KiB
Markdown
63 lines
3.4 KiB
Markdown
# Streaming Diagnostics & Tooling
|
||
|
||
A standalone tool verifies that a stream delivers correctly — that segments arrive in order and the delivery queue does not break. It is independent of the request path; for that, see the [Streaming Subsystem](streaming-subsystem.md).
|
||
|
||
---
|
||
|
||
## `tools/stream-check/stream_queue_check.py` (Python, stdlib only)
|
||
|
||
Standalone monitor for **segment/packet queue integrity** with an optional **live buffer dashboard**. Auto-detects HLS vs MPEG-TS.
|
||
|
||
```bash
|
||
python3 tools/stream-check/stream_queue_check.py "<url>" --duration 30 # batch check
|
||
python3 tools/stream-check/stream_queue_check.py "<url>" --json # cron / monitoring
|
||
python3 tools/stream-check/stream_queue_check.py "<url>" --live --duration 0 # live dashboard
|
||
```
|
||
|
||
What "queue intact" means per stream type:
|
||
|
||
| Stream | Queue check |
|
||
| --- | --- |
|
||
| HLS (`.m3u8`) | `EXT-X-MEDIA-SEQUENCE` monotonic and contiguous (no dropped or rewound segments), no `EXT-X-DISCONTINUITY`, every newly appearing segment downloadable. Master playlists are resolved to their first variant. |
|
||
| MPEG-TS (`.ts`, `/play/<token>/ts`) | per-PID `continuity_counter` (lost / duplicated / reordered packets = queue break), sync-byte loss, transport-error indicator, and delivery stalls. |
|
||
|
||
Key options:
|
||
|
||
| Flag | Purpose |
|
||
| --- | --- |
|
||
| `--duration N` | seconds to observe (`0` = until Ctrl-C in `--live`) |
|
||
| `--tolerance N` | allow N transient queue breaks before reporting `BROKEN` (ignores rare source glitches relayed by `-c copy`) |
|
||
| `--stall-timeout S` | delivery gap counted as a stall; keep it above the segment duration (default 15) |
|
||
| `--live` | colored TUI dashboard (below) |
|
||
| `--prebuffer S` / `--buffer-target S` | live: virtual-player prebuffer and buffer-graph scale |
|
||
| `--json` / `--no-color` | machine output / disable ANSI |
|
||
|
||
Exit code: `0` healthy, `2` queue problem or stall, `1` usage.
|
||
|
||
### Live dashboard (`--live`)
|
||
|
||
Models a virtual player: the playhead advances at wall-clock rate while content is "received". For **TS** the received timeline comes from **PCR** (the stream clock); for **HLS** from the segments' `EXTINF` durations. Buffered playtime ("cache") = received − played; if it reaches zero the playhead freezes (a rebuffer event).
|
||
|
||
```text
|
||
STREAM QUEUE / BUFFER MONITOR TS up 00:22
|
||
cache buffer (s), last 60s:
|
||
▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▄▄▄▇▇▇▆▆▆▅▅▅▄▄▇▇▇▆▆▆▅ <- burst-then-drain = delivery sawtooth
|
||
IN CACHE : [█████████████████░░░░░░░░░░░░░] 11.6s / 20s
|
||
PLAYING : PLAYING head 00:18 received 00:29
|
||
rate 1000 kbit/s received 4.1 MB last data 7.0s ago
|
||
QUEUE OK cc:0 sync:0 gaps:0 disc:0 rebuffers:0
|
||
```
|
||
|
||
The buffer graph and gauge are colored green (healthy) / yellow (low) / red (starving). For HLS a row of blocks shows the segments still in cache ahead of the playhead.
|
||
|
||
> **Note — delivery pacing.** Live client delivery is now handled by the
|
||
> `xc_fanout` daemon (see [Streaming Subsystem → Daemon delivery](streaming-subsystem.md#daemon-delivery-xc_fanout)), which pulls each source once and fans it out over a unix socket. `stream_queue_check.py --live` visualises the buffer behaviour a real player would see against the delivered stream.
|
||
|
||
---
|
||
|
||
## Related files
|
||
|
||
| File | Purpose |
|
||
| --- | --- |
|
||
| `tools/stream-check/stream_queue_check.py` | queue-integrity monitor + live buffer dashboard |
|