Feat: Modernize PyTune - PyQt5 migration, Python 3 compatibility, and real-time playback features

[anubhuti24]

Overview

This PR modernizes the PyTune project by migrating from deprecated PyQt4 to PyQt5, updating all dependencies to Python 3.11.7 compatible versions, and adding significant new features including real-time audio playback with chord detection.

🎯 Key Changes

1. Dependency Updates & Modernization

• ✅ Migrated from PyQt4 to PyQt5 (v5.15.11)
• ✅ Updated Cython to v3.2.1 (from older versions)
• ✅ Updated NumPy to v2.3.5
• ✅ Updated SciPy to v1.16.3
• ✅ Added requirements.txt with pinned dependency versions
• ✅ All dependencies now compatible with Python 3.11.7

2. Python 3 Compatibility Fixes

Cython Module Updates (pytune/*.pyx)

• Import statements: Updated all relative imports to use pytune. prefix for proper module resolution
  • import functions → import pytune.functions
  • import notefinder → import pytune.notefinder
• Python 3 compatibility: Fixed zip() usage to return lists explicitly
  • zip(freqsl, weight) → list(zip(freqsl, weight))

Wave File Handling (pytune/wave2.pyx)

• Complete rewrite of getFromFile() function for Python 3 compatibility:
  • Removed Python 2-specific str filename type hints
  • Fixed byte/string handling for wave.readframes() (now returns bytes in Python 3)
  • Added support for multiple WAV formats:
    • 8-bit unsigned PCM (with proper signed conversion)
    • 16-bit PCM
    • 24-bit PCM (manual byte decoding)
    • 32-bit PCM and float32 WAV
  • Added multi-channel to mono conversion (averaging)
  • Improved error handling with FileNotFoundError and ValueError
  • Changed file mode from 'r' to 'rb' for binary reading

3. Main Application Enhancements (chordfinder.py)

PyQt5 Migration

• Replaced all PyQt4 imports with PyQt5 equivalents
• Updated signal/slot syntax to PyQt5 standards
• Fixed QFileDialog.getOpenFileName() to return tuple (PyQt5 behavior)

New Features

• 🎵 Real-time Audio Playback

  • Integrated QMediaPlayer for WAV file playback
  • Play/Pause/Stop controls with visual feedback
  • Real-time chord display during playback
  • Current playback time display (MM:SS.mm format)

• 📊 Automatic Song Analysis

  • Pre-analyzes entire song in 2-second segments on file load
  • Creates chord timeline for seamless playback experience
  • Background thread processing with progress updates

• 🎨 Enhanced UI Components

  • Improved waveform visualization with selection highlighting
  • Better marker system for start/end point selection
  • Enhanced chord display widget with main chord and alternatives
  • Selection info label showing time ranges and duration
  • Progress bar and status text for analysis operations

• 🔧 Code Quality Improvements

  • Better error handling and bounds checking
  • Improved thread safety for background operations
  • Cleaner signal/slot connections
  • More robust file handling

4. Documentation & Project Files

• ✅ Added comprehensive README.md with:
  • Project description and features
  • Step-by-step installation instructions using pyenv
  • Usage guidelines
  • Branch-specific information about updates
• ✅ Added .gitignore for Python projects:
  • Excludes __pycache__/, *.pyc, *.so, *.c files
  • Excludes build artifacts and virtual environments
  • Excludes IDE-specific files

📊 Statistics

• 8 files changed
• 715 insertions(+), 98 deletions(-)
• Major files modified:
  • chordfinder.py: +432 lines (new features and PyQt5 migration)
  • pytune/wave2.pyx: +123 lines (complete rewrite for Python 3)
  • README.md: +102 lines (new documentation)
  • .gitignore: +138 lines (new file)

🧪 Testing

• ✅ Tested with Python 3.11.7 using pyenv
• ✅ Verified Cython compilation with updated dependencies
• ✅ Tested WAV file loading (8/16/24/32-bit PCM, float32)
• ✅ Verified real-time playback and chord detection
• ✅ Tested waveform selection and segment analysis

📝 Migration Notes

For Users Upgrading:

1. Ensure Python 3.11.7 is installed via pyenv
2. Create new virtual environment as per README instructions
3. Install updated dependencies from requirements.txt
4. Recompile Cython extensions: python setup.py build_ext --inplace

Breaking Changes:

• Requires Python 3.11.7 (no longer compatible with Python 2.x)
• Requires PyQt5 (PyQt4 no longer supported)
• WAV file format required (other formats not supported)

🎉 Benefits

1. Future-proof: Compatible with modern Python and Qt versions
2. Better UX: Real-time playback with live chord detection
3. More Robust: Improved error handling and file format support
4. Easier Setup: Clear documentation and dependency management
5. Maintainable: Clean code structure and proper module imports

🔗 Related Issues

• Addresses deprecated library warnings
• Modernizes codebase for Python 3.x
• Adds requested playback features

---