MELOPHOS

Song made visible. An open instrument learning platform.

Documentation · Roadmap · Discussions · Contributing

I have monocular vision, which makes judging depth and scanning across a wide 88-key keyboard harder than it looks. Light-up keyboards helped, but every one I found was locked to one brand's app, one instrument and a subscription.

MELOPHOS is the tool I wanted: lights on a single flat line right where my hands are, any instrument I own now or later and my practice data kept on my own server.

The name, pronounced MEL-oh-fos, joins two Greek words:

Together they describe what the hub does: it turns the notes of a song into light you can follow, which is where the tagline comes from: song made visible.

MELOPHOS is the sister project of PHAEMOS, named the same way. The phos in MELOPHOS and the phaen- in PHAEMOS ("to reveal, to bring to light") go back to the same ancient root, meaning "to shine". One project brings failing machines to light, the other brings music to light.

flowchart LR
    INST["Keyboard or guitar"] -- "USB-MIDI, Bluetooth MIDI,<br/>MIDI jack or audio" --> HUB["Hub<br/>ESP32-S3"]
    HUB --> LED["LED bars<br/>above keys and frets"]
    HUB -- MQTT --> SRV["Server<br/>FastAPI"]
    SRV --> DB[("Postgres and<br/>TimescaleDB")]
    SRV <-->|HTTPS and WebSocket| STUDIO["Studio<br/>browser app"]
    SRV --> INT["Spotify, WLED,<br/>Home Assistant and webhooks"]

The hub sits behind the instrument, reads every note and lights the notes to play next. It sends each practice session to a server you host yourself, where a Rust scoring engine measures accuracy and timing. Studio, the browser app, holds the song library and shows your progress. The full picture is in docs/architecture.md.

• Light-guided practice. LEDs above each key or along a fretboard show the next notes to play. Melody waits for the right note, Rhythm holds a set tempo and Listen plays the piece through.
• Any instrument. Notes arrive over USB-MIDI, Bluetooth MIDI, MIDI jacks or an audio input. Each instrument is described by an open profile, so a new keyboard or a guitar is a configuration change rather than a rebuild.
• Practice you can see. Every note is logged against a session and the server turns sessions into streaks, accuracy, tempo progress and per-key heatmaps.
• Accessible by design. Guidance sits on one flat line, colour is never the only signal and timing cues are visual as well as audible.
• Self-hosted. One docker compose command runs the whole server stack on a home server or a small VPS.
• Open hardware and software. CERN-OHL-S boards and AGPL code, with every design file in the open.

The written plan, with targets for each version, is in docs/roadmap.md.

Languages

C++	Rust	Python	TypeScript

Hub and hardware

ESP32	Arduino	PlatformIO	FastLED	KiCad

Server and data

FastAPI	PostgreSQL	TimescaleDB	MQTT	Docker

Studio

Vite	WebAssembly	Web MIDI	Web Bluetooth

Instrument profiles

JSON

Every component repository is a read-only copy published from the monorepo. Issues, discussions and pull requests all go to melophos/melophos.

• Start here: the welcome post and the roadmap post
• Try it without a hub: run MELOPHOS on a laptop with the hub simulator
• Questions and ideas: Discussions, with Q&A for help and Research for papers and datasets
• Bugs and feature requests: issues on the monorepo
• First contribution: an instrument profile for a keyboard or guitar that is not covered yet
• Contributing: the contributing guide
• Security: report vulnerabilities privately through the security policy

The software is licensed under AGPL-3.0-or-later and the hardware designs under CERN-OHL-S-2.0. NOTICE.md explains which licence covers what.