arppegiator/README_VENV.md

Virtual Environment Setup

This project now supports virtual environment setup for better dependency management and isolation.

Quick Setup

Windows

# Run the setup script
python setup_venv.py

# Activate the virtual environment (choose one)
activate.bat                 # Command Prompt
.\activate.ps1              # PowerShell

# Run the application
python run.py

# Or run directly without manual activation
run_in_venv.bat

Linux/Mac

# Run the setup script
python3 setup_venv.py

# Activate the virtual environment
source activate.sh

# Run the application  
python run.py

# Or run directly without manual activation
./run_in_venv.sh

What the Setup Script Does

1. Creates a virtual environment in the venv folder
2. Installs all dependencies from requirements files
3. Creates activation scripts for easy environment management
4. Verifies installation to ensure everything works
5. Handles MIDI library issues gracefully (falls back to simulator mode)

File Structure After Setup

arppegiator/
├── venv/                    # Virtual environment (created)
├── activate.bat             # Windows activation (created)
├── activate.ps1             # PowerShell activation (created) 
├── activate.sh              # Unix activation (created)
├── run_in_venv.bat          # Windows direct run (created)
├── run_in_venv.sh           # Unix direct run (created)
├── setup_venv.py            # Setup script (created)
├── requirements-dev.txt     # Development dependencies (created)
├── requirements.txt         # Main dependencies
├── requirements-windows.txt # Windows-specific dependencies
└── ... (rest of project files)

Manual Virtual Environment Setup

If the setup script doesn't work, you can set up manually:

# Create virtual environment
python -m venv venv

# Activate it
# Windows:
venv\Scripts\activate.bat
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python run.py

Development Setup

For development with additional tools:

# After setting up the main environment, install dev dependencies
pip install -r requirements-dev.txt

This includes:

• pytest - Testing framework
• pytest-qt - Qt application testing
• black - Code formatting
• flake8 - Code linting
• mypy - Type checking
• coverage - Code coverage analysis

Troubleshooting

Common Issues

1. Python version too old

• Requires Python 3.8 or newer
• Check with: python --version

2. Virtual environment creation fails

• Make sure venv module is available: python -m venv --help
• On Ubuntu/Debian: sudo apt install python3-venv

3. Permission errors on Windows

• Run Command Prompt/PowerShell as Administrator
• Or use: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

4. MIDI libraries fail to install

• This is normal on some systems
• The application will work in simulator mode
• For hardware MIDI, you may need Visual Studio Build Tools

5. PyQt5 installation fails

• Try: pip install --only-binary=PyQt5 PyQt5
• Or install from conda: conda install pyqt

Verifying Installation

Test that everything is working:

# With environment activated
python -c "
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 - Hardware MIDI available')
except: print('⚠️ RTMIDI not available - Simulator mode only')
print('🎹 Ready to run!')
"

Removing the Virtual Environment

To completely remove the virtual environment:

# Make sure you're not in the environment
deactivate

# Delete the environment folder
# Windows:
rmdir /s venv
# Linux/Mac:
rm -rf venv

# Also remove the activation scripts if desired
# Windows:
del activate.bat activate.ps1 run_in_venv.bat
# Linux/Mac: 
rm activate.sh run_in_venv.sh

Benefits of Virtual Environment

✅ Isolation: Dependencies don't conflict with other Python projects
✅ Reproducibility: Exact same versions across different machines
✅ Cleanliness: Easy to remove everything without affecting system Python
✅ Testing: Test with different dependency versions safely
✅ Distribution: Share exact environment with others

IDE Integration

VS Code

1. Open the project folder
2. VS Code should auto-detect the virtual environment in venv/
3. Select the Python interpreter: Ctrl+Shift+P → "Python: Select Interpreter"
4. Choose the one in venv/Scripts/python.exe (Windows) or venv/bin/python (Unix)

PyCharm

1. File → Settings → Project → Python Interpreter
2. Add → Existing Environment
3. Choose venv/Scripts/python.exe (Windows) or venv/bin/python (Unix)

Other IDEs

Point your IDE's Python interpreter to the one inside the venv folder.