# WS-03 Parameterinventar — Semantik & Runtime-Konsistenz

> Repo-grounded Übersicht der öffentlich sichtbaren und runtime-relevanten Parameter aus `internal/config`, `internal/control`, `internal/app/engine` und dem HTTP-API-Stack.

## Ziel

Dieses Dokument liefert einen festen Referenzpunkt für WS-03:
1. Welche Parameter konfiguriert werden können (JSON + CLI + HTTP).
2. Welche Wertebereiche und Einheiten sie haben.
3. Welche davon live per HTTP-Patch übernommen werden.
4. Wo im Code die Validierung, Anwendung und Telemetrie lebt.

Alle Angaben beziehen sich direkt auf die `Config`-Definition (`internal/config/config.go`), den Control-Server (`internal/control/control.go`) und die Engine-Live-Updates (`internal/app/engine.go`, `internal/offline/generator.go`).

---

## 1. Control-Plane & Backend (requires restart)

| Parameter | Typ | Default | Range / Einheit | Hot reload | Beschreibung & Code-Referenzen |
|---|---|---|---|---|---|
| `control.listenAddress` | `string` | `"127.0.0.1:8088"` | `<host>:<port>` | ❌ (Server-Neustart) | HTTP-Server-Bindadresse, `cmd/fmrtx/main.go` startet Listen mit `cfg.Control.ListenAddress`. |
| `backend.kind` | `string` | `"file"` | `file` / `pluto` / `soapy` | ❌ | Wahl des TX-Backends; `selectDriver` (cmd/fmrtx/main.go) entscheidet darauf basierend. |
| `backend.device` | `string` | `""` | SoapySDR/Pluto device string | ❌ | Wird an `platform.SoapyConfig.Device` weitergegeben. |
| `backend.deviceSampleRateHz` | `float64` | `0` | >0 Hz (0 = fallback auf `fm.compositeRateHz`) | ❌ | Treibt `cfg.EffectiveDeviceRate()` und damit Treiber-Konfiguration (`cmd/fmrtx/main.go`). |
| `backend.uri` / `deviceArgs` | `string` / `map[string]string` | `""` / `nil` | Driver-spezifisch | ❌ | Zusätzliche Soapy-Parameter, weitergereicht an `platform.SoapyConfig`. |

> `backend.*` dürfen zur Konfiguration gepatcht werden, gelten aber erst nach Neustart des TX-Modus.

---

## 2. Audio-Quelle (reload requires restart)

| Parameter | Typ | Default | Range | Hot reload | Referenzen |
|---|---|---|---|---|---|
| `audio.inputPath` | `string` | `""` | Pfad zu WAV-Dateien | ❌ | `offline/generator.sourceFor` entscheidet, ob WAV oder interne Töne genutzt werden; `audio.LoadWAVSource`. |
| `audio.gain` | `float64` | `1.0` | `0..4` | ❌ | Verstärkt vor Pre-Emphasis (`generator.NewPreEmphasizedSource`, `docs/DSP-CHAIN.md`). |
| `audio.toneLeftHz`, `toneRightHz` | `float64` | `1000`, `1600` | >0 Hz | ❌ | Fallback-Tonquelle (`audio.NewConfiguredToneSource`). |
| `audio.toneAmplitude` | `float64` | `0.4` | `0..1` | ❌ | Amplitude der internen Töne, skaliert vor DSP. |

Diese Parameter sind nur im JSON/HTTP-Config sichtbar, aber nicht live per `LiveConfigUpdate` (keine `LivePatch`-Felder). Ein Restart der TX-Engine ist nötig.

---

## 3. FM-DSP Parameter (häufig hot-reloadable)

