# Virtual Environment Setup

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

## Quick Setup

### Windows
```bash
# 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
```bash
# 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:

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

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

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

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