# Windows Installation Guide

## Requirements

- **Python 3.8 or newer** (check with `python --version`)
- Windows 10 or newer (older versions may work but aren't tested)

## Recommended: Virtual Environment Setup (New!)

**Best option for most users - completely isolated and automated:**

```bash
# Download/clone the project, then run:
python setup_venv.py

# Run the application:
run_in_venv.bat
# Or manually activate and run:
activate.bat
python run.py
```

The virtual environment setup will:
- Create an isolated Python environment
- Install all dependencies automatically
- Handle MIDI library issues gracefully  
- Create convenient activation scripts
- Work in simulator mode if MIDI fails

See [README_VENV.md](README_VENV.md) for detailed virtual environment documentation.

## Legacy Installation Options

### Quick Installation (Global Environment)

If you prefer global installation or the virtual environment setup doesn't work, use this Windows-specific installer:

```bash
python install_windows.py
```

This script will:
- Install core packages (PyQt5, numpy, pygame, mido)
- Try multiple MIDI library options
- Create fallbacks if MIDI libraries fail
- Still work in simulator mode even if MIDI fails

## Manual Installation (if the script doesn't work)

### 1. Install Core Packages First
```bash
pip install PyQt5>=5.15.0
pip install numpy>=1.21.0
pip install pygame>=2.1.0
pip install mido>=1.2.10
```

### 2. Try MIDI Library Installation
Try these in order until one works:

**Option A: Latest python-rtmidi**
```bash
pip install python-rtmidi
```

**Option B: Specific working version**
```bash
pip install python-rtmidi==1.5.8
```

**Option C: Alternative MIDI library**
```bash
pip install rtmidi-python
```

**Option D: Skip MIDI (simulator only)**
If all MIDI libraries fail, you can still use the application in simulator mode with built-in audio synthesis.

## Common Issues and Solutions

### Issue 1: Cython Compilation Error
```
Error compiling Cython file... Cannot assign type 'void (*)'...
```
**Solution:** Install Visual Studio Build Tools or use pre-compiled wheel:
```bash
pip install --only-binary=python-rtmidi python-rtmidi
```

### Issue 2: No MIDI Devices Found
**Solutions:**
1. Use simulator mode (works without any MIDI hardware)
2. Check Windows MIDI device drivers
3. Try different USB ports for MIDI devices

### Issue 3: Audio Not Working
**Solutions:**
1. Check Windows audio device settings
2. Try different audio buffer sizes in the app settings
3. Make sure no other applications are using audio exclusively

## Verify Installation

Run this to test if everything works:
```bash
python -c "
try:
    import PyQt5; print('✓ PyQt5 OK')
    import numpy; print('✓ NumPy OK') 
    import pygame; print('✓ Pygame OK')
    import mido; print('✓ Mido OK')
    try:
        import rtmidi; print('✓ RTMIDI OK')
    except: print('⚠ RTMIDI failed - simulator mode only')
    print('Ready to run!')
except Exception as e:
    print(f'✗ Error: {e}')
"
```

## Running the Application

### Virtual Environment (Recommended)
```bash
# Option 1: Direct run (easiest)
run_in_venv.bat

# Option 2: Manual activation
activate.bat
python run.py

# Option 3: PowerShell users
.\activate.ps1
python run.py
```

### Global Installation
```bash
python run.py
```

The application will start in simulator mode by default, which works without any MIDI hardware and provides:
- Internal audio synthesis
- Visual lighting simulation  
- All arpeggiator functionality
- Complete GUI interface

For hardware MIDI, select "Hardware Mode" in the Output Controls tab.

## Which Installation Method Should I Use?

**Use Virtual Environment if:**
- You're new to Python or want the easiest setup
- You want to avoid conflicts with other Python projects
- You want the most reliable installation experience
- You plan to develop or modify the code

**Use Global Installation if:**
- You prefer installing packages system-wide
- You're experienced with Python dependency management
- You're already managing your Python environment manually