home@slashpaf ~ $

MQTT / Home Assistant

<- torna alla radice della documentazione  

Cosa fa MQTT per Audio Forge

MQTT permette ad Audio Forge di comunicare con la tua casa intelligente in modo da:

  • Visualizzare cosa sta facendo Audio Forge (quale libreria, se Music/Ambiance sono in riproduzione).
  • Attivare la riproduzione da Home Assistant, Node‑RED o qualsiasi strumento compatibile con MQTT.
  • Collegare Audio Forge alle automazioni con luci, macchine del fumo, interruttori di scena e altro.

Se già gestisci un broker MQTT (Mosquitto, il broker integrato di Home Assistant, ecc.), Audio Forge può connettersi ad esso e pubblicare il suo stato mentre ascolta i comandi.

Abilitare MQTT nelle Impostazioni

In Audio Forge, vai su Impostazioni → Integrazione MQTT e abilita la funzione.

Puoi configurare:

  • Host e Porta (1883 di default, o 8883 per TLS).
  • Attivazione TLS/SSL.
  • Nome utente / Password se il tuo broker li richiede.
  • Client ID (mantieni il predefinito a meno che tu non sappia di averne bisogno uno personalizzato).
  • Base Topic (predefinito: audioforge/<nome-o-id-dispositivo>; ad esempio audioforge/my-pc).
  • QoS (0/1/2; 1 è un buon valore predefinito).
  • Se mantenere lo stato, connettersi automaticamente all’avvio, pubblicare lo stato e abbonarsi ai comandi.
  • Scoperta MQTT e un opzionale Prefisso di scoperta (di solito homeassistant).
  • Opzioni avanzate per esporre interruttori di Ambiance, esporre volumi di categoria e esporre pulsanti Echo come entità extra.

Una volta connesso, Audio Forge pubblicherà la sua disponibilità e stato al tuo broker e (opzionalmente) ascolterà i comandi.

Gallery image 1 of 1

Temi principali

Assumendo che il tuo base topic sia audioforge/my-pc, Audio Forge utilizza:

  • audioforge/my-pc/availability – stato online / offline (mantenuto).
  • audioforge/my-pc/state – istantanea JSON dello stato di riproduzione corrente (mantenuto se abiliti Mantenere lo stato).
  • audioforge/my-pc/catalog – catalogo JSON di tutte le librerie e loro categorie (mantenuto).
  • audioforge/my-pc/cmd – dove invii comandi JSON per controllare la riproduzione.
  • audioforge/my-pc/result – risposte JSON opzionali (successo / errore).
  • audioforge/my-pc/events/echo – eventi “echo” una tantum (non mantenuti).

Il payload dello stato include elementi come:

  • deviceId, libraryUuid, libraryName.
  • Se Music o Ambiance stanno suonando, oltre ai loro volumi di base.
  • Le categorie attualmente riprodotte (musicCategories / ambianceCategories).
  • Fattori di volume per categoria (categoryVolume mapping).
  • L’ultimo one‑shot (Echo) riprodotto e l’attuale volumeTransitionMs.

Controllo di base da Home Assistant

Puoi usare Home Assistant in due modi:

  1. Entità MQTT manuali: crea sensori/pulsanti in YAML (o tramite l’interfaccia) che leggono da state e pubblicano su cmd.
  2. Scoperta MQTT (consigliata): abilita “Scoperta MQTT” nell’app e Audio Forge creerà automaticamente le entità per te.

Quando la scoperta è abilitata, vedrai un dispositivo Audio Forge con:

  • Sensori binari (Disponibile, Music in riproduzione, Ambiance in riproduzione).
  • Sensori (Nome della libreria, categorie Music/Ambiance, Ultimo Echo).
  • Pulsanti (Play / Pause / Stop per Music e Ambiance).
  • Selettori (scegli le categorie Music/Ambiance, cambia libreria).
  • Numeri (volume Music/Ambiance, tempo di transizione del volume, volumi opzionali per categoria).
  • Interruttori opzionali (uno per categoria Ambiance se scegli di esporli).
  • Pulsanti Echo opzionali (uno per categoria Echo quando i pulsanti Echo sono esposti).
Gallery image 1 of 1

Comandi comuni

I comandi sono piccoli oggetti JSON pubblicati su <base>/cmd. Ecco alcuni esempi utili:

Riproduci un’intera sezione:

{"command": "play", "section": "Music"}

Riproduci una categoria specifica per nome:

{"command": "play", "section": "Music", "categoryName": "Battle"}

Metti in pausa o ferma:

{"command": "pause", "section": "Ambiance"}
{"command": "stop",  "section": "Music"}

Imposta il volume (0.0–1.0):

{"command": "setVolume", "section": "Music", "value": 0.65}

Cambia libreria:

{"command": "setActiveLibrary", "libraryName": "La Mia Libreria"}

Riproduci un one‑shot Echo:

{"command": "playEcho", "section": "Ambiance", "categoryName": "Chime"}

Ripristina uno stato salvato da un link creato dall’app:

{"command": "restoreState", "link": "<state-link-from-app>"}

Se un comando non può essere eseguito (ad esempio, un nome di categoria non esiste), Audio Forge pubblica un errore su <base>/result.

Esempio: semplice automazione Home Assistant

Ecco un’automazione minima di Home Assistant che avvia una categoria “Battle” in Music quando un interruttore helper viene attivato:

alias: Play Battle in Audio Forge
trigger:
  - platform: state
    entity_id: input_boolean.play_battle
    to: "on"
action:
  - service: mqtt.publish
    data:
      topic: "audioforge/my-pc/cmd"
      payload: >
        {"command":"play","section":"Music","categoryName":"Battle"}
  - service: input_boolean.turn_off
    target:
      entity_id: input_boolean.play_battle

Questo è solo un esempio; puoi collegare Audio Forge a qualsiasi evento desideri (cambi scena, pulsanti fisici, pulsanti stream deck, ecc.).