JUCE-RS: Rust Implementation of JUCE

A complete Rust reimplementation of the JUCE framework with FFI bindings for correctness testing. JUCE-RS provides safe, idiomatic Rust APIs for cross-platform audio application and plugin development.

Features

• 23 Complete Modules: Full implementation of all JUCE modules
• Cross-Platform: Windows, macOS, Linux, iOS, and Android support
• Audio Processing: Real-time audio buffers, MIDI handling, DSP effects
• Plugin Formats: VST3, AU, AAX, and LV2 support
• GUI Components: Complete widget library with customizable look-and-feel
• Thread-Safe: Leverages Rust's type system for safe concurrent programming
• Property-Based Testing: Extensive test suite ensuring correctness
• FFI Bindings: Interoperability with C++ JUCE for validation

Quick Start

Add JUCE-RS to your Cargo.toml:

[dependencies]
juce-core = "0.1"
juce-audio-basics = "0.1"
juce-audio-processors = "0.1"

Hello World Audio Plugin

use juce_audio_processors::{AudioProcessor, AudioProcessorEditor};
use juce_audio_basics::AudioBuffer;

struct MyPlugin {
    gain: f32,
}

impl AudioProcessor for MyPlugin {
    fn process_block(&mut self, buffer: &mut AudioBuffer<f32>, _midi: &MidiBuffer) {
        buffer.apply_gain(self.gain);
    }
    
    fn prepare_to_play(&mut self, sample_rate: f64, max_block_size: usize) {
        // Initialize your plugin
    }
    
    fn release_resources(&mut self) {
        // Clean up
    }
}

Audio Buffer Processing

use juce_audio_basics::AudioBuffer;

let mut buffer = AudioBuffer::<f32>::new(2, 512);

// Apply gain
buffer.apply_gain(0.5);

// Apply gain ramp
buffer.apply_gain_ramp(0.0, 1.0);

// Process each channel
for ch in 0..buffer.get_num_channels() {
    if let Some(samples) = buffer.get_write_pointer(ch) {
        for sample in samples.iter_mut() {
            *sample = sample.tanh(); // Soft clipping
        }
    }
}

MIDI Message Handling

use juce_audio_basics::{MidiMessage, MidiBuffer};

let mut midi_buffer = MidiBuffer::new();

// Add MIDI messages
midi_buffer.add_event(MidiMessage::note_on(1, 60, 100), 0);
midi_buffer.add_event(MidiMessage::note_off(1, 60, 0), 480);

// Process messages
for (message, timestamp) in midi_buffer.iter() {
    if message.is_note_on() {
        println!("Note: {} Velocity: {}", 
                 message.get_note_number(), 
                 message.get_velocity());
    }
}

GUI Components

use juce_gui_basics::{Component, Button, Label, Slider};

struct MyComponent {
    button: Button,
    slider: Slider,
}

impl Component for MyComponent {
    fn paint(&mut self, g: &mut Graphics) {
        g.fill_all(Colour::from_rgb(30, 30, 30));
    }
    
    fn resized(&mut self) {
        // Layout components
    }
}

Module Overview

Module	Description
juce-core	Strings, containers, files, threading, time, serialization
juce-events	Message queue, timers, broadcaster/listener patterns
juce-graphics	2D graphics, colors, images, fonts, rendering
juce-gui-basics	Components, widgets, windows, layout managers
juce-audio-basics	Audio buffers, MIDI, synthesis, sample formats
juce-audio-devices	Audio I/O, MIDI devices, device management
juce-audio-formats	WAV, AIFF, FLAC, MP3, Ogg Vorbis codecs
juce-audio-processors	Plugin infrastructure, VST3, AU, AAX, LV2
juce-dsp	Filters, oscillators, convolution, effects
juce-data-structures	ValueTree, UndoManager, application properties
juce-cryptography	RSA, Blowfish, MD5, SHA hashing
juce-opengl	OpenGL context, shaders, textures
juce-video	Video playback, camera capture
juce-osc	OSC message handling
juce-animation	Animation framework
juce-gui-extra	Code editor, web browser components
juce-box2d	Physics engine wrapper
juce-analytics	Analytics collection
juce-product-unlocking	Licensing, in-app purchases
juce-midi-ci	MIDI Capability Inquiry
juce-javascript	JavaScript engine integration

Documentation

Tutorials

• Getting Started - Complete beginner's guide
• Audio Plugin Tutorial - Build VST/AU/AAX plugins
• GUI Application Tutorial - Create complex user interfaces

