JUCE Audio Processor

A high-performance native audio processor built with JUCE for Node.js and Electron applications, specifically designed for DJ software and real-time audio processing.

🎵 Features

• Real-time Audio Processing: Built on JUCE's industry-standard audio processing framework
• DJ Effects: Includes flanger, filter, pitch shifting, and volume control
• Dual Runtime Support: Works with both Node.js and Electron applications
• Cross-platform: Supports Windows, macOS, and Linux
• High Performance: Native C++ implementation for low-latency audio processing
• Lazy Initialization: Safe initialization for Electron environments
• Comprehensive Logging: Built-in debug logging for troubleshooting
• Version Agnostic: Works with any Node.js (14+) or Electron (37+) version

⚠️ Prerequisites

Before installing this package, you MUST install the following software:

Required Software

1. CMake (Required)

• Download: https://cmake.org/download/
• Version: 3.15 or higher
• Installation: Add CMake to your system PATH

2. C++ Build Tools (Required)

Windows:

• Visual Studio: 2019 or 2022 (with C++ build tools)
• Download: Visual Studio Community
• Required Components: C++ CMake tools, Windows 10/11 SDK

macOS:

• Xcode Command Line Tools: xcode-select --install
• Xcode: 12.0 or higher (for full development)

Linux:

• GCC: 7.0 or higher
• Build Essentials: sudo apt-get install build-essential

3. JUCE Framework (Required)

• Download: https://juce.com/get-juce
• Version: 6.0 or higher
• Installation: Extract to C:\JUCE (Windows) or /usr/local/JUCE (macOS/Linux)

System Requirements

• Node.js: 14.0.0 or higher (any version)
• Electron: 37.0.0 or higher (any version)
• Architecture: x64 and ARM64 (Apple Silicon)

🚀 Installation

Step 1: Install Prerequisites

Make sure you have installed all the required software above.

Step 2: Install the Package

For Node.js Applications:

npm install juce-audio-processor

For Electron Applications:

npm install juce-audio-processor
# The package will automatically detect Electron and build accordingly

Step 3: Verify Installation

# Test in Node.js
npm test

# Test in Electron
npm run test:electron

Troubleshooting Installation

Common Issues

1. "CMake not found" Error

Solution: Install CMake and add it to your PATH

• Windows: Restart your terminal after installing CMake
• macOS: brew install cmake
• Linux: sudo apt-get install cmake

2. "Visual Studio not found" Error (Windows)

Solution: Install Visual Studio with C++ build tools

• Download Visual Studio Community
• Select "Desktop development with C++" workload
• Include Windows 10/11 SDK

3. "JUCE not found" Error

Solution: Download and install JUCE framework

• Extract to C:\JUCE (Windows) or /usr/local/JUCE (macOS/Linux)
• Update CMakeLists.txt if needed

4. Build Fails During Installation

Solution: Check all prerequisites are installed

# Check CMake
cmake --version

# Check Visual Studio (Windows)
where cl

# Check GCC (macOS/Linux)
gcc --version

📖 Usage

Basic Usage

const JUCEAudioProcessor = require("juce-audio-processor");

// Create a new processor instance
const processor = new JUCEAudioProcessor();

// Check if processor is initialized
if (processor.isInitialized()) {
  console.log("Processor is ready!");
}

// Configure effects
processor.setVolume(0.8); // Set volume (0.0 to 1.0)
processor.setFlangerEnabled(true); // Enable/disable flanger
processor.setFlangerRate(0.5); // Set flanger rate (0.0 to 1.0)
processor.setFlangerDepth(0.3); // Set flanger depth (0.0 to 1.0)
processor.setFilterCutoff(1000); // Set filter cutoff frequency (Hz)
processor.setFilterResonance(1.2); // Set filter resonance (0.0 to 2.0)
processor.setPitchBend(2.0); // Set pitch bend in semitones
processor.setJogWheelPosition(0.5); // Set jog wheel position (0.0 to 1.0)

// Process audio
processor.processAudio(audioBuffer);

Electron Integration

const { app, BrowserWindow } = require("electron");
const JUCEAudioProcessor = require("juce-audio-processor");

app.whenReady().then(() => {
  try {
    const processor = new JUCEAudioProcessor();

    if (processor.isInitialized()) {
      console.log("Audio processor ready in Electron!");
      // Configure your audio processing here
    }
  } catch (error) {
    console.error("Failed to initialize audio processor:", error);
  }
});

🔧 API Reference

Constructor

• new JUCEAudioProcessor() - Creates a new audio processor instance

Initialization

• isInitialized() - Returns true if the processor is ready to use