| Parameter | Typ | Default | Range / Einheit | Hot reload | Beschreibung & Code-Referenzen |
|---|---|---|---|---|---|
| `fm.frequencyMHz` | `float64` | `100.0` | `65..110` MHz | ✅ (LivePatch → Engine.UpdateConfig) | Ruft `Engine.pendingFreq` auf, `driver.Tune` wird zwischen Chunks ausgeführt (`internal/app/engine.go`, `control.LivePatch`). |
| `fm.outputDrive` | `float64` | `0.5` | `0..10` (empfohlen `1..4`) | ✅ | Multiplikator vor Limiter/Klipps (`generator.GenerateFrame`, `docs/DSP-CHAIN.md`). Validierung: `internal/config/config.go` + `Engine.UpdateConfig` (CFG-SEM-001 behoben, nun 0..10). |
| `fm.stereoEnabled` | `bool` | `true` | — | ✅ | Schaltet Stereo-Encode und Pilot (Intern `offpkg.Generator`). |
| `fm.pilotLevel` | `float64` | `0.09` | `0..0.2` (9% ±75 kHz) | ✅ | Pilot-Addition nach Composite-Clipper (`generator.GenerateFrame`). |
| `fm.rdsInjection` | `float64` | `0.04` | `0..0.15` | ✅ | RDS-Träger am Ende der Kette (`generator.GenerateFrame`). |
| `fm.preEmphasisTauUS` | `float64` | `50` | `0` / `50` / `75` µs | ❌ | Pre-Emphasis-Filter vor Tonquelle (`NewPreEmphasizedSource`). |
| `fm.limiterEnabled` | `bool` | `true` | — | ✅ | Aktiviert StereoLimiter (`dsp.NewStereoLimiter`). |
| `fm.limiterCeiling` | `float64` | `1.0` | `0..2` | ✅ | Maximalwert für Clips und Composite Sättigung. |
| `fm.bs412Enabled` | `bool` | `false` | — | ❌ | Optionaler ITU-R BS.412 MPX Power Limiter (`dsp.NewBS412Limiter`). |
| `fm.bs412ThresholdDBr` | `float64` | `0` | beliebig (dBr) | ❌ | Grenzwert für BS.412-Limiter. |
| `fm.mpxGain` | `float64` | `1.0` | `0.1..5` | ❌ | Hardware-Calibration für effective Deviation (`generator.init`, `FMModulator`). |
| `fm.maxDeviationHz` | `float64` | `75000` | `0..150000` Hz | ❌ | Steuert `FMModulator.MaxDeviation`. |
| `fm.compositeRateHz` | `int` | `228000` | — | ❌ | Setzt DSP-Sample-Rate, beeinflusst `generator` + `Engine` (`cfg.EffectiveDeviceRate`). |
| `fm.fmModulationEnabled` | `bool` | `true` | — | ❌ | Schaltet `dsp.FMModulator`; beim Split-Rate-Modus wird es automatisch deaktiviert. |

> Hot-reload-fähige Felder kommen in `LiveConfigUpdate`. Parameter wie `preEmphasisTauUS`, `bs412*`, `mpxGain` bleiben nur nach Neustart gültig und können via `/config` gepatched werden, aber nicht live übernommen.

---

## 4. RDS & Telemetrie

| Parameter | Typ | Default | Range | Hot reload | Beschreibung |
|---|---|---|---|---|---|
| `rds.enabled` | `bool` | `true` | — | ✅ | Aktiviert Encoder und Telemetrie (`generator.init`). |
| `rds.pi` | `string` | `"1234"` | Hex, 4 Zeichen | ❌ | Validierung `ParsePI`. |
| `rds.ps` | `string` | `"FMRTX"` | max 8 Zeichen | ✅ | Realtime-Update via `rdsp.UpdateText`. |
| `rds.radioText` | `string` | `"fm-rds-tx"` | max 64 Zeichen | ✅ | Text wird an Encoder weitergereicht. |
| `rds.pty` | `int` | `0` | `0..31` | ❌ | Wird nur bei Init in Encoder gesetzt. |

Telemetrie: `/status` (control) meldet `rdsEnabled`, `pilotLevel`, `limiterEnabled` u.a. (`internal/control/control.go`).

---

## 5. Hot-Update-Fluss

1. `POST /config` (`internal/control.control.go`) aktualisiert das Snapshot-Config und validiert mit `Config.Validate()`.
2. Für die Live-fähigen Parameter (⇓) wird ein `LivePatch` erstellt.
3. `TXController.UpdateConfig` (z.B. `txBridge`) übersetzt in `LiveConfigUpdate` und ruft `Engine.UpdateConfig`.
4. `Engine` validiert identische Bereiche (jetzt 0..10 für `outputDrive`) und schreibt in Generator-Live-Params.
5. Änderungen werden zwischen Chunks angewendet (`pendingFreq`, `generator.UpdateLive`).

| Live-Feld | Code-Quellen |
|---|---|
| `frequencyMHz` | `LiveConfigUpdate`, `Engine.pendingFreq`, `driver.Tune` |
| `outputDrive` | `Generator.LiveParams.OutputDrive`, `CFG-SEM-001 fix` |
| `stereoEnabled`, `pilotLevel`, `rdsInjection` | `generator.GenerateFrame` |
| `rdEnabled`, `limiterEnabled`, `limiterCeiling` | `LiveParams`, `Engine.UpdateConfig` |
| `PS`, `RadioText` | `generator.RDSEncoder().UpdateText` |

Dieses Inventar ist Referenz für WS-03-T1/T2 und bildet die Basis für Tests und Telemetrie.

---

## 6. Weiteres Nachweis-Tracking

- Parameterwerte validiert über `config.Config.Validate()` (`internal/config/config.go`).
- CFG-SEM-001 (`fm.outputDrive`) wird sowohl von Config als auch von Live-Update begrenzt (nun 0..10).
- Dokumentation: `docs/DSP-CHAIN.md` beschreibt die grafische Signalverkettung und damit die Bedeutung von `outputDrive`, `limiterCeiling`, `pilotLevel` und `rdsInjection`.
- Runtime-Exposition: `/status` und `/runtime` melden Sample-, Driver- und Engine-Stats (control handler).

Diese Datei gehört ab sofort zu WS-03 und sollte bei weiteren Änderungen an öffentlichen Parametern gepflegt werden.