Klangkiste Dev Playbook

Purpose

This playbook documents the "virtual box" development environment. It is a complete, hardware-free simulation that runs entirely inside the repo and lets you test setup, playback, and API flows end-to-end.

Docs live in the repo-level docs/ to keep all dev guidance in one predictable place for both Box and GUI contributors.

Prerequisites

Python 3
Node.js + npm
From repo root

Step-by-step

Quickstart (3-5 minutes):

Start everything:

./dev.sh

Open the WiFi setup UI:

http://127.0.0.1:9000/setup

Add a WiFi profile and submit.
Check status:

curl http://127.0.0.1:8000/status

Start playback:

curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"nfc_on","payload":{"uid":"UID_1"}}'

Troubleshooting

Box not starting:
- Ensure dependencies are installed and ports 8000/9000 are free.
GUI cannot reach API:
- Check VITE_BOX_API_URL and Box logs.

What Is Mock vs Real

Mock: WiFi, IP, Spotify, audio, hardware. These are logical simulations only.
Real: Box process, playback state machine, API, CLI, resume logic, media traversal.

1.6 KiB Raw Blame History