Configuration

Pixop Prime is a live MPEG-TS appliance: WAN transport, GPU picture processing, and HEVC encoder output are independent control planes. This page is the operations landing—where configuration lives, what restarts cost, and which specialist guide to open next. Use it before editing files during an on-air window.

Start here: Run pixop-version and record it in your change ticket. Relay transport and extended tsduckctl introspection appear only on relay-capable recipes—confirm command -v tsduck-transport-info and TRANSPORT_BACKEND before relay workflows. Native-only appliances default to native SRT via .env keys. KVM uses the same guest image model; hypervisor setup is KVM quickstart.

For controlled edits, backups, and acceptance tests, follow Configuration change control.

Configuration control planes

Each plane has its own source of truth, edit surface, and apply boundary. Mixing planes (for example encoder colour flags vs UI tone mapping) is the most common commissioning defect.

Plane	Source of truth	How operators change it	Takes effect
Encoded output	`/etc/pixop-live/nvencc.args`	SSH + editor on marked operator blocks	After `pixopctl restart` (`pixop-live.service` only)
Picture processing	Runtime: Pixop filter in memory; persisted: `/var/lib/pixop-live/parameters/params.json`	Web UI / REST on TCP 8080 (trusted management CIDR only)	Runtime API updates apply without container restart; Save writes `params.json` for the next startup
Network / transport	`/etc/pixop-live/network.env`, per-instance `/etc/pixop-live/tsduck/.env`, relay `.ingest.args` / `*.egress.args` when `TRANSPORT_BACKEND=relay`	`tsduckctl`, controlled file edits	After `tsduckctl restart` on the affected instance (`main` = ingest + internal mux; `egress-main` = egress leg only)
Host image & lifecycle	`/etc/pixop-live/live.env`, `tsduck.env` (`LIVE_IMAGE` / `TSDUCK_IMAGE` digests)	pixop-image-update (not hand-edited tags)	Restarts only units that were active at apply time
Licensing & Pulse	AWS: Marketplace activation artifacts; KVM: `/etc/pixop-live/license.jwt`	AWS: first-boot flow + pixop-license; KVM: `pixop-install license set` on host	Entitlement gate for processing; JWT UID 1001, mode 0400
Automatic recovery	`/etc/pixop-live/healthcheck.env`	Edit thresholds only with support guidance	`pixop-healthcheck.timer` may call `pixopctl recover` (stops primary ingress, restarts Pixop, restarts ingress)
File processing presets	TOML under `/opt/pixop/share/process-presets/` and `/etc/pixop-live/process-presets/`	pixop-process / site drops	No live pipeline effect; batch jobs share GPU with live paths

Source vs persisted picture parameters

At container startup, NVEncC loads --vpp-pixop-live from nvencc.args, including params_file=/var/lib/pixop-live/parameters/params.json. When a key exists in params.json, it overrides the matching --vpp-pixop-live CLI value for that process (a virgin AMI has no params.json). Baseline keys such as restoration_mode=full and controller_preset=realtime_balanced in nvencc.args are policy defaults, not day-to-day operator knobs.

UI runtime changes apply immediately; Save writes params.json for the next startup. Detail: Picture processing.

On-appliance data path (reference)

SRT :5000 → tsduck-in@main → 239.0.0.1:5500 → pixop-live → 239.0.0.1:5501
                              → mux/PCR/PID → 239.0.0.1:5600 → tsduck-out@egress-main → SRT :5001

Multicast addresses are on-guest hand-offs, not customer WAN endpoints. Topology, ports, and release gates: Network and transport.

Filesystem inventory

Templates under /etc/pixop-live install when missing; appliance provisioning and package apply do not overwrite operator-edited files (missing relay *.args may still be added on upgrade). Never blind-copy an entire /etc/pixop-live tree from another host: JWT, Pulse, Docker Hub, and SRT passphrases are instance-specific.

