diff --git a/README.md b/README.md index 19ea328..7fc7543 100644 --- a/README.md +++ b/README.md @@ -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