53 lines
2.7 KiB
Markdown
53 lines
2.7 KiB
Markdown
# KeySelector
|
|
|
|
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](https://nodejs.org/)
|
|
|
|
1. **Repository klonen**
|
|
```bash
|
|
git clone https://git.orfel.de/Jannik/KeySelector.git
|
|
cd KeySelector
|
|
```
|
|
|
|
2. **Backend starten (Node.js)**
|
|
```bash
|
|
cd server
|
|
npm install
|
|
|
|
# Umgebungsvariablen (wie API Keys) exportieren oder in eine .env Datei in server/ schreiben
|
|
npm start
|
|
```
|
|
Die App ist danach unter `http://localhost:3000` erreichbar.
|
|
|
|
## ☁️ 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`
|