tsduckctl

Manage TSDuck tsduck-in@ and tsduck-out@ instances. Per-instance environment: /etc/pixop-live/tsduck/<name>.env. Relay transport (newer builds) also uses /etc/pixop-live/tsduck/<name>.{ingest|egress}.args templates.

Version note: Native-only images use .env keys only—no relay *.args templates, no bonded listener groups, and no tsduck-transport-info helper. Relay-capable images add those templates and the helper; the effective backend per instance is still chosen separately via TRANSPORT_BACKEND in .env (native or relay). A relay-capable image may run TRANSPORT_BACKEND=native with the helper installed. The tsduckctl transport subcommand is always in the CLI wrapper; without the helper it exits with not installed. With the helper, it introspects native or relay. Confirm with pixop-version, command -v tsduck-transport-info, and tsduckctl transport main. Operators do not type sudo; the script re-executes via /opt/pixop/bin/tsduckctl (do not sudo tsduckctl — secure_path may hide /opt/pixop/bin).

Usage (complete surface)

tsduckctl list
tsduckctl credentials
tsduckctl transport NAME
tsduckctl start   NAME [--type in|out]
tsduckctl stop    NAME [--type in|out]
tsduckctl restart NAME [--type in|out]
tsduckctl status  NAME [--type in|out]
tsduckctl logs    NAME [--type in|out]
tsduckctl enable  NAME [--type in|out]
tsduckctl disable NAME [--type in|out]
tsduckctl check   NAME [--type in|out]
tsduckctl detect-video-pid NAME [--secs N] [--apply]
tsduckctl tune-latency     NAME [--apply]
tsduckctl start-all | stop-all | restart-all | status-all | logs-all
tsduckctl -h|--help

Refused: tsduckctl pull → exit 2; use pixop-image-update.

Instance map

Known names (explicit table — not “any .env filename”):

Name	Type	systemd unit	Default SRT UDP
`main`	ingress	`[email protected]`	5000
`egress-main`	egress	`[email protected]`	5001
`egress-aux1`	egress	`[email protected]`	5002
`egress-aux2`	egress	`[email protected]`	5003

list discovers every *.env in the env dir and prints TYPE / ACTIVE / UNIT. Unknown names require --type in|out for start/stop/etc.

Aux egress is disabled until configured (passphrase and enablement). start-all / restart-all skip unconfigured aux egress with SKIP: on stderr and continue.

Transport: inspect vs configure

Action	Tool	Mutates?
Inspect effective backend, health-check policy, listener layout	`tsduckctl transport NAME`	No
Inspect bind vs `ss` (JSON)	tsduck-transport-info `bind-status`	No
Configure SRT ports, passphrases, `PIPELINE_LATENCY`, PIDs	Edit `.env` / relay `*.args` templates	Yes (manual)
Apply PID or latency recommendations	`detect-video-pid --apply`, `tune-latency --apply`	Yes

transport never prints SRT_PASSPHRASE. It may show credentials: SRT_PASSPHRASE configured (value not shown).

Backends

`TRANSPORT_BACKEND`	Native-only image (helper absent)	Relay-capable image (helper installed)
`native` (default)	Supported; use `check` + `.env`	Supported; `tsduckctl transport` can report native when helper present
`relay`	Not supported (no templates / helper)	Supported

Stream redundancy / SRT bonding (multiple UDP listeners, srt-bonded-udp health checks) appears only on relay templates. Do not configure bonded groups on native-only appliances.

Relay template paths:

Ingest: /etc/pixop-live/tsduck/main.ingest.args
Egress: /etc/pixop-live/tsduck/egress-main.egress.args (and aux analogs)

Shared relay container template: /etc/pixop-live/tsduck/relay-template.args.

Credentials (sensitive)

tsduckctl credentials

Prints a connection sheet: private/public IPv4 (IMDS best-effort; missing public IPv4 → not assigned), SRT mode, port, URIs, encryption (from SRT_PBKEYLEN), and passphrase in clear text.

