pixop-flow

Read-only snapshot of UDP payload bitrate (Mbps) at five points in the Pixop LIVE pipeline. Uses a short tcpdump capture on any; does not change configuration, restart services, write packet payloads, or print credentials.

Version note: Confirm with pixop-version, command -v pixop-flow, and pixop-flow -h. Do not prefix with sudo; the script self-elevates via its absolute path (caller environment is not preserved across sudo).

Usage

pixop-flow
pixop-flow --secs N
pixop-flow -h|--help

Option	Default	Valid range
`--secs N`	2	1–30 (integer)

Invalid options or out-of-range --secs → exit 2 with usage on stderr.

Measurement points

Traffic is classified from tcpdump LINUX_SLL2 lines (UDP length field = payload bytes, not frame size).

Display label	What is counted
`SRT ingest :<port>`	Inbound UDP dest port = ingest SRT port
`Ingress -> Pixop :<tap_port>`	Outbound to multicast tap (`TAP_OUT_ADDR`:`TAP_OUT_PORT`)
`Pixop -> replacement :<repl_port>`	Outbound to replacement input
`Final merged TS :<final_port>`	Outbound merged transport stream
`SRT main egress :<port>`	Outbound UDP source port = main egress SRT port

Defaults for multicast stages come from /etc/pixop-live/network.env:

Key	Default if unset
`TAP_OUT_ADDR` / `TAP_OUT_PORT`	`239.0.0.1` / 5500
`REPLACEMENT_IN_ADDR` / `REPLACEMENT_IN_PORT`	`239.0.0.1` / 5501
`FINAL_OUT_ADDR` / `FINAL_OUT_PORT`	`239.0.0.1` / 5600
`TS_TARGET_BITRATE`	Backbone capacity (bits per second); if missing, utilization lines show `unavailable`

Port overrides (advanced)

Variable	Default	Effect
`PIXOP_FLOW_INGEST_PORT`	5000	SRT ingest filter + label
`PIXOP_FLOW_EGRESS_PORT`	5001	SRT main egress filter + label

Caveat: Stage labels in the printed table use INGEST_PORT / EGRESS_PORT only. Multicast addresses and ports always follow network.env (or defaults above). If you remap SRT ports via env overrides, the numeric labels reflect overrides but aux egress ports 5002–5003 are not sampled.

Exit codes

Code	Meaning
0	Capture succeeded; tap (`:5500` by default) below `TS_TARGET_BITRATE` backbone (idle / zero Mbps is OK)
2	Usage error
3	Capture succeeded; tap rate at or above backbone capacity (warning printed)
10	Capture / measurement failure (`tcpdump` missing, permission, interface, zero elapsed time)

Interpreting output

Example shape (values depend on your stream; do not expect these numbers on your system):

Pixop LIVE data flow
====================

Stage                                    Mbps
--------------------------------------------
SRT ingest :5000                           0.00
Ingress -> Pixop :5500                     0.00  [0.0%]
Pixop -> replacement :5501                 0.00
Final merged TS :5600                      0.00
SRT main egress :5001                      0.00

Input backbone capacity:                   50.00 Mbps
Input backbone utilization:               0.0%

Sample:                                    2.0 s
Rates are UDP payload Mbps; SRT rates include protocol overhead
and retransmissions.

Observation	What it suggests
`SRT ingest` > 0, `Ingress -> Pixop` ≈ 0	Ingress not forwarding to tap, or wrong PID / Pixop not consuming
Tap high, egress low	Egress down or no peer connected
Exit 3	Input TS exceeds configured backbone — risk of drops before Pixop
All zeros, exit 0	No UDP on filtered ports during sample (idle pipeline)

What counters do not prove

SRT session health (encryption, passphrase, caller/listener mode)
Video decode quality or GPU load
Correct PCR or PID mapping
AWS security group or public IPv4 assignment (other tools report not assigned; pixop-flow only sees local UDP)

Backbone utilization is computed from tap stage bytes vs TS_TARGET_BITRATE, not from SRT :5000.

Prerequisites

tcpdump installed and allowed to capture (CAP_NET_RAW / root after self-elevate).
For meaningful non-zero rates, ingress should be receiving TS and Pixop processing (or at least tap traffic present).
If /var/lib/pixop-live/instance-init.complete is missing, a banner notes first-boot may make flow incomplete.

Comparison to service metrics

Tool	Interface
`pixop-flow`	Packet capture, five UDP stages
`pixopctl health`	HTTP GET `/v1/metrics` (Prometheus text)
`pixop-healthcheck`	`/v1/metrics.json` + restart policy

Use flow for bitrate plumbing; use metrics HTTP for encoder / decoder counters and health automation.

Troubleshooting

Failure	Action
Exit 10 permission	Confirm you ran `pixop-flow` without manual sudo; check AppArmor/capabilities
Exit 10 tcpdump missing	Install/fix appliance image — not operator-fixable on locked AMI
Exit 3	Lower source bitrate, raise `TS_TARGET_BITRATE` only if network design allows, or fix oversubscribed input
Misleading zeros	Increase `--secs` (up to 30); verify stream with `tsduckctl check main`