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
MIDI I/O: RtMidi
MIDI File Parsing: 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()

Hardware Thread: RtMidi captures key presses via a low-overhead driver callback. It instantly pushes lightweight events into the lock-free queue.
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):

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 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.