# volaTileMidi 🎹✨

A high-performance, cross-platform MIDI visualizer and interactive piano trainer written in modern C++. 

The name is a geeky nod to the C++ `volatile` keyword and the smooth, cascading visual notes (**vola-Tile**) that stream down to your keyboard. It connects directly to your USB MIDI piano to offer real-time interaction with zero perceived latency.

---

## 🚀 Features

* **Real-time MIDI Input:** Connects to any USB/Midi keyboard instantly using `RtMidi`.
* **Lock-Free Architecture:** Uses a custom Single-Producer Single-Consumer (SPSC) lock-free ring buffer to forward MIDI events from the driver thread to the main loop without blocking or stuttering.
* **Modern 2D Rendering:** Powered by `SDL3` leveraging GPU acceleration for perfectly smooth rendering at high refresh rates.
* **Accurate MIDI Parsing:** Pre-calculates MIDI track events from `.mid` files using `libremidi`, converting native MIDI ticks into absolute time seconds while fully respecting mid-song tempo changes.
* **Resolution Independent:** Uses a logical rendering viewport size ensuring the falling tiles and keyboard stay perfectly proportioned regardless of your window size or monitor aspect ratio.
* **Cross-Platform:** Built from the ground up to compile and run natively on both **Windows** and **Linux** (ALSA/PipeWire).

---

## 🛠️ Tech Stack & Dependencies

* **Language:** Modern C++ (C++20 recommended)
* **Build System:** CMake
* **Windowing & Graphics:** [SDL3](https://github.com/libsdl-org/SDL)
* **MIDI I/O:** [RtMidi](https://github.com/garyscavone/rtmidi)
* **MIDI File Parsing:** [libremidi](https://github.com/jcelerier/libremidi)

---

## 🏗️ Architecture Architecture Overview

The core design centers around a `CoreManager` class that orchestrates the engine lifecycle, ensuring a strict separation between hardware input, logic updates, and presentation:

```
[ USB Piano Input ] ──> (RtMidi Driver Thread / Lambda)
│
[ SpscMidiQueue (Lock-Free) ]
│
▼
[ SDL3 Main Loop ] ──> CoreManager::update() ──> CoreManager::render()
```

1. **Hardware Thread:** `RtMidi` captures key presses via a low-overhead driver callback. It instantly pushes lightweight events into the lock-free queue.
2. **Main Loop Thread:** The `CoreManager` pumps OS events, consumes all pending live MIDI events, updates the scrolling timeline based on a precise delta time, and renders the active shapes to the screen.

---

## 📦 Building from Source

### Prerequisites

Make sure you have a C++20 compliant compiler, CMake, and the necessary development packages installed.

#### On Linux (Ubuntu/Debian example):
```bash
sudo apt update
sudo apt install build-essential cmake libasound2-dev libjack-jackd2-dev
# Install SDL3 from source or repository when fully available on your distro
```

# Clone the repository
git clone [https://github.com/yourusername/volaTileMidi.git](https://github.com/yourusername/volaTileMidi.git)
cd volaTileMidi

# Configure CMake
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build the project
cmake --build build --config Release

🗺️ Roadmap / Todo
[ ] Initialize SDL3 window context and abstract coordinate system viewport.

[ ] Implement the SpscMidiQueue lock-free ring buffer.

[ ] Bind RtMidi with a non-capturing lambda callback forwarding to CoreManager.

[ ] Render the basic 88-key static virtual keyboard.

[ ] Integrate libremidi parser for absolute timeline conversion (Ticks ➔ Seconds).

[ ] Implement the interactive "Practice Mode" where the scrolling pauses until the correct key is pressed.

📄 License
This project is open-source. Feel free to use, modify, and distribute it as you see fit.