Alfred
/
fm-rds-tx
1
0
Fork 0
Code Issues 0 Pull-Requests 0 Releases 6 Wiki Aktivität
Quellcode durchsuchen

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

main
Jan vor 1 Monat
Ursprung
8794d484cd
Commit
51db52f934
9 geänderte Dateien mit 2215 neuen und 758 gelöschten Zeilen
Geteilte Ansicht
Diff-Optionen
Statistiken anzeigen Patch-Datei herunterladen Vergleichs-Datei herunterladen
  1. +356
    -340
      README.md
  2. +427
    -416
      docs/API.md
  3. +1097
    -0
      docs/audio-ingest-implementation-plan.md
  4. +267
    -0
      docs/audio-ingest-rework.md
  5. +27
    -0
      docs/config.sample.json
  6. +8
    -0
      internal/config/config_test.go
  7. +2
    -2
      internal/control/control.go
  8. +2
    -0
      internal/ingest/adapters/icecast/source.go
  9. +29
    -0
      internal/ingest/adapters/icecast/source_test.go

+ 356
- 340
README.md Datei anzeigen

@@ -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.

+ 427
- 416
docs/API.md Datei anzeigen

@@ -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.

+ 1097
- 0
docs/audio-ingest-implementation-plan.md
Datei-Diff unterdrückt, da er zu groß ist
Datei anzeigen


+ 267
- 0
docs/audio-ingest-rework.md Datei anzeigen

@@ -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.

+ 27
- 0
docs/config.sample.json Datei anzeigen

@@ -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"
}
}
}

+ 8
- 0
internal/config/config_test.go Datei anzeigen

@@ -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


+ 2
- 2
internal/control/control.go Datei anzeigen

@@ -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


+ 2
- 0
internal/ingest/adapters/icecast/source.go Datei anzeigen

@@ -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 {


+ 29
- 0
internal/ingest/adapters/icecast/source_test.go Datei anzeigen

@@ -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)
}
}

Verfassen Vorschau
Laden…
Abbrechen
Speichern