Documentation

File-processing presets

File processing presets

Pixop Prime offline jobs (pixop-process) use TOML presets to describe NVEncC encoder arguments and optional container environment. That model is separate from 24/7 live output, which is driven by /etc/pixop-live/nvencc.args, systemd, and the remote-control UI (params.json). Changing a file preset does not alter the live encoder path; editing nvencc.args does not change --preset behaviour. See Live output and encoding for the live stack and Configuration for how appliance paths fit together.

Version gate: On every appliance, confirm the tool exists before you rely on these workflows:

pixop-version
command -v pixop-process
pixop-process -h

Older Marketplace or lab images may ship without pixop-process or with a smaller preset set. The commands below are read-only where noted and safe to run for verification.

Preset layers and name resolution

Named presets are discovered in strict priority (first file wins; lower layers are shadowed but still used as extends parents):

PriorityLayerDefault pathOverwritten on image apply?
1 (highest)Local./.pixop/presets/ relative to current working directoryNo — operator-managed
2Site/etc/pixop-live/process-presets/Never overwritten by apply
3Factory/opt/pixop/share/process-presets/Refreshed with the appliance software

Advanced overrides (testing only): PIXOP_PROCESS_LOCAL_PRESETS, PIXOP_PROCESS_SITE_PRESETS, and PIXOP_PROCESS_FACTORY_PRESETS repoint those directories.

Working directory matters for local presets. pixop-process searches local presets in $PWD/.pixop/presets, not relative to your input files. Run pixop-process from the project directory where .pixop/presets/ lives, or set PIXOP_PROCESS_LOCAL_PRESETS to an absolute path.

You can also pass an explicit path: --preset /path/to/my.toml or --preset ./relative.toml (paths containing /, starting with ., or ending in .toml are treated as files).

Inspect presets on the appliance

These modes do not start Docker and do not require a license:

pixop-process --list-presets
pixop-process --show-preset 4k-hlg
pixop-process --show-preset /etc/pixop-live/process-presets/site-4k-hlg.toml

--list-presets prints operator-facing names and descriptions. Presets whose names start with _ (for example _base-pixop-hlg) are inheritance-only bases: hidden from the list, still resolvable with --show-preset and usable in extends.

--show-preset is the authoritative view of fully merged inheritance, effective [env], Pixop filter summary, and the final NVEncC argv list.

TOML schema (version 1)

Every preset file must set version = 1. Other versions are rejected.

KeyRequiredSemantics
versionYesMust be 1
extendsNoSingle parent name or path; one parent only (lists are invalid)
descriptionYes on leaf/standalone; may inheritNon-empty string after merge
output_extensionYes after mergeMust look like .mp4 (leading dot, no /)
[nvencc].argsNon-empty on standalone; may be empty on child if parent supplies argsArray of non-empty strings
[env]OptionalTable of string keys and string values

Reserved NVEncC tokens must not appear in preset TOML (validation fails at load time):

-i, --input, -o, --output, --realtime, --http-port, --https-port

The pixop-process wrapper always supplies input/output paths and disables the embedded HTTP ports for file jobs.

Do not embed secrets in presets: no license paths, JWTs, API tokens, or Hub credentials in TOML. License mounting for Pixop grades is handled automatically from /etc/pixop-live/live.env when the resolved argv uses the Pixop filter (see CLI reference).

Inheritance and merge rules

Inheritance is a single-parent chain, resolved depth-first from root to leaf, maximum 16 levels. Cycles and missing parents produce clear errors.

When sources are merged (factory → … → site/local leaf):

  • description and output_extension: last non-null value along the chain wins.
  • [env]: keys merge; child overrides parent for the same key.
  • [nvencc].args: concatenation — parent tokens first, then each child in order.

There is no deduplication. NVEncC generally applies last-value-wins for repeated scalar options (for example a later --vbr-quality overrides an earlier one). Duplicated flags can still produce confusing encoder behaviour; prefer small, intentional child fragments and verify with --show-preset.

Parent lookup: A bare name searches local → site → factory (skipping the child file when resolving a same-named extends). A path in extends resolves relative to the child preset file’s directory first, then as an explicit file.

--vpp-pixop-live caveat: argv is merged as whole tokens. Display logic can show comma-separated Pixop keys, but a child cannot change a single Pixop key inside a parent’s composite string without repeating the full value. For Pixop tuning, prefer factory leaves or documented CLI overrides after -- when appropriate.

Example: site preset extending 4k-hlg

Factory 4k-hlg restores and upscales to 3840×2160 with SDR→HLG signalling. A common site pattern is to keep that grade and adjust encoder VBR only:

# /etc/pixop-live/process-presets/site-4k-hlg.toml
version = 1
extends = "4k-hlg"
description = "Site 4K HLG with conservative VBR"

[nvencc]
args = [
    "--vbr-quality", "15",
]

Creating files under /etc/pixop-live/process-presets/ typically requires root (sudo install or equivalent). pixop-process itself runs as the invoking user (no sudo for normal jobs).

Validate before a long batch:

pixop-process --show-preset site-4k-hlg
pixop-process /data/in/sample.mxf /data/out/sample.mp4 --preset site-4k-hlg --dry-run

You may also shadow a factory name at site layer (for example 4k-hlg.toml with extends = "4k-hlg" plus extra args); --show-preset 4k-hlg then reflects the winning layer. A local ./.pixop/presets/4k-hlg.toml with the same pattern wins over site when your cwd is correct.

From preset to job

ModeInvocationBehaviour
Single filepixop-process INPUT OUTPUT --preset NAMEOne encode; output must be a file when input is a file
Directorypixop-process INDIR OUTDIR --preset NAMERecursive; relative tree preserved; symlinks skipped

Output directory must not lie inside the input tree. Outputs are named stem + output_extension from the resolved preset (often .mp4). Colliding outputs in one batch are rejected. Non-empty existing outputs are skipped unless --overwrite is set.

Atomic outputs: media is written via a *.pixop-partial temporary name and promoted only on success. Each output has a sibling <output>.pixop.log sidecar (resolved preset, image digest, docker command, cleaned transcript). Failed jobs retain the sidecar; partial media is not promoted.

SimpleVQA MOS/QCS lines appear in the sidecar when the job runs the Pixop filter (most enhancement and bicubic presets). The transcode preset has no Pixop filter and no SimpleVQA. Bicubic presets still use the Pixop filter path with DNN processing disabled.

License: Presets that resolve to --vpp-pixop-live / pixop-live resize require a readable license at the host path from live.env (normally /etc/pixop-live/license.jwt). transcode does not. --dry-run and preset introspection do not check license.

GPU and live stack: If pixop-live.service is active, pixop-process warns that file jobs may compete for GPU with live enhancement. There is no hard scheduler guarantee; plan maintenance windows or stop the live stack when you need exclusive GPU time. See Monitoring and troubleshooting.

Pixop does not guarantee batch completion times, output bitrates, or visual results for every source; validate grades on representative content.

CLI overrides (not in TOML)

Arguments after -- append additional NVEncC tokens after the merged preset argv and before the wrapper’s fixed -i / -o tail. Reserved options cannot be passed after --.

pixop-process input.mxf output.mp4 --preset 4k-hlg -- --vbr-quality 15

Use this for one-off experiments. Prefer site presets for repeatable site policy.

FlagNotes
--dry-runPrints per-job headers and docker argv; no containers, no outputs
--env KEY=VALUEInjected into docker run (repeatable). Security: values may appear in process listings and logs; redaction in sidecars is best effort (names containing TOKEN, SECRET, PASSWORD, etc.). Do not put credentials in site presets—inject at runtime via a secure channel
--docker-argExtra docker run flags before the image (not for -e / env files)
--continue-on-errorDirectory mode: continue after a failed file (exit non-zero if any failed)

This CLI is not the integrated REST/UI live control plane. Live picture processing and params.json are documented under Picture processing.

Lifecycle: factory vs site presets

Factory files under /opt/pixop/share/process-presets/ ship with the AMI and are replaced when appliance software is applied (same class of update as the digest-pinned LIVE image and /opt/pixop/share/docs/pixop-process.md). Site and local presets are never removed by that process.

Applying a new LIVE digest with pixop-image-update updates LIVE_IMAGE in live.env; file jobs always use that digest. Factory preset content may change on a full image upgrade—re-run --list-presets and --show-preset after major updates. Your site TOML in /etc/pixop-live/process-presets/ persists across those operations.

Runnable workflow summary

# Discover and verify
pixop-process --list-presets
pixop-process --show-preset 4k-hlg

# Single file (dry-run first)
pixop-process /data/in/clip.mxf /data/out/clip.mp4 --preset 4k-hlg --dry-run
pixop-process /data/in/clip.mxf /data/out/clip.mp4 --preset 4k-hlg

# Batch tree
pixop-process /data/in /data/out --preset 1080p --dry-run
pixop-process /data/in /data/out --preset 1080p --continue-on-error

# On-appliance operator guide (pager when TTY)
pixop-process --docs

Related documentation

Updated about 8 hours ago

Did this page help you?