MIDI Arpeggiator - Lighting Controller

A modular MIDI arpeggiator application with integrated lighting control and Native Instruments Maschine support.

Features

Core Functionality

• FL Studio-style Arpeggiator: Complete arpeggiator with up/down/random patterns, scales, swing, gate control
• Multi-Synth Support: Control up to 16 synthesizers simultaneously with individual voice management
• Volume/Brightness Patterns: Dynamic volume patterns that control both audio levels and lighting brightness
• Routing Patterns: Spatial routing patterns for creating lighting effects (bounce, wave, cascade, etc.)

Audio & MIDI

• Dual Output Modes: Built-in simulator with audio synthesis or external hardware MIDI output
• Program Change Support: Individual instrument selection per channel with General MIDI compatibility
• Voice Management: 3-voice polyphony per synthesizer with intelligent voice stealing
• Real-time MIDI Processing: High-precision timing for tight synchronization

Lighting Control

• MIDI-Controlled Lighting: Each synth doubles as a lighting fixture controlled by MIDI notes
• Visual Patterns: Specialized patterns designed for lighting effects (ripple, spotlight, cascade)
• Brightness Control: Volume and velocity control lighting brightness in real-time
• Pattern Coordination: Synchronize musical and visual patterns for cohesive shows

Hardware Integration

• Native Instruments Maschine: Full integration with Maschine controllers for hands-on control
• Real-time Control: Pads, encoders, and buttons mapped to arpeggiator parameters
• LED Feedback: Visual feedback on Maschine pads showing current state and activity
• Multiple Control Modes: Switch between note input, channel control, and pattern selection modes

User Interface

• Modular GUI: Clean PyQt5 interface with tabbed control panels
• Real-time Visualization: Visual representation of synth array with lighting simulation
• Preset System: Save and recall complete system configurations
• Configuration Management: Persistent settings with intelligent defaults

Installation

Requirements

• Python 3.8+
• PyQt5
• pygame (for audio synthesis)
• python-rtmidi (for MIDI I/O)
• mido (for MIDI message handling)
• numpy (for audio processing)

Quick Setup (Recommended - Virtual Environment)

Automatic setup with isolated environment:

# Clone the project
git clone <repository-url>
cd arppegiator

# Run the virtual environment setup script
python setup_venv.py

# Activate the virtual environment and run
# Windows:
activate.bat && python run.py
# Or directly:
run_in_venv.bat

# Linux/Mac:
source activate.sh && python run.py
# Or directly:
./run_in_venv.sh

See README_VENV.md for detailed virtual environment documentation.

Manual Setup (Global Environment)

1. Clone or download the project
2. Install dependencies:

   # Standard installation
   pip install -r requirements.txt
      
   # Windows-specific (if above fails)
   pip install -r requirements-windows.txt
   

3. Run the application:

   python run.py
   

Platform-Specific Installation

Windows:

# If you get compilation errors, use the Windows installer:
python install_windows.py

# Then run:
python run.py

Linux/Mac:

# Standard installation should work:
pip install -r requirements.txt
python run.py

Troubleshooting Installation

If you encounter issues, see:

• README_VENV.md - Virtual environment setup and troubleshooting
• INSTALL_WINDOWS.md - Windows-specific installation guide

Module Structure

Core Modules (core/)

• midi_channel_manager.py: MIDI channel management and voice allocation
• arpeggiator_engine.py: Main arpeggiator logic and pattern generation
• volume_pattern_engine.py: Volume and brightness pattern generation
• synth_router.py: Note routing and spatial pattern management
• output_manager.py: MIDI output handling (simulator vs hardware)

GUI Modules (gui/)

• main_window.py: Main application window and layout
• arpeggiator_controls.py: Arpeggiator parameter controls
• channel_controls.py: MIDI channel and instrument management
• volume_controls.py: Volume/brightness pattern controls
• simulator_display.py: Visual synth array display
• output_controls.py: Output mode and device selection
• preset_controls.py: Preset management interface

Simulator Module (simulator/)

• simulator_engine.py: Internal audio synthesis and lighting simulation

Maschine Integration (maschine/)

• maschine_interface.py: Low-level Maschine MIDI communication
• maschine_controller.py: High-level Maschine integration controller

Configuration (config/)

• configuration.py: Application settings and persistence

Usage

Basic Operation

1. Select Output Mode: Choose between "Simulator" (internal audio) or "Hardware" (external MIDI)
2. Configure Channels: Set number of active synths and assign instruments
3. Set Arpeggiator Parameters: Choose root note, scale, pattern, tempo, etc.
4. Configure Patterns: Select routing patterns for spatial effects and volume patterns for brightness
5. Play Notes: Use computer keyboard, MIDI controller, or Maschine to trigger arpeggiator

Maschine Integration

1. Connect Native Instruments Maschine hardware
2. Enable Maschine integration in settings
3. Use pads to trigger notes, encoders for real-time parameter control
4. Switch pad modes for different control functions
5. LED feedback shows current state and activity

Lighting Control

• Each synthesizer channel corresponds to a lighting fixture
• Note velocity and channel volume control brightness
• Volume patterns create dynamic lighting effects
• Routing patterns determine which lights activate for each note

Preset Management

• Save current settings as named presets
• Load presets for quick configuration changes
• Import/export presets to share configurations
• Automatic preset backup and recovery

Configuration

The application creates a config.json file with all settings. Key configuration sections:

• Audio: Sample rate, buffer size, master volume
• MIDI: Default devices and connection settings
• Arpeggiator: Default parameters and ranges
• Channels: Default synth count and instruments
• Volume Patterns: Default patterns and ranges
• Maschine: Hardware integration settings
• Interface: Theme and display preferences

Troubleshooting

Audio Issues

• Check audio device selection in system settings
• Try different buffer sizes if experiencing dropouts
• Ensure sample rate matches system audio settings

MIDI Issues

• Refresh MIDI device list if devices not appearing
• Check MIDI device connections and drivers
• Use "Panic" button to stop stuck notes

Maschine Issues

• Ensure Maschine is in MIDI mode, not Controller mode
• Check USB connection and drivers
• Try disconnecting/reconnecting if not responding

Architecture Notes

The application uses a modular architecture with clear separation of concerns:

• Core modules handle the core arpeggiator logic and MIDI processing
• GUI modules provide the user interface without business logic
• Simulator module provides standalone audio synthesis
• Maschine module handles hardware integration
• Configuration module manages persistence and settings

This design makes the application easy to understand, maintain, and extend with new features.

License

This project is open source. See LICENSE file for details.