pixop-process

Process video files or directories through the same digest-pinned Pixop LIVE Docker image used for live enhancement. Runs as the invoking user for normal jobs (no sudo). Uses host Docker with GPU passthrough as defined in the execution plan.

Version note: Confirm on your appliance with pixop-version, command -v pixop-process, and pixop-process -h. Your image may ship a smaller CLI surface than this page.

Usage

pixop-process [-h] [--preset PRESET] [--list-presets]
              [--show-preset NAME|PATH] [--docs] [--dry-run]
              [--overwrite] [--continue-on-error]
              [--env KEY=VALUE] [--docker-arg ARG]
              [input] [output]
              [-- EXTRA_NVENCC_ARGS...]

Mode	Arguments	Behavior
Preset introspection	`--list-presets`, `--show-preset`, `--docs`	No Docker, no license
File	`INPUT OUTPUT --preset NAME`	Single transcode/enhance
Directory	`INDIR OUTDIR --preset NAME`	Recursive; relative tree preserved

Processing jobs require INPUT, OUTPUT, and --preset.

Quick start

pixop-process --list-presets
pixop-process --show-preset 4k-hlg
pixop-process input.mxf output.mp4 --preset 4k-hlg
pixop-process /data/input /data/output --preset 4k-hlg --dry-run
pixop-process --docs

Options

Option	Safe / mutating	Description
`--preset PRESET`	Config	Factory, site, local name, or path to `.toml`
`--list-presets`	Read-only	Names + descriptions (no `_`-prefixed internal bases)
`--show-preset NAME\|PATH`	Read-only	Fully resolved preset (inheritance, env redacted secrets)
`--docs`	Read-only	Prints operator guide via pager (`less`) when TTY; else stdout
`--dry-run`	Read-only	Resolved docker command per job; no containers
`--overwrite`	Mutating	Replace non-empty existing outputs
`--continue-on-error`	Mutating	Directory mode: keep going after a failed file
`--env KEY=VALUE`	Mutating	Injected into `docker run` (repeatable; secrets redacted in sidecar)
`--docker-arg ARG`	Mutating	Extra `docker run` arg before image (repeatable; not for `-e`/`--env`)

Arguments after -- pass additional NVEncC CLI tokens (merged after preset args). Reserved NVEncC options cannot be set in preset TOML; use CLI -- for overrides documented in the full guide.

Preset layers and version gate

Layer	Path	Overwritten on image apply?
Factory	`/opt/pixop/share/process-presets/`	Refreshed with appliance
Site	`/etc/pixop-live/process-presets/`	Never overwritten by apply
Local	`./.pixop/presets/` (cwd)	Operator-managed

Resolution order for a name: local → site → factory (first file wins). extends in TOML supports single parent chains; preset version = 1 required (other versions rejected).

Internal inheritance-only presets start with _ (for example _base-pixop-hlg); hidden from --list-presets but resolvable with --show-preset.

Operator-facing factory presets (examples)

Preset	Typical use
`4k-hlg`, `4k-pq`, `4k`	UHD output grades
`1080p`, `1080p-interlaced`, `16x9`, `16x9-interlaced`	HD / aspect targets
`1x`, `2x`	Spatial scale factors
`sdr-hlg`, `sdr-pq`	SDR → HDR conversion paths
`bicubic-*`	Reference bicubic grades (quality baseline)
`transcode`	Source resolution, no Pixop filter

Run --list-presets on the appliance for the authoritative list and descriptions.

Input / output constraints

Rule	Detail
Video suffixes	`.mp4`, `.mov`, `.mkv`, `.mxf`, `.ts`, `.m2ts`, `.avi`, `.mpg`, `.mpeg`
File mode	Output must be a file path if input is a file
Directory mode	Output must be a directory; refuses output inside input tree
Symlinks	Skipped during directory discovery
Output naming	`stem + preset.output_extension` (often `.mp4`)
Collisions	Two inputs mapping to same output → error
Existing output	Skipped unless `--overwrite` and size > 0

Execution and sidecars

Artifact	Purpose
Final media	Written atomically (via `*.pixop-partial` rename)
`<output>.pixop.log`	Resolved preset, image ref, docker command, transcript
SimpleVQA	Recorded when Pixop filter runs — not for `transcode` preset

--dry-run prints the same header blocks without running Docker.

License and LIVE interaction

Preset type	License
Uses Pixop filter (most presets)	Readable `/etc/pixop-live/license.jwt` (or staged copy for user namespace)
`transcode`	No Pixop filter — license not required

If pixop-live.service is active, stderr warning:

warning: pixop-live.service is active; file processing may compete for GPU resources

Prefer off-hours batch jobs on a live encoder, or pixop-stack stop for exclusive GPU use.

`--docs` behavior

Does not open a browser or URL. On a TTY it runs $PAGER (default less -FRX) on /opt/pixop/share/docs/pixop-process.md when that file is installed on the appliance.

Environment overrides (advanced)

Variable	Default
`PIXOP_PROCESS_LIVE_ENV`	`/etc/pixop-live/live.env` (image digest source)
`PIXOP_PROCESS_FACTORY_PRESETS`	`/opt/pixop/share/process-presets`
`PIXOP_PROCESS_SITE_PRESETS`	`/etc/pixop-live/process-presets`
`PIXOP_PROCESS_LOCAL_PRESETS`	`$PWD/.pixop/presets`
`PIXOP_PROCESS_DOCKER`	`/usr/bin/docker`

Exit codes

Code	Meaning
0	Success or dry-run complete
1	Processing failure (or last failed file without `--continue-on-error`)
2	Invalid arguments / usage error

Task matrix

Task	Command
Pick a grade	`--list-presets` / `--show-preset NAME`
Validate batch plan	`... --dry-run`
Single file enhance	`in.mxf out.mp4 --preset 4k-hlg`
Batch tree	`indir/ outdir/ --preset 1080p --continue-on-error`
Site custom preset	Drop `my-grade.toml` in `/etc/pixop-live/process-presets/`
Extra NVEncC flags	`... --preset 4k-hlg -- --bitrate 50000` (example)
Read full guide	`pixop-process --docs`

Troubleshooting

Issue	Check
`preset not found`	Spelling; site vs factory path; `--show-preset` for resolution
`license` errors	`pixop-license status`; KVM `pixop-install license`
Docker GPU errors	GPU requirements (FAQ); driver/image match
OOM / slow with LIVE up	Stop live stack or use maintenance window

Configuration
GPU requirements (FAQ)
pixop-license
pixop-image-update (factory presets refresh with LIVE image, not site presets)