Initial Phoenix analyzer

2026-06-02 20:56:19 +02:00
commit e499bac928
62 changed files with 28893 additions and 0 deletions
@@ -0,0 +1,241 @@
+# Phoenix v1.0.0
+
+Phoenix ist das native Rust-Backend des Analyzers auf Raspberry Pi.
+
+Der Browser rendert nur noch die GUI. Audio-Capture, Messung, Recorder und die globale Gerätekonfiguration laufen in Phoenix.
+
+## Aktueller Stand
+
+Phoenix übernimmt heute:
+
+- ALSA-Audio-Capture
+- Live-Metering über WebSocket
+- globale Gerätekonfiguration
+- RTA
+- Spectrogram
+- Waveform
+- XY / Goniometer
+- Phase Wheel
+- Recorder in `wav`, `mp3` und `webm`
+- direktes Speichern auf dem Gerät
+
+Nicht mehr Teil der Architektur:
+
+- WebAudio-/AudioWorklet-Analyse im Browser
+- Browser-MediaRecorder als Haupt-Recorder
+- Umschalten zwischen `line` und `spdif`
+
+Der aktuelle Zielpfad ist `Line In` auf der Behringer/USB-Audio-Hardware.
+
+## Architektur
+
+- Phoenix besitzt die Audio-Hardware
+- Phoenix berechnet die Messwerte
+- die Web-GUI verbindet sich per `HTTP + WebSocket` mit Phoenix
+- globale Geräteoptionen werden in Phoenix gespeichert und an Browser synchronisiert
+- browser-lokale Optionen wie `Phoenix URL` bleiben clientseitig
+
+## Standard-Endpunkte
+
+- `GET /health`
+- `GET /api/v1/status`
+- `GET /api/v1/global-config`
+- `POST /api/v1/global-config`
+- `GET /api/v1/rta-config`
+- `POST /api/v1/rta-config`
+- `GET /api/v1/metrics/ws`
+- `POST /api/v1/recordings/wav/start/:session_id`
+- `POST /api/v1/recordings/wav/stop/:session_id`
+- `POST /api/v1/recordings/stop/:session_id/:format`
+- `POST /api/v1/recordings/save/:target/:filename`
+
+## Build
+
+Lokaler Build:
+
+```bash
+cargo build --release
+```
+
+Check:
+
+```bash
+cargo check
+```
+
+Das Binary liegt danach unter:
+
+```text
+target/release/phoenix
+```
+
+## Raspberry Pi Betrieb
+
+Für den Pi ist der maßgebliche Ablauf in:
+
+[RASPBERRY_PI_SETUP.txt](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/RASPBERRY_PI_SETUP.txt)
+
+Dort sind enthalten:
+
+- benötigte Systempakete
+- systemd-Services
+- Kiosk-Start
+- Webserver auf Port `80`
+- Autostart
+
+Relevante Dateien:
+
+- [kiosk-start.sh](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/kiosk-start.sh)
+- [session.sh](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/session.sh)
+- [analyzer-kiosk.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-kiosk.service)
+- [analyzer-web.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-web.service)
+
+## Volumio-Betrieb
+
+Für Volumio gibt es einen getrennten Kiosk-Pfad mit eigener Session und eigenen systemd-Units:
+
+- [session_volumio.sh](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/session_volumio.sh)
+- [analyzer-kiosk-volumio.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-kiosk-volumio.service)
+- [analyzer-web-volumio.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-web-volumio.service)
+
+Erwarteter Projektpfad auf dem Zielgerät:
+
+```text
+/home/volumio/Phoenix
+```
+
+Volumio-spezifisch:
+
+- `session_volumio.sh` startet Analyzer-GUI und Volumio im Dual-Tab-Kiosk
+- die Analyzer-GUI läuft im Volumio-Fall auf `http://localhost:8088/`
+- `toggle-ext` wird unter `Phoenix/toggle-ext` erwartet
+- `VirtualKeyboard` wird bevorzugt unter `Phoenix/VirtualKeyboard` gesucht, mit Fallback auf die bekannten Systempfade
+- Logs liegen typischerweise unter:
+
+```text
+/home/volumio/dual-kiosk.log
+/home/volumio/phoenix.log
+```
+
+Wenn `toggle-ext` genutzt werden soll, sollte es also unter diesem Pfad liegen:
+
+```text
+/home/volumio/Phoenix/toggle-ext
+```
+
+## Analyzer vs. Volumio
+
+Die beiden Betriebsarten teilen sich Phoenix, aber nicht denselben Kiosk-Rahmen.
+
+- Analyzer:
+  - Projektpfad: `/home/analyzer/Phoenix`
+  - Web-GUI: `http://localhost/`
+  - systemd-Units: [analyzer-kiosk.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-kiosk.service), [analyzer-web.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-web.service)
+  - Session: [session.sh](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/session.sh)
+  - Chromium-Profil: `/data/chrome-analyzer`
+
+- Volumio:
+  - Projektpfad: `/home/volumio/Phoenix`
+  - Analyzer-GUI: `http://localhost:8088/`
+  - Volumio-GUI intern: `http://localhost:3000/`
+  - systemd-Units: [analyzer-kiosk-volumio.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-kiosk-volumio.service), [analyzer-web-volumio.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-web-volumio.service)
+  - Session: [session_volumio.sh](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/session_volumio.sh)
+  - Chromium-Profil: `/data/chrome-dualtabs`
+  - `toggle-ext` erwartet unter `/home/volumio/Phoenix/toggle-ext`
+
+Wichtig:
+
+- Volumio darf den Analyzer-Webserver nicht auf `:80` binden, weil dort Volumio selbst bzw. dessen Frontproxy hängt.
+- Die einzige beabsichtigte Global-Config-Abweichung zwischen den Referenzständen ist normalerweise `recordTarget`.
+
+## Referenz-Global-Configs
+
+Für einen sauberen Gerätestand liegen zwei Referenzdateien im Projekt:
+
+- [phoenix-global-config.analyzer.json](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/reference-config/phoenix-global-config.analyzer.json)
+- [phoenix-global-config.volumio.json](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/reference-config/phoenix-global-config.volumio.json)
+
+Kopieren auf dem Zielgerät:
+
+```bash
+mkdir -p ~/.config/phoenix
+cp /home/<user>/Phoenix/reference-config/phoenix-global-config.<profil>.json ~/.config/phoenix/global-config.json
+```
+
+Beispiele:
+
+```bash
+cp /home/analyzer/Phoenix/reference-config/phoenix-global-config.analyzer.json /home/analyzer/.config/phoenix/global-config.json
+cp /home/volumio/Phoenix/reference-config/phoenix-global-config.volumio.json /home/volumio/.config/phoenix/global-config.json
+```
+
+Danach Phoenix bzw. den Kiosk-Dienst neu starten.
+
+## Erster Start auf neuem Gerät
+
+Für einen frischen Pi werden mindestens diese Build-Abhängigkeiten benötigt:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y pkg-config libasound2-dev curl ca-certificates git build-essential
+```
+
+Wenn `cargo`/`rustc` fehlen oder zu alt sind, kann `kiosk-start.sh` beim Start eine aktuelle Rust-Toolchain per `rustup` installieren.
+Das ist besonders für ältere Volumio-/Debian-Systeme wichtig, deren `apt`-Rust oft zu alt für aktuelle Crates ist.
+
+## Wichtige Umgebungsvariablen
+
+- `PHOENIX_LISTEN`
+  default: `127.0.0.1:8789`
+
+- `PHOENIX_ALSA_CARD`
+  default: `2`
+
+- `PHOENIX_ALSA_DEVICE`
+  optional explizites ALSA-Gerät, z. B. `hw:CARD=CODEC,DEV=0`
+
+- `PHOENIX_SAMPLE_RATE`
+  default: `48000`
+
+- `PHOENIX_PERIOD_SIZE`
+  default: `128`
+
+- `PHOENIX_BUFFER_SIZE`
+  default: `512`
+
+- `PHOENIX_GLOBAL_CONFIG_PATH`
+  default: `$HOME/.config/phoenix/global-config.json`
+
+- `PHOENIX_RECORDINGS_DIR_ANALYZER`
+  default: `/home/analyzer/Aufnahmen`
+
+- `PHOENIX_RECORDINGS_DIR_VOLUMIO`
+  default: `/home/volumio/Aufnahmen`
+
+- `PHOENIX_MAX_RECORDING_UPLOAD_BYTES`
+  default: `2147483648`
+
+- `PHOENIX_LR_FRAC_DELAY_ENABLED`
+  default: `true`
+
+- `PHOENIX_LR_FRAC_DELAY_SAMPLES`
+  default: `0.996`
+
+- `PHOENIX_LOG`
+  default: `phoenix=info,tower_http=info`
+
+## Hinweise
+
+- Phoenix ist jetzt der produktive Hauptpfad, nicht mehr nur ein Scaffold.
+- Das Changelog der GUI liegt in [index.html](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/www/index.html).
+- Build-Logs beim Pi-Start landen in der Regel unter:
+
+```text
+~/phoenix-build.log
+```
+
+- Laufzeit-Logs der X-/Kiosk-Session liegen unter:
+
+```text
+/home/analyzer/analyzer-kiosk.log
+```