# Piano Tutor App  ------   www.parturamusic.com

A comprehensive WPF-based piano learning application that helps you practice piano by combining MusicXML sheet music display with real-time MIDI input feedback and playback capabilities.

![Piano Tutor App](assets/MidiAppIcon.ico)

## 🎹 Features

### Core Functionality
- **MusicXML Support**: Load and display sheet music from MusicXML files (.musicxml, .xml)
- **Real-time MIDI Input**: Connect your MIDI keyboard for interactive practice
- **MIDI Playback**: Play back loaded scores with adjustable speed control
- **Visual Feedback**: Notes light up green when played correctly, red when incorrect
- **Practice Mode**: Select specific sections of music for focused practice
- **Solfege Note Names**: Optional display of note names (do, re, mi, etc.) when playing

### User Interface
- **Professional Score Rendering**: High-quality music notation using the Leland font
- **Interactive Canvas**: Click and drag to select practice sections
- **Zoom & Pan**: Mouse wheel zooming with Ctrl key, automatic panning during playback
- **Adjustable Spacing**: Customize note spacing for comfortable reading
- **Speed Control**: Adjust playback tempo from 50% to 150%

### MIDI Features
- **MIDI Input Device Selection**: Choose from available MIDI input devices
- **MIDI Output/Thru**: Route MIDI through to external devices or software
- **Real-time Note Detection**: Instant feedback on played notes
- **All Notes Off**: Automatic MIDI cleanup when stopping playback

## 🚀 Getting Started

### System Requirements
- Windows 10/11
- .NET 8.0 Runtime
- MIDI keyboard (optional but recommended)

### Installation
1. Download the latest release from the releases page on www.parturamusic.com
2. Extract the files to your desired location
3. Run `PianoTutorApp.exe`

### Important: Security Warning on First Launch
You might see a warning from Windows (a blue SmartScreen window) or your antivirus software when you first run the application. This is a standard security measure for applications from unknown developers.

**Why does this happen?**
The warning appears because the application is not signed with an official (and expensive) code signing certificate. Since I develop this project as a hobby and share it for free, I have chosen not to incur this cost.

**Is it safe?**
Yes! I guarantee that the code is written entirely by me and is completely safe. The application contains no viruses, malware, or spyware. I personally vouch for the quality and safety of this software.

**To bypass the warning:**
If you see the Windows SmartScreen prompt, you can safely bypass it by clicking "More info" and then "Run anyway".

## 📖 How to Use

### Basic Setup
1. **Connect your MIDI keyboard** to your computer via USB
2. **Launch Piano Tutor App**
3. **Select your MIDI device** from the "MIDI Input" dropdown
4. **Optionally select a MIDI output device** for MIDI thru functionality

### Loading Music
1. Click **File → Open MusicXML...** from the menu
2. Browse and select a MusicXML file
3. The sheet music will be displayed on the canvas

### Practice Mode
1. **Click and drag** on the score canvas to select a section for practice
2. Selected notes will appear in blue
3. **Play the selected notes** on your MIDI keyboard
4. Correct notes turn green, incorrect notes briefly flash red
5. **Click in empty space** to return to full score practice

### Playback
1. Click the **▶ Play** button to hear the loaded score
2. Use the **Speed slider** to adjust playback tempo
3. Click **■ Stop** to halt playback
4. The cursor will follow along during playback

### Controls
- **Spacing Slider**: Adjust horizontal spacing of notes (50%-200%)
- **Speed Slider**: Control playback speed (50%-150%)
- **Show Note Names**: Display solfege names (do, re, mi, etc.) when playing
- **Mouse Wheel + Ctrl**: Zoom in/out on the score
- **Horizontal Scrolling**: Navigate through longer pieces

## 🛠️ Technical Details

### Built With
- **Framework**: .NET 8.0 WPF
- **MIDI Library**: NAudio 2.2.1
- **Music Notation**: Leland font for professional music symbols
- **File Format**: MusicXML for sheet music import