Location	Sensitive?	Typical editor	Effect / restart
`/etc/pixop-live/nvencc.args`	No secrets; defines output contract	Root or sudo (`root:root` 0640)	`pixopctl restart`
`/etc/pixop-live/live.env`, `tsduck.env`	Image digests; not passphrases	`pixop-image-update`	Active units restarted on apply
`/etc/pixop-live/network.env`	No	Root/sudo	TSDuck units reading backbone keys; often paired with `main.env`
`/etc/pixop-live/tsduck/*.env`	Yes (`SRT_PASSPHRASE`, etc.)	Root/sudo (0600)	`tsduckctl restart` on that instance
`/etc/pixop-live/tsduck/.ingest.args`, `.egress.args`	Placeholders only (`@SRT_PASSPHRASE@`)	Root/sudo (0640)	Relay backend; restart affected instance
`/etc/pixop-live/healthcheck.env`	No	Support-directed	Timer-driven recovery policy
`/etc/pixop-live/license.jwt`	Yes	Provisioning / license CLI	Container read via bind mount; never in support tarballs
`/etc/pixop-live/pulse.env`, `docker.env`	Yes	First-boot / support	Excluded from packers
`/var/lib/pixop-live/parameters/params.json`	Site processing profile	UI Save (UID 1001 writes)	Overrides CLI at next Pixop start; backup separately
`/etc/pixop-live/process-presets/*.toml`	Usually no	Operator	File jobs only

Permissions: ec2-user (groups pixop, docker) runs CLIs without prefixing sudo. TSDuck .env files are 0600; use tsduckctl credentials on-box—never paste passphrases into tickets.

Back up for restore: Private copies of nvencc.args, relevant tsduck/*.env and relay args, and params.json (not captured by pixop-pack-config). Procedure: Configuration change control.

Task → guide matrix

Your task	Open
Output resolution, chroma, HEVC bitrate, VUI SDR/HLG/PQ flags, optional YADIF	Live output and encoding
Restoration, scaling, HDR/SDR processing, grain, PostFX, controller	Picture processing
SRT passphrases, latency, PIDs, relay vs native, multipath	Transport configuration → Network and transport
Change tickets, backups, acceptance, rollback	Configuration change control
Offline transcode / preset TOML	File processing presets
Container digest update	pixop-image-update
Entitlement	Licensing and support
Health signals and automatic restart	Monitoring and health signals

Restart and blast radius

Action	What restarts	Operator impact
`pixopctl restart`	`pixop-live.service` only	Output gap on the replacement elementary path while Pixop is down; primary SRT ingest unit is not stopped by design, but downstream viewers must not assume gapless enhanced video
`pixopctl recover`	Stops `tsduck-in@main`, restarts Pixop, starts ingress	Ingest interruption on the primary leg; used by healthcheck and manual wedge recovery
`tsduckctl restart main`	Primary ingress + internal mux/tap path	Ingest and merged TS gap until listeners and merge recover
`tsduckctl restart egress-main`	Egress SRT only	Downstream receiver stream gap; ingest and Pixop keep running
`tsduckctl detect-video-pid main --apply` / `tune-latency main --apply`	Rewrites `.env` and restarts ingress	Same as `restart main` when `--apply` is used
UI runtime tuning	None (in-process)	Immediate picture change; may spike GPU load
UI Save	None	Persists `params.json`; full effect on next `pixopctl restart` or container recreate
`pixop-image-update --apply`	Active Pixop/TSDuck units per tool policy	Software version change; plan like any production release
File preset edit	None for live	Affects future `pixop-process` jobs only

There is no supported “zero outage” guarantee for encoder or transport configuration changes on a single appliance.

Safe change checklist (summary)

Baseline — pixop-version, pixop-stack status, transport checks, and (when on air) pixop-flow --secs 5 per Configuration change control.
Private backup — Root-readable archive of nvencc.args, transport env/args, and params.json before edits; restrict directory mode 0700.
Edit sanctioned knobs only — Operator blocks in nvencc.args; transport keys documented in Transport configuration; picture keys via UI—not ad-hoc duplication into nvencc.args.
Validate — pixop-preflight after host-level changes; tsduckctl check after transport restarts; decoder/player check for program, resolution, and colour.
Rollback — Restore backed-up files, repeat the same restart class, re-run acceptance. Do not treat pixop-pack-config output as a secret restore bundle.

Support packaging: pixop-pack-config and pixop-support-bundle provide redacted /etc/pixop-live snapshots for diagnosis. They exclude license.jwt and Pulse/Docker credential bodies, do not include params.json, and are not a substitute for your private backups.

Escalation

When opening a Pixop support case, attach version output, a support bundle or pack-config archive (review for residual secrets), and a non-secret description of the change. Keep JWTs, SRT passphrases, and Pulse credentials out of email and chat. For live incidents, start from Monitoring and troubleshooting and Incident response runbook.