ProjectM

ProjectM is a C++ application that uses CMake as its build system and SDL2 for graphics. This project is intended to be built and run on macOS with a modern C++ toolchain.

Prerequisites

1. Xcode Command Line Tools
   • Install with: xcode-select --install
2. Homebrew
   • Install from: https://brew.sh/
3. CMake, SDL2, and libprojectM
   • Install with: brew install cmake sdl2 projectm

Optional (Recommended) Audio Loopback Driver

To capture system audio on macOS you need a virtual loopback device so the operating system can route the output stream into our capture pipeline. Popular options include BlackHole (free, open source) or Loopback Audio (commercial). Install one of these solutions and set it as the default system output device, then configure the Mac to route sound to both the loopback device and your speakers/headphones (e.g., by creating an aggregate/multi-output device in Audio MIDI Setup).

Building ProjectM

1. Clone this repository and open a terminal in the project root.
2. Create a build directory:

   mkdir build && cd build

3. Run CMake to configure the project:

   cmake ..

4. Build the project:

   cmake --build .

Running ProjectM

After building, run the executable from the build directory:

cd build
./ProjectM

The application opens a 1280x720 resizable window with real-time music visualizations.

Controls

• SPACE - Next preset
• P - Previous preset
• R - Random preset
• L - Lock/unlock preset
• F - Toggle fullscreen
• M - Toggle preset name display
• H - Toggle help overlay (shows controls on-screen)
• ESC / Q - Quit

Features

• 4,199 MilkDrop Presets - Full library of classic visualization presets
• libprojectM 4.1.4 - Latest version with vastly improved Milkdrop compatibility and performance
• On-Screen Display (OSD) - Help overlay showing controls, preset names, and status messages
• Real-time Audio Capture - Captures system audio via BlackHole virtual audio device
• Automatic Preset Transitions - Smooth crossfading between presets every 20 seconds
• OpenGL 3.3 Rendering - Hardware-accelerated graphics with 60 FPS target
• Preset Controls - Navigate, lock, or randomize presets during playback
• Fullscreen Mode - Seamless fullscreen for presentations and recordings
• Apple Silicon (M1) Optimized - Native support for Mac Mini M1

Recording for YouTube

To create music videos:

1. Use a screen recorder (QuickTime, OBS, etc.) to capture the ProjectM window
2. Play your music through the Multi-Output device (BlackHole + your audio interface)
3. Switch between visualization modes (1-4 keys) during recording for variety
4. The beat detection and particles will automatically react to the music

Creating a Distributable App

To create a standalone .app bundle that can be copied to /Applications:

cd packaging
./create_dmg.sh

This script:

• Creates a self-contained ProjectM.app bundle
• Bundles all required libraries (SDL2, FreeType, projectM)
• Fixes library paths so the app works anywhere
• Creates a DMG installer for easy distribution

The resulting app can be:

• Copied to /Applications and run directly
• Distributed to other Macs without requiring Homebrew
• Run from any location

Troubleshooting

App won't launch from Applications:

• The app needs its dependencies bundled. Run packaging/create_dmg.sh to create a proper bundle.
• See docs/app-bundle-fix.md for technical details.

No audio data appears:

• BlackHole is installed and detected (check console output)
• Your Multi-Output device includes BlackHole
• The Multi-Output device is set as the default macOS output
• ProjectM has microphone permission (macOS treats loopback capture as input access)
• Music is playing through the Multi-Output device

---

Directory Structure

• src/ — C++ source files
• include/ — C++ header files
• build/ — Build output (not tracked in git)
• tests/ — Unit and integration tests
• docs/ — Documentation

---

✅ Now Using libprojectM 4.1.4!

Upgraded on: October 10, 2025

This project now uses libprojectM 4.1.4 (released January 2025) with major improvements:

• ✨ Complete expression parser rewrite (much faster execution)
• 🎨 Vastly improved Milkdrop compatibility
• 🎵 Better audio processing matching Milkdrop exactly
• 🌊 Support for new waveform modes (BeatDrop, Milkdrop2077)
• 🔒 ABI stability - future 4.x updates can be dropped in without recompiling

What changed:

• Migrated from C++ API (3.x) to C API (4.x)
• Added playlist library support
• Improved audio device detection (BlackHole + Multi-Output)
• Backup of 3.x version saved in src/main_3x_backup.cpp

---

License

[Specify your license here]