### Architecture
The application follows a clean separation of concerns:
- **Models**: Data structures for musical elements
- **Parsing**: MusicXML file processing
- **Rendering**: Visual score display and interaction
- **MIDI Handling**: Real-time input/output processing

### Supported Features
- Treble and bass clef notation
- Time signatures
- Key signatures and accidentals
- Note articulations (staccato, accent, tenuto, marcato)
- Fingering annotations
- Slurs and musical expressions
- Rest notation
- Ledger lines

## 📁 File Structure

```
PianoTutorApp/
├── Models/              # Data models for musical elements
├── Parsing/             # MusicXML parsing logic
├── Rendering/           # Score visualization and rendering
├── Fonts/               # Leland music notation fonts
├── assets/              # Application icons and resources
└── MainWindow.xaml(.cs) # Main application interface
```

## 🎵 Sample Files

The application includes a sample file:
- `Jingle_Bells.musicxml` - A simple Christmas carol for testing

## 🐛 Troubleshooting

### MIDI Issues
- **No MIDI devices showing**: Ensure your MIDI keyboard is connected and drivers are installed
- **Notes not registering**: Check MIDI device selection and cable connections
- **Delayed response**: Try different MIDI buffer settings in your operating system

### Display Issues
- **Fonts not displaying correctly**: Ensure the Leland font files are in the Fonts/ directory
- **Score too small/large**: Use Ctrl + Mouse Wheel to zoom, or adjust spacing slider

### File Loading Problems
- **MusicXML won't load**: Ensure the file is a valid MusicXML format
- **Missing elements**: Some advanced MusicXML features may not be fully supported

## 🤝 Contributing

This is a hobby project, but contributions are welcome! Areas for improvement:
- Additional MusicXML feature support
- Enhanced MIDI functionality
- UI/UX improvements
- Performance optimizations

## 📜 License

### Freeware License Agreement

**Piano Tutor App** is distributed as **freeware** under the following terms and conditions:

#### Copyright Protection
This software and all associated documentation, source code, graphics, icons, and other materials ("Software") are **protected by copyright** under the laws of Belgium and international copyright treaties. All rights are reserved by the author.

#### Permitted Use
You are granted a **non-exclusive, non-transferable license** to:
- ✅ **Use** the Software for personal, educational, or non-commercial purposes
- ✅ **Install** the Software on multiple computers you own or control
- ✅ **Share** the Software with others by providing a link to the official download location www.parturamusic.com
- ✅ **Make backup copies** for archival purposes

#### Restrictions
You are **NOT permitted** to:
- ❌ **Sell, rent, lease, or sublicense** the Software
- ❌ **Reverse engineer, decompile, or disassemble** the Software
- ❌ **Modify, adapt, or create derivative works** based on the Software
- ❌ **Remove or alter** any copyright notices, trademarks, or licensing information
- ❌ **Distribute modified versions** of the Software
- ❌ **Use the Software for commercial purposes** without explicit written permission

#### Disclaimer and Limitation of Liability
The Software is provided **"AS IS"** without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. The author shall not be liable for any damages arising from the use of this Software.

#### Intellectual Property
All intellectual property rights in the Software remain the exclusive property of the author. This license does not grant you any rights to use trademarks, service marks, or trade names of the author.

#### Termination
This license is effective until terminated. Your rights under this license will terminate automatically without notice if you fail to comply with any term of this agreement.

#### Governing Law
This license agreement shall be governed by and construed in accordance with the laws of **Belgium**. Any disputes arising from this agreement shall be subject to the exclusive jurisdiction of the Belgian courts.

#### Contact
For permissions beyond the scope of this license, commercial use inquiries, or questions about this license, please contact the author through the project repository.

---

© 2024 Piano Tutor App. All rights reserved. This software is protected by copyright law and international treaties.

---

**Enjoy practicing piano with Piano Tutor App! 🎹🎶**