Reference

• API Guide - Complete API documentation with examples
• Examples - Working code examples for all modules
• Migration Guide - Porting from C++ JUCE
• FFI Guide - Interoperability patterns and best practices
• Performance Benchmarks - Performance comparisons and optimization tips
• Optimization Guide - Performance optimization techniques and workflow
• Performance Optimization Summary - Overview of optimization infrastructure

Performance

JUCE-RS is designed to meet strict performance requirements:

• Audio Processing: Within 5% of C++ JUCE performance
• GUI Rendering: Within 10% of C++ JUCE performance
• SIMD Operations: Matches C++ JUCE performance

Benchmarking

Run comprehensive benchmarks:

cargo bench --manifest-path tests/benchmarks/Cargo.toml

View results:

# Open HTML report
open target/criterion/report/index.html  # macOS
xdg-open target/criterion/report/index.html  # Linux
start target\criterion\report\index.html  # Windows

Performance Profiling

Profile hot paths and identify optimization opportunities:

# Linux/macOS
./scripts/profile_performance.sh

# Windows
scripts\profile_performance.bat

Verify Performance Targets

Verify that all performance requirements are met:

# Linux/macOS
./scripts/verify_performance_targets.sh

# Windows
scripts\verify_performance_targets.bat

See Optimization Guide for detailed performance optimization techniques.

Prerequisites

• Rust 1.70+ (rustup update)
• CMake 3.15+
• C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2019+)
• Git with submodule support

Installation

Clone with JUCE submodule:

git clone --recursive https://github.com/yourusername/juce-rs.git
cd juce-rs

If already cloned without --recursive:

git submodule update --init --recursive

Build the project:

cargo build

Troubleshooting

Build fails with CMake errors

Ensure CMake 3.15+ is installed:

cmake --version

Linux Issues

Linker errors on Linux

Install required dependencies:

# Debian/Ubuntu
sudo apt-get install libasound2-dev libx11-dev libxext-dev libfreetype6-dev libwebkit2gtk-4.0-dev libglu1-mesa-dev

# Fedora/RHEL
sudo dnf install alsa-lib-devel libX11-devel libXext-devel freetype-devel webkit2gtk3-devel mesa-libGLU-devel

# Arch
sudo pacman -S alsa-lib libx11 libxext freetype2 webkit2gtk glu

Audio device access denied

Add your user to the audio group:

sudo usermod -aG audio $USER
# Log out and back in for changes to take effect

macOS Issues

Xcode Command Line Tools missing

Install Xcode Command Line Tools:

xcode-select --install

CMake not found

Install via Homebrew:

brew install cmake

Linker errors with system frameworks

Ensure Xcode is properly configured:

sudo xcode-select --reset
sudo xcodebuild -license accept

Code signing issues for audio plugins

For development, disable library validation:

codesign --force --deep --sign - target/debug/your_plugin.vst3

Permission denied for audio devices

Grant microphone/audio permissions in System Preferences → Security & Privacy → Privacy → Microphone

Windows Issues

MSVC not found

Install Visual Studio 2019 or later with "Desktop development with C++" workload:

• Download from Visual Studio
• Or install Build Tools: winget install Microsoft.VisualStudio.2022.BuildTools

CMake not found

Install via:

# Using winget
winget install Kitware.CMake

# Using chocolatey
choco install cmake

# Or download from https://cmake.org/download/

Rust MSVC toolchain issues

Ensure you're using the MSVC toolchain:

rustup default stable-msvc
rustup target add x86_64-pc-windows-msvc

Linker errors (LNK2019, LNK1120)

Make sure you're running from "Developer Command Prompt for VS" or:

# Add MSVC to PATH
"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"

DLL not found errors

Add the build directory to PATH or copy required DLLs:

$env:PATH += ";$PWD\target\debug"

Windows Defender blocking build

Add exclusion for your project directory:

Add-MpPreference -ExclusionPath "C:\path\to\juce-rs"

General Issues

Submodule not initialized

git submodule update --init --recursive

Cargo build hangs during C++ compilation

The first build compiles JUCE and can take 5-10 minutes. Subsequent builds are much faster due to caching.

Out of memory during build

Limit parallel jobs:

cargo build -j 2

FFI binding generation fails

Ensure cbindgen is installed:

cargo install cbindgen

Acknowledgments

Built on top of the excellent JUCE framework by Roli Ltd.

---

Made with ❤️ by the Rust audio community