home@slashpaf ~ $

MQTT / Home Assistant

<- torna alla radice della documentazione  

Cosa fa MQTT per Audio Forge

MQTT consente ad Audio Forge di interagire con la tua smart home in modo da poter:

  • Vedere cosa sta facendo Audio Forge (quale libreria, se la Musica/l’Ambiente stanno suonando).
  • Avviare la riproduzione da Home Assistant, Node‑RED o qualsiasi strumento compatibile con MQTT.
  • Collegare Audio Forge alle automazioni con luci, macchine del fumo, switch di scena e altro.

Se già utilizzi 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 → Controllo Esterno → Integrazione MQTT e abilita la funzione.

Puoi configurare:

  • Host e Porta (1883 di default, o 8883 per TLS).
  • Attivazione/disattivazione TLS/SSL.
  • Nome utente / Password se richiesti dal tuo broker.
  • ID client (lascia il valore predefinito a meno che tu non sappia di averne bisogno di 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, connessione automatica all’avvio, pubblicare lo stato, e sottoscriversi ai comandi.
  • Scoperta MQTT e un opzionale prefisso di scoperta (di solito homeassistant).
  • Opzioni avanzate per esporre switch Ambiance, esporre i volumi delle categorie e esporre i pulsanti Echo come entità aggiuntive.

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

Gallery image 1 of 1

Argomenti principali

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

  • audioforge/my-pc/availability – stato online / offline (conservato).
  • audioforge/my-pc/state – istantanea JSON dello stato di riproduzione corrente (conservato se abiliti Mantenere lo stato).
  • audioforge/my-pc/catalog – catalogo JSON di tutte le librerie e le loro categorie (conservato).
  • 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” unici (non conservati).

Il payload di stato include informazioni come:

  • deviceId, libraryUuid, libraryName.
  • Se Musica o Ambiente stanno suonando, più i loro volumi di base.
  • Le categorie attualmente in riproduzione (musicCategories / ambianceCategories).
  • Fattori di volume per categoria (categoryVolume mapping).
  • L’ultimo evento one‑shot (Echo) e l’attuale volumeTransitionMs.

Controllo di base da Home Assistant

Puoi utilizzare Home Assistant in due modi:

  1. Entità MQTT manuali: creare sensori/pulsanti in YAML (o tramite l’interfaccia grafica) che leggono dallo state e pubblicano su cmd.
  2. Scoperta MQTT (consigliato): abilita la “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, Musica in Riproduzione, Ambiente in Riproduzione).
  • Sensori (Nome libreria, Categorie Musica/Ambiente, Ultimo Echo).
  • Pulsanti (Play / Pausa / Stop per Musica e Ambiente).
  • Selettori (scegliere categorie Musica/Ambiente, cambiare librerie).
  • Numeri (Volume Musica/Ambiente, tempo di transizione del volume, volumi per categoria opzionali).
  • Switch opzionali (uno per ogni categoria Ambience se si sceglie di esporli).
  • Pulsanti Echo opzionali (uno per ogni categoria Echo quando i pulsanti Echo vengono esposti).
Gallery image 1 of 1

Comandi comuni

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

Riprodurre un’intera sezione:

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

Riprodurre una categoria specifica per nome:

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

Mettere in pausa o fermare:

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

Impostare il volume (0.0–1.0):

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

Cambiare libreria:

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

Riprodurre un Echo one‑shot:

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

Ripristinare 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 di Home Assistant

Ecco una semplice automazione di Home Assistant che avvia una categoria “Battle” nella Musica quando uno switch 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 tu voglia (cambiamenti di scena, pulsanti fisici, pulsanti del stream deck, ecc.).