KeySelector ist ein browserbasiertes DJ-Tool, das dir dabei hilft, harmonisch passende Tracks für dein nächstes Set zu finden. Es nutzt Audio-Fingerprinting (über das Mikrofon), um laufende Songs zu erkennen, analysiert deren BPM sowie die musikalische Tonart (ausgedrückt als Camelot-Code) und schlägt darauf basierend harmonisch kompatible Nachfolgetracks vor.

🌟 Features

🎤 Live Audio Recognition: Erkennt den aktuell laufenden Track in der Umgebung (via AcoustID / Mock).
🎛️ Harmonic Mixing Suggestions: Nutzt die "Mixed In Key"-Regeln, um perfekte Übergänge (Perfect, Quinte, Energy, Scale etc.) vorzuschlagen.
🎡 Interaktives Camelot Wheel: Visualisiert die aktuelle Tonart und hebt kompatible Tonarten direkt im Wheel hervor.
🔍 Manueller Fallback: Song nicht erkannt? Die manuelle Suche findet Tracks über Metadaten.
🌓 Dark/Light Mode: Nahtloser Wechsel zwischen verschiedenen Farbschemata.

🏗️ Architektur

Das Projekt ist bewusst leichtgewichtig aufgebaut und auf Dauerbetrieb in der Cloud ausgelegt:

Frontend (public/): Pures Vanilla JS, HTML und CSS. Kein Build-Schritt, schnelle Ladezeiten.
Backend (server/): Node.js mit Express. Handhabt das Audio-Fingerprinting, ruft Metadaten ab (GetSongBPM, Last.fm) und liefert Cover via iTunes-API (umgeht Frontend-CORS).
Shared (shared/): Geteilte Logik für Camelot-Geometrie und Harmonie-Regeln.
Datenbank (db/): PostgreSQL (via Jannik-Cloud bereitgestellt) für einen massiven Seed aus AcousticBrainz-Daten.

🚀 Installation & Setup (Lokale Entwicklung)

Voraussetzungen: Node.js und Docker.

Repository klonen

git clone https://git.orfel.de/Jannik/KeySelector.git
cd KeySelector

Umgebungsvariablen einrichten

./generate-env.sh
# Danach die erstellte .env Datei bearbeiten und API-Keys eintragen

Lokal mit Docker starten
```
docker-compose up -d
```
Die App ist danach unter http://localhost:3000 erreichbar.
Entwicklung ohne Docker (nur Node.js)
```
cd server
npm install
npm start
```

☁️ Deployment (Jannik-Cloud)

KeySelector ist als nativer Service in die Jannik-Cloud integriert. Die Deployment-Files (wie z.B. das Caddy-Routing und das Produktions-docker-compose.yml) befinden sich im zentralen Cloud-Infrastruktur-Repository unter services/keyselector.

Sobald Code auf den main-Branch dieses Repos gepusht wird, kann der Service in der Jannik-Cloud hochgezogen werden. Er zieht sich automatisch den neuesten Code, baut den Container und geht online unter keyselector.orfel.de.

📚 Dokumentation

Weitere technische Details und Spezifikationen (sowie die initiale Konzept-Idee) findest du im docs/ Ordner:

docs/KeySelector_SPEC.md
docs/Camelot-Wheel-Chart.png