Phoenix/README.md

# 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/RÄ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/RÄTSEL/VERSION2/Phoenix/kiosk-start.sh)
- [session.sh](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/session.sh)
- [analyzer-kiosk.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-kiosk.service)
- [analyzer-web.service](/Users/mike_i386/Desktop/RÄ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/RÄTSEL/VERSION2/Phoenix/session_volumio.sh)
- [analyzer-kiosk-volumio.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-kiosk-volumio.service)
- [analyzer-web-volumio.service](/Users/mike_i386/Desktop/RÄ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/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-kiosk.service), [analyzer-web.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-web.service)
  - Session: [session.sh](/Users/mike_i386/Desktop/RÄ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/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-kiosk-volumio.service), [analyzer-web-volumio.service](/Users/mike_i386/Desktop/RÄTSEL/VERSION2/Phoenix/etc/systemd/system/analyzer-web-volumio.service)
  - Session: [session_volumio.sh](/Users/mike_i386/Desktop/RÄ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/RÄTSEL/VERSION2/Phoenix/reference-config/phoenix-global-config.analyzer.json)
- [phoenix-global-config.volumio.json](/Users/mike_i386/Desktop/RÄ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/RÄ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
```