ACMX2

Overview

ACMX2 is a powerful C++ application for applying real-time OpenGL shader effects to video streams from cameras, video files, or static images. Built on the MX2 Engine (libmx2), it provides both a command-line interface and a Qt6-based GUI for managing shader libraries, recording processed output, and real-time audio reactivity.

The application supports live webcam effects, video file processing with shader effects, 3D model rendering with shaders, and audio-reactive visual effects (when compiled with AUDIO_ENABLED).

Key Features

Architecture

Core Components

• acmx.cpp - Main application with OpenGL rendering loop and shader management
• interface/ - Qt6 GUI application for user-friendly shader management
• audio.cpp - RtAudio integration for audio reactivity (optional)
• MXWrite/ - FFmpeg wrapper library for video encoding/decoding
• shader_generator/ - AI-powered shader generation using Ollama

Shader System

Shaders are GLSL fragment shaders that receive the following uniforms:

• sampler2D samp - Input texture (camera/video frame)
• float time_f / float iTime - Elapsed time
• vec2 iResolution - Output resolution
• vec4 iMouse - Mouse position
• int iFrame - Frame counter
• float amp / float uamp - Audio amplitude (when enabled)
• vec4 iDate - Current date/time
• float iFrameRate - Current FPS

Shader libraries are organized in folders with an index.txt file listing shader filenames:

color_swirl_c.glsl
tremor4.glsl
ripple_a.glsl

Command-Line Arguments

Audio Arguments AUDIO_ENABLED Required

Keyboard Controls

Shader Management

Playback Controls

Time & Animation

Camera & View (3D Mode)

Capture & Display

Usage Examples

1. Basic Camera with Default Settings

./acmx2

Opens default camera device with 1280x720 resolution.

2. Camera with Custom Resolution & Recording

./acmx2 -c 1920x1080 -o output.mp4 -b 18

Captures at 1080p, records to output.mp4 with CRF 18 (higher quality).

3. Video File with Single Shader

./acmx2 -i video.mp4 -f shaders/effect.glsl -r 1280x720 -o processed.mp4

Processes video.mp4 with effect.glsl shader, outputs at 720p.

4. Shader Library with Looping

./acmx2 -i video.mp4 -s ./filters -h 2 -a

Uses shader library in ./filters, starts at shader index 2, loops video.

5. Audio-Reactive Webcam

./acmx2 -w -l 2 -q 15.0 -y

Enables audio reactivity with 2 channels, sensitivity 15.0, and audio pass-through.

6. 3D Mode with Model

./acmx2 --enable-3d --model cube.mxmod.z -s ./filters

Renders shaders on 3D cube model with camera controls.

7. Fullscreen with Texture Cache

./acmx2 -i video.mp4 -n --texture-cache --cache-delay 2

Fullscreen mode with texture caching (2-frame delay).

8. Copy Audio Track

./acmx2 -i input.mp4 -s ./filters -o output.mp4 --copy-audio

Processes video and copies original audio track to output.

GUI Application (Qt6 Interface)

The Qt6 interface provides a user-friendly way to manage shaders and sessions:

Main Features

• Shader Library Manager - Create, edit, and organize shader collections
• Code Editor - Built-in GLSL editor with syntax highlighting
• Session Properties - Configure camera, resolution, FPS, and output settings
• Audio Settings - Control audio reactivity, channels, sensitivity, and devices
• Live Preview - Run shaders directly from the interface

Building the GUI

cd interface
qmake6
make -j$(nproc)
./interface

GUI Settings

Settings are stored using QSettings under "LostSideDead" organization:

• exePath - Path to acmx2 executable
• shaders - Current shader library folder
• prefix_path - Screenshot/output directory

Building from Source

Dependencies

• C++20 compatible compiler (GCC 10+, Clang 12+, MSVC 2019+)
• CMake 3.10+
• SDL2
• OpenGL (3.3+) & GLAD
• OpenCV 4.x
• FFmpeg development libraries (libavcodec, libavformat, libavutil, libswscale)
• Qt6 (for GUI application)
• libmx2 (MX2 Engine) - https://github.com/lostjared/libmx2
• RtAudio (optional, for audio reactivity)

Build Steps