Volume Control

• setVolume(volume) - Set master volume (0.0 to 1.0)

Flanger Effect

• setFlangerEnabled(enabled) - Enable or disable flanger effect (boolean)
• setFlangerRate(rate) - Set flanger rate (0.0 to 1.0)
• setFlangerDepth(depth) - Set flanger depth (0.0 to 1.0)

Filter

• setFilterCutoff(cutoff) - Set low-pass filter cutoff frequency in Hz
• setFilterResonance(resonance) - Set filter resonance (0.0 to 2.0)

Pitch Control

• setPitchBend(semitones) - Set pitch bend in semitones

Jog Wheel

• setJogWheelPosition(position) - Set jog wheel position (0.0 to 1.0)

Audio Processing

• processAudio(buffer) - Process audio buffer (implementation depends on your audio system)

️ Building from Source

Prerequisites

1. Install CMake
2. Install JUCE Framework
3. Set up your platform-specific build tools

Build Commands

# Clean build directory
npm run clean

# Build for Node.js
npm run build:node

# Build for Electron
npm run build:electron

# Build for both runtimes
npm run build

# Auto-detect runtime and build
npm run build:auto

# Rebuild (clean + build)
npm run rebuild

Platform-Specific Build Instructions

Windows

# Ensure Visual Studio is installed
npm run build:electron

macOS

# Ensure Xcode command line tools are installed
xcode-select --install
npm run build:electron

Linux

# Install build essentials
sudo apt-get update
sudo apt-get install build-essential cmake
npm run build:electron

Testing

Run Tests

# Test in Node.js
npm test

# Test in Electron
npm run test:electron

# Run example
npm run example

Debug Logging

The package includes comprehensive debug logging. Check these files:

• juce_debug.log - C++ and JavaScript logs
• electron_debug.log - Electron-specific logs

🐛 Troubleshooting

Common Issues

1. "Cannot find module" Error

Problem: Native addon not found Solution:

npm run clean
npm run build:electron

2. "DLL initialization routine failed" Error

Problem: Runtime mismatch between Node.js and Electron Solution: Rebuild for the correct runtime

npm run build:electron

3. "napi.h not found" Error

Problem: Missing node-addon-api dependency Solution:

npm install node-addon-api
npm run rebuild

4. CMake Not Found

Problem: CMake not installed or not in PATH Solution:

• Windows: Install from cmake.org
• macOS: brew install cmake
• Linux: sudo apt-get install cmake

5. JUCE Not Found

Problem: JUCE framework not installed Solution:

1. Download JUCE from juce.com
2. Extract to C:\JUCE (Windows) or /usr/local/JUCE (macOS/Linux)
3. Update CMakeLists.txt if needed

Debug Mode

Enable verbose logging:

# Set environment variable
set DEBUG=juce-audio-processor:*

# Run with debug output
npm run test:electron

📁 Project Structure

juce-audio-processor/
├── src/
│   ├── binding.cpp              # N-API bindings
│   ├── juce_audio_processor.h   # JUCE processor header
│   ├── juce_audio_processor.cpp # JUCE processor implementation
│   ├── audio-processor-mock.js  # Mock implementation
│   ├── audio-processor-child.js # Child process for Electron
│   └── audio-processor-wrapper.js # IPC wrapper
├── test/
│   ├── test.js                  # Node.js tests
│   ├── electron-test.js         # Electron tests
│   └── electron-test.html       # Electron test UI
├── scripts/
│   └── build-auto.js            # Auto-build script
├── build/                       # Build output directory
├── CMakeLists.txt              # CMake configuration
├── package.json                # NPM package configuration
├── index.js                    # Main entry point
└── README.md                   # This file

🔄 Version Compatibility

| Package Version | Node.js | Electron | JUCE | CMake | | --------------- | ------- | -------- | ---- | ----- | | 1.0.15+ | 14.0.0+ | 37.0.0+ | 6.0+ | 3.15+ |

Note: This package is designed to work with any Node.js version 14+ and any Electron version 37+. The build system automatically detects and builds for the correct runtime version.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/iagomartins/juce-audio-processor.git
cd juce-audio-processor
npm install
npm run build
npm test

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

🙏 Acknowledgments

• JUCE Framework for the audio processing foundation
• Node.js N-API for native addon support
• CMake.js for cross-platform building

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

🔗 Links

• Homepage: https://github.com/iagomartins/juce-audio-processor
• NPM Package: https://www.npmjs.com/package/juce-audio-processor
• Documentation: https://github.com/iagomartins/juce-audio-processor#readme

Made with ❤️ for the audio development community