pixop-timing-probe
pixop-timing-probe
Measure MPEG-TS timing between the pre-Pixop tap (:5500 by default) and post-Pixop replacement feed (:5501) using TSDuck pcrextract probes. Supports latency tuning workflows with tsduckctl tune-latency main (reads pixop-timing-probe --json).
Availability: Verify this tool on your appliance with command -v pixop-timing-probe and pixop-version (the tool may report its own semver, for example 2.1.0, independent of the AMI recipe). Run pixop-timing-probe -h for flags. Installed path when present: /opt/pixop/bin/pixop-timing-probe. Requires root (auto sudo via absolute script path unless PIXOP_TIMING_PROBE_NOSUDO=1).
Purpose and scope
Read-only with respect to appliance configuration: spawns short-lived TSDuck docker run or host tsp listeners, correlates matched PTS values, and prints diagnostics. Does not write PIPELINE_LATENCY unless you use tsduckctl tune-latency main --apply separately.
Requires a live stream on both endpoints with timestamp passthrough and correct video/PCR PIDs. A bare pixop-timing-probe does not load main.env; use pixop-timing-probe main to load /etc/pixop-live/tsduck/main.env timing keys (passphrases in that file are ignored).
Usage summary
pixop-timing-probe [NAME] [options]| Option | Default / notes |
|---|---|
NAME | Load timing keys from /etc/pixop-live/tsduck/NAME.env |
--input / --output | UDP endpoints; defaults from tap/replacement env or 239.0.0.1:5500 / :5501 |
--input-pid, --input-pcr-pid, --output-pid, --output-pcr-pid | PIDs; hex allowed |
--samples | 500 matched PTS pairs |
--timeout | 30 seconds |
--percentile | 99 (nearest-rank for tail stats) |
--guard-frames | 0 extra frames on arrival holdback |
--result alignment|arrival | Stdout integer: timestamp alignment (default) or arrival holdback |
--evaluate-offset-ms | Evaluate candidate offset; defaults to PIPELINE_LATENCY when set in env |
--socket-buffer | UDP buffer; default REPLACEMENT_IP_BUFFER_SIZE or 8388608 |
--docker-image | TSDuck image; else TSDUCK_IMAGE / tag from env |
--allow-non-kernel | Allow non-kernel input timestamps (not recommended) |
--max-delay-ms | Reject implausible transit delays above 10000 |
--json | Full result object on stdout |
--show-config | Resolved settings JSON, then exit |
-v / --verbose | TSDuck stderr to stderr |
--version | Probe script version |
Precedence: explicit flag → named instance file → process environment → /etc/pixop-live/tsduck.env → built-in default.
Exit codes: 0 success; 1 runtime error (no matches, probe failure); 2 configuration error; 130 interrupt.
stdout vs stderr
- Default stdout: single integer — timestamp alignment (
decode_phase_alignment_ms) unless--result arrival(arrival holdback ms). - Human summary and warnings go to stderr.
--jsonputs the full structure on stdout (use this for automation andtune-latency).
Key JSON fields (when present):
| Field | Meaning |
|---|---|
complete | true when usable matches ≥ --samples |
arrival_holdback_ms | Frame-rounded tail transit holdback |
decode_phase_alignment_ms | Nearest-frame timestamp alignment recommendation |
decode_safe_minimum_ms | Lower-bound diagnostic (not a comfort margin) |
transit | PTS transit delay distribution (median, percentile, max) |
matched_samples / requested_samples | Sample counts after filtering |
tsduckctl tune-latency main compares current PIPELINE_LATENCY to max(arrival_holdback_ms, decode_safe_minimum_ms) with alignment raised when reported — supported apply range 200–1500 ms inclusive (see tsduckctl source/docs).
Operator workflows
Primary pipeline with instance env (recommended):
pixop-timing-probe main --json | jq '{complete, arrival_holdback_ms, decode_phase_alignment_ms, decode_safe_minimum_ms}'Shell-friendly integer (default --result alignment):
ALIGNMENT_MS="$(pixop-timing-probe main)"
echo "$ALIGNMENT_MS"Verify resolved endpoints before a long capture:
pixop-timing-probe main --show-configArrival holdback only:
pixop-timing-probe main --result arrivalRun only while pixop-flow shows traffic on :5500 and :5501 and PIDs match your program.
Troubleshooting
| Error / symptom | Action |
|---|---|
no matching PTS values were observed | Wrong endpoints/PIDs, no multicast, or passthrough disabled — confirm with pixop-flow and tsduckctl detect-video-pid main |
kernel timestamps failure | Probes require kernel TSP timestamps; fix tap path or use --allow-non-kernel only if clocks are comparable |
timed out ... only N/M usable matched samples | Partial result; increase --timeout or ensure stable source |
could not derive timestamp alignment | Use --result arrival or fix B-frame / PCR sample quality |
docker not found but ... TSDUCK_IMAGE | Docker required when image env is set |
Preflight intentionally does not run this probe (avoids false FAIL on idle hosts).
Limitations
- Short observation window — not a 24h QoS study.
- Identical PTS collisions in the window cannot be correlated uniquely.
- Egress instance names are rejected by
tune-latency; probemainonly for primary latency policy. - Spawns concurrent Docker containers with
--pull=never; fails if TSDuck image missing locally.
Related
- tsduckctl —
tune-latency main, PID detection - Network and transport — SRT latency and holdback context
- pixop-flow — backbone throughput at tap
Updated about 8 hours ago