Transport configuration

This guide describes controlled changes to SRT and relay transport on a Pixop Prime appliance: what files to edit, what restarts do, and how to validate before returning to air. It assumes you have read Network and transport for topology and ports.

Capability gate: Relay templates, TRANSPORT_BACKEND=relay, bonded listener groups, and non-default protocols in relay *.args apply only when the relay backend is selected on a relay-capable image. tsduckctl transport (and tsduck-transport-info) are tied to the helper binary, not to TRANSPORT_BACKEND: when installed, they report native or relay effective backend. On native-only images (helper absent), configure via .env keys, skip relay-specific sections, and use tsduckctl check / ss instead of transport. Confirm with pixop-version, read-only tsduckctl check main / egress-main, command -v tsduck-transport-info (and tsduckctl transport when the helper is present). Instance .env files under /etc/pixop-live/tsduck/ are often root:root 0600 — unprivileged grep on those paths is not a valid operator step; review TRANSPORT_BACKEND and related keys only with authorized access (e.g. approved privilege escalation or your change-control backup).

Change-control workflow

Use this sequence for any transport change in production:

1. Capture baseline (read-only) — works on any appliance:

   Bash

   pixop-version
   tsduckctl check main
   tsduckctl check egress-main
   pixop-flow --secs 5

   Optional on any build: ss -uln | grep -E ':5000|:5001'.

   When tsduck-transport-info is installed (command -v tsduck-transport-info succeeds):

   Bash

   tsduckctl transport main
   tsduckctl transport egress-main

   tsduckctl transport re-executes via sudo so relay templates (root:root 0640) are readable — do not invoke bare tsduck-transport-info on template paths unless you are root or have a deliberate break-glass procedure.

2. Edit one concern at a time — ingest URI, egress URI, backend switch, or latency/PID — not several unrelated edits in one maintenance window.

3. Validate relay template syntax before restart (relay backend on a relay-capable image):

   Bash

   tsduckctl transport main    # surfaces warnings when .env and template diverge

   Advanced (root or sudo): tsduck-transport-info args … --role ingest|egress --format json — prefer tsduckctl transport for routine work.

4. Restart the affected instance only:

   Bash

   tsduckctl restart main          # ingest + internal mux path
   tsduckctl restart egress-main   # egress SRT only

5. Verify readiness — UDP bind is not SRT session health. Expect OK: listener … bound (SRT session unverified) when introspection applies:

   Bash

   tsduckctl check main
   tsduckctl check egress-main
   pixop-flow --secs 5

   When the helper is installed, re-run tsduckctl transport if you changed relay templates or TRANSPORT_BACKEND.

6. Rollback: Restore the previous file contents from your change ticket backup, restart the same instance, re-run checks. Native rollback: set TRANSPORT_BACKEND=native and restart (requires native-capable image).

Safety labels

Package updates and AMI refresh install missing *.args templates but never overwrite operator-edited files.

Per-instance file map

Shared backbone multicast and TS_TARGET_BITRATE live in /etc/pixop-live/network.env (and duplicated keys on main.env where noted in Configuration). Changing backbone bitrate does not change SRT ports.

Native backend (native SRT and rollback)

Set in the instance .env:

TRANSPORT_BACKEND=native

Primary keys (typical):

Native ingress uses nested TSDuck -I srt; egress uses -O srt with passphrase file indirection inside the container. There is no main.ingest.args on a pure native workflow unless you migrate to relay later.

RESTART after any .env transport key change.

Relay backend (relay-capable appliances)

Set:

TRANSPORT_BACKEND=relay

