Update
This commit is contained in:
@@ -1,92 +1,169 @@
|
||||
# Klangkiste
|
||||
# 🎵 Klangkiste
|
||||
|
||||
Klangkiste ist eine DIY-Kinder-Audiobox mit serverseitiger Verwaltung und
|
||||
vollstaendiger Offline-Faehigkeit. Ziel ist eine robuste, kindgerechte Box:
|
||||
Tags auflegen, Inhalte starten, und Eltern verwalten alles bequem ueber eine
|
||||
einfache Web-Oberflaeche.
|
||||
**Klangkiste** ist eine DIY-Kinder-Audiobox mit serverseitiger Verwaltung und vollständiger Offline-Fähigkeit.
|
||||
Das Ziel ist eine robuste, kindgerechte Box mit einem klaren Prinzip: **Tag auflegen, Inhalt hören** – während Eltern alles komfortabel über eine einfache Web-Oberfläche verwalten können. 🧸✨
|
||||
|
||||
## Was die Box aktuell kann
|
||||
- NFC-Workflow (simuliert): Tags auflegen, Tags erkennen, Tag-IDs in der
|
||||
Datenbank speichern, Tags Medienordnern zuordnen.
|
||||
- Playback-Steuerung (simuliert): Play/Pause, Next, Prev, Stop, Volume.
|
||||
- Spotify-Anbindung (Token-Flow, Playback-Integration vorbereitet).
|
||||
- Webradio-Start ueber Tags (geplant/Workflow vorgesehen).
|
||||
- Medienverwaltung: Ordnerstruktur anzeigen, Uploads, Umbenennen, Verschieben,
|
||||
Loeschen.
|
||||
- Eigene Medienverwaltung ohne Cloud-Abhaengigkeit.
|
||||
- Box-Verwaltung: Pairing/Unpairing, Box-Status, Commands an einzelne Boxen.
|
||||
- Tag-Verwaltung: Alias, Zuordnung, Sperren pro Box, Import von lokalen Tags.
|
||||
- Tag-Matrix mit Sperren pro Box (Whitelist/Block-Logik).
|
||||
- Offline-Logik (simuliert): Box arbeitet mit lokalem Cache, Server kann wieder
|
||||
synchronisieren.
|
||||
- Mehrere Boxen gleichzeitig (box + box2) fuer Multi-Box-Tests.
|
||||
Im Mittelpunkt stehen dabei Offenheit, Kontrolle und Langlebigkeit: keine Cloud-Zwänge, keine geschlossenen Ökosysteme, keine versteckten Abhängigkeiten.
|
||||
|
||||
## Was geplant ist
|
||||
- Echte NFC-Hardware-Integration (Lesen/Schreiben von Tag-IDs).
|
||||
- Reale Audio-Ausgabe auf der Box, nicht nur Simulation.
|
||||
- Robuste Setup-Flows fuer WLAN, Updates und Fehlerdiagnose.
|
||||
- Feinschliff der GUI (Mobile-Flows, Accessibility, klare Nutzerfuehrung).
|
||||
- Vereinfachte Installation fuer Familien (Image/Installer).
|
||||
- Anbindung externer Server und Rueckfuehrung der dortigen Medien auf den
|
||||
eigenen Server inkl. Tag-Erstellung.
|
||||
---
|
||||
|
||||
## Abgrenzung zu gaengigen Audioboxen
|
||||
Klangkiste verfolgt einen anderen Ansatz als gaengige Audioboxen:
|
||||
- Keine proprietaeren Cloud-Bindungen: Inhalte liegen lokal und bleiben
|
||||
voll kontrollierbar.
|
||||
- Eigene Medien und Ordnerstrukturen statt geschlossener Oekosysteme.
|
||||
- Flexible Server-Anbindung (geplant), inkl. Rueckfuehrung und Tag-Workflows.
|
||||
- Tag-Matrix und Sperren pro Box fuer feinere Kontrolle in Mehrbox-Setups.
|
||||
- Vollstaendige Transparenz durch offene APIs und lokale Datenhaltung.
|
||||
## 🧭 Vision
|
||||
|
||||
## Status
|
||||
Phase 1.x – lokale Entwicklung ohne Hardware (Mocks + API + GUI)
|
||||
Klangkiste soll eine Audiobox sein, die Kindern einen einfachen,
|
||||
bildschirmfreien Zugang zu Medien ermöglicht – und Eltern gleichzeitig
|
||||
volle Kontrolle über Inhalte, Daten und Technik gibt.
|
||||
|
||||
## Repo-Struktur
|
||||
- `box/` – Box-Software (Python, NFC/Playback/Resume, API)
|
||||
- `box2/` – zweite Box-Instanz fuer Multi-Box-Tests
|
||||
- `gui/backend/` – Backend (Node.js + SQLite, Box-Verwaltung, Media-API)
|
||||
- `gui/frontend/` – Control-Panel (React + Vite)
|
||||
- `docs/` – Dev-Playbook, API-Vertrag, Tests
|
||||
Das Projekt setzt bewusst auf:
|
||||
- lokale Medien statt Cloud-Zwang
|
||||
- offene Standards statt geschlossener Ökosysteme
|
||||
- langlebige, reparierbare Technik
|
||||
- klare Trennung zwischen kindlicher Nutzung und elterlicher Verwaltung
|
||||
|
||||
## Quickstart (lokal)
|
||||
1) Alles starten:
|
||||
Klangkiste ist kein Produkt, das ersetzt werden soll –
|
||||
sondern ein System, das mitwachsen darf.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Aktueller Funktionsumfang
|
||||
|
||||
### 🎫 NFC-Workflow (simuliert)
|
||||
- Tags auflegen und erkennen
|
||||
- Speicherung von Tag-IDs in der Datenbank
|
||||
- Zuordnung von Tags zu Medienordnern
|
||||
|
||||
### ▶️ Playback-Steuerung (simuliert)
|
||||
- Play / Pause
|
||||
- Next / Previous
|
||||
- Stop
|
||||
- Lautstärkeregelung
|
||||
|
||||
### 🎧 Medien & Streaming
|
||||
- Spotify-Anbindung (OAuth-Token-Flow vorhanden, Playback-Integration vorbereitet)
|
||||
- Webradio-Start über Tags (Workflow vorgesehen)
|
||||
- Eigene Medienverwaltung ohne Cloud-Abhängigkeit
|
||||
|
||||
### 📂 Medienverwaltung
|
||||
- Anzeige der Ordnerstruktur
|
||||
- Upload eigener Inhalte
|
||||
- Umbenennen, Verschieben und Löschen von Medien
|
||||
|
||||
### 🧩 Box- & Tag-Management
|
||||
- Pairing und Unpairing von Boxen
|
||||
- Live-Box-Status und gezielte Commands pro Box
|
||||
- Tag-Verwaltung (Alias, Zuordnung, Sperren pro Box)
|
||||
|
||||
- **Import lokaler Tags & Ökosystem-Transfer**
|
||||
- Tags können aus einem **fremden Ökosystem** übernommen werden, z. B. wenn eine Box temporär mit einem externen Server (anderer Haushalt) verbunden ist.
|
||||
- Medien, die dort über fremde Tags abgespielt werden, werden **lokal auf der Box gespeichert**.
|
||||
- Auf Wunsch lassen sich diese Inhalte anschließend **in das eigene Ökosystem zurückführen**.
|
||||
- Dabei **können** passende **eigene Tags erzeugt** und den importierten Medien zugeordnet werden.
|
||||
- So können Inhalte bewusst „mitgenommen“ werden – ohne dauerhafte Bindung an fremde Server oder Strukturen.
|
||||
|
||||
- **Tag-Matrix** mit Whitelist- und Block-Logik pro Box
|
||||
|
||||
### 📴 Offline-Logik (simuliert)
|
||||
- Box arbeitet mit lokalem Cache
|
||||
- Server synchronisiert sich automatisch nach Wiederverbindung
|
||||
|
||||
### 📦 Multi-Box-Support
|
||||
- Mehrere Boxen gleichzeitig (z. B. `box` + `box2`)
|
||||
- Geeignet für Familien-Setups und Multi-Box-Tests
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Geplante Erweiterungen
|
||||
|
||||
- 🔌 Echte NFC-Hardware-Integration (Lesen & Schreiben von Tags)
|
||||
- 🔊 Reale Audio-Ausgabe auf der Box (statt Simulation)
|
||||
- 📶 Robuste Setup-Flows für WLAN, Updates und Fehlerdiagnose
|
||||
- 🎨 GUI-Feinschliff (Mobile-Flows, Accessibility, klare Nutzerführung)
|
||||
- 📦 Vereinfachte Installation für Familien (fertiges Image / Installer)
|
||||
- 🌍 Anbindung externer Server inkl. Rückführung externer Medien
|
||||
- 🏷️ Optionale automatische Tag-Erstellung für importierte Inhalte
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Abgrenzung zu gängigen Audioboxen
|
||||
|
||||
Klangkiste verfolgt bewusst einen anderen Ansatz als viele kommerzielle Audioboxen:
|
||||
|
||||
- ❌ Keine proprietären Cloud-Bindungen
|
||||
- 📁 Eigene Medien und offene Ordnerstrukturen statt geschlossener Ökosysteme
|
||||
- 🔄 Flexible Server-Anbindung mit kontrollierter Rückführung von Inhalten
|
||||
- 🧮 Fein steuerbare **Tag-Matrix pro Box**, ideal für Mehrbox-Setups
|
||||
- 🔎 Volle Transparenz durch offene APIs und lokale Datenhaltung
|
||||
|
||||
---
|
||||
|
||||
## 📍 Projektstatus
|
||||
|
||||
**Phase 1.x**
|
||||
Lokale Entwicklung ohne Hardware
|
||||
(Mock-Boxen, API, GUI)
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ Repository-Struktur
|
||||
|
||||
```text
|
||||
box/ Box-Software (Python, NFC / Playback / Resume, Box-API)
|
||||
box2/ Zweite Box-Instanz für Multi-Box-Tests
|
||||
gui/backend/ Backend (Node.js + SQLite, Box- & Medienverwaltung)
|
||||
gui/frontend/ Control-Panel (React + Vite)
|
||||
docs/ Dev-Playbook, API-Verträge, Tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Quickstart (lokal)
|
||||
|
||||
### Alles starten
|
||||
```bash
|
||||
./dev.sh
|
||||
```
|
||||
2) Setup-WebGUI (Box):
|
||||
```
|
||||
|
||||
### Setup-Web-GUI (Box)
|
||||
http://127.0.0.1:9000/setup
|
||||
```
|
||||
3) Backend pruefen:
|
||||
```
|
||||
|
||||
### Backend prüfen
|
||||
curl http://127.0.0.1:5001/api/boxes
|
||||
```
|
||||
4) Frontend oeffnen:
|
||||
```
|
||||
|
||||
### Frontend öffnen
|
||||
http://127.0.0.1:5174
|
||||
```
|
||||
|
||||
## Ports (Default)
|
||||
- Backend API: `5001`
|
||||
- Frontend GUI: `5174`
|
||||
- Box API: `8000`
|
||||
- Setup UI: `9000`
|
||||
- Box2 API (optional): `8001`
|
||||
- Box2 Setup (optional): `9001`
|
||||
### 🌐 Ports (Default)
|
||||
|
||||
## Entwicklungsprinzipien (Kurz)
|
||||
- Box und GUI/Backend teilen keinen Code.
|
||||
- Kommunikation nur ueber JSON-APIs.
|
||||
- Box ist Quelle der Wahrheit fuer Playback/State.
|
||||
- Server verwaltet Tags, Medien und Boxen.
|
||||
| Dienst | Port |
|
||||
| --------------------- | ---- |
|
||||
| Backend API | 5001 |
|
||||
| Frontend GUI | 5174 |
|
||||
| Box API | 8000 |
|
||||
| Setup UI | 9000 |
|
||||
| Box2 API (optional) | 8001 |
|
||||
| Box2 Setup (optional) | 9001 |
|
||||
|
||||
## Technisch (kurz)
|
||||
- Start via `./dev.sh` (startet Frontend, Backend, Box-Simulation).
|
||||
- Frontend spricht mit Backend (`/api`), Backend spricht mit Boxen (HTTP).
|
||||
- NFC/Playback sind aktuell simuliert; reale Hardware folgt.
|
||||
---
|
||||
|
||||
### 🧠 Entwicklungsprinzipien
|
||||
- Box und GUI/Backend teilen keinen Code
|
||||
- Kommunikation ausschließlich über JSON-basierte APIs
|
||||
- Die Box ist Single Source of Truth für Playback und State
|
||||
- Der Server verwaltet Tags, Medien und Boxen
|
||||
|
||||
### ⚙️ Technischer Überblick
|
||||
- Start über ./dev.sh
|
||||
- Frontend → Backend (/api)
|
||||
- Backend → Boxen (HTTP)
|
||||
- NFC und Playback aktuell simuliert
|
||||
- Reale Hardware-Integration folgt
|
||||
|
||||
### 📚 Dokumentation
|
||||
- docs/README.md – Einstieg und Dev-Playbook
|
||||
- docs/dev-workflow.md – Start/Stop, Ports, Logs
|
||||
- docs/api.md – API-Vertrag
|
||||
|
||||
---
|
||||
|
||||
🎶 Klangkiste steht für Freiheit, Kontrolle und kindgerechte Einfachheit –
|
||||
ein offenes Audiobox-Projekt zum Mitbauen, Verstehen und Erweitern.
|
||||
|
||||
## Doku
|
||||
- `docs/README.md` – Startpunkt fuer den Dev-Playbook
|
||||
- `docs/dev-workflow.md` – Start/Stop, Ports, Logs
|
||||
- `docs/api.md` – API-Vertrag
|
||||
|
||||
Reference in New Issue
Block a user