ACMX

ACMX is an open-source, real-time video-synthesis and glitch-art workstation. It processes cameras, video files, and still images through GPU shader chains, then previews, records, or captures the result. One Qt interface manages shader libraries, live editing, custom uniforms, playlists, multipass effects, audio and MIDI controls, recording, and both rendering engines.

The repository name, acidcam-gpu, is historical. The current application is ACMX, and the shared interface and ACMXVK backend are version 2.142.0. The established ACMX2 engine retains its own backend version, 2.101.1.

Photosensitivity Mitigation

ACMXVK now includes an optional built-in Photosensitivity Mitigation stage for visually intense shader chains.

The mitigation shader runs as the final compute pass after the user's selected effects. It is designed to reduce some characteristics that may make highly animated or psychedelic visuals uncomfortable for photosensitive viewers while preserving as much of the original artwork as possible.

The pass can selectively reduce:

• extreme brightness and bright highlights
• large luminance differences introduced by effects
• excessive local contrast
• dense, high-frequency visual patterns
• strongly saturated red regions
• some of the harsher visual intensity produced by complex effect chains

Rather than simply dimming or desaturating the entire image, the shader compares the processed result with the current unmodified source frame and applies stronger mitigation where the effect chain has introduced unusually intense changes.

Optional Final Processing

Photosensitivity Mitigation is completely optional.

With mitigation disabled, ACMXVK uses the normal shader pipeline without modification:

Input
  -> User Effect Chain
  -> Output

With mitigation enabled:

Input
  -> User Effect Chain
  -> Photosensitivity Mitigation
  -> Output

The mitigation pass always runs after the final user-selected effect, so existing shaders and effect chains do not need to be modified.

Adjustable Strength

The mitigation strength can be adjusted from 0.0 to 1.0.

0.0   No mitigation
0.45  Recommended starting point
1.0   Strongest mitigation

A value around 0.45 provides a useful starting point for many visually intense effects while still preserving color, detail, and motion.

The setting is persisted by the Qt interface and can be changed while ACMXVK is running.

With the ACMXVK backend selected, use Playback > Photosensitivity Mitigation to toggle the pass and Playback > Photosensitivity Mitigation Strength... to set its strength. For a terminal or headless run, add --photosensitivity-mitigation and optionally --photosensitivity-mitigation-strength 0.45. The strength option accepts a value from 0 to 1 and does not enable the pass by itself.

Headless Rendering

Photosensitivity Mitigation is also available through the ACMXVK command-line/headless rendering path.

This makes it possible to use the same final processing stage for:

• interactive playback
• recorded output
• PNG rendering
• headless rendering
• scripted or automated batch processing

The feature is therefore not dependent on the Qt interface.

SDR and HDR Support

Both SDR and HDR shader variants are included.

The built-in mitigation shader supports:

• rgba8 SDR output
• rgba16f HDR output

The appropriate shader is compiled, installed, and loaded through the existing ACMXVK built-in shader system.

Original Frame Reference

The mitigation stage receives both:

samp          = processed output from the user's effect chain
originalFrame = current unmodified source frame

originalFrame is the clean source image for the current frame. It is not a previous-frame history buffer.

This allows the mitigation shader to estimate how much additional brightness, contrast, color intensity, and pattern complexity were introduced by the selected effects.

Sharing Intense Visuals

For videos containing intense flashing, rapidly changing patterns, strong contrast, or other potentially uncomfortable visual effects, I also recommend using a visible photosensitivity warning before playback.

For ACMXVK encoded video, enable Prepend 4-second photosensitivity warning in the Qt Settings dialog's output section, or add --photosensitivity-warning to a command that also uses --output. The recording starts with a black card containing white warning text for four seconds, followed by a half-second fade into the processed video. The four-second card is added to encoded video, not PNG output. Its duration is added to the recording; source, file, or live audio is delayed to follow it.

Authors can mark a Vulkan shader library or effect pack with "intense_flashing": true in library.json or effect.json. This metadata describes the content; it does not turn on the warning card or mitigation.

Photosensitivity Mitigation is intended as an additional tool for artists who want to reduce visual intensity before publishing their work.

Important: Photosensitivity Mitigation reduces some potentially problematic visual characteristics, but it does not guarantee that an image or video is safe for every photosensitive viewer. It should be treated as a mitigation tool, not a safety certification.

Current status

ACMX is usable on Linux, macOS, and Windows, with feature availability depending on the selected backend and build options. The portable shader paths do not require NVIDIA hardware. CUDA filters, CUDA/Vulkan interop, and Deep Dream are optional features for supported NVIDIA configurations.

As of October 2026, the shared interface and ACMXVK are at 2.142.0 and ACMX2 is at 2.101.1. ACMXVK's six-stage HDR port and all ten planned Effect Pack implementation increments are complete. Effect Packs include pack-local shader builds, live activation, saved controls, audio/MIDI mappings, optional Deep Dream settings, and project import/export. The remaining Effect Pack work is validation on native macOS and Windows builds and manual GPU, audio, MIDI, and cross-machine transfer checks; see the progress log.

