musicmouse/docs/REPO_OVERVIEW.md

MusicMouse — repo overview

Orientation doc for AI agents (or humans) working on this repo for the first time.

What this is

MusicMouse is a DIY, Toniebox-style physical music player for kids, shaped like a mouse and living on a shelf. Small 3D-printed animal figurines (fox, owl, dog, elephant, squirrel, crocodile, rabbit, snowman, puppy — see hardware/3dprints/figures/) each carry an RFID tag. Placing a figurine on the mouse starts that figure's playlist. The mouse also has a rotary encoder and capacitive touch areas (ears/feet) for volume/skip control, addressable RGBW LED rings with animated effects, and MQTT/Home Assistant integration.

Repo layout

Path	What it is
python-backend/	Python host application — the main runtime. Has its own README.md with the architecture; start there for backend work.
web/	React + TypeScript front-end (Vite). Browse the whole library and play any of it from a browser. Built output is served by python-backend itself.
esp-firmware/	ESP32 firmware (C++, Arduino framework via PlatformIO). Reads the RFID reader and buttons, drives the LED strips, talks to python-backend over serial.
hardware/	3D-print models for the figurines and enclosure (FreeCAD/Blender/OBJ/STL), a Fritzing electronics sketch, datasheets, and pinout.md (RFID reader + button-board wiring).
claude-design/	The interaction and visual specs the web front-end was built from, as standalone HTML mockups with hardcoded data: "Dolphin Beats" (the player), "Mein Zimmer" (the room page) and "Delphin Uhr" (the clock overlay). web/ is the real implementation of all three; the mockups are kept as the reference for the keyboard model and the styling.
scripts/	check.sh (every check, see below) and sync-library.sh (seed a device's library and analysis cache).
docs/	This file.

How the pieces talk to each other

• ESP32 firmware ↔ python-backend: a length-prefixed binary protocol over serial. Frames are uint32 magic | uint8 type | uint16 size | payload, little-endian, with firmware log text interleaved on the same link. The Python side lives in python-backend/musicmouse/devices/wire.py, the firmware side in esp-firmware/src/Messages.h.

  The contract is hand-duplicated in two languages. tests/test_wire.py parses Messages.h and fails if the message ids drift, and tests/test_effects.py pins the exact bytes of every effect payload — so a firmware change that breaks the host now breaks a test instead of just the LEDs.

• python-backend ↔ web/: JSON over HTTP for the library and for commands, plus a push-only websocket at /api/ws for state. Commands emit exactly the same intents the physical buttons emit, so the web UI has no privileged path — and no way to get out of step with a figure someone puts on the reader. See python-backend/README.md for the endpoint list.

• python-backend ↔ Home Assistant: two separate paths.

  • MQTT, for the mouse itself. The backend publishes three discoverable lights, a player sensor, a volume number, transport buttons, device triggers for every button and touch area, and a tag scanner for the RFID reader. Behaviour like "the left ear turns the room light pink" is an HA automation, not backend code. See python-backend/README.md for the trigger topics and the old colour mapping.
  • HTTP, for the web front-end's room page only: /api/ha/... proxies state reads and service calls to Home Assistant's REST API with the token from general.ha, so the token never reaches the browser.

• python-backend ↔ IR remote: a TCP client for lircd (general.lirc), turned into the same intents as every other front-end.

Running it

python -m musicmouse --config /media/musicmouse/config.yml

On a machine with no mouse attached — real audio and a real web UI, no serial port:

python -m musicmouse --config ./config.yml --no-hardware

general.serial_port: simulate does the same thing from the config, and general.alsa_device: simulate swaps in a silent player. Both warn at startup, and both keys are required - omitting one is an error rather than an implicit simulation.

Or with no hardware and no audio:

python -m musicmouse --config ./config.yml --simulate

The simulator runs the whole app against a fake serial link and a fake player, either interactively or from a scenario file. python-backend/musicmouse.service is the systemd unit for the device.

For front-end work, run the backend (either way above) and then:

cd web && npm install && npm run dev     # http://localhost:5173, /api proxied to :8080

npm run build writes web/dist, which general.web.static_dir points at in production so one process serves both the UI and the API.

Config

python-backend/config.yml.example documents the schema. In short:

• general.{library.*, serial_port, baudrate, reconnect_interval, alsa_device, min_volume, max_volume, initial_volume, volume_increment, button_leds_brightness, audio_extensions, podcast_episode_limit}, plus optional sections mqtt, web, ha (room page), lirc (IR remote), screen (monitor on/off), tippen (typing game) and clock (school bus countdown).
• figures.<name>.{id, colors, kind} — id is a 5-byte hex RFID tag, unique per figure; colors is exactly four (primary, secondary, bg, accent), each "#rrggbb" or "wNN"; kind is music (default) or book.
• remote.<digit> — what each IR-remote number key plays. Written by the web UI.

general.library.root is the one path to the music. The shelves under it are fixed names, not settings, because each has quirks the scanner knows about:

<root>/Figuren/<figure name>/          one folder per figurine (or album subfolders
                                       in it, up to six, picked on the LED ring)
<root>/Musik/<Artist> - <Album>/       albums, grouped by artist
<root>/Hörbücher/<Artist> - <Album>/   audiobooks, grouped by character
<root>/Kinderpodcasts/<Show>/          shows, newest episode first

Config is validated with pydantic: unknown keys are errors, and every problem is reported at once.

Notes for agents

• There is no CI. scripts/check.sh runs every check the repo has - backend pytest, ruff and mypy --strict, web vitest, tsc and eslint - and is the gate: run it before proposing changes. A checker that cannot run (mypy once aborted on numpy's stubs for two weeks without anyone noticing) is a failure, not a skip.
• Prefer adding a scenario in python-backend/scenarios/ over a hand-rolled test when the behaviour is end-to-end — those files are executed by the test suite.
• python-backend/notebooks/ is LED-effect scratch work, not part of the app.
• The firmware has no automated tests beyond a PlatformIO native env for LED effects.
• The front-end has vitest over the pure modules (web/src/lib/), tsc and eslint; there is no component-level test harness.
• The library index is cached under general.library.cache. It is keyed by file mtime and size, so a change to how the scanner derives a title, artist or series is invisible until the cache is invalidated — bump _INDEX_VERSION in musicmouse/library/cache.py when you touch that logic.
• Track analysis (librosa) runs in a pool of worker processes - see musicmouse/library/workers.py. Anything an Analyzer returns therefore has to be picklable, and an analyzer that records state in its own instance (a test double counting calls) only behaves as written with analysis_workers=1.