CLI reference

Command-line interface for video and OpenEXR conversion with OpenColorIO. The same entry point launches the GUI when no convert subcommand is given.

Outputs: video2exr writes an OpenEXR sequence. exr2video and proxy write a video file. PNG, JPEG, WebP, and DPX are inputs for exr2video (image sequences). The app does not write PNG or other still-image output.

Slate, burn-in, the visible text watermark, and post-convert toggles are GUI-only. See GUI. The invisible proxy watermark is available from the CLI as proxy --watermark.

# From a source checkout
uv run python main.py --help
uv run python main.py video2exr --help
uv run python main.py exr2video --help

# Packaged binary (examples)
exr_converter --help
"/Applications/EXR Converter.app/Contents/MacOS/exr_converter" --help

Related: GUI · ProRes and VideoToolbox · Nuke integration · README

---

#Modes

Global flags (before the subcommand; convert flags may also appear after it):

Interrupt: during CLI convert, Ctrl-C sets a cancel flag so the pipeline stops cooperatively (pool work is cancelled) and the process exits with status 130.

---

#GUI launch (for shells & Nuke)

# Open GUI with an EXR sequence already loaded (EXR → Video tab)
uv run python main.py --open "/show/shot/plate.####.exr"

# Force Video → EXR tab + custom OCIO
uv run python main.py --open /path/clip.mov --mode video2exr \
  --gui-ocio /path/to/config.ocio

# Packaged app
open -a "EXR Converter" --args --open "/path/to/seq" --gui-ocio "$OCIO"
# or call the binary directly:
"/Applications/EXR Converter.app/Contents/MacOS/exr_converter" \
  --open "/path/to/seq" --gui-ocio "/path/to/config.ocio" --mode exr2video

OCIO resolution for the GUI when --gui-ocio is set: custom file source (same as picking a config in the UI). Otherwise the app uses its saved preference / bundled ACES Studio / $OCIO as usual.

For a one-click Nuke menu that fills these in from a Read node, see nuke.md.

---

#video2exr: video to EXR

uv run python main.py video2exr -i plate.mov
uv run python main.py video2exr -i plate.mov -o /tmp/exr_out --exr-compression zip
uv run python main.py video2exr -i plate.mov --frame-range 1-100 --workers 4
# Optional RED R3D / N-RAW (requires local R3D SDK bridge; see docs/r3d.md):
uv run python main.py video2exr -i clip.R3D -o /tmp/exr_out \
  --src "Log3G10 REDWideGamutRGB" --dst ACEScg
# Optional Blackmagic RAW (requires local BRAW SDK bridge; see docs/braw.md):
uv run python main.py video2exr -i clip.braw -o /tmp/exr_out \
  --src ACES2065-1 --dst ACEScg

Output naming: stem.####.exr inside the output directory (pad width from --padding). Default directory is <input_parent>/<stem>/ (same idea as the GUI).

RED R3D / N-RAW: optional. Requires building the R3D bridge against the official proprietary SDK. See r3d.md. Without it, .r3d / .nev inputs error with a clear missing-SDK message.

Blackmagic RAW: optional. Requires building the BRAW bridge against the official proprietary SDK. See braw.md. Public Releases ship the bridge when secret BRAW_SDK_READ_TOKEN is set. Without it, .braw inputs error with a clear missing-SDK message. Decode is Linear ACES AP0 (Metal / CUDA / OpenCL when available, otherwise CPU).

---

#exr2video: image sequence to video

Primary path is OpenEXR. Also accepted as input: DPX, and display stills PNG, JPEG (.jpg / .jpeg), WebP. Mixed folders prefer EXR, then DPX, then display stills. The command always encodes a video file.

uv run python main.py exr2video -i ./plate
uv run python main.py exr2video -i ./plate -o review.mov --fps 24
uv run python main.py exr2video -i ./plate/plate.1001.exr -o review.mov --fps 24
uv run python main.py exr2video -i ./png_seq -o review.mp4 --codec h264 --fps 24
uv run python main.py exr2video -i ./plate --codec h264 --crf 18

Default output path when -o is omitted: sibling of the sequence folder, named after the folder, with a codec-appropriate extension:

#Codecs (honest bit depths)

Keys match exr2video --codec. Software ProRes is always 10-bit encode (prores_ks); do not treat 4444/XQ as true 12-bit on that path.

