ACMX2 v2.22.0
(C) 2026 LostSideDead
https://lostsidedead.biz
ACMX2: v2.22.0
(C) 2026 LostSideDead
https://lostsidedead.biz

Arguments
Short and long forms are equivalent; values shown in <> are required.

General
  -v, --help
    Show this help screen and keyboard controls.
    example: acmx2 --help
  -p <path>, --path <path>
    Set assets root directory (shaders, data files, defaults).
    example: acmx2 --path ./data
  -r <WxH>, --resolution <WxH>
    Set output/window resolution (for display and recording).
    example: acmx2 --resolution 1920x1080
  -N, --fullscreen
    Start in fullscreen mode (Escape to exit fullscreen).
    example: acmx2 --fullscreen
  --silent
    Run headless (no preview window). Intended for file-to-file rendering.
    example: acmx2 -i in.mp4 -o out.mp4 --silent
  --duration <seconds>
    Auto-stop recording/output after elapsed seconds.
    example: acmx2 -i in.mp4 -o out.mp4 --duration 30
  --max-size <MB>
    Auto-stop when output file size exceeds MB.
    example: acmx2 -i in.mp4 -o out.mp4 --max-size 500.0

Input Source
  -i <file>, --input <file>
    Input video file.
    example: acmx2 --input clip.mp4
  -g <file>, --graphic <file>
    Input still image instead of camera/video.
    example: acmx2 --graphic frame.png
  -d <idx>, --device <idx>
    Camera device index to open.
    example: acmx2 --device 0
  -c <WxH>, --camera-res <WxH>
    Request camera capture resolution.
    example: acmx2 --camera-res 1280x720
  --enumerate-device <idx>
    Print camera resolutions/formats supported by device and exit.
    example: acmx2 --enumerate-device 0
  --use-yuv
    Prefer YUYV camera capture over MJPG for compatible devices.
    example: acmx2 --device 0 --use-yuv

Shaders And Visual Pipeline
  -s <index.txt>, --shaders <index.txt>
    Use shader library index file (playlist-able shader set).
    example: acmx2 --shaders ./shaders/index.txt
  -f <frag.glsl>, --fragment <frag.glsl>
    Use a single fragment shader file directly.
    example: acmx2 --fragment ./shaders/wave.glsl
  -h <index>, --shader <index>
    Select initial shader index from the active library.
    example: acmx2 --shaders index.txt --shader 3
  --shader-pass <list>
    Run multiple shader indices per frame (comma-separated).
    example: acmx2 --shader-pass 0,4,7
  --playlist <file>
    Load shader playlist text file (one shader name per line).
    example: acmx2 --playlist live_set.txt
  --cross-fade <seconds>
    Set smooth transition time between playlist shader switches.
    example: acmx2 --playlist live_set.txt --cross-fade 1.25
  --autopilot-frames <N>
    Auto-switch to random playlist shader every N rendered frames (minimum 4).
    example: acmx2 --playlist live_set.txt --autopilot-frames 240
  --autopilot-timeout <N>
    Alias for --autopilot-frames (minimum 4).
    example: acmx2 --playlist live_set.txt --autopilot-timeout 240
  --autopilot-random <N>
    Use random autopilot interval 4..N frames for each J/Y autoplay switch.
    example: acmx2 --playlist live_set.txt --autopilot-random 300
  --time-speed <mult>
    Scale shader time uniform speed (1.0 = normal).
    example: acmx2 --time-speed 0.5
  --build <library-path>
    Compile shader library into cache, then exit.
    example: acmx2 --build ./shaders
  --remove-broken <library-path>
    Compile-check each shader, remove failing entries from index.txt, then exit.
    example: acmx2 --remove-broken ./shaders
  --no-cache
    Disable shader binary cache and always compile at startup.
    example: acmx2 --no-cache
  --texture-cache
    Enable texture/frame cache for cache-aware shader effects.
    example: acmx2 --texture-cache
  --cache-delay <frames>
    Delay frame cache feed by N frames for temporal effects.
    example: acmx2 --texture-cache --cache-delay 6
  --texture-cache-size <N>
    Set texture cache ring buffer size (1-64, default 8).
    example: acmx2 --texture-cache --texture-cache-size 16
  --enable-3d
    Enable 3D object rendering pipeline.
    example: acmx2 --enable-3d
  --model <file>
    Load a custom 3D model file for the 3D scene.
    example: acmx2 --enable-3d --model scene.obj
  --flip
    Flip final output vertically before display/encode.
    example: acmx2 --flip

DNN And ONNX Models
  --human <file>
    Load ONNX human segmentation model (e.g., pphumanseg .onnx) to isolate foreground person.
    example: acmx2 --human human_seg.onnx -i input.mp4 -o output.mp4
  --background
    When --human is used, apply shaders only to background; composite person on top.
    example: acmx2 --human model.onnx --background
  --black <threshold>
    Set mask black point / shadow crush threshold for color/segmentation masks (default: 0.35).
    example: acmx2 --human seg.onnx --black 0.25
  --white <threshold>
    Set mask white point / opacity saturation threshold for color/segmentation masks (default: 0.75).
    example: acmx2 --human seg.onnx --white 0.85
  --edge <file>
    Load ONNX edge detection model (e.g., Dexined .onnx) to replace frame with edge map.
    example: acmx2 --edge edges.onnx -i video.mp4 -o edges.mp4
  --onnx <file>
    Load generic ONNX model from YAML config file; replaces frame with model output.
    example: acmx2 --onnx bubble.yaml -i input.mp4 -o output.mp4

GPU And CUDA
  --gpu-filter <list>
    Apply CUDA filter chain by index list (comma-separated).
    example: acmx2 --gpu-filter 1,12,18
  --gpu-buffer <N>
    Set GPU temporal frame buffer size (4..32).
    example: acmx2 --gpu-buffer 12
  --list-filters
    List all built-in GPU filters and their indices.
    example: acmx2 --list-filters
  -m <idx>, --cuda-device <idx>
    Select CUDA device index to run processing on.
    example: acmx2 --cuda-device 0
  --list-cuda-devices
    List CUDA devices visible to the runtime.
    example: acmx2 --list-cuda-devices
  --check-cuda
    Report whether this build has CUDA support enabled.
    example: acmx2 --check-cuda

Recording And Encoding
  -o <file>, --output <file>
    Write processed video to output file.
    example: acmx2 -i in.mp4 -o out.mp4
  --png
    Video file mode: write output as PNG frame sequence in an output subdirectory.
    example: acmx2 -i in.mp4 -o out.mp4 --png
  --generate <N>
    Save a PNG frame every N frames to an output subdirectory (video or camera mode).
    example: acmx2 -i in.mp4 --generate 30
  -e <prefix>, --prefix <prefix>
    Snapshot filename prefix for captured frames.
    example: acmx2 --prefix snap/frame_
  -u <fps>, --fps <fps>
    Set output frame rate for recording.
    example: acmx2 --fps 60
  -b <crf>, --bitrate <crf>
    Legacy CRF quality option for encoder.
    example: acmx2 --bitrate 20
  --encode-preset <name>
    Encoder speed/quality preset (ultrafast .. veryslow).
    example: acmx2 --encode-preset fast
  --encode-tune <name>
    Tune encoder for content type or low latency.
    example: acmx2 --encode-tune film
  --encode-crf <0-51>
    Set encoder quality directly (lower = better quality/larger file).
    example: acmx2 --encode-crf 18
  --encode-codec <mode>
    Codec backend: auto, software, or nvenc.
    example: acmx2 --encode-codec nvenc
  --encode-realtime
    Enable low-latency encoder settings for live pipelines.
    example: acmx2 --encode-realtime
  --no-drop
    Never drop frames; block producer when encoder queue is full.
    example: acmx2 --no-drop
  --display-filter
    Show current shader/stack and GPU filter in upper-left corner.
    example: acmx2 --display-filter
  --use-watermark <text>
    Enable watermark with given text in recorded videos (upper-left).
    example: acmx2 --use-watermark "My Channel"
  --use-watermark-color <r,g,b>
    Watermark text color as 0-255 components.
    example: acmx2 --use-watermark-color 255,255,0
  --copy-audio
    Mux input audio track into encoded output when possible.
    example: acmx2 -i in.mp4 -o out.mp4 --copy-audio
  -a, --repeat
    Loop video input source continuously.
    example: acmx2 -i loop.mp4 --repeat

Runtime Overlay
  --disable-counter
    Hide timer and FPS overlay text.
    example: acmx2 --disable-counter

Keyboard Controls

Main
  Escape
    Quit.
  Ctrl+X
    Quit without audio mux.
  Up Arrow
    Previous shader (or previous playlist entry in playlist/autopilot mode).
  Down Arrow
    Next shader (or next playlist entry in playlist/autopilot mode).
  Shift+Up Arrow
    In playlist/autopilot mode: change post-multipass shader backward.
  Shift+Down Arrow
    In playlist/autopilot mode: change post-multipass shader forward.
  Left Arrow
    Previous GPU filter (if enabled).
  Right Arrow
    Next GPU filter (if enabled).
  Space
    Enable/disable processing.
  L
    Toggle video freeze (Video/Image modes).
  P
    Toggle pause (Video/Image) or toggle shader playlist.
  J
    Toggle autopilot mode (requires playlist).
  Y
    Toggle sequential autopilot (cycles playlist in order, requires playlist).
  N
    Toggle random crossfade selection for autopilot shader switches.
  T
    Enable/disable time.
  U / I
    Step time when time is disabled.
  Page Up / Page Down
    Increase/decrease time speed.
  M
    Toggle multi-pass / multi-shader pass.
  F
    Toggle fullscreen.
  Q
    Toggle reactive time (if AUDIO_ENABLED).
  Insert
    Increase audio sensitivity.
  Delete
    Decrease audio sensitivity.
  End
    Toggle spectrum sensitivity scaling.
  Home
    Toggle audio delta time scaling.
  3
    Toggle 2D/3D mode.

Snapshots
  Z
    Save PNG snapshot (SDR 8-bit; HDR mode still outputs SDR PNG).
  4
    Save TIFF snapshot (SDR: 8-bit RGBA; HDR: 16-bit RGBA; requires ACMX2_WITH_TIFF).
  5
    Save lossless WebP snapshot (HDR is tone-mapped; requires ACMX2_WITH_WEBP).
  6
    Save raw RGBA snapshot (HDR: 16-bit RGBA, otherwise 8-bit RGBA).
    example: ffplay -f rawvideo -pixel_format rgba64le -video_size WxH file.raw

3D Mode
  W / A / S / D
    Look around.
  V
    Toggle view rotation.
  O
    Toggle oscillation.
  X
    Reset camera distance.
  + / -
    Increase/decrease camera distance.
  B
    Increase movement speed.
  N (held in 3D)
    Decrease movement speed.
  C
    Toggle object wave.
  E
    Enable/disable watermark.
  ]
    Increase model scale.
  [
    Decrease model scale.
  . (period)
    Increase camera rotation speed.
  , (comma)
    Decrease camera rotation speed.

Environment Variables
  ACMX2_PATH
    Default assets root directory (equivalent to --path). Used when --path is not specified.
    example: export ACMX2_PATH=/usr/local/share/acmx2
  ACMX2_SHADER_PATH
    Default shader library index file or directory (equivalent to --shaders). Used when neither --shaders nor --fragment is specified.
    example: export ACMX2_SHADER_PATH=/usr/local/share/acmx2/filters
