arppegiator/INSTALL_WINDOWS.md

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:

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

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

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

pip install python-rtmidi

Option B: Specific working version

pip install python-rtmidi==1.5.8

Option C: Alternative MIDI library

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:

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:

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)

# 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

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