Security rule	Why
Treat output as secret	Same sensitivity as env files (`root:root` 0600)
Do not log or ticket	Passphrases grant SRT access
Wait for first-boot	Blocks until `instance-init.complete` or times out with guidance

Waits up to PIXOP_CREDENTIALS_WAIT_SECS (default 15) for /var/lib/pixop-live/instance-init.complete while pixop-instance-init.service is activating.

Lifecycle commands

Command	Behavior
`start` / `restart`	`require_egress_srt_config` for egress; `systemctl start
`stop`	`systemctl stop` only
`enable` / `disable`	Boot policy only
`status`	`systemctl status` for one unit
`logs`	Tail `/var/log/pixop-live/tsduck-{in
`check`	Active unit + listener readiness; does not verify SRT peer connected — may show `bound (SRT session unverified)`

Egress SRT_PASSPHRASE required when:

Native backend (always), or
Relay template contains @SRT_PASSPHRASE@ token.

Missing passphrase → exit 2 with path to .env.

Aggregate commands

Command	Notes
`start-all` / `restart-all`	Skip unconfigured aux egress; exit 1 if any non-skipped instance fails wait
`stop-all`	Stops all discovered units (`
`status-all`	UNIT / ACTIVE table
`logs-all`	Multi-unit `journalctl -f`

Commissioning helpers (ingress `main` only)

`detect-video-pid`

Samples the pre-Pixop multicast tap (TAP_OUT_ADDR:TAP_OUT_PORT from network.env, default 239.0.0.1:5500). Egress names rejected → exit 2.

Flag	Detail
`--secs N`	Sample duration 1–30 (default 3 in helper)
`--apply`	On unambiguous result: atomic update `ORIGINAL_VIDEO_PID` + `INPUT_PCR_PID` in `main.env`, restart ingress via `tsduckctl`

Without --apply: read-only. Multiple video PIDs, scrambled TS, or no input produce non-zero helper exit codes (see tsduck-detect-video-pid on appliance).

`tune-latency`

Compares PIPELINE_LATENCY in main.env to pixop-timing-probe --json (not pixop-flow).

Concept	Value
Supported range	200–1500 ms inclusive
`--apply`	Writes recommended ms when different (raise or lower), restarts primary ingress
Out-of-range recommendation	Rejected, not clamped

Report-only exits include safe / needs adjustment / no measurement / probe error (see helper --help on appliance).

SRT URL and passphrase handling

Setting	Location
`SRT_PORT`, `SRT_PBKEYLEN`, `SRT_PASSPHRASE`	`/etc/pixop-live/tsduck/<name>.env`
`PIPELINE_LATENCY`, video PIDs	Ingress `main.env`
Caller vs listener	Native env or relay args template

credentials builds srt://<ip>:<port> for listeners when IPv4 is known. Caller mode relay: local UDP bind check not applicable; check may return OK when unit active only.

Command matrix (tasks)

Task	Commands
Connection sheet for partners	`tsduckctl credentials`
Non-secret transport summary	`tsduckctl transport main`
Ready for first SRT connect	`tsduckctl check main` → `tsduckctl start main`
Bounce egress after env edit	`tsduckctl restart egress-main --type out`
Enable aux path	Edit `egress-aux1.env`, `tsduckctl enable egress-aux1 --type out`, `start`
Fix video PID	`tsduckctl detect-video-pid main --apply`
Fix latency	`tsduckctl tune-latency main` then `tune-latency main --apply`
Deep bind diagnostics	tsduck-transport-info

Troubleshooting

Symptom	Check
`did not bind SRT UDP`	`transport main`; firewall; `journalctl -u tsduck-in@main`
`bound` but no video	`detect-video-pid main`; Pixop with `pixopctl status`
`transport introspection failed` or `tsduck-transport-info is not installed`	Helper missing, or relay/native template unreadable or invalid
`credentials` missing secrets	`systemctl status pixop-instance-init.service`
Restart validates before stop	Bad egress config will not stop a healthy unit on failed `restart` pre-check

tsduck-transport-info (advanced read-only)
Connect your first SRT stream
Network and transport
pixop-stack
pixop-flow