docs(ingest): align phase-1 status and decoder fallback semantics

пре 1 месец · 51db52f934
--- a/README.md
+++ b/README.md
@@ -1,340 +1,356 @@
 # fm-rds-tx
 Go-based FM stereo transmitter with RDS. Supports ADALM-Pluto (PlutoSDR) and SoapySDR-compatible TX devices.
 ## Status
 **Current status:** `v0.9.0` — runtime hardening milestone
 What is already in place:
 - complete DSP chain: audio -> pre-emphasis -> stereo encoding -> RDS -> MPX -> limiter -> FM modulation
 - real hardware TX paths for PlutoSDR / SoapySDR backends
 - continuous TX engine with runtime telemetry
 - dry-run, offline generation, and simulated TX modes
 - HTTP control plane with live config patching and runtime/status endpoints
 - browser UI on `/`
 - live audio ingestion via stdin or HTTP stream input
 Current engineering focus:
 - merge/release stabilization after runtime hardening
 - deferred hardware-in-the-loop / RF validation work
 - deferred device-aware capability / calibration work
 - deferred signal self-monitoring work
 For the active runtime-hardening track, see:
 - `docs/pro-runtime-hardening-workboard.md`
 ## Signal path
 ```text
 Audio Source -> PreEmphasis(50us/75us/off) -> StereoEncoder(19k + 38k DSB-SC)
 -> RDS(57k BPSK) -> MPX Combiner -> Limiter -> FM Modulator(+/-75kHz)
 -> optional split-rate FM upsampling -> SDR backend -> RF output
 ```
 For deeper DSP details, see:
 - `docs/DSP-CHAIN.md`
 ## Prerequisites
 ### Go
 - Go version from `go.mod` (currently Go 1.22)
 ### Native SDR dependencies
 Depending on backend, native libraries are required:
 - **SoapySDR backend**
  - build with `-tags soapy`
  - requires SoapySDR native library (`SoapySDR.dll` / `libSoapySDR.so` / `libSoapySDR.dylib`)
  - on Windows, PothosSDR is the expected setup
 - **Pluto backend**
  - uses native `libiio`
  - Windows expects `libiio.dll`
  - Linux build/runtime expects `pkg-config` + `libiio`
 ### Hardware / legal
 - validate RF output, deviation, filtering, and power with proper measurement equipment
 - use only within applicable legal and regulatory constraints
 ## Quick start
 ## Build
 ```powershell
 # Build CLI tools without hardware-specific build tags:
 go build ./cmd/fmrtx
 go build ./cmd/offline
 # Build fmrtx with SoapySDR support:
 go build -tags soapy ./cmd/fmrtx
 ```
 ## Quick verification
 ```powershell
 # Print effective config
 go run ./cmd/fmrtx -print-config
 # Run tests
 go test ./...
 # Basic dry-run summary
 go run ./cmd/fmrtx --dry-run --dry-output build/dryrun/frame.json
 ```
 For additional build/test commands, see:
 - `docs/README.md`
 ## Common usage flows
 ### 1) List available SDR devices
 ```powershell
 .\fmrtx.exe --list-devices
 ```
 ### 2) Dry-run / config verification
 ```powershell
 .\fmrtx.exe --dry-run --dry-output build/dryrun/frame.json
 # Write dry-run JSON to stdout
 .\fmrtx.exe --dry-run --dry-output -
 ```
 ### 3) Offline IQ/composite generation
 ```powershell
 go run ./cmd/offline -duration 2s -output build/offline/composite.iqf32
 # Optional output rate override
 go run ./cmd/offline -duration 500ms -output build/offline/composite.iqf32 -output-rate 228000
 ```
 ### 4) Simulated transmit path
 ```powershell
 go run ./cmd/fmrtx --simulate-tx --simulate-output build/sim/simulated-soapy.iqf32 --simulate-duration 250ms
 ```
 ### 5) Real TX with config file
 ```powershell
 # Start TX service with manual start over HTTP
 .\fmrtx.exe --tx --config docs/config.plutosdr.json
 # Start and begin transmitting immediately
 .\fmrtx.exe --tx --tx-auto-start --config docs/config.plutosdr.json
 ```
 ### 6) Live audio via stdin
 ```powershell
 ffmpeg -i "http://svabi.ch:8443/stream" -f s16le -ar 44100 -ac 2 - | .\fmrtx.exe --tx --tx-auto-start --audio-stdin --config docs/config.plutosdr.json
 ```
 ### 7) Custom audio input rate
 ```powershell
 ffmpeg -i source.wav -f s16le -ar 48000 -ac 2 - | .\fmrtx.exe --tx --tx-auto-start --audio-stdin --audio-rate 48000 --config docs/config.plutosdr.json
 ```
 ### 8) HTTP audio ingest
 Start the control plane with `--audio-http` to accept raw PCM pushes on `/audio/stream` and feed them into the live encoder:
 Set `Content-Type` to `application/octet-stream` (or `audio/L16`) when posting audio data:
 ```powershell
 ffmpeg -i music.mp3 -f s16le -ar 44100 -ac 2 - | curl -X POST -H "Content-Type: application/octet-stream" --data-binary @- http://localhost:8088/audio/stream
 ```
 ## CLI overview
 ## `fmrtx`
 Important runtime modes and flags include:
 - `--tx`
 - `--tx-auto-start`
 - `--dry-run`
 - `--dry-output <path|- >`
 - `--simulate-tx`
 - `--simulate-output <path>`
 - `--simulate-duration <duration>`
 - `--config <path>`
 - `--print-config`
 - `--list-devices`
 - `--audio-stdin`
 - `--audio-rate <hz>`
 - `--audio-http`
 ## `offline`
 Useful flags include:
 - `-duration <duration>`
 - `-output <path>`
 - `-output-rate <hz>`
 If the README is too high-level for the exact CLI surface, check:
 - `cmd/fmrtx/main.go`
 - `cmd/offline/main.go`
 ## HTTP control plane
 Base URL: `http://{listenAddress}` (default typically `127.0.0.1:8088`)
 Security note:
 - keep the control plane bound locally unless you intentionally place it behind a trusted and hardened access layer
 ### Main endpoints
 ```text
 GET  /              browser UI
 GET  /healthz       health check
 GET  /status        current config/status snapshot
 GET  /runtime       live engine / driver / audio telemetry
 GET  /config        full config
 POST /config        patch config / live updates
 GET  /dry-run       synthetic frame summary
 POST /tx/start      start transmission
 POST /tx/stop       stop transmission
 POST /audio/stream  push raw S16LE stereo PCM into live stream buffer (Content-Type: application/octet-stream or audio/L16 required)
 ```
 ### What the control plane covers
 - TX start / stop
 - runtime status and driver telemetry
 - config inspection
 - live patching of selected parameters
 - dry-run inspection
 - browser-accessible control UI
 - optional HTTP audio ingest (enable with `--audio-http`)
 ### Live config notes
 `POST /config` supports live updates for selected fields such as:
 - frequency
 - stereo enable/disable
 - pilot / RDS injection levels
 - RDS enable/disable
 - limiter settings
 - PS / RadioText
 Some parameters are saved but not live-applied and require restart.
 For the full API contract, examples, live-patch semantics, and `/audio/stream` details, see:
 - `docs/API.md`
 ## Configuration
 Sample configs:
 - `docs/config.sample.json`
 - `docs/config.plutosdr.json`
 - `docs/config.orangepi-pluto-soapy.json`
 Important config areas include:
 - `fm.*`
 - `rds.*`
 - `audio.*`
 - `backend.*`
 - `control.*`
 Examples of relevant fields you may want to inspect:
 - `fm.outputDrive`
 - `fm.mpxGain`
 - `fm.bs412Enabled`
 - `fm.bs412ThresholdDBr`
 - `fm.fmModulationEnabled`
 - `backend.kind`
 - `backend.driver`
 - `backend.deviceArgs`
 - `backend.uri`
 - `backend.deviceSampleRateHz`
 - `backend.outputPath`
 - `control.listenAddress`
 For deeper config/API behavior, refer to:
 - `internal/config/config.go`
 - `docs/API.md`
 - `docs/config.sample.json`
 ## Development and testing
 Useful commands:
 ```powershell
 go test ./...
 go run ./cmd/fmrtx -print-config
 go run ./cmd/fmrtx -config docs/config.sample.json
 go run ./cmd/fmrtx --dry-run --dry-output build/dryrun/frame.json
 go run ./cmd/fmrtx --simulate-tx --simulate-output build/sim/simulated-soapy.iqf32 --simulate-duration 250ms
 go run ./cmd/offline -duration 500ms -output build/offline/composite.iqf32
 ```
 See also:
 - `docs/README.md`
 ## PlutoSDR / backend notes
 - PlutoSDR commonly runs with a device-side sample rate above composite rate, so split-rate mode may be used automatically
 - SoapySDR backend is suitable for Soapy-compatible TX hardware
 - backend/device settings are selected through config rather than hardcoded paths
 - runtime telemetry should be used to inspect effective TX state during operation
 ## Repository layout
 ```text
 cmd/
  fmrtx/                     main CLI
  offline/                   offline generator
 internal/
  app/                       TX engine + runtime state
  audio/                     audio input, resampling, tone generation, stream buffering
  config/                    config schema and validation
  control/                   HTTP control plane + browser UI
  dryrun/                    dry-run JSON summaries
  dsp/                       DSP primitives
  mpx/                       MPX combiner
  offline/                   full offline composite generation
  output/                    output/backend abstractions
  platform/                  backend abstractions and device/runtime stats
  platform/soapysdr/         CGO SoapySDR binding
  platform/plutosdr/         Pluto/libiio backend code
  rds/                       RDS encoder
  stereo/                    stereo encoder
 docs/
  API.md
  DSP-CHAIN.md
  README.md
  config.sample.json
  config.plutosdr.json
  config.orangepi-pluto-soapy.json
  pro-runtime-hardening-workboard.md
 scripts/
 examples/
 ```
 ## Planning / workboard
 For the current runtime-hardening / professionalization track, see:
 - `docs/pro-runtime-hardening-workboard.md`
 This is the living workboard for:
 - status tracking
 - confirmed findings
 - open technical decisions
 - verification notes
 - implementation progress
 ## Release / project docs
 Additional project docs:
 - `CHANGELOG.md`
 - `RELEASE.md`
 - `docs/README.md`
 - `docs/API.md`
 - `docs/DSP-CHAIN.md`
 - `docs/NOTES.md`
 ## Legal note
 This project is intended only for lawful use within relevant license and regulatory constraints.
 RF output, deviation, filtering, and transmitted power must be validated with proper measurement equipment.
 # fm-rds-tx
 Go-based FM stereo transmitter with RDS. Supports ADALM-Pluto (PlutoSDR) and SoapySDR-compatible TX devices.
 ## Status
 **Current status:** `v0.9.0` — runtime hardening milestone
 What is already in place:
 - complete DSP chain: audio -> pre-emphasis -> stereo encoding -> RDS -> MPX -> limiter -> FM modulation
 - real hardware TX paths for PlutoSDR / SoapySDR backends
 - continuous TX engine with runtime telemetry
 - dry-run, offline generation, and simulated TX modes
 - HTTP control plane with live config patching and runtime/status endpoints
 - browser UI on `/`
 - ingest runtime in front of TX stream sink, plus shared source/runtime stats
 - ingest source factory for `stdin`, `http-raw`, and `icecast`
 - Icecast source adapter with reconnect and decoder selection (`auto`/`native`/`ffmpeg`)
 - decoder layer with explicit ffmpeg fallback path
 Current engineering focus:
 - merge/release stabilization after runtime hardening
 - deferred hardware-in-the-loop / RF validation work
 - deferred device-aware capability / calibration work
 - deferred signal self-monitoring work
 - finish native Icecast decoder wiring (`mp3`/`oggvorbis`/`aac` are placeholders; ffmpeg fallback is the currently functional decode path)
 For the active runtime-hardening track, see:
 - `docs/pro-runtime-hardening-workboard.md`
 ## Signal path
 ```text
 Audio Source -> PreEmphasis(50us/75us/off) -> StereoEncoder(19k + 38k DSB-SC)
 -> RDS(57k BPSK) -> MPX Combiner -> Limiter -> FM Modulator(+/-75kHz)
 -> optional split-rate FM upsampling -> SDR backend -> RF output
 ```
 For deeper DSP details, see:
 - `docs/DSP-CHAIN.md`
 ## Prerequisites
 ### Go
 - Go version from `go.mod` (currently Go 1.22)
 ### Native SDR dependencies
 Depending on backend, native libraries are required:
 - **SoapySDR backend**
  - build with `-tags soapy`
  - requires SoapySDR native library (`SoapySDR.dll` / `libSoapySDR.so` / `libSoapySDR.dylib`)
  - on Windows, PothosSDR is the expected setup
 - **Pluto backend**
  - uses native `libiio`
  - Windows expects `libiio.dll`
  - Linux build/runtime expects `pkg-config` + `libiio`
 ### Hardware / legal
 - validate RF output, deviation, filtering, and power with proper measurement equipment
 - use only within applicable legal and regulatory constraints
 ## Quick start
 ## Build
 ```powershell
 # Build CLI tools without hardware-specific build tags:
 go build ./cmd/fmrtx
 go build ./cmd/offline
 # Build fmrtx with SoapySDR support:
 go build -tags soapy ./cmd/fmrtx
 ```
 ## Quick verification
 ```powershell
 # Print effective config
 go run ./cmd/fmrtx -print-config
 # Run tests
 go test ./...
 # Basic dry-run summary
 go run ./cmd/fmrtx --dry-run --dry-output build/dryrun/frame.json
 ```
 For additional build/test commands, see:
 - `docs/README.md`
 ## Common usage flows
 ### 1) List available SDR devices
 ```powershell
 .\fmrtx.exe --list-devices
 ```
 ### 2) Dry-run / config verification
 ```powershell
 .\fmrtx.exe --dry-run --dry-output build/dryrun/frame.json
 # Write dry-run JSON to stdout
 .\fmrtx.exe --dry-run --dry-output -
 ```
 ### 3) Offline IQ/composite generation
 ```powershell
 go run ./cmd/offline -duration 2s -output build/offline/composite.iqf32
 # Optional output rate override
 go run ./cmd/offline -duration 500ms -output build/offline/composite.iqf32 -output-rate 228000
 ```
 ### 4) Simulated transmit path
 ```powershell
 go run ./cmd/fmrtx --simulate-tx --simulate-output build/sim/simulated-soapy.iqf32 --simulate-duration 250ms
 ```
 ### 5) Real TX with config file
 ```powershell
 # Start TX service with manual start over HTTP
 .\fmrtx.exe --tx --config docs/config.plutosdr.json
 # Start and begin transmitting immediately
 .\fmrtx.exe --tx --tx-auto-start --config docs/config.plutosdr.json
 ```
 ### 6) Live audio via stdin
 ```powershell
 ffmpeg -i "http://svabi.ch:8443/stream" -f s16le -ar 44100 -ac 2 - | .\fmrtx.exe --tx --tx-auto-start --audio-stdin --config docs/config.plutosdr.json
 ```
 ### 7) Custom audio input rate
 ```powershell
 ffmpeg -i source.wav -f s16le -ar 48000 -ac 2 - | .\fmrtx.exe --tx --tx-auto-start --audio-stdin --audio-rate 48000 --config docs/config.plutosdr.json
 ```
 ### 8) HTTP audio ingest
 Start the control plane with `--audio-http` to accept raw PCM pushes on `/audio/stream` and feed them into the live encoder:
 Set `Content-Type` to `application/octet-stream` (or `audio/L16`) when posting audio data:
 ```powershell
 ffmpeg -i music.mp3 -f s16le -ar 44100 -ac 2 - | curl -X POST -H "Content-Type: application/octet-stream" --data-binary @- http://localhost:8088/audio/stream
 ```
 ### 9) Icecast ingest via config
 Use `ingest.kind = "icecast"` and set `ingest.icecast.url` in config.
 Decoder semantics in Phase 1:
 - `ingest.icecast.decoder = "auto"`: try native by content-type, fallback to ffmpeg on unsupported paths
 - `ingest.icecast.decoder = "native"`: native only, no fallback
 - `ingest.icecast.decoder = "ffmpeg"` (or `fallback`): ffmpeg only
 Current implementation note: native codec packages exist but are placeholders; practical decode today is ffmpeg fallback.
 ## CLI overview
 ## `fmrtx`
 Important runtime modes and flags include:
 - `--tx`
 - `--tx-auto-start`
 - `--dry-run`
 - `--dry-output <path|- >`
 - `--simulate-tx`
 - `--simulate-output <path>`
 - `--simulate-duration <duration>`
 - `--config <path>`
 - `--print-config`
 - `--list-devices`
 - `--audio-stdin`
 - `--audio-rate <hz>`
 - `--audio-http`
 ## `offline`
 Useful flags include:
 - `-duration <duration>`
 - `-output <path>`
 - `-output-rate <hz>`
 If the README is too high-level for the exact CLI surface, check:
 - `cmd/fmrtx/main.go`
 - `cmd/offline/main.go`
 ## HTTP control plane
 Base URL: `http://{listenAddress}` (default typically `127.0.0.1:8088`)
 Security note:
 - keep the control plane bound locally unless you intentionally place it behind a trusted and hardened access layer
 ### Main endpoints
 ```text
 GET  /              browser UI
 GET  /healthz       health check
 GET  /status        current config/status snapshot
 GET  /runtime       live engine / driver / audio telemetry
 GET  /config        full config
 POST /config        patch config / live updates
 GET  /dry-run       synthetic frame summary
 POST /tx/start      start transmission
 POST /tx/stop       stop transmission
 POST /audio/stream  push raw S16LE stereo PCM into live stream buffer (Content-Type: application/octet-stream or audio/L16 required)
 ```
 ### What the control plane covers
 - TX start / stop
 - runtime status and driver telemetry
 - config inspection
 - live patching of selected parameters
 - dry-run inspection
 - browser-accessible control UI
 - optional HTTP audio ingest (enable with `--audio-http`)
 ### Live config notes
 `POST /config` supports live updates for selected fields such as:
 - frequency
 - stereo enable/disable
 - pilot / RDS injection levels
 - RDS enable/disable
 - limiter settings
 - PS / RadioText
 Some parameters are saved but not live-applied and require restart.
 For the full API contract, examples, live-patch semantics, and `/audio/stream` details, see:
 - `docs/API.md`
 ## Configuration
 Sample configs:
 - `docs/config.sample.json`
 - `docs/config.plutosdr.json`
 - `docs/config.orangepi-pluto-soapy.json`
 Important config areas include:
 - `fm.*`
 - `rds.*`
 - `audio.*`
 - `backend.*`
 - `control.*`
 - `ingest.*`
 Examples of relevant fields you may want to inspect:
 - `fm.outputDrive`
 - `fm.mpxGain`
 - `fm.bs412Enabled`
 - `fm.bs412ThresholdDBr`
 - `fm.fmModulationEnabled`
 - `backend.kind`
 - `backend.driver`
 - `backend.deviceArgs`
 - `backend.uri`
 - `backend.deviceSampleRateHz`
 - `backend.outputPath`
 - `control.listenAddress`
 For deeper config/API behavior, refer to:
 - `internal/config/config.go`
 - `docs/API.md`
 - `docs/config.sample.json`
 ## Development and testing
 Useful commands:
 ```powershell
 go test ./...
 go run ./cmd/fmrtx -print-config
 go run ./cmd/fmrtx -config docs/config.sample.json
 go run ./cmd/fmrtx --dry-run --dry-output build/dryrun/frame.json
 go run ./cmd/fmrtx --simulate-tx --simulate-output build/sim/simulated-soapy.iqf32 --simulate-duration 250ms
 go run ./cmd/offline -duration 500ms -output build/offline/composite.iqf32
 ```
 See also:
 - `docs/README.md`
 ## PlutoSDR / backend notes
 - PlutoSDR commonly runs with a device-side sample rate above composite rate, so split-rate mode may be used automatically
 - SoapySDR backend is suitable for Soapy-compatible TX hardware
 - backend/device settings are selected through config rather than hardcoded paths
 - runtime telemetry should be used to inspect effective TX state during operation
 ## Repository layout
 ```text
 cmd/
  fmrtx/                     main CLI
  offline/                   offline generator
 internal/
  app/                       TX engine + runtime state
  audio/                     audio input, resampling, tone generation, stream buffering
  config/                    config schema and validation
  control/                   HTTP control plane + browser UI
  dryrun/                    dry-run JSON summaries
  dsp/                       DSP primitives
  mpx/                       MPX combiner
  offline/                   full offline composite generation
  output/                    output/backend abstractions
  platform/                  backend abstractions and device/runtime stats
  platform/soapysdr/         CGO SoapySDR binding
  platform/plutosdr/         Pluto/libiio backend code
  rds/                       RDS encoder
  stereo/                    stereo encoder
 docs/
  API.md
  DSP-CHAIN.md
  README.md
  config.sample.json
  config.plutosdr.json
  config.orangepi-pluto-soapy.json
  pro-runtime-hardening-workboard.md
 scripts/
 examples/
 ```
 ## Planning / workboard
 For the current runtime-hardening / professionalization track, see:
 - `docs/pro-runtime-hardening-workboard.md`
 This is the living workboard for:
 - status tracking
 - confirmed findings
 - open technical decisions
 - verification notes
 - implementation progress
 ## Release / project docs
 Additional project docs:
 - `CHANGELOG.md`
 - `RELEASE.md`
 - `docs/README.md`
 - `docs/API.md`
 - `docs/DSP-CHAIN.md`
 - `docs/NOTES.md`
 ## Legal note
 This project is intended only for lawful use within relevant license and regulatory constraints.
 RF output, deviation, filtering, and transmitted power must be validated with proper measurement equipment.
--- a/docs/API.md
+++ b/docs/API.md
@@ -1,416 +1,427 @@
 # fm-rds-tx HTTP Control API
 Base URL: `http://{listenAddress}` (default `127.0.0.1:8088`)
 ---
 ## Endpoints
 ### `GET /healthz`
 Health check.
 **Response:**
 ```json
 {"ok": true}
 ```
 This endpoint is a simple liveness signal — it does not include runtime-state data or audit counters. Use it for readiness/liveness probes.
 ---
 ### `GET /status`
 Current transmitter status (read-only snapshot). Runtime indicator, alert, and queue stats from the running TX controller are mirrored here for quick health checks.
 **Response:**
 ```json
 {
  "service": "fm-rds-tx",
  "backend": "pluto",
  "frequencyMHz": 100.0,
  "stereoEnabled": true,
  "rdsEnabled": true,
  "preEmphasisTauUS": 50,
  "limiterEnabled": true,
  "fmModulationEnabled": true,
  "runtimeIndicator": "normal",
  "runtimeAlert": "",
  "queue": {
    "capacity": 3,
    "depth": 1,
    "fillLevel": 0.33,
    "health": "low"
  }
 }
 ```
 `runtimeIndicator` is derived from the engine queue health plus any late buffers observed in the last 5 seconds and can be "normal", "degraded", or "queueCritical".
 `runtimeState` mirrors the same runtime-state machine string that `/runtime` exposes as `engine.state` when a TX controller is active, so quick health checks reuse the same terminology.
 `runtimeAlert` surfaces a short reason (e.g. "queue health low" or "late buffers") when the indicator is not "normal", but late-buffer alerts expire after a few seconds once cycle times settle so the signal doesn't stay stuck on degraded. The cumulative `lateBuffers` counter returned by `/runtime` still shows how many late cycles have occurred since start for post-mortem diagnosis.
 ---
 ### `GET /runtime`
 Live engine and driver telemetry. Only populated when TX is active.
 **Response:**
 ```json
 {
  "engine": {
    "state": "running",
    "runtimeStateDurationSeconds": 12.4,
    "appliedFrequencyMHz": 100.0,
    "chunksProduced": 12345,
    "totalSamples": 1408950000,
    "underruns": 0,
    "lastError": "",
    "uptimeSeconds": 3614.2,
    "faultCount": 2,
    "lastFault": {
      "time": "2026-04-06T00:00:00Z",
      "reason": "queueCritical",
      "severity": "faulted",
      "message": "queue health critical for 5 checks"
    },
    "faultHistory": [
      {
        "time": "2026-04-06T00:00:00Z",
        "reason": "queueCritical",
        "severity": "faulted",
        "message": "queue health critical for 5 checks"
      }
    ],
    "transitionHistory": [
      {
        "time": "2026-04-06T00:00:00Z",
        "from": "running",
        "to": "degraded",
        "severity": "warn"
      }
    ]
  },
  "driver": {
    "txEnabled": true,
    "streamActive": true,
    "framesWritten": 12345,
    "samplesWritten": 1408950000,
    "underruns": 0,
    "underrunStreak": 0,
    "maxUnderrunStreak": 0,
    "effectiveSampleRateHz": 2280000
  },
  "controlAudit": {
    "methodNotAllowed": 0,
    "unsupportedMediaType": 0,
    "bodyTooLarge": 0,
    "unexpectedBody": 0
  }
 }
 ```
 `engine.state` spiegelt jetzt die Runtime-State-Maschine wider (idle, arming, prebuffering, running, degraded, muted, faulted, stopping) und bietet eine erste beobachtbare Basis für Fault-Transitions.
 `runtimeStateDurationSeconds` sagt, wie viele Sekunden die Engine bereits im aktuellen Runtime-Zustand verweilt. So erkennt man schnell, ob `muted`/`degraded` zu lange dauern oder ob ein Übergang gerade frisch begonnen hat.
 `transitionHistory` liefert die jüngsten Übergänge (from/to, severity, timestamp) damit API und UI die Runtime History synchronisieren können.
 `engine.appliedFrequencyMHz` meldet die zuletzt tatsächlich getunte Frequenz auf der Hardware, sodass man sie mit dem gewünschten `/config`-Wert vergleichen und ausstehende Live-Updates sofort entdecken kann.
 `driver.underrunStreak` reports how many consecutive reads returned silence, and `driver.maxUnderrunStreak` captures the longest such run since the engine started. Together they help differentiate short glitches from persistent underrun storms and can be plotted alongside queue health sparkline telemetry.
 `lastFault.reason` kann jetzt auch `writeTimeout` lauten, wenn der Treiber Schreibaufrufe wiederholt verweigert oder blockiert. Die Control-Plane hebt solche Driver-Faults hervor, damit man Blockaden im Writer-Pfad ohne Log-Search sieht.
 `controlAudit` mirrors the control plane's HTTP reject counters (405/415/413/400). Whenever the HTTP server rejects a request (method not allowed, unsupported media type, body too large, or unexpected body), the respective counter increments — this lets runtime telemetry spot abusive clients without polluting the runtime state payload.
 ---
 ### `POST /runtime/fault/reset`
 Manually acknowledge a `faulted` runtime state so the supervisor can re-enter the recovery path (the engine moves back to `degraded` once the reset succeeds).
 **Response:**
 ```json
 {"ok": true}
 ```
 **Errors:**
 - `405 Method Not Allowed` if the request is not a POST
 - `503 Service Unavailable` when no TX controller is attached (`--tx` mode not active)
 - `409 Conflict` when the engine is not currently faulted or the reset was rejected (e.g. still throttled)
 ---
 ### `GET /config`
 Full current configuration (all fields, including non-patchable).
 **Response:** Complete `Config` JSON object.
 ---
 ### `POST /config`
 **Live parameter update.** Changes are applied to the running TX engine immediately — no restart required. Only include fields you want to change (PATCH semantics).
 The control snapshot (GET /config) only reflects new values once they pass validation and, if the TX engine is running, after the live update succeeded. That keeps the API from reporting desired values that were rejected or still pending.
 **Request body:** JSON with any subset of patchable fields.
 **Content-Type:** `application/json` (charset parameters allowed). Requests without it are rejected with 415 Unsupported Media Type.
 **Response:**
 ```json
 {"ok": true, "live": true}
 ```
 `"live": true` = changes were forwarded to the running engine.  
 `"live": false` = engine not active, changes saved for next start.
 #### Patchable fields — DSP (applied within ~50ms)
 | Field | Type | Range | Description |
 |---|---|---|---|
 | `frequencyMHz` | float | 65–110 | TX center frequency. Tunes hardware LO live. |
 | `outputDrive` | float | 0–10 | Composite output level multiplier (empfohlen 1..4). |
 | `stereoEnabled` | bool | | Enable/disable stereo (pilot + 38kHz subcarrier). |
 | `pilotLevel` | float | 0–0.2 | 19 kHz pilot injection level. |
 | `rdsInjection` | float | 0–0.15 | 57 kHz RDS subcarrier injection level. |
 | `rdsEnabled` | bool | | Enable/disable RDS subcarrier. |
 | `limiterEnabled` | bool | | Enable/disable MPX peak limiter. |
 | `limiterCeiling` | float | 0–2 | Limiter ceiling (max composite amplitude). |
 #### Patchable fields — RDS text (applied within ~88ms)
 | Field | Type | Max length | Description |
 |---|---|---|---|
 | `ps` | string | 8 chars | Program Service name (station name on receiver display). |
 | `radioText` | string | 64 chars | RadioText message (scrolling text on receiver). |
 When `radioText` is updated, the RDS A/B flag toggles automatically per spec, signaling receivers to refresh their display.
 #### Patchable fields — other (saved, not live-applied)
 | Field | Type | Description |
 |---|---|---|
 | `toneLeftHz` | float | Left tone frequency (test generator). |
 | `toneRightHz` | float | Right tone frequency (test generator). |
 | `toneAmplitude` | float | Test tone amplitude (0–1). |
 | `preEmphasisTauUS` | float | Pre-emphasis time constant. **Requires restart.** |
 #### Examples
 ```bash
 # Tune to 99.5 MHz
 curl -X POST localhost:8088/config -d '{"frequencyMHz": 99.5}'
 # Switch to mono
 curl -X POST localhost:8088/config -d '{"stereoEnabled": false}'
 # Update now-playing text
 curl -X POST localhost:8088/config \
  -d '{"ps": "MYRADIO", "radioText": "Artist - Song Title"}'
 # Reduce power + disable limiter
 curl -X POST localhost:8088/config \
  -d '{"outputDrive": 0.8, "limiterEnabled": false}'
 # Full update
 curl -X POST localhost:8088/config -d '{
  "frequencyMHz": 101.3,
  "outputDrive": 2.2,
  "stereoEnabled": true,
  "pilotLevel": 0.041,
  "rdsInjection": 0.021,
  "rdsEnabled": true,
  "limiterEnabled": true,
  "limiterCeiling": 1.0,
  "ps": "PIRATE",
  "radioText": "Broadcasting from the attic"
 }'
 ```
 #### Error handling
 Invalid values return `400 Bad Request` with a descriptive message:
 ```bash
 curl -X POST localhost:8088/config -d '{"frequencyMHz": 200}'
 # → 400: frequencyMHz out of range (65-110)
 ```
 ---
 ### `POST /tx/start`
 Start transmission. Requires `--tx` mode with hardware.
 **Response:**
 ```json
 {"ok": true, "action": "started"}
 ```
 **Errors:**
 - `405` if not POST
 - `503` if no TX controller (not in `--tx` mode)
 - `409` if already running
 ---
 ### `POST /tx/stop`
 Stop transmission.
 **Response:**
 ```json
 {"ok": true, "action": "stopped"}
 ```
 ---
 ### `GET /dry-run`
 Generate a synthetic frame summary without hardware. Useful for config verification.
 **Response:** `FrameSummary` JSON with mode, rates, source info, preview samples.
 ---
 ## Live update architecture
 All live updates are **lock-free** in the DSP path:
 | What | Mechanism | Latency |
 |---|---|---|
 | DSP params | `atomic.Pointer[LiveParams]` loaded once per chunk | ≤ 50ms |
 | RDS text | `atomic.Value` in encoder, read at group boundary | ≤ 88ms |
 | TX frequency | `atomic.Pointer` in engine, `driver.Tune()` between chunks | ≤ 50ms |
 No mutex, no channel, no allocation in the real-time path. The HTTP goroutine writes atomics, the DSP goroutine reads them.
 ## Parameters that require restart
 These cannot be hot-reloaded (they affect DSP pipeline structure):
 - `compositeRateHz` — changes sample rate of entire DSP chain
 - `deviceSampleRateHz` — changes hardware rate / upsampler ratio
 - `maxDeviationHz` — changes FM modulator scaling
 - `preEmphasisTauUS` — changes filter coefficients
 - `rds.pi` / `rds.pty` — rarely change, baked into encoder init
 - `audio.inputPath` — audio source selection
 - `backend.kind` / `backend.device` — hardware selection
 ---
 ### `POST /audio/stream`
 Push raw audio data into the live stream buffer. Format: **S16LE stereo PCM** at the configured `--audio-rate` (default 44100 Hz).
 Requires `--audio-stdin`, `--audio-http`, or another configured stream source to feed the buffer.
 **Request:** Binary body, `application/octet-stream`, raw S16LE stereo PCM bytes. Set `Content-Type` to `application/octet-stream` or `audio/L16`; other media types are rejected. Requests larger than 512 MiB are rejected with `413 Request Entity Too Large`.
 **Response:**
 ```json
 {
  "ok": true,
  "frames": 4096,
  "stats": {
    "available": 12000,
    "capacity": 131072,
    "buffered": 0.09,
    "bufferedDurationSeconds": 0.27,
    "highWatermark": 15000,
    "highWatermarkDurationSeconds": 0.34,
    "written": 890000,
    "underruns": 0,
    "overflows": 0
  }
 }
 ```
 **Example:**
 ```bash
 # Push a file
 ffmpeg -i song.mp3 -f s16le -ar 44100 -ac 2 - | \
  curl -X POST -H "Content-Type: application/octet-stream" --data-binary @- http://pluto:8088/audio/stream
 ```
 **Errors:**
 - `405` if not POST
 - `415` if Content-Type is missing or unsupported (must be `application/octet-stream` or `audio/L16`)
 - `413` if the upload body exceeds the 512 MiB limit
 - `503` if no audio stream configured
 ---
 ## Audio Streaming
 ### Stdin pipe (primary method)
 Pipe any audio source through ffmpeg into the transmitter:
 ```bash
 # Internet radio stream
 ffmpeg -i "http://stream.example.com/radio.mp3" -f s16le -ar 44100 -ac 2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin --config config.json
 # Local music file
 ffmpeg -i music.flac -f s16le -ar 44100 -ac 2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin
 # Playlist (ffmpeg concat)
 ffmpeg -f concat -i playlist.txt -f s16le -ar 44100 -ac 2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin
 # PulseAudio / ALSA capture (Linux)
 parecord --format=s16le --rate=44100 --channels=2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin
 # Custom sample rate (e.g. 48kHz source)
 ffmpeg -i source.wav -f s16le -ar 48000 -ac 2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin --audio-rate 48000
 ```
 ### HTTP audio push
 Push audio from a remote machine via the HTTP API. Run the server with `--audio-http` (and typically `--tx`/`--tx-auto-start`) so the `/audio/stream` endpoint is available.
 ```bash
 # From another machine on the network
 ffmpeg -i music.mp3 -f s16le -ar 44100 -ac 2 - | \
  curl -X POST -H "Content-Type: application/octet-stream" --data-binary @- http://pluto-host:8088/audio/stream
 ```
 ### Audio buffer
 The stream uses a lock-free ring buffer (default: 2 seconds at input rate). Buffer stats are available in `GET /runtime` under `audioStream`:
 ```json
 {
  "audioStream": {
    "available": 12000,
    "capacity": 131072,
    "buffered": 0.09,
    "bufferedDurationSeconds": 0.27,
    "highWatermark": 15000,
    "highWatermarkDurationSeconds": 0.34,
    "written": 890000,
    "underruns": 0,
    "overflows": 0
  }
 }
 ```
 - **underruns**: DSP consumed faster than audio arrived (silence inserted)
 - **overflows**: Audio arrived faster than DSP consumed (data dropped)
 - **buffered**: Fill ratio (0.0 = empty, 1.0 = full)
 - **bufferedDurationSeconds**: Approximate seconds of audio queued in the buffer (`available` frames divided by the sample rate)
 - **highWatermark**: Highest observed buffer occupancy (frames) since the buffer was created
 - **highWatermarkDurationSeconds**: Equivalent peak time (`highWatermark` frames divided by the sample rate)
 When no audio is streaming, the transmitter falls back to the configured tone generator or silence.
 # fm-rds-tx HTTP Control API
 Base URL: `http://{listenAddress}` (default `127.0.0.1:8088`)
 ---
 ## Endpoints
 ### `GET /healthz`
 Health check.
 **Response:**
 ```json
 {"ok": true}
 ```
 This endpoint is a simple liveness signal — it does not include runtime-state data or audit counters. Use it for readiness/liveness probes.
 ---
 ### `GET /status`
 Current transmitter status (read-only snapshot). Runtime indicator, alert, and queue stats from the running TX controller are mirrored here for quick health checks.
 **Response:**
 ```json
 {
  "service": "fm-rds-tx",
  "backend": "pluto",
  "frequencyMHz": 100.0,
  "stereoEnabled": true,
  "rdsEnabled": true,
  "preEmphasisTauUS": 50,
  "limiterEnabled": true,
  "fmModulationEnabled": true,
  "runtimeIndicator": "normal",
  "runtimeAlert": "",
  "queue": {
    "capacity": 3,
    "depth": 1,
    "fillLevel": 0.33,
    "health": "low"
  }
 }
 ```
 `runtimeIndicator` is derived from the engine queue health plus any late buffers observed in the last 5 seconds and can be "normal", "degraded", or "queueCritical".
 `runtimeState` mirrors the same runtime-state machine string that `/runtime` exposes as `engine.state` when a TX controller is active, so quick health checks reuse the same terminology.
 `runtimeAlert` surfaces a short reason (e.g. "queue health low" or "late buffers") when the indicator is not "normal", but late-buffer alerts expire after a few seconds once cycle times settle so the signal doesn't stay stuck on degraded. The cumulative `lateBuffers` counter returned by `/runtime` still shows how many late cycles have occurred since start for post-mortem diagnosis.
 ---
 ### `GET /runtime`
 Live engine and driver telemetry. When ingest runtime is configured, this endpoint also exposes shared ingest/source stats under `ingest`.
 **Response:**
 ```json
 {
  "engine": {
    "state": "running",
    "runtimeStateDurationSeconds": 12.4,
    "appliedFrequencyMHz": 100.0,
    "chunksProduced": 12345,
    "totalSamples": 1408950000,
    "underruns": 0,
    "lastError": "",
    "uptimeSeconds": 3614.2,
    "faultCount": 2,
    "lastFault": {
      "time": "2026-04-06T00:00:00Z",
      "reason": "queueCritical",
      "severity": "faulted",
      "message": "queue health critical for 5 checks"
    },
    "faultHistory": [
      {
        "time": "2026-04-06T00:00:00Z",
        "reason": "queueCritical",
        "severity": "faulted",
        "message": "queue health critical for 5 checks"
      }
    ],
    "transitionHistory": [
      {
        "time": "2026-04-06T00:00:00Z",
        "from": "running",
        "to": "degraded",
        "severity": "warn"
      }
    ]
  },
  "driver": {
    "txEnabled": true,
    "streamActive": true,
    "framesWritten": 12345,
    "samplesWritten": 1408950000,
    "underruns": 0,
    "underrunStreak": 0,
    "maxUnderrunStreak": 0,
    "effectiveSampleRateHz": 2280000
  },
  "controlAudit": {
    "methodNotAllowed": 0,
    "unsupportedMediaType": 0,
    "bodyTooLarge": 0,
    "unexpectedBody": 0
  },
  "ingest": {
    "active": {
      "id": "icecast-main",
      "kind": "icecast",
      "family": "streaming",
      "transport": "http",
      "codec": "auto",
      "detail": "http://example.invalid/stream"
    },
    "source": {
      "state": "running",
      "connected": true,
      "chunksIn": 123,
      "samplesIn": 251904
    },
    "runtime": {
      "state": "running",
      "droppedFrames": 0,
      "convertErrors": 0,
      "writeBlocked": false
    }
  }
 }
 ```
 `engine.state` spiegelt jetzt die Runtime-State-Maschine wider (idle, arming, prebuffering, running, degraded, muted, faulted, stopping) und bietet eine erste beobachtbare Basis für Fault-Transitions.
 `runtimeStateDurationSeconds` sagt, wie viele Sekunden die Engine bereits im aktuellen Runtime-Zustand verweilt. So erkennt man schnell, ob `muted`/`degraded` zu lange dauern oder ob ein Übergang gerade frisch begonnen hat.
 `transitionHistory` liefert die jüngsten Übergänge (from/to, severity, timestamp) damit API und UI die Runtime History synchronisieren können.
 `engine.appliedFrequencyMHz` meldet die zuletzt tatsächlich getunte Frequenz auf der Hardware, sodass man sie mit dem gewünschten `/config`-Wert vergleichen und ausstehende Live-Updates sofort entdecken kann.
 `driver.underrunStreak` reports how many consecutive reads returned silence, and `driver.maxUnderrunStreak` captures the longest such run since the engine started. Together they help differentiate short glitches from persistent underrun storms and can be plotted alongside queue health sparkline telemetry.
 `lastFault.reason` kann jetzt auch `writeTimeout` lauten, wenn der Treiber Schreibaufrufe wiederholt verweigert oder blockiert. Die Control-Plane hebt solche Driver-Faults hervor, damit man Blockaden im Writer-Pfad ohne Log-Search sieht.
 `controlAudit` mirrors the control plane's HTTP reject counters (405/415/413/400). Whenever the HTTP server rejects a request (method not allowed, unsupported media type, body too large, or unexpected body), the respective counter increments — this lets runtime telemetry spot abusive clients without polluting the runtime state payload.
 ---
 ### `POST /runtime/fault/reset`
 Manually acknowledge a `faulted` runtime state so the supervisor can re-enter the recovery path (the engine moves back to `degraded` once the reset succeeds).
 **Response:**
 ```json
 {"ok": true}
 ```
 **Errors:**
 - `405 Method Not Allowed` if the request is not a POST
 - `503 Service Unavailable` when no TX controller is attached (`--tx` mode not active)
 - `409 Conflict` when the engine is not currently faulted or the reset was rejected (e.g. still throttled)
 ---
 ### `GET /config`
 Full current configuration (all fields, including non-patchable).
 **Response:** Complete `Config` JSON object.
 ---
 ### `POST /config`
 **Live parameter update.** Changes are applied to the running TX engine immediately — no restart required. Only include fields you want to change (PATCH semantics).
 The control snapshot (GET /config) only reflects new values once they pass validation and, if the TX engine is running, after the live update succeeded. That keeps the API from reporting desired values that were rejected or still pending.
 **Request body:** JSON with any subset of patchable fields.
 **Content-Type:** `application/json` (charset parameters allowed). Requests without it are rejected with 415 Unsupported Media Type.
 **Response:**
 ```json
 {"ok": true, "live": true}
 ```
 `"live": true` = changes were forwarded to the running engine.  
 `"live": false` = engine not active, changes saved for next start.
 #### Patchable fields — DSP (applied within ~50ms)
 | Field | Type | Range | Description |
 |---|---|---|---|
 | `frequencyMHz` | float | 65–110 | TX center frequency. Tunes hardware LO live. |
 | `outputDrive` | float | 0–10 | Composite output level multiplier (empfohlen 1..4). |
 | `stereoEnabled` | bool | | Enable/disable stereo (pilot + 38kHz subcarrier). |
 | `pilotLevel` | float | 0–0.2 | 19 kHz pilot injection level. |
 | `rdsInjection` | float | 0–0.15 | 57 kHz RDS subcarrier injection level. |
 | `rdsEnabled` | bool | | Enable/disable RDS subcarrier. |
 | `limiterEnabled` | bool | | Enable/disable MPX peak limiter. |
 | `limiterCeiling` | float | 0–2 | Limiter ceiling (max composite amplitude). |
 #### Patchable fields — RDS text (applied within ~88ms)
 | Field | Type | Max length | Description |
 |---|---|---|---|
 | `ps` | string | 8 chars | Program Service name (station name on receiver display). |
 | `radioText` | string | 64 chars | RadioText message (scrolling text on receiver). |
 When `radioText` is updated, the RDS A/B flag toggles automatically per spec, signaling receivers to refresh their display.
 #### Patchable fields — other (saved, not live-applied)
 | Field | Type | Description |
 |---|---|---|
 | `toneLeftHz` | float | Left tone frequency (test generator). |
 | `toneRightHz` | float | Right tone frequency (test generator). |
 | `toneAmplitude` | float | Test tone amplitude (0–1). |
 | `preEmphasisTauUS` | float | Pre-emphasis time constant. **Requires restart.** |
 #### Examples
 ```bash
 # Tune to 99.5 MHz
 curl -X POST localhost:8088/config -d '{"frequencyMHz": 99.5}'
 # Switch to mono
 curl -X POST localhost:8088/config -d '{"stereoEnabled": false}'
 # Update now-playing text
 curl -X POST localhost:8088/config \
  -d '{"ps": "MYRADIO", "radioText": "Artist - Song Title"}'
 # Reduce power + disable limiter
 curl -X POST localhost:8088/config \
  -d '{"outputDrive": 0.8, "limiterEnabled": false}'
 # Full update
 curl -X POST localhost:8088/config -d '{
  "frequencyMHz": 101.3,
  "outputDrive": 2.2,
  "stereoEnabled": true,
  "pilotLevel": 0.041,
  "rdsInjection": 0.021,
  "rdsEnabled": true,
  "limiterEnabled": true,
  "limiterCeiling": 1.0,
  "ps": "PIRATE",
  "radioText": "Broadcasting from the attic"
 }'
 ```
 #### Error handling
 Invalid values return `400 Bad Request` with a descriptive message:
 ```bash
 curl -X POST localhost:8088/config -d '{"frequencyMHz": 200}'
 # → 400: frequencyMHz out of range (65-110)
 ```
 ---
 ### `POST /tx/start`
 Start transmission. Requires `--tx` mode with hardware.
 **Response:**
 ```json
 {"ok": true, "action": "started"}
 ```
 **Errors:**
 - `405` if not POST
 - `503` if no TX controller (not in `--tx` mode)
 - `409` if already running
 ---
 ### `POST /tx/stop`
 Stop transmission.
 **Response:**
 ```json
 {"ok": true, "action": "stopped"}
 ```
 ---
 ### `GET /dry-run`
 Generate a synthetic frame summary without hardware. Useful for config verification.
 **Response:** `FrameSummary` JSON with mode, rates, source info, preview samples.
 ---
 ## Live update architecture
 All live updates are **lock-free** in the DSP path:
 | What | Mechanism | Latency |
 |---|---|---|
 | DSP params | `atomic.Pointer[LiveParams]` loaded once per chunk | ≤ 50ms |
 | RDS text | `atomic.Value` in encoder, read at group boundary | ≤ 88ms |
 | TX frequency | `atomic.Pointer` in engine, `driver.Tune()` between chunks | ≤ 50ms |
 No mutex, no channel, no allocation in the real-time path. The HTTP goroutine writes atomics, the DSP goroutine reads them.
 ## Parameters that require restart
 These cannot be hot-reloaded (they affect DSP pipeline structure):
 - `compositeRateHz` — changes sample rate of entire DSP chain
 - `deviceSampleRateHz` — changes hardware rate / upsampler ratio
 - `maxDeviationHz` — changes FM modulator scaling
 - `preEmphasisTauUS` — changes filter coefficients
 - `rds.pi` / `rds.pty` — rarely change, baked into encoder init
 - `audio.inputPath` — audio source selection
 - `backend.kind` / `backend.device` — hardware selection
 ---
 ### `POST /audio/stream`
 Push raw audio data into the ingest `http-raw` source. Format: **S16LE PCM** (`ingest.httpRaw.format`), currently validated as `s16le`, with channels/sample-rate from ingest config.
 Requires HTTP ingest wiring (typically `--audio-http`, which maps ingest kind to `http-raw`).
 **Request:** Binary body, `application/octet-stream`, raw S16LE stereo PCM bytes. Set `Content-Type` to `application/octet-stream` or `audio/L16`; other media types are rejected. Requests larger than 512 MiB are rejected with `413 Request Entity Too Large`.
 **Response:**
 ```json
 {
  "ok": true,
  "frames": 4096
 }
 ```
 **Example:**
 ```bash
 # Push a file
 ffmpeg -i song.mp3 -f s16le -ar 44100 -ac 2 - | \
  curl -X POST -H "Content-Type: application/octet-stream" --data-binary @- http://pluto:8088/audio/stream
 ```
 **Errors:**
 - `405` if not POST
 - `415` if Content-Type is missing or unsupported (must be `application/octet-stream` or `audio/L16`)
 - `413` if the upload body exceeds the 512 MiB limit
 - `503` if HTTP raw ingest is not configured
 ---
 ## Audio Streaming
 ### Stdin pipe (primary method)
 Pipe any audio source through ffmpeg into the transmitter:
 ```bash
 # Internet radio stream
 ffmpeg -i "http://stream.example.com/radio.mp3" -f s16le -ar 44100 -ac 2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin --config config.json
 # Local music file
 ffmpeg -i music.flac -f s16le -ar 44100 -ac 2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin
 # Playlist (ffmpeg concat)
 ffmpeg -f concat -i playlist.txt -f s16le -ar 44100 -ac 2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin
 # PulseAudio / ALSA capture (Linux)
 parecord --format=s16le --rate=44100 --channels=2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin
 # Custom sample rate (e.g. 48kHz source)
 ffmpeg -i source.wav -f s16le -ar 48000 -ac 2 - | \
  fmrtx --tx --tx-auto-start --audio-stdin --audio-rate 48000
 ```
 ### HTTP audio push
 Push audio from a remote machine via the HTTP API. Run the server with `--audio-http` (and typically `--tx`/`--tx-auto-start`) so the `/audio/stream` endpoint is available.
 ```bash
 # From another machine on the network
 ffmpeg -i music.mp3 -f s16le -ar 44100 -ac 2 - | \
  curl -X POST -H "Content-Type: application/octet-stream" --data-binary @- http://pluto-host:8088/audio/stream
 ```
 ### Audio buffer
 The stream uses a lock-free ring buffer (default: 2 seconds at input rate). Buffer stats are available in `GET /runtime` under `audioStream`:
 ```json
 {
  "audioStream": {
    "available": 12000,
    "capacity": 131072,
    "buffered": 0.09,
    "bufferedDurationSeconds": 0.27,
    "highWatermark": 15000,
    "highWatermarkDurationSeconds": 0.34,
    "written": 890000,
    "underruns": 0,
    "overflows": 0
  }
 }
 ```
 - **underruns**: DSP consumed faster than audio arrived (silence inserted)
 - **overflows**: Audio arrived faster than DSP consumed (data dropped)
 - **buffered**: Fill ratio (0.0 = empty, 1.0 = full)
 - **bufferedDurationSeconds**: Approximate seconds of audio queued in the buffer (`available` frames divided by the sample rate)
 - **highWatermark**: Highest observed buffer occupancy (frames) since the buffer was created
 - **highWatermarkDurationSeconds**: Equivalent peak time (`highWatermark` frames divided by the sample rate)
 When no audio is streaming, the transmitter falls back to the configured tone generator or silence.
--- a/docs/audio-ingest-implementation-plan.md
+++ b/docs/audio-ingest-implementation-plan.md
--- a/docs/audio-ingest-rework.md
+++ b/docs/audio-ingest-rework.md
@@ -0,0 +1,267 @@
 # Audio Ingest Rework
 ## Hinweis zum Stand (2026-04-07)
 Dieses Dokument beschreibt das Zielbild. Der aktuelle Ist-Stand in Phase 1 ist:
 - shared ingest runtime + unified source factory sind implementiert
 - `stdin`, `http-raw`, `icecast` Adapter sind implementiert
 - Icecast Decoder-Layer + ffmpeg fallback sind implementiert
 - native Decoder `mp3` / `oggvorbis` / `aac` sind noch Platzhalter
 - funktionaler Decode-Pfad heute: ffmpeg fallback
 ## Ziel
 `fm-rds-tx` soll mittelfristig mehrere Audio-Ingest-Pfade sauber unterstützen, ohne den bestehenden `ffmpeg`-Pfad kaputt zu machen.
 Die strategische Richtung ist daher **nicht** „ffmpeg sofort ersetzen“, sondern:
 - bestehenden `ffmpeg`-Pfad als universellen Fallback behalten
 - native Ingest-Familien daneben aufbauen
 - alle Pfade auf eine gemeinsame interne PCM-/Audio-Source-Abstraktion führen
 - neue native Pfade schrittweise produktionsreif machen
 ## Leitprinzipien
 1. **Kein Big-Bang-Rewrite** – Bestehendes bleibt lauffähig.
 2. **Native Pfade zuerst dort, wo sie klaren Mehrwert bringen**.
 3. **Go-Libraries bevorzugen** – Decoder/Protocol-Handling einkaufen statt neu erfinden.
 4. **Ein gemeinsames Ingest-Modell** – unabhängig von Quelle oder Protokoll.
 5. **Control Plane / Runtime / Telemetrie von Decoder-Details trennen**.
 ## Zielbild: drei Ingest-Familien
 ### 1. FFmpeg Family
 Bestehender universeller Adapter.
 **Rolle:**
 - Fallback
 - Legacy-Kompatibilität
 - exotische oder seltene Formate
 - schneller pragmatischer Pfad für Quellen, die nativ noch nicht unterstützt werden
 **Wichtig:**
 - bleibt vorerst erhalten
 - wird nicht „rausoptimiert“, sondern architektonisch nachrangig
 - sollte in der Runtime als eigener Ingest-Typ sichtbar sein
 ### 2. AoIP Family
 Für professionelle / broadcast-nahe Audioquellen.
 **Ziel-Protokolle / Modi:**
 - RTP multicast
 - AES67-lite
 - SDP
 - SAP
 - später: NMOS IS-04 / IS-05
 - später: SRT framed PCM
 **Basis:**
 - `aoiprxkit`
 **Rolle:**
 - deterministische LAN-Audiozuführung
 - Broadcast-/AoIP-Umgebungen
 - spätere professionelle Discovery/Activation
 ### 3. Streaming Family
 Für klassische Internet-/HTTP-/Radio-Streamingquellen.
 **Ziel-Protokolle / Modi:**
 - HTTP audio streams
 - Icecast / Shoutcast
 - ICY metadata
 - MP3
 - AAC / HE-AAC (je nach verfügbarer Lib)
 - später ggf. Opus
 **Rolle:**
 - Webradio / Online-Streams
 - Metadatenübernahme
 - native Alternative zu `ffmpeg` für die häufigsten Streaming-Fälle
 **Wichtig:**
 Diese Familie sollte **nicht** in `aoiprxkit` gepresst werden. AoIP und Streaming sind konzeptionell verschieden genug, dass getrennte Package-Bereiche sinnvoll sind.
 ## Gemeinsame interne Abstraktion
 Alle Ingest-Familien sollen auf dieselbe interne PCM-Einspeisung münden.
 ### Ziel
 Unabhängig davon, ob Samples von:
 - `ffmpeg`
 - RTP/AES67
 - Icecast/MP3
 - SRT framed PCM
 kommen, soll der Rest der Sende-/RDS-/Runtime-Logik immer dieselbe Audioquelle sehen.
 ### Grobe Zielverantwortung
 Eine Quelle soll idealerweise liefern können:
 - PCM-Samples
 - Sample-Rate
 - Kanalzahl
 - Source-Label / Source-Type
 - Laufzeitstatus / Health
 - Basisstatistiken
 - optional Metadaten (z. B. ICY title)
 ### Wichtige Designregel
 **Decoder/Protocol-Layer** und **Sender-Runtime** nicht vermischen.
 Das Ingest-System soll:
 - Audio empfangen / decodieren / normieren
 - Health / Stats liefern
 - Audio in die bestehende Audio-Pipeline schieben
 Die Sender-Runtime soll:
 - Quellen starten/stoppen
 - aktive Quelle verwalten
 - Fehler/Fallback/Status darstellen
 - UI/Control-Plane bedienen
 ## Einordnung von `aoiprxkit`
 ## Was `aoiprxkit` heute schon gut abdeckt
 - RTP multicast RX
 - L24-Decoding
 - Jitter/Reorder
 - statische SDP-Auswertung
 - SAP-Listener
 - Stream-Finder per SDP `s=` Name
 - Basis-Stats
 - Live-Metering
 - NMOS-/SRT-Grundgerüst
 ## Was `aoiprxkit` heute noch nicht vollständig als Produkt ist
 - keine voll integrierte `fm-rds-tx`-Runtime-Anbindung
 - SRT-Pfad eher Scaffold als fertig produktionsreif
 - NMOS eher vorbereitend als vollständig integriert
 - noch kein gemeinsames Source-Management mit anderen Ingest-Familien
 ## Konsequenz
 `aoiprxkit` ist **integrationswürdig**, aber aktuell noch eher ein Modul/Baukasten als direktes Hauptsystem.
 ## Empfohlene Package-/Modul-Richtung in `fm-rds-tx`
 Dies ist ein Zielbild, kein harter Sofort-Umbau.
 ### Kandidaten
 - `internal/audioingest`
  - gemeinsame Interfaces / gemeinsame Typen / gemeinsame Runtime-Adapter
 - `internal/audioingest/ffmpeg`
  - bestehender ffmpeg-basierter Pfad
 - `internal/audioingest/aoip`
  - Adapter zwischen `aoiprxkit` und `fm-rds-tx`
 - `internal/audioingest/streaming`
  - HTTP/Icecast/Shoutcast/ICY + Decoder-Libs
 Optional später:
 - `internal/audioingest/shared`
  - Resampling, channel mapping, sample normalization, metadata structs
 ## Konfigurationszielbild
 Die Runtime sollte einen expliziten Ingest-Typ kennen.
 Beispielhaft:
 ```yaml
 input:
  kind: ffmpeg | aoip-rtp | aoip-sap | aoip-srt | stream-http
 ```
 Später können pro Familie Unterstrukturen folgen.
 Beispielhaft:
 ```yaml
 input:
  kind: aoip-rtp
  aoip:
    multicastGroup: 239.69.0.1
    port: 5004
    payloadType: 97
    sampleRateHz: 48000
    channels: 2
 ```
 oder
 ```yaml
 input:
  kind: stream-http
  streaming:
    url: https://example.org/live.mp3
    icyMeta: true
 ```
 ## Runtime-Zielbild
 Die Runtime sollte Quellen einheitlich behandeln können:
 - initialisieren
 - starten
 - stoppen
 - Status abfragen
 - Health/Stats lesen
 - Audio in denselben bestehenden Ringbuffer / Audio-Input-Pfad drücken
 ## Telemetrie / UI
 Die Control Plane sollte mittelfristig ingest-bezogen sichtbar machen:
 - aktiver Ingest-Typ
 - Source-Label
 - Transport / Codec / Sample-Rate / Channels
 - Fehlerzustand
 - Puffer-/Jitter-/Underrun-relevante Daten
 - optional Metadata (z. B. StreamTitle)
 Wichtig ist hier eine Trennung zwischen:
 - **Audio ingest health**
 - **TX/runtime health**
 ## Empfohlene Umsetzungsreihenfolge
 ### Phase 1 – Architektur sauberziehen
 - gemeinsames Ingest-Zielbild festziehen
 - bestehende Audio-Input-Andockpunkte in `fm-rds-tx` dokumentieren
 - entscheiden, welche internen Interfaces nötig sind
 ### Phase 2 – AoIP MVP
 - `aoiprxkit` nicht blind verschieben, sondern zuerst als Adapter anbinden
 - erster nativer Ingest-Modus: statischer RTP/AES67-lite Pfad
 - PCM-Frames in bestehende Audio-Pipeline einspeisen
 - Runtime-/Health-/Status sichtbar machen
 ### Phase 3 – SDP / SAP Discovery
 - statische SDP-Unterstützung
 - optional SAP Listener + Session-Auswahl
 - Discovery klar von Audio-Transport trennen
 ### Phase 4 – Streaming MVP
 - neuer nativer HTTP/Icecast/Shoutcast-Pfad
 - bewährte Go-Libs für Decoder und ICY nutzen
 - erstes Ziel: häufige Webradio-Fälle ohne `ffmpeg`
 ### Phase 5 – Vereinheitlichung / Telemetrie
 - gemeinsame Ingest-Stats
 - gemeinsame Statusmodelle
 - UI/Control-Plane-Integration
 - Quellwechsel / Fehlermeldungen / Health States
 ### Phase 6 – Erweiterte Pfade
 - SRT sauber produktionsfähig machen
 - NMOS weiter integrieren
 - später ggf. Opus / weitere Streaming-Codecs
 ## Was explizit vermieden werden soll
 - `ffmpeg` sofort herausreissen
 - AoIP und Web-Streaming in denselben unscharfen Package-Topf werfen
 - Decoder / Demux / Protocol-Layer unnötig selbst neu bauen
 - Discovery-Logik eng mit der PCM-Pipeline verheiraten
 - UI bauen, bevor Runtime-Modelle sauber stehen
 ## Erste konkrete Bauschritte ab jetzt
 1. bestehenden Audio-Input-Pfad in `fm-rds-tx` analysieren
 2. kleinste gemeinsame Ingest-Abstraktion definieren
 3. `aoiprxkit`-RTP als ersten nativen Adapter integrieren
 4. danach Streaming-Familie planen und anbinden
 ## Kurzfazit
 `ffmpeg` bleibt vorerst als nützlicher Universalpfad erhalten.
 Die Zukunft liegt aber in zwei nativen Familien:
 - **AoIP** für professionelle/broadcast-nahe Zuführung
 - **Streaming** für HTTP/Icecast/Shoutcast/ICY + Standardcodecs
 Beide sollen sauber über eine gemeinsame interne Audio-Ingest-Schicht in `fm-rds-tx` zusammenlaufen.
--- a/docs/config.sample.json
+++ b/docs/config.sample.json
@@ -34,5 +34,32 @@
  },
  "control": {
    "listenAddress": "127.0.0.1:8088"
  },
  "runtime": {
    "frameQueueCapacity": 3
  },
  "ingest": {
    "kind": "none",
    "prebufferMs": 1500,
    "stallTimeoutMs": 3000,
    "reconnect": {
      "enabled": true,
      "initialBackoffMs": 1000,
      "maxBackoffMs": 15000
    },
    "stdin": {
      "sampleRateHz": 44100,
      "channels": 2,
      "format": "s16le"
    },
    "httpRaw": {
      "sampleRateHz": 44100,
      "channels": 2,
      "format": "s16le"
    },
    "icecast": {
      "url": "",
      "decoder": "auto"
    }
  }
 }
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -160,6 +160,14 @@ func TestValidateRejectsUnsupportedIcecastDecoder(t *testing.T) {
 	}
 }
 func TestValidateAcceptsIcecastDecoderFallbackAlias(t *testing.T) {
 	cfg := Default()
 	cfg.Ingest.Icecast.Decoder = "fallback"
 	if err := cfg.Validate(); err != nil {
 		t.Fatalf("expected fallback alias to be accepted: %v", err)
 	}
 }
 func TestValidateRejectsReconnectWithMissingBackoff(t *testing.T) {
 	cfg := Default()
 	cfg.Ingest.Reconnect.Enabled = true
--- a/internal/control/control.go
+++ b/internal/control/control.go
@@ -336,8 +336,8 @@ func (s *Server) handleRuntimeFaultReset(w http.ResponseWriter, r *http.Request)
 	_ = json.NewEncoder(w).Encode(map[string]any{"ok": true})
 }
 // handleAudioStream accepts raw S16LE stereo PCM via HTTP POST and pushes
 // it into the live audio ring buffer. Use with:
 // handleAudioStream accepts raw S16LE PCM via HTTP POST and pushes
 // it into the configured ingest http-raw source. Use with:
 //
 //	curl -X POST --data-binary @- http://host:8088/audio/stream < audio.raw
 //	ffmpeg ... -f s16le -ar 44100 -ac 2 - | curl -X POST --data-binary @- http://host:8088/audio/stream
--- a/internal/ingest/adapters/icecast/source.go
+++ b/internal/ingest/adapters/icecast/source.go
@@ -241,6 +241,8 @@ func (s *Source) decodeWithPreference(ctx context.Context, stream io.Reader, met
 		}
 		return native.DecodeStream(ctx, stream, meta, s.emitChunk)
 	case "auto":
 		// Phase-1 policy: try native decoder first, then fall back to ffmpeg
 		// only when native selection/decode reports "unsupported".
 		native, err := s.decReg.SelectByContentType(meta.ContentType)
 		if err == nil {
 			if err := native.DecodeStream(ctx, stream, meta, s.emitChunk); err == nil {
--- a/internal/ingest/adapters/icecast/source_test.go
+++ b/internal/ingest/adapters/icecast/source_test.go
@@ -105,3 +105,32 @@ func TestDecodeWithPreferenceFFmpegOnly(t *testing.T) {
 		t.Fatalf("fallback called %d times", fallback.called)
 	}
 }
 func TestDecodeWithPreferenceAutoUnsupportedContentTypeFallsBack(t *testing.T) {
 	fallback := &testDecoder{name: "ffmpeg"}
 	reg := decoder.NewRegistry()
 	reg.Register("ffmpeg", func() decoder.Decoder { return fallback })
 	src := New("ice-test", "http://example", nil, ReconnectConfig{},
 		WithDecoderRegistry(reg),
 		WithDecoderPreference("auto"),
 	)
 	err := src.decodeWithPreference(context.Background(), bytes.NewReader(nil), decoder.StreamMeta{
 		ContentType: "application/octet-stream",
 		SourceID:    "ice-test",
 	})
 	if err != nil {
 		t.Fatalf("decode: %v", err)
 	}
 	if fallback.called != 1 {
 		t.Fatalf("fallback called %d times", fallback.called)
 	}
 }
 func TestWithDecoderPreferenceFallbackAliasNormalizesToFFmpeg(t *testing.T) {
 	src := New("ice-test", "http://example", nil, ReconnectConfig{}, WithDecoderPreference("fallback"))
 	if got := src.Descriptor().Codec; got != "ffmpeg" {
 		t.Fatalf("codec=%s want ffmpeg", got)
 	}
 }