michael/klangkiste
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update

Browse Source
This commit is contained in:
mboehmlaender
2026-01-14 13:11:07 +00:00
parent 0a4a1d3e48
commit ad6f1ed6c5
25 changed files with 8685 additions and 1662 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+8 -2
View File
@@ -16,7 +16,7 @@ Quickstart (3-5 Minuten):
```
./dev.sh
```
2) Setup-WebGUI oeffnen:
2) Setup-WebGUI der Box oeffnen:
```
http://127.0.0.1:9000/setup
```
@@ -29,12 +29,18 @@ curl http://127.0.0.1:5001/api/boxes
```
http://127.0.0.1:5174
```
6) Tags testen:
- Tag auflegen
- Medien zuordnen
- Playback starten
## Troubleshooting
- Box startet nicht:
- Pruefe Abhaengigkeiten und ob Ports 8000/9000 frei sind.
- GUI erreicht API nicht:
- Pruefe `VITE_BACKEND_URL` und Backend-Logs.
- Vite-Proxy: GUI ruft `/api/...` auf.
- Backend laeuft auf `http://127.0.0.1:5001`.
- Wenn Reverse-Proxy genutzt wird, `/api` auf das Backend routen.
## Was ist Mock vs. real
- Mock: WLAN, IP, Spotify, Audio, Hardware. Diese Backends sind logische Simulationen.
docs/acceptance-tests.md
+5 -1
View File
@@ -7,7 +7,11 @@ Konsistenter Testkatalog basierend auf dem aktuellen Code. Alle Tests trennen Si
- Repo-Root
- Python 3
- Box API fuer Simulation: `python3 box/main.py run`
- GUI optional: `cd gui && npm run dev`
- GUI optional: `cd gui/frontend && npm run dev`
- Backend optional: `cd gui/backend && npm run dev`
Hinweis:
- Sobald die Box gepairt ist, erfordern `/command` Aufrufe den Header `X-API-Token`.
## Schritt-fuer-Schritt
Die Tests koennen einzeln oder der Reihe nach ausgefuehrt werden.
docs/api.md
+17
View File
@@ -32,6 +32,7 @@ Felder:
- `last_nfc`:
- `uid`: letzte erkannte UID oder `null`
- `known`: `true` wenn Tag in der Box zugeordnet ist
- `blocked_tags`: Liste gesperrter Tag-UIDs
- `playback_state`:
- `state`: `IDLE | PLAYING | PAUSED`
- `active_uid`
@@ -53,6 +54,7 @@ Beispielantwort:
"connected_ssid": "HomeWiFi",
"wifi_profiles_count": 1,
"spotify_status": "READY",
"blocked_tags": [],
"playback_state": {
"state": "PLAYING",
"active_uid": "UID_1",
@@ -67,6 +69,14 @@ Beispielantwort:
}
```
## GET /local-tags
Nur fuer gepairte Boxen (Header: `X-API-Token`).
Zeigt lokale Tags, inkl. Dateiliste und Groesse.
```
curl http://127.0.0.1:8000/local-tags \
-H "X-API-Token: <api_token>"
```
## POST /command
Request Body:
```
@@ -95,10 +105,17 @@ Unterstuetzte Commands:
- `unpair`
- `tag_assign` `{ uid, media_path }`
- `tag_remove` `{ uid }`
- `tag_block` `{ uid }`
- `tag_unblock` `{ uid }`
- `export_tag` `{ uid, target_folder }`
- `factory_reset`
## Tag-Commands
- `tag_assign` `{ uid, media_path }` weist ein Tag einem Medienordner zu.
- `tag_remove` `{ uid }` entfernt die Zuordnung fuer ein Tag.
- `tag_block` sperrt den Tag fuer diese Box.
- `tag_unblock` hebt die Sperre auf.
- `export_tag` uebertraegt die lokalen Medien dieses Tags an den Server.
## Auth fuer Commands
- Vor Pairing sind nur diese Commands erlaubt:
docs/debugging.md
+6 -1
View File
@@ -17,7 +17,9 @@ Nutze die Sektionen nach Symptomen.
curl http://127.0.0.1:5001/api/boxes
```
- GUI API-Base pruefen:
- `VITE_BACKEND_URL` oder Default `http://127.0.0.1:5001`
- GUI nutzt `/api/...` und Vite-Proxy.
- `VITE_BACKEND_URL` zeigt auf das Backend (ohne `/api`).
- Reverse-Proxy: `/api` muss auf Port 5001 zeigen (ohne doppeltes `/api`).
### Playback startet nicht
- Tags pruefen:
@@ -32,6 +34,9 @@ ls -la gui/backend/media
```
curl http://127.0.0.1:8000/status
```
- Tag lokal vorhanden, aber nicht in DB:
- GUI: "Tags nur auf dieser Box" pruefen.
- Import ueber "Auf Server uebertragen".
### Resume bleibt leer
- State pruefen:
docs/dev-workflow.md
+7 -4
View File
@@ -24,7 +24,7 @@ python3 box/main.py run
Frontend only:
```
cd gui/frontend
npm run dev -- --host 0.0.0.0 --port 5174 --strictPort
VITE_BACKEND_URL=http://127.0.0.1:5001 npm run dev -- --host 0.0.0.0 --port 5174 --strictPort
```
Backend only:
```
@@ -37,10 +37,12 @@ npm run dev
- Frontend GUI: `http://127.0.0.1:5174`
- Box API: `http://127.0.0.1:8000`
- Setup UI: `http://127.0.0.1:9000/setup`
- GUI: `http://127.0.0.1:5174`
- Box2 API (optional): `http://127.0.0.1:8001`
- Box2 Setup (optional): `http://127.0.0.1:9001/setup`
## API-URL fuer die GUI
Default ist `http://<HOST-IP>:5001` (aus `hostname -I`). Override:
Die GUI nutzt relative Pfade (`/api/...`) und einen Vite-Proxy.
Der Proxy-Target wird so gesetzt:
```
KLANGKISTE_BACKEND_URL=http://<server-ip>:5001 ./dev.sh
VITE_BACKEND_URL=http://<server-ip>:5001 npm run dev
@@ -67,4 +69,5 @@ VITE_BACKEND_URL=http://<server-ip>:5001 npm run dev
- CORS-Fehler:
- API muss laufen und erreichbar sein.
- GUI zeigt "Failed to fetch":
- `VITE_BACKEND_URL` pruefen.
- Vite-Proxy pruefen (`VITE_BACKEND_URL`).
- Reverse-Proxy: `/api` muss auf das Backend zeigen (ohne doppeltes `/api`).
docs/gui-control-panel.md
+20 -6
View File
@@ -14,18 +14,31 @@ Nutzung des Frontend Control Panels zur Steuerung und Beobachtung der Boxen uebe
http://127.0.0.1:5174
```
2) In "Neue Boxen" die Box auswaehlen und "Pairen" klicken.
3) In "Gepairte Boxen" eine Box anklicken.
3) In der Sidebar unter "Aktive Sessions" eine Box aktiv setzen (gilt fuer alle Seiten).
4) Status und Commands nutzen.
## Controls (im GUI vorhanden)
- Pairen (Button in "Neue Boxen")
- Statusanzeige (automatisch)
- Statusanzeige (automatisch, Polling)
- Play/Pause, Next, Prev, Vol +/-, Stop
- NFC on/off (UID eingeben)
- NFC on/off (UID manuell eingeben; kein Auto-Fill)
- Unpair (Button in "Gepairte Boxen")
- Medienkatalog (Explorer-Ansicht, nur Lesen)
- Neuer Tag erkannt (Panel) mit ID-Zuweisung und Zuordnung
- Tags werden nur nach NFC-Erkennung erstellt und zugeordnet.
- Medien-Explorer (Ordner/Dateien, Upload, Rename, Move, Delete)
- Neuer/Leerer Tag erkannt (Panel)
- Wenn keine UID erkannt: ID zuweisen & schreiben
- Wenn UID erkannt, `known=false`: nur Medienordnerwahl + "Nur in die DB uebernehmen"
- Medienordner zuordnen
- Importierte Tag-IDs wiederverwenden
- Tags (Datenbank)
- Alias setzen, Medium zuweisen, Tag loeschen
- Tag-Matrix (Sperren)
- Tags pro Box sperren/entsperren
- Tags nur auf dieser Box
- Lokale Tags ohne DB-Eintrag
- Dateien anzeigen
- Auf Server uebertragen (mit neuem Ordnernamen)
- Mobile: Aktive Sessions als Bottom-Sheet (Topbar-Icon)
- Hardware-UID (simuliert) wird im Tag-Panel und Live-Status angezeigt, wenn NFC on ohne UID genutzt wird
## Controls (nur Backend/API)
- WiFi add/reset
@@ -46,6 +59,7 @@ curl -X POST http://127.0.0.1:5001/api/boxes/<box_id>/command \
- ✅ GUI laedt und zeigt Backend-URL
- ✅ Neue Boxen erscheinen unter "Neue Boxen"
- ✅ Pairing verschiebt die Box in die gepaarte Liste
- ✅ Aktive Box ist global gesetzt (Sidebar "Aktive Sessions")
- ✅ Buttons aendern den `/status`
## Troubleshooting
docs/virtual-box.md
+2
View File
@@ -14,6 +14,8 @@ Beschreibt den vollstaendigen, hardwarefreien Box-Flow fuer die IDE.
3) Setup UI unter `http://127.0.0.1:9000/setup`.
4) Nach Submit wird `WIFI_ONLINE`.
5) API unter `http://127.0.0.1:8000`.
6) Box meldet sich beim Backend (announce).
7) Pairing ueber GUI oder API.
## Troubleshooting
- Setup UI nicht erreichbar: