# 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.7+
- PyQt5
- pygame (for audio synthesis)
- python-rtmidi (for MIDI I/O)
- mido (for MIDI message handling)
- numpy (for audio processing)

### Setup
1. Clone or download the project
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
3. Run the application:
   ```bash
   python run.py
   ```

## 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.