Skip to content

README.md

Latest commit

 

History

History
299 lines (222 loc) · 9.65 KB

README.md

File metadata and controls

299 lines (222 loc) · 9.65 KB
Raw

Musical Dynamics Training Software

Python 3.8+ License: MIT Code style: black

A Python application that helps pianists practice and visualize their dynamic expression in real-time using MIDI input from digital pianos.

🎹 Features

  • Real-time Dynamics Visualization: See your playing dynamics as colored bars above each piano key
  • Musical Notation Display: Shows current dynamics level (pp, p, mp, mf, f, ff, etc.)
  • MIDI Input Support: Works with any MIDI-compatible digital piano or keyboard
  • Visual Feedback: Color-coded bars that respond to your playing intensity
  • Cross-platform: Works on Windows, macOS, and Linux

🎯 Purpose

While there are many programs that help learn to play piano or improve sight-reading, few focus specifically on practicing and fine-tuning dynamic expression. This software fills that gap by providing immediate visual feedback on your dynamic control.

📸 Screenshots

Application Screenshot

The application shows colored bars above each piano key indicating the velocity/dynamics of your playing.

🚀 Quick Start

Prerequisites

  • Python 3.8 or higher
  • A MIDI-compatible digital piano or keyboard (optional - you can use mock mode)
  • MIDI drivers installed on your system (for real MIDI devices)

Installation

  1. Clone the repository:

    git clone https://github.com/scottroot/Piano-Dynamics-Midi-Trainer.git
cd Piano-Dynamics-Midi-Trainer

  2. Install the package:

    pip install -e .

Running the Application

Option 1: With a Real MIDI Device

  1. Connect your MIDI device and ensure it's recognized by your system
  2. List available MIDI ports (optional): 
    musical-dynamics-trainer --list-ports
  3. Run the application: 
    # Use default MIDI port (usually port 0)
musical-dynamics-trainer

# Or specify a specific port
musical-dynamics-trainer --port 1

Option 2: Without a MIDI Device (Mock Mode)

Perfect for testing or when you don't have a MIDI device handy:

musical-dynamics-trainer --mock-midi

This will simulate MIDI input automatically, playing random notes every second so you can see how the visualization works.

Option 3: Try the Basic Example

Want to see the core functionality without the GUI? Run the basic usage example:

python examples/basic_usage.py

This demonstrates the dynamics mapping, MIDI key conversion, and color coding without needing any MIDI hardware.

Command Line Options

# Basic usage
musical-dynamics-trainer                    # Use default MIDI port
musical-dynamics-trainer --port 1          # Use specific MIDI port
musical-dynamics-trainer --mock-midi       # Use mock MIDI (no device needed)

# Information and debugging
musical-dynamics-trainer --list-ports      # Show available MIDI ports
musical-dynamics-trainer --verbose         # Enable detailed logging
musical-dynamics-trainer --help            # Show all options
musical-dynamics-trainer --version         # Show version info

🎮 How to Use

  1. Launch the application using one of the methods above
  2. If using a real MIDI device: Play your piano - you'll see colored bars appear above the keys you press
  3. If using mock mode: The app will automatically simulate playing, showing you how the visualization works
  4. Observe the dynamics - the top of the window shows your current dynamics level
  5. Practice control - try to maintain consistent dynamics or practice crescendos/diminuendos
  6. Press Escape to exit the application

Dynamics Mapping

Velocity Range Dynamics Description Color
1-8 pppp Extremely soft Dark blue
9-31 pp Very soft Blue
32-53 p/mp Soft/Moderately soft Light blue
54-79 mf Moderately loud Purple
80-95 f Loud Orange
96-127 ff/fff Very loud/Extremely loud Red

🛠️ Development

Setting Up Development Environment

  1. Clone and install development dependencies:

    git clone https://github.com/scottroot/Piano-Dynamics-Midi-Trainer.git
cd Piano-Dynamics-Midi-Trainer
make dev-setup

  2. Run tests:

    make test

  3. Check code quality:

    make check

Project Structure

Musical-Dynamics-Training-Software/
├── src/musical_dynamics/     # Main package
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # Command-line entry point
│   ├── config.py            # Configuration settings
│   ├── constants.py         # MIDI mappings and constants
│   ├── gui.py              # Tkinter GUI implementation
│   └── midi_handler.py     # MIDI input processing
├── tests/                   # Test suite
├── docs/                    # Documentation
├── examples/                # Usage examples
├── img/                     # Images and assets
├── pyproject.toml          # Package configuration
├── requirements.txt        # Runtime dependencies
├── requirements-dev.txt    # Development dependencies
└── README.md              # This file

Available Make Commands

make help          # Show all available commands
make install       # Install package in development mode
make install-dev   # Install development dependencies
make test          # Run tests
make test-cov      # Run tests with coverage
make lint          # Run linting checks
make format        # Format code with black
make clean         # Clean build artifacts
make build         # Build package
make check         # Run all quality checks

🧪 Testing

The project includes comprehensive tests for all core functionality:

# Run all tests
pytest

# Run with coverage report
pytest --cov=musical_dynamics --cov-report=html

# Run specific test file
pytest tests/test_constants.py

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Run quality checks: make check
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

📋 Requirements

Runtime Dependencies

  • numpy>=1.18.1,<2.0.0
  • rtmidi>=1.4.0,<2.0.0

Development Dependencies

  • pytest>=7.0.0,<8.0.0
  • pytest-cov>=4.0.0,<5.0.0
  • black>=23.0.0,<24.0.0
  • flake8>=6.0.0,<7.0.0
  • mypy>=1.0.0,<2.0.0
  • pre-commit>=3.0.0,<4.0.0

🐛 Troubleshooting

Common Issues

"No MIDI ports found"

  • Ensure your MIDI device is connected and drivers are installed
  • Try running musical-dynamics-trainer --list-ports to see available ports
  • On Windows, you may need to install ASIO drivers
  • No MIDI device? Use musical-dynamics-trainer --mock-midi to test without hardware

"Failed to open MIDI input"

  • Check that your MIDI device is not being used by another application
  • Try a different MIDI port number
  • Restart your MIDI device
  • Still having issues? Try mock mode to verify the application works: musical-dynamics-trainer --mock-midi

"Piano image not found"

  • The application will run without the background image
  • Ensure the img/piano_3.png file is in the correct location

"Application won't start"

  • Make sure you've installed the package: pip install -e .
  • Check your Python version: python --version (needs 3.8+)
  • Try running with verbose logging: musical-dynamics-trainer --verbose

Quick Solutions

Want to test the app without MIDI hardware?

musical-dynamics-trainer --mock-midi

Want to see what the app does without the GUI?

python examples/basic_usage.py

Having MIDI connection issues?

  1. First try: musical-dynamics-trainer --list-ports
  2. If no ports show up, check your MIDI device drivers
  3. If ports show up but connection fails, try different port numbers
  4. As a last resort, use mock mode to test the application

Getting Help

  • Check the Issues page
  • Create a new issue with detailed information about your problem
  • Include your operating system, Python version, and MIDI device information
  • Try mock mode first to confirm the application works on your system

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • python-rtmidi: For MIDI input handling capabilities
  • Tkinter: For the GUI framework
  • NumPy: For numerical operations
  • The open source community: For inspiration and tools

📈 Roadmap

  • Support for different piano layouts
  • Recording and playback functionality
  • Statistical analysis of dynamics patterns
  • Customizable color schemes
  • Export functionality for practice sessions
  • Integration with music notation software

📞 Contact

Happy practicing! 🎹✨