VideoToolbox (prores_vt_*) is Apple’s hardware ProRes encoder on macOS only. It is faster than software, and 4444/XQ keep ~12-bit class precision that prores_ks does not. Experimental oxideav 4444/XQ (prores_ox_4444, prores_ox_xq) are true 12-bit on every OS. oxideav 422 profiles (prores_ox_proxy / lt / 422 / hq) code 12-bit coefficients and present as 10-bit (apco / apcs / apcn / apch) to FFmpeg, Resolve, and QuickTime. Full explanation: ProRes and VideoToolbox.

List keys on your build. --help omits macOS-only VideoToolbox codecs on other operating systems, and omits prores_ox_* when the oxideav extension is not built:

uv run python main.py exr2video --help

User guide for the three ProRes encoders (software vs VideoToolbox vs oxideav): ProRes and VideoToolbox. Research notes for the oxideav path: plan-12bit-prores-oxideav.md. Experimental presets prores_ox_* use in-process oxideav PyO3 bindings when exr_prores is built (make oxideav-prores); they are omitted from --codec choices otherwise.

---

#Color management notes

• Transforms are applied with PyOpenColorIO (not OIIO’s colorconvert).
• Omitted --src: video2exr uses stream TRC/primaries/codec candidates then Output - Rec.709; exr2video uses still metadata / format (scene-linear vs sRGB-ish). Omitted --dst: fixed defaults + roles (ACEScg / scene_linear for video→EXR; Rec.709 for EXR→video), not media probing. Names remap via find_equivalent_space when needed. exr2video dest names that are OCIO displays bake the viewing-rule default view (ACES 2.0 SDR Rec.709 on current Studio configs), matching Nuke/DJV, not Un-tone-mapped.
• Packaged app needs OpenColorIO 2.5+ for the bundled ACES Studio v4 config. From source: make ensure-ocio if the runtime library is older than 2.5.

---

#proxy: video to editing proxies

Lightweight proxies for editing, like DaVinci Resolve's proxy generation. No OCIO step: proxies keep the source look, timecode, and audio. Same engine as the GUI's Video → Proxy tab.

# One clip → ./Proxy/A001C003.mov (ProRes 422 Proxy, half resolution)
uv run python main.py proxy -i A001C003.mov

# Every clip in a card folder, quarter-res H.264
uv run python main.py proxy -i ./A001_card --resolution quarter --codec h264

# Whole shoot day into one folder
uv run python main.py proxy -i ./day1 --recursive -o /proxies

# Watch folder daemon: proxy each new clip once it finishes copying (Ctrl-C stops)
uv run python main.py proxy --watch /Volumes/Ingest
uv run python main.py proxy --watch /Volumes/Ingest --recursive --existing --codec dnxhr_lb

# Invisible TrustMark watermark on every proxy frame (off unless --watermark is given)
uv run python main.py proxy -i ./A001_card --watermark ABCD1234 --watermark-strength 1.0

Flags match proxy --help. The --codec list in that help text is whatever this operating system can encode, so prores_vt_proxy and prores_vt_lt appear on macOS only.

The watermark is embedded in the resized RGB frame, on every frame, before the codec. Proxies do not run an OCIO view transform, so that RGB image is the picture the proxy shows. A payload that is too long or not printable ASCII, or a --watermark-strength outside 0.1 to 2.0 (checked only with --watermark), exits with code 2 before any clip is converted. If the model cannot be downloaded, each clip fails with an error (a batch exits with code 1).

To read a mark back, use uv run python scripts/trustmark_detect.py PROXY.mov (add --samples N to read more frames; the default is 9). That helper downloads decoder_Q.onnx (not shipped with the app), samples frames, and majority-votes the bits. It prints the payload and exits 0, or prints detected: no and exits 1. Cache locations, what survives re-encoding, and other limits: GUI: Invisible watermark.

The watch folder polls instead of relying on OS file events, so it works on network shares and removable volumes. Proxies are written to a hidden .name.partial.ext file and renamed when complete. RAW clips (.r3d, .nev, .braw) are not supported by proxy.

---

#Exit codes

---

#See also

• main.py --help, video2exr --help, exr2video --help, proxy --help (always current)
• GUI
• Nuke integration
• Releasing