Templates are one CLI flag per line (# comments allowed). Required structural flags:

Placeholder:

Do not put the live passphrase in the template. HTTP for embedded relay binds to 127.0.0.1 with --control-enabled false and --metrics-enabled false in shipped templates.

Shipped relay templates (do not replace wholesale)

Package templates are one flag per line under /etc/pixop-live/tsduck/. Edit transport URIs in place — do not delete structural flags. Placeholder @SRT_PASSPHRASE@ is substituted at runtime from the instance .env (never paste live secrets into *.args).

Complete primary ingest template (matches shipped main.ingest.args):

--strict-config
--input-connected-stall-recovery-ms 3000
--input srt://0.0.0.0:5000?mode=listener&transtype=live&passphrase=@SRT_PASSPHRASE@&pbkeylen=16&rcvbuf=52428688&peeridletimeo=3000&conntimeo=3000&linger=0
--output stdout
--http-host 127.0.0.1
--http-port 9464
--control-enabled false
--metrics-enabled false
--exit-on-output-failure true
--stats-interval-ms 30000

Complete primary egress template (matches shipped egress-main.egress.args):

--strict-config
--input stdin
--output srt://0.0.0.0:5001?mode=listener&transtype=live&passphrase=@SRT_PASSPHRASE@&pbkeylen=32&sndbuf=52428688&linger=0
--http-host 127.0.0.1
--http-port 9465
--control-enabled false
--metrics-enabled false
--stats-interval-ms 30000

URI-only fragments (swap into the existing --input / --output line — keep all other flags):

Use documentation-only addresses (203.0.113.0/24, 198.51.100.0/24). Replace with your peer IPs. RESTART the affected instance after URI edits. For caller ingest, readiness is systemd active only — local bind checks do not prove the remote peer accepted the session.

Transport protocol matrix (relay)

MPEG-TS semantics: Relay stdin/stdout paths are byte-exact MPEG-TS. Prefer avio+ for opaque TS (for example RIST). avformat+ demux/remux is not byte-exact — do not stack remux on top of native TS when you need transparent PID layout.

PMT / program edits: Routine operator work uses ORIGINAL_VIDEO_PID, INPUT_PCR_PID, and tsduckctl detect-video-pid — not manual PMT mutation in relay args. Do not document or attempt unsupported PSI surgery in transport templates.

Ingress stall recovery (relay, SRT listener only): Shipped main.ingest.args includes --input-connected-stall-recovery-ms 3000. Remove this line if you switch the template to UDP, RIST, or RTMP — it is meaningful only on the SRT receiving-listener path.

Egress fan-out: Repeat --output lines in one egress template for independent sinks (each line is separate failover semantics, not bonding — see Multipath and bonded SRT).

Credentials and permissions

View connection parameters:

tsduckctl credentials

READ-ONLY but output contains passphrases in clear text — treat like key material.

Aux egress: SRT_PASSPHRASE empty until you set it; tsduckctl start / start-all skip unconfigured aux instances.

Pipeline timing and bitrate (not SRT URI)

These live in main.env / network.env and affect mux behavior, not the WAN protocol:

PIPELINE_LATENCY and PID apply commands RESTART primary ingress when --apply is used.

Video loss policy

In main.env:

PIXOP_VIDEO_LOSS_POLICY=fail-closed   # default
# PIXOP_VIDEO_LOSS_POLICY=fail-open

fail-open keeps the TS emitting when Pixop replacement disappears; it does not pass through the original encoder video. Change only with explicit operational approval.

Egress startup drain

egress-main.env sets EGRESS_STARTUP_DRAIN_MS=2000 — discards roughly two seconds of merged TS at TS_TARGET_BITRATE after start/reconnect. Expect downstream receivers to need a moment to lock after egress RESTART.

Validation and divergence warnings

On relay-capable images with TRANSPORT_BACKEND=relay, tsduckctl transport (via tsduck-transport-info) reads SRT port and pbkeylen from relay templates. Duplicating URI fields in .env is not required; if .env and template disagree, tooling emits warnings — resolve before production.

On native backends, tsduckctl check uses SRT_PORT / SRT_LISTEN_ADDR from .env and ss for UDP bind. When the helper is installed, tsduckctl transport can still summarize native configuration. Without the helper, tsduckctl transport fails with not installed — use check and .env. If you configure relay on an image without tsduck-transport-info, start/check paths fail closed rather than guessing ports from stale env keys.

Related

• Network and transport — topology and port table
• Multipath and bonded SRT — bonded group URI
• Transport troubleshooting — when validation fails
• tsduckctl, tsduck-transport-info