DigiRadio/Software/docs/app-cursor-brief-2026-08-25.md

Brief per Cursor — allineamento app iOS al nuovo firmware DSP (DigiRadioFinale)

Il firmware ADAU1701 è stato sostituito con un programma DSP molto più ricco (224 parametri contro 74 prima). Questo documento descrive cosa è cambiato lato API HTTP e quali controlli nuovi puoi costruire in app, più qualche indicazione di UX. I dettagli implementativi Swift (struttura file, ViewModels esistenti, tab bar) restano una tua scelta — qui do solo il contratto dati e gli obiettivi funzionali.

Dispositivo di test: http://192.168.1.62 (mDNS digiradio-CC4DB4.local).

---

1. Breaking change: mixer → active_source

Prima: GET/PUT /api/audio/profile aveva un oggetto "mixer" con guadagni indipendenti per Si4684, ESP32 e i due leg del mixer — permetteva di "mescolare" radio e Bluetooth insieme.

Ora: il firmware non ha più un mixer. C'è un selettore di sorgente esclusivo — si ascolta una sorgente alla volta, come su un vero stereo.

{
  "active_source": "radio",
  "master": {"left_db": 0, "right_db": 0},
  "eq": [ ... 6 bande, invariato ... ],
  "enhancements": {"stereo_level": 0, "bass_level": 0}
}

active_source accetta esattamente "radio", "bluetooth", "beep". "beep" è il tono di test interno (usato per diagnostica firmware, probabilmente da nascondere in UI di produzione o mettere in una sezione "Diagnostica").

Azione richiesta: sostituire ogni UI che oggi mostra due slider indipendenti (volume radio / volume BT) con un selettore a scelta singola (segmented control o lista) tra Radio e Bluetooth. Non esiste più un modo per sentirli mescolati.

---

2. enhancements ora pilota algoritmi DSP reali, non più un trucco EQ

Prima: bass_level/stereo_level sovrascrivevano silenziosamente alcune bande dell'equalizzatore manuale (da cui il campo "locked" per banda, per segnalarlo).

Ora: pilotano due blocchi DSP dedicati e indipendenti dall'EQ:

• bass_level (0-100) → Bass Boost1, un vero algoritmo ADI di "Dynamic Bass Boost" (filtro crossover + compander dinamico). Effetto udibile solo su contenuto reale con dinamica (radio, streaming) — su un tono fisso costante non si sente quasi nulla, è normale (l'algoritmo reagisce a variazioni di livello nel tempo).
• stereo_level (0-100) → SPhat1 ("SuperPhat" Spatializer/stereo widener), un secondo algoritmo ADI dedicato.

Il campo "locked" per banda EQ ora è sempre false tranne la banda 0 (passa-alto fisso, sempre true, invariato da prima). Puoi quindi rimuovere qualunque logica "banda grigia perché l'enhancement l'ha sovrascritta" — l'EQ manuale ora è sempre indipendente dagli enhancement.

Azione richiesta: nessun cambio di forma dati per enhancements (stessi due slider 0-100 di prima), ma puoi rimuovere la UI "banda bloccata" per le bande 1-5 (resta solo per la banda 0, che era già così).

---

3. Non ancora disponibile lato firmware (in arrivo)

• VU-meter / readback dei livelli (in ingresso e in uscita) — il firmware ha 6 sensori di livello nel DSP ma il meccanismo di lettura (un registro indiretto dell'ADAU1701) non è ancora implementato. Non costruire ancora una UI che dipende da dati di livello in tempo reale dal firmware — se vuoi una sezione "grafica" ora, usa un placeholder o un'animazione generica non agganciata a dati reali, finché non arriva l'endpoint.
• Voice Clarifier — la cella DSP dedicata (Gen Filter1) esiste nella catena del segnale ma non è ancora tarata (passa tutto invariato). Nessuna API la pilota ancora. Non esporre ancora questo controllo in UI, o mettilo disabilitato/"prossimamente".
• Mute in uscita (pre-Output1/Output2) — non presente in questo export del firmware. Se serve, va aggiunto lato SigmaStudio prima di poter esporlo via API.

Ti avviso appena questi sono pronti lato firmware con l'endpoint esatto.

---

4. Riepilogo controlli disponibili ORA (tutti testati dal vivo sul dispositivo)

Controllo	Endpoint	Corpo
Sorgente attiva	PUT /api/audio/profile (campo active_source)	"radio" | "bluetooth" | "beep"
Master volume	PUT /api/audio/profile (campo master)	{"left_db":..,"right_db":..}, range tipico -96..+12 dB
Equalizzatore (6 bande)	PUT /api/audio/profile (campo eq)	invariato: gain_db, center_hz, q per banda; banda 0 sempre inerte
Bass Boost	POST /api/audio/bass-enhance	{"level":0-100}
Stereo Spread	POST /api/audio/stereo-enhance	{"level":0-100}
Tono di test (diagnostica)	POST /api/audio/beep	{"enabled":true/false} — richiede anche active_source:"beep" per essere udibile
Lettura stato completo	GET /api/audio/profile	risposta con tutti i campi sopra

---

5. Indicazioni di stile (dalla richiesta dell'utente)

• Stile Apple/HIG nativo: niente slider/bottoni "grezzi" o accozzaglia in un'unica schermata. Raggruppa per tab/sezione logica (es. "Ascolto" per sorgente+volume, "Suono" per EQ+Bass Boost+Stereo Spread, "Bluetooth" per pairing, "Diagnostica" per tono di test/dettagli tecnici).
• Preferisci componenti nativi SwiftUI (Picker segmented per la sorgente, Slider con .tint() per i livelli, liste con Form/List in stile Impostazioni) piuttosto che controlli custom pesanti.
• La sezione "grafica" (visualizzazione carina) può oggi mostrare solo dati già disponibili (EQ come curva, o un'animazione leggera legata allo stato sorgente/tono) — non agganciarla a VU-meter reali finché non sono pronti (punto 3).
• Dato che non esiste più il mix simultaneo radio+BT, il cambio sorgente è un'azione "netta" (come cambiare stazione) — vale la pena un feedback visivo chiaro (es. breve transizione/fade nell'interfaccia, non nell'audio: il cambio DSP è istantaneo) quando l'utente lo seleziona.