86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
# 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.
|