# Clone libmx2
git clone https://github.com/lostjared/libmx2.git
cd libmx2/libmx
mkdir build && cd build
cmake .. -DOPENGL=ON
make -j$(nproc) && sudo make install

# Build MXWrite library
cd ../../../ACMX2/MXWrite
mkdir build && cd build
cmake ..
make -j$(nproc) && sudo make install

# Build ACMX2
cd ../..
mkdir build && cd build
cmake .. -DAUDIO=ON
make -j$(nproc) && sudo make install

# Build GUI (optional)
cd ../interface
qmake6
make -j$(nproc)

Enabling Audio Support

To enable audio reactivity, ensure RtAudio is installed and add -DAUDIO_ENABLED=ON to CMake:

cmake .. -DAUDIO_ENABLED=ON

Shader Development

Basic Shader Template

#version 330 core
in vec2 tc;
out vec4 color;

uniform sampler2D samp;
uniform float time_f;
uniform vec2 iResolution;
uniform float amp;  // Audio amplitude

void main(void) {
    vec2 uv = tc;
    
    // Your shader code here
    vec4 texColor = texture(samp, uv);
    
    color = texColor;
}

Available Uniforms

Creating Shader Libraries

Organize shaders in a folder with an index.txt file:

my_shaders/
├── index.txt
├── wave_effect.glsl
├── color_shift.glsl
└── distortion.glsl

index.txt:

wave_effect.glsl
color_shift.glsl
distortion.glsl

AI Shader Generator

The shader_generator tool uses Ollama to generate GLSL shaders from natural language prompts:

Building

cd shader_generator
mkdir build && cd build
cmake ..
make

Usage

./shader_generator [host] [model] [output_file]

# Example:
./shader_generator localhost codellama:7b my_shader.glsl

You'll be prompted to describe the desired shader effect. The generator will create a complete GLSL shader file.

Audio Transfer Utility

The audio_transfer utility copies audio tracks between video files:

./audio_transfer source_video.mp4 destination_video.mp4

This is useful when you've processed video without audio and want to add the original audio track back.

Technical Details

Video Encoding (MXWrite)

ACMX2 uses the custom MXWrite library (wrapper around FFmpeg) for video encoding:

• Codec: H.264 (libx264)
• Format: MP4 or MPEG-TS
• Quality: CRF-based (default: 23, lower = higher quality)
• Frame rate: Configurable (default: 24 FPS)

Texture Caching

When enabled with --texture-cache, ACMX2 maintains a frame buffer cache to improve performance with certain shader effects. The --cache-delay parameter controls buffer depth (default: 1 frame).

Audio Processing

Audio reactivity (when enabled) uses RtAudio to capture real-time audio input and calculate amplitude values:

• Sample rate: 44100 Hz
• Buffer size: 512 frames
• Channels: Configurable (1-32)
• Sensitivity: Multiplier for amplitude (default: 25.0)

3D Rendering

3D mode uses the MX2 Model system to load and render .mxmod.z files with shaders applied as textures. Camera controls use quaternion-based rotation for smooth movement.

Supported File Formats

Input Video

Any format supported by OpenCV VideoCapture (MP4, AVI, MOV, MKV, etc.)

Input Images

PNG, JPG, BMP (via OpenCV imread)

Output Video

MP4 (H.264), TS (MPEG Transport Stream)

Shaders

GLSL (.glsl) fragment shaders (GLSL version 330 core)

3D Models

.mxmod.z (MX2 compressed model format)

Troubleshooting

Common Issues

License

ACMX2 is released under the MIT License.

Copyright (c) 2024-2025 Jared Bruni (LostSideDead)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Credits & Libraries

• SDL2 - Window management and OpenGL context
• OpenGL - GPU-accelerated rendering
• OpenCV - Camera/video capture and image processing
• FFmpeg - Video encoding/decoding
• Qt6 - GUI framework
• RtAudio - Real-time audio I/O
• libmx2 - MX2 Engine (https://github.com/lostjared/libmx2)
• Argz - Command-line argument parsing
• libcurl - HTTP client for shader generator

Author

Developed by Jared Bruni (LostSideDead)
Website: https://lostsidedead.biz
This software is dedicated to all who have experienced mental illness.

Additional Resources

• libmx2 GitHub Repository
• ACMX2 GitHub Repository
• Detailed Keyboard Controls Reference
• MXWrite Library Documentation