ACMX2

Overview

ACMX2 is a high-performance, GPU-accelerated video processing application that applies real-time OpenGL shader effects to webcam feeds, video files, or graphics files. Built on the libmx2 (MX2 Engine) and leveraging NVIDIA CUDA, ACMX2 delivers fluid, psychedelic visual transformations at 60+ FPS even at 4K resolution.

Getting Started

System Requirements

• Operating System: Linux (x86_64)
• Graphics: NVIDIA GPU with CUDA 12.x support
• Drivers: NVIDIA proprietary drivers installed
• Display: X11 or XWayland
• Optional: Webcam for camera input, microphone for audio reactivity

Installation via Podman (Build from Source)

cd podman

podman build -t acmx2-arch -f Containerfile.arch .

chmod +x run-acmx2-arch.sh
./run-acmx2-arch.sh

First-Time Setup

When you first launch ACMX2, you'll need to configure the shader library path:

1. Go to File → Properties
2. Set the path to your ACMX2 executable
3. Set the path to your Shader Library folder (must contain an index.txt file)
4. Click OK to save your settings

Input Sources

ACMX2 supports three types of input sources. Configure your input via Session → Session Properties.

🎥 Webcam Input

Use a live webcam feed as your video source for real-time effects.

• Select "Use Camera" radio button
• Camera Index: Choose from detected webcam devices
• Camera Resolution: Select your preferred capture resolution (e.g., 1280x720, 1920x1080)
• FPS: Set the capture frame rate (1-120 FPS)

📁 Video File Input

Process an existing video file with shader effects.

• Select "Use Video File as Input" radio button
• Click Browse to select your video file
• Supported formats include MP4, AVI, MKV, and other FFmpeg-compatible formats
• Texture Cache: Enable to cache frames for smoother playback (optional)

🖼️ Graphics File Input

Use a static image as your input source, perfect for creating animated loops from still images.

• Select "Use Graphics File as Input" radio button
• Click Browse to select your image file (PNG, JPG, etc.)
• The image will be animated using the selected shader effects

Output Resolution

Set the output resolution independently of your input source. The input will be scaled to match the output resolution.

CUDA Device Selection

If you have multiple NVIDIA GPUs, select which device to use for GPU-accelerated processing from the CUDA Device dropdown.

Working with Shaders

Shaders are GLSL (OpenGL Shading Language) programs that define how each pixel is transformed. ACMX2 uses fragment shaders to create its visual effects.

Shader Libraries

Shaders are organized into libraries. A library is a folder containing:

• index.txt - A text file listing all shader filenames (one per line)
• Individual .glsl shader files

Creating a New Shader Library

1. Go to List → New Shader Library
2. Choose a location and name for your new library folder
3. The library will be created with an empty index.txt

Managing Shaders in the List

The main window displays your loaded shaders in a list. Use the List menu to manage them:

Running Shaders

• Run Selected (F5): Run the currently selected shader from the list
• Run All (Ctrl+E): Run the entire shader library, allowing you to cycle through them

Shader Cache

ACMX2 can cache compiled shaders for faster startup times:

• Rebuild Shader Cache: Recompile all shaders and update the cache
• Run from Cache: Toggle to use cached shaders (faster) or recompile each time

Shader Code Editor

ACMX2 includes a built-in code editor with GLSL syntax highlighting for editing shader files. Double-click any shader in the list to open it in the editor.

Editor Features

Editor Controls

Writing GLSL Shaders

ACMX2 shaders receive several uniforms you can use in your effects:

uniform sampler2D samp;          // The input video texture
uniform vec2 iResolution;        // Output resolution
uniform float time_f;            // Time value for animations
uniform float amp;               // amplitude value (audio reactive)
uniform float uamp;              // amplitude value (audio reactive)
uniform vec3 iMouse;             // Mouse position
uniform int iFrame;              // Current frame number

GPU Filters

In addition to OpenGL shaders, ACMX2 provides a library of GPU-accelerated filters powered by NVIDIA CUDA. These filters process frames directly on the GPU for maximum performance.

Accessing GPU Filter Settings

Go to Session → GPU Filter Settings

Configuring GPU Filters

GPU Filter Controls

Multi-Pass Shader Rendering

Multi-pass rendering allows you to chain multiple shaders together, with each shader processing the output of the previous one. This enables complex, layered effects.

Accessing Multi-Pass Settings

Go to Playback → Multi-Pass Shader Settings...

Setting Up Multi-Pass Rendering

1. Check "Enable Multi-Pass Shader Processing"
2. Search for shaders using the search box
3. Add shaders to the pass chain using "Add →"
4. Arrange the order using ↑ Up and ↓ Down
5. Click OK to apply

How It Works

In multi-pass mode:

• Pass 1: First shader receives the original video frame
• Pass 2: Second shader receives the output of Pass 1
• Pass 3+: Each subsequent shader receives the previous pass's output
• Final Output: The last shader's output is displayed/recorded

Audio Reactivity

ACMX2 can analyze audio input and feed that data into your shaders, creating visuals that respond to sound in real-time.

Accessing Audio Settings

Go to Session → Audio Settings

Audio Options

Using Audio in Shaders

When audio reactivity is enabled, the amp/uamp uniforms receive a value based on the audio level. Use it in your shaders like this:

// Example: Scale effect based on audio
vec2 uv = fragCoord / iResolution.xy;
float audioScale = 1.0 + (amp * uamp) * 0.5;  // Scale based on audio
uv = (uv - 0.5) * audioScale + 0.5;
vec4 color = texture(samp, uv);
fragColor = color;

Reactive Time Mode

Press Q during playback to toggle Reactive Time mode. In this mode, the time_f uniform advances based on audio intensity rather than wall-clock time.

Recording Output

ACMX2 can record your processed video output to a file using FFmpeg encoding.

Setting Up Recording

1. In Session → Session Properties
2. Check "Save Output to Video File"
3. Click Browse to choose the output filename and location
4. Set the CRF (Constant Rate Factor) for quality (0-51, lower = higher quality)

Quality Settings

Copy Audio Track

When using a video file as input, enable "Copy Audio Track" to include the original audio in your output file.

Taking Snapshots

During playback, press Z to save a PNG snapshot of the current frame. Snapshots are saved to the prefix path configured in the properties.

Keyboard Controls

During playback, use these keyboard shortcuts to control ACMX2:

Interface Shortcuts

Playback Controls

Repeat Mode

Enable Playback → Repeat to loop video files continuously.

Stop Playback

Use Playback → Stop or press Esc in the output window to stop the current session.

3D Mode

ACMX2 supports 3D model rendering. Enable 3D mode in Session Properties and select an .mxmod.z model file to render 3D content with your shaders.

Interface Customization

Custom Style Theme

Toggle the red/black theme via Session → Use Custom Style. Uncheck to use your system's default Qt theme.

Log Output

The bottom panel displays log messages including:

• Shader loading status
• Process output and errors
• System messages

Troubleshooting

nvidia-smi

ls -la /dev/video*

Building & Running the Podman Container (Arch Linux)

The repository includes podman/Containerfile.arch — an Arch Linux-based container that installs opencv-cuda from pacman so you don't have to compile OpenCV from source. A matching launch script podman/run-acmx2-arch.sh handles all the runtime configuration.

Step 1: Enter the podman directory

cd /path/to/acidcam-gpu/podman

Step 2: Build the image

Packages are split into separate cached layers so the build is resumable if interrupted:

podman build -t acmx2-arch -f Containerfile.arch .

Step 3: CUDA architecture (optional)

The default is CMAKE_CUDA_ARCHITECTURES="75" (RTX 20xx / GTX 16xx). Edit Containerfile.arch before building if needed:

Step 4: Verify the image built successfully

podman images | grep acmx2-arch

Step 5: Run with the launch script

Use run-acmx2-arch.sh from the podman/ directory:

chmod +x run-acmx2-arch.sh
./run-acmx2-arch.sh