• ACMX2 is the mature OpenGL/libmx2 backend. It supports runtime GLSL, OpenGL fragment and compute chains, shader caching where the driver permits it, HDR video, headless processing, audio/MIDI, OpenCV DNN effects, and the optional acidcam-gpu CUDA filter library.
• ACMXVK is the modern Vulkan/MXVK backend. It supports mixed fragment and compute SPIR-V chains, incremental shader-library builds, live recompilation, HDR processing, surface-free headless rendering, Vulkan playlists and transitions, Windows named shared memory, and optional CUDA interop.
• Deep Dream is implemented in ACMXVK through CUDA LibTorch, with VGG16 and Inception V3 feature models, temporal feedback, octaves, random animation, channel targeting, and live interface control.
• Stable Diffusion video is an optional ACMXVK integration with a compatible stable-diffusion.cpp sd-server from the project's maintained fork. It keeps the model loaded for img2img processing, supports preview and constant-frame-rate recording, and can use multiple weighted LoRA adapters. It also supports Vulkan compute upscale, server-side ESRGAN during image-to-image processing, or standalone ESRGAN upscale-only preprocessing before the shader chain, with a configurable neural working resolution.

ACMXVK is the active expansion path, but it is not a drop-in shader replacement for ACMX2: OpenGL GLSL libraries use a different uniform and descriptor ABI from Vulkan source libraries compiled to SPIR-V. The interface keeps each backend's executable, library, recent paths, and compatible controls separate.

Rendering backends

Backend	Graphics stack	Shader workflow	Best fit
ACMX2	OpenGL / libmx2 / SDL2	Runtime GLSL fragment and compute shaders	Existing ACMX2 libraries, broad GPU compatibility, mature OpenGL workflows
ACMXVK	Vulkan / MXVK / SDL3	Source manifests compiled incrementally to SPIR-V	Modern fragment/compute pipelines, HDR, advanced headless work, Deep Dream, and Stable Diffusion

Both engines share the same creative workflow through acmx2_interface. Select the renderer from the interface's Backend menu before choosing a library or running a session.

Major features

• Camera, video-file, and still-image inputs with configurable input and output resolution
• Fragment/compute multipass chains, named playlists, crossfades, shader randomization, and random autopilot
• ACMXVK Effect Packs: shareable curated shader setups with friendly controls, optional Dream settings, and live activation
• ACMXVK projects: save and export portable .acmxproj folders with media, shader resources, and effect packs
• Built-in shader editor with diagnostics, live preview/reload, Find in Files, snippets, and custom-uniform controls
• Texture history, FFT and spectrum history, audio-reactive time, live or source-file audio, recording, and MIDI mapping
• Software and hardware FFmpeg encoding through the repository-local MXWrite, including CRF/CQ or bitrate control, constant frame rate, editing-compatible PTS fill, source-audio muxing, and HDR Main10
• PNG, WebP, TIFF, and raw snapshots according to enabled dependencies
• Optional OpenCV DNN, acidcam-gpu CUDA filters, Deep Dream, and Stable Diffusion processing
• Qt settings that persist independently where backend behavior differs

See each backend README for its complete option list, requirements, platform notes, shader ABI, examples, and current limitations.

Repository layout

Path	Purpose
ACMX2/	OpenGL engine, its backend documentation, runtime assets, shader packs, and models
ACMXVK/	Vulkan engine, SPIR-V build workflow, AI integrations, and Vulkan backend documentation
ACMX2/interface/	Shared Qt interface and standalone MIDI-map utility
acidcam-gpu/	Optional CUDA filter library and command-line filter utility
MXWrite/	Repository-local FFmpeg video writer used by both engines
models/ and shaders/	Shared model configurations and example GLSL assets
flatpak/	Linux Flatpak manifest, patches, and packaging scripts
build-script/, scripts/, and podman/	Dependency, build, export, and container helpers

Generated build trees, .acmxvk-build shader outputs, compiler databases, logs, packaged binaries, and model downloads should remain outside commits.

Build overview

The backend READMEs are authoritative for feature-specific builds:

• Build and use ACMX2
• Build and use ACMXVK
• Build the shared Qt interface

The portable ACMX2 CMake configuration is:

cmake -S ACMX2 -B build/acmx2 -DCMAKE_BUILD_TYPE=Release -DWITH_CUDA=OFF
cmake --build build/acmx2 --parallel
./build/acmx2/acmx2 --help

After MXVK and its dependencies are installed, a basic ACMXVK configuration is:

cmake -S ACMXVK -B build/acmxvk -DCMAKE_BUILD_TYPE=Release
cmake --build build/acmxvk --parallel
./build/acmxvk/acmxvk --help

Build the shared interface separately:

cmake -S ACMX2/interface -B build/interface -DCMAKE_BUILD_TYPE=Release
cmake --build build/interface --parallel

Headless ACMXVK rendering

ACMXVK can render an input video without opening an SDL window. Supply an encoded output and use --headless (or its --silent alias):

./build/acmxvk/acmxvk \
    --headless --input input.mp4 --output rendered.mp4 \
    --shaders /path/to/spv-library --shader-file effect.frag.spv \
    --constant-frame-rate --no-drop

For a looping batch render, add an explicit duration. This gives the job a defined completion point and lets ACMXVK report an accurate percentage and estimated remaining render time across every source loop:

./build/acmxvk/acmxvk \
    --headless --input short-clip.mp4 --output repeated.mp4 \
    --shaders /path/to/spv-library --shader-file effect.frag.spv \
    --repeat --duration 60 --constant-frame-rate --no-drop

Headless mode intentionally ignores --interface-shm; the Qt interface cannot replace shader, playback, or render settings while an offline render is in progress. See the ACMXVK headless guide for source-audio, HDR, Deep Dream, and Stable Diffusion combinations.

MXWrite Python module

MXWrite’s optional nanobind module can be installed directly from this checkout after FFmpeg development packages and a C++ toolchain are available:

python3 -m pip install ./MXWrite
python3 -c "import mxwrite_ext; print(len(mxwrite_ext.available_video_encoders()))"

The package builds the local CMake project with scikit-build-core and installs NumPy for host RGBA frame input. Run MXWrite/examples/python_example.py after installation for a self-checking encode example, including an --explicit-pts timestamp mode.

Complete project helpers

build-project-pcons.py builds libmx2, MXVK, ACMX2, ACMXVK, and the Qt interface into a local prefix without installing system packages. Dependencies must already be available through PATH and pkg-config.

python3 build-project-pcons.py --jobs 4

The script clones missing libmx2 and MXVK checkouts beside this repository and prints the final PATH export. Use --help to select existing dependency sources, a build directory, an install prefix, or optional components. The Pcons also supports ACMXVK Stable Diffusion with --stable-diffusion, and Linux CUDA LibTorch Deep Dream with --deep-dream. Use --help for the --torch-prefix and --cuda-prefix overrides; the ACMXVK Pcons section lists the required packages and runtime dependencies.

On macOS, build-project-macos-cmake.sh installs the required Homebrew dependencies, builds libmx2 and MXVK, configures ACMXVK with MoltenVK, then builds both engines and the interface into a local prefix:

./build-project-macos-cmake.sh

build-project-macos-pcons.py is available for the corresponding Pcons build. Windows builds support MSYS2 UCRT64 and native MSVC dependency workflows; see the ACMX2 Windows guide and ACMXVK MSVC/vcpkg guide for commands and runtime layout. Build each backend's dependencies with the matching compiler and architecture.

Optional acceleration and AI

The normal OpenGL and Vulkan shader workflows work without CUDA. Enable only the components needed by the target system:

Component	Build option	Main requirements
acidcam-gpu filters	-DWITH_CUDA=ON	NVIDIA CUDA Toolkit and CUDA-enabled OpenCV
OpenCV DNN effects	-DWITH_OPENCV_DNN=ON	OpenCV DNN; ACMX2 additionally requires yaml-cpp
Deep Dream (ACMXVK)	-DWITH_DEEP_DREAM=ON	NVIDIA CUDA, cuDNN, and CUDA-enabled LibTorch
Stable Diffusion (ACMXVK)	-DWITH_STABLE_DIFFUSION=ON	libcurl and a compatible local sd-server; jsoncpp is an ACMXVK core dependency
Audio / MIDI	-DAUDIO=ON, -DMIDI=ON	RtAudio / RtMidi and the backend's media dependencies

For ACMX2, installing the CUDA Toolkit alone does not make a stock OpenCV build CUDA-capable. Use a CUDA-enabled OpenCV build or configure WITH_CUDA=OFF. ACMXVK's Deep Dream option is independent of the acidcam-gpu filter option. ACMXVK can also inherit CUDA requirements from its installed MXVK package with WITH_CUDA=OFF; use a non-CUDA MXVK build for a fully portable setup. See the dependency catalog for backend-specific packages and compile-time defaults.

Downloads and documentation

• ACMX documentation
• Linux Flatpak
• Linux installation and first-use tutorial
• Windows beta
• Default Vulkan shader library
• ACMX2 backend guide
• ACMXVK backend guide
• Qt interface guide
• MXWrite guide

Regenerate the versioned Doxygen documentation with:

cd ACMX2
./build-docs.sh

License

ACMX is distributed under the BSD 2-Clause License. Optional dependencies, models, shader packs, and NVIDIA components retain their own licenses and distribution terms.