# MIDI Arpeggiator - Usage Guide

## 🎹 How to Use the Arpeggiator

### Quick Start
1. **Run the application**: `python run.py`
2. **Play notes**: Use keyboard keys (see below) or click Play for test notes
3. **Start arpeggiator**: Press SPACEBAR or click Play button
4. **Stop arpeggiator**: Press SPACEBAR again or click Stop button

### 🎵 Playing Notes with Computer Keyboard

Use these keys to play notes (like a piano):
```
  W   E       T   Y   U    
 A S D  F   G H J  K L ;   
```

**Key Mapping:**
- **A** = C (Middle C - note 60)
- **W** = C# (sharp)
- **S** = D
- **E** = D# (sharp)
- **D** = E
- **F** = F
- **T** = F# (sharp)
- **G** = G
- **Y** = G# (sharp)
- **H** = A
- **U** = A# (sharp)
- **J** = B
- **K** = C (next octave)

**Controls:**
- **SPACEBAR** = Start/Stop arpeggiator
- **Hold multiple keys** = Play chords
- **Release keys** = Stop notes

### 🎛️ Simulator Mode (Default)
- **Built-in audio synthesis** - hear sounds directly from the app
- **Visual lighting display** - see synth array with brightness patterns
- **No external hardware needed** - perfect for testing and development

**What you should hear/see:**
- ✅ Audio when notes are triggered by the arpeggiator
- ✅ Visual synths lighting up in patterns
- ✅ Different instruments per channel
- ✅ Volume patterns creating lighting effects

### 🔌 Hardware MIDI Mode
Switch to hardware mode in the "Output" tab:
1. Click **"Hardware Mode"** radio button
2. Select your MIDI device from dropdown
3. Connect to external synthesizer/software

**Available MIDI Devices** (from your system):
- Microsoft GS Wavetable Synth (built-in Windows synth)
- LoopBe Internal MIDI (virtual MIDI cable)
- Other virtual MIDI devices

### 🎚️ Controls

#### Arpeggiator Tab
- **Root Note**: Starting note (default: C4)
- **Scale**: Musical scale (Major, Minor, Dorian, etc.)
- **Pattern**: Up, Down, Up-Down, Random, etc.
- **Octave Range**: 1-4 octaves
- **Tempo**: 40-200 BPM
- **Note Speed**: 1/32 to whole notes
- **Gate**: Note length (10%-200%)
- **Swing**: Timing swing (-100% to +100%)
- **Velocity**: Note velocity (1-127)

#### Channels Tab
- **Active Synths**: 1-16 synths
- **Instruments**: Individual GM instruments per channel
- **Global Instrument**: Apply same instrument to all channels
- **Voice Monitoring**: See active voices per channel

#### Volume/Lighting Tab
- **Pattern**: Volume patterns (Static, Swell, Breathing, Wave, etc.)
- **Speed**: Pattern speed multiplier
- **Intensity**: Pattern intensity
- **Global Ranges**: Min/max volume and velocity for all channels
- **Individual Ranges**: Per-channel volume and velocity ranges

#### Output Tab
- **Mode Selection**: Simulator vs Hardware
- **MIDI Device**: Select hardware MIDI output
- **Test Output**: Send test note
- **Panic**: All notes off

#### Presets Tab
- **Save/Load**: Store and recall complete configurations
- **Import/Export**: Share presets with others
- **Rename/Delete**: Manage preset library

### 🎪 Lighting Effects

The arpeggiator creates synchronized lighting effects:

**Routing Patterns** (which synths play):
- **Bounce**: Notes bounce between first and last synths
- **Cycle**: Notes rotate through all synths
- **Wave**: Smooth wave motion across synths
- **Random**: Random synth selection for sparkle effects

**Volume Patterns** (brightness control):
- **Swell**: Gradual volume increase/decrease
- **Breathing**: Rhythmic in/out like breathing
- **Wave**: Sine wave across channels
- **Cascade**: Volume cascade across synths
- **Random Sparkle**: Random volume variations

### 🔧 Troubleshooting

#### No Audio in Simulator Mode
- Check Windows audio settings
- Ensure no other app is using audio exclusively
- Try adjusting master volume in simulator controls
- Check audio device in Windows sound settings

#### No Sound in Hardware Mode
- **Microsoft GS Wavetable Synth**: Check Windows volume mixer - might be muted
- **Virtual MIDI**: Make sure receiving software synth is running
- **External Hardware**: Check MIDI cables and device settings
- Use "Test Output" button to verify MIDI connection

#### Keyboard Input Not Working
- Make sure main window has focus (click on it)
- Keys only work when window is active
- Try clicking in the window then pressing keys

#### Performance Issues
- Reduce active synth count if sluggish
- Lower volume pattern update rate
- Close other resource-intensive applications

### 💡 Tips for Best Results

1. **Start Simple**: Use default settings, add a few notes, press Play
2. **Experiment with Patterns**: Try different arp patterns and routing patterns
3. **Layer Effects**: Combine musical patterns with volume patterns for cool visuals
4. **Use Presets**: Save configurations you like for quick recall
5. **Hardware Setup**: Use virtual MIDI cables to connect to software synths like VCV Rack, Ableton Live, etc.

### 🎨 Art Installation Usage

For your art installation:
1. Set **Active Synths** to match your physical synth count (1-16)
2. Configure **Routing Patterns** for spatial lighting effects
3. Set **Volume Patterns** for dynamic brightness
4. Use **Hardware Mode** to send MIDI to your synth array
5. **Maschine Integration** for live control (when connected)

Each synth channel will control both the audio synthesis and lighting brightness simultaneously!

---

**Have fun creating amazing arpeggiated lighting shows!** 🌟