Full rearchitecture using Claude

- event bus systen
- all components are independent
- preparation for web frontend

python-backend/config.yml.example

@@ -1,50 +1,59 @@
-# Example config.yml for the MusicMouse python-backend.
+# Example config for the MusicMouse backend.
 #
-# Reverse-engineered from main.py (load_config/Controller) since no schema
-# was previously documented. Copy this file to config.yml in the directory
-# passed as the CLI argument to main.py, e.g.:
+#   python -m musicmouse --config /media/musicmouse/config.yml
 #
-#   python main.py /media/musicmouse/
-#
-# main.py reads "<config_dir>/config.yml". Real credentials (hass_token,
-# mqtt.password) should never be committed - keep the real config.yml
-# outside the repo (e.g. only on the deployed device).
+# Unknown keys are rejected rather than ignored, and every problem in the file is
+# reported at once, so a typo fails at startup with the path to the offending line.
+# Keep the real config (with credentials) off the repo - on the device only.
 
 general:
-  # ALSA output device passed to python-vlc, e.g. "hw:0,0"; omit/null for VLC's default.
+  # Root folder holding one subfolder per figure. Relative paths resolve against
+  # this file's directory. Each figure plays <figure_folder>/<figure name>,
+  # in alphabetical order by filename.
+  figure_folder: music
+
+  # Serial port the ESP32 firmware is on. A dropped link is retried, not fatal.
+  serial_port: "/dev/ttyUSB0"
+  baudrate: 115200
+  reconnect_interval: 5.0
+
+  # ALSA output device passed to VLC, e.g. "hw:0,0". Omit for VLC's default.
   alsa_device: "softvol_effects"
 
-  # Serial port the ESP32 firmware is connected on.
-  serial_port: "/dev/ttyUSB0"
+  # Volume, 0..100. min/max clamp everything, including the rotary encoder.
+  min_volume: 0
+  max_volume: 60
+  initial_volume: 40
+  volume_increment: 5          # per rotary-encoder click
 
-  # Home Assistant connection used for light/service calls (hass_service()).
-  hass_url: "http://homeassistant.local:8123"
-  hass_token: "REPLACE_WITH_LONG_LIVED_ACCESS_TOKEN"
+  # Backlight of the prev/next buttons while a figure is playing, 0..1.
+  button_leds_brightness: 0.5
 
-  # MQTT broker used for the Home-Assistant-discoverable "shelf light".
+  # Which files count as music. Anything else in a figure folder is ignored.
+  audio_extensions: [".mp3", ".ogg", ".oga", ".opus", ".flac", ".wav", ".m4a", ".aac"]
+
+  # Home Assistant integration. Omit the whole section to run without MQTT.
+  # The backend exposes three lights, a player sensor, a volume slider, transport
+  # buttons, device triggers for every button/touch area, and a tag scanner.
   mqtt:
     server: "homeassistant.local"
+    port: 1883
     user: "musicmouse"
     password: "REPLACE_WITH_MQTT_PASSWORD"
+    base_topic: "musicmouse"
+    discovery_prefix: "homeassistant"
+    device_id: "musicmouse"
+    device_name: "Music Mouse"
+    reconnect_interval: 10.0
 
-  # Optional playback/UI tuning (all have defaults if omitted).
-  min_volume: 0
-  max_volume: 32
-  volume_increment: 5          # per rotary-encoder tick
-  button_leds_brightness: 0.5  # 0..1, brightness of the prev/next button backlight
-
-# One entry per figurine. The key is an arbitrary figure name (also used as
-# the subdirectory name under the config dir when media_files is omitted).
+# One entry per figurine. The key is the figure name and the subfolder name.
 figures:
   fuchs:
-    # RFID tag id as a hex string (matched against bytes read from the reader).
+    # RFID tag id, 5 bytes as hex. Must be unique across figures.
     id: "04a1b2c3d4"
-    # Exactly 4 colors: [primary, secondary, background, accent].
-    # Accepted formats: "#rrggbb" (RGB hex) or "wNN" (white channel hex, e.g. "wff").
-    colors: ["#ff6600", "#ffcc00", "#331100", "#ffffff"]
-    # Optional explicit list of media file paths for this figure's playlist.
-    # If omitted, main.py globs os.path.join(config_dir, "<figure_name>").
-    media_files: []
+    # Exactly four colours: primary, secondary, background, accent.
+    # Either "#rrggbb" (RGB) or "wNN" (white channel only, hex).
+    colors: ["#ff6600", "#ffcc00", "#331100", "wff"]
 
   eule:
     id: "04b2c3d4e5"