home@slashpaf ~ $

MQTT / Home Assistant

<- zurück zur Dokumentation  

Was MQTT für Audio Forge tut

MQTT ermöglicht es Audio Forge, mit Ihrem Smart Home zu kommunizieren, sodass Sie:

  • Sehen können, was Audio Forge gerade macht (welche Bibliothek, ob Musik/Ambiance abgespielt werden).
  • Die Wiedergabe von Home Assistant, Node-RED oder jedem MQTT-fähigen Tool auslösen können.
  • Audio Forge in Automatisierungen mit Lichtern, Nebelmaschinen, Szenenschaltern und mehr einbinden können.

Wenn Sie bereits einen MQTT-Broker (Mosquitto, den integrierten Broker von Home Assistant usw.) betreiben, kann Audio Forge sich damit verbinden, seinen Status veröffentlichen und Befehle empfangen.

Aktivierung von MQTT in den Einstellungen

Gehen Sie in Audio Forge zu Einstellungen → MQTT-Integration und aktivieren Sie die Funktion.

Sie können konfigurieren:

  • Host und Port (standardmäßig 1883 oder 8883 für TLS).
  • TLS/SSL-Umschalter.
  • Benutzername / Passwort, falls Ihr Broker diese erfordert.
  • Client-ID (lassen Sie den Standardwert, es sei denn, Sie benötigen eine benutzerdefinierte).
  • Basisthema (standardmäßig: audioforge/<gerät-name-oder-id>; zum Beispiel audioforge/mein-pc).
  • QoS (0/1/2; 1 ist ein guter Standardwert).
  • Ob der Status beibehalten, automatisch beim Start verbunden, Status veröffentlicht und Befehle abonniert werden sollen.
  • MQTT-Erkennung und ein optionales Erkennung-Präfix (normalerweise homeassistant).
  • Erweiterte Optionen zum Exponieren von Ambiance-Schaltern, Exponieren von Kategorielautstärken und Exponieren von Echo-Tasten als zusätzliche Entitäten.

Sobald die Verbindung hergestellt ist, wird Audio Forge seine Verfügbarkeit und seinen Status an Ihren Broker veröffentlichen und (optional) Befehle empfangen.

Gallery image 1 of 1

Hauptthemen

Angenommen, Ihr Basisthema ist audioforge/mein-pc, verwendet Audio Forge:

  • audioforge/mein-pc/verfügbarkeit – online / offline Status (beibehalten).
  • audioforge/mein-pc/status – JSON-Snapshot des aktuellen Wiedergabezustands (beibehalten, wenn Sie Status beibehalten aktivieren).
  • audioforge/mein-pc/katalog – JSON-Katalog aller Bibliotheken und ihrer Kategorien (beibehalten).
  • audioforge/mein-pc/cmd – hier senden Sie JSON-Befehle zur Steuerung der Wiedergabe.
  • audioforge/mein-pc/ergebnis – optionale JSON-Antworten (Erfolg / Fehler).
  • audioforge/mein-pc/ereignisse/echo – einmalige “Echo”-Ereignisse (nicht beibehalten).

Die Statusnutzlast umfasst Dinge wie:

  • deviceId, libraryUuid, libraryName.
  • Ob Musik oder Ambiance abgespielt wird, plus deren Basislautstärken.
  • Die derzeit abgespielten Kategorien (musicCategories / ambianceCategories).
  • Pro-Kategorie-Lautstärkefaktoren (categoryVolume Zuordnung).
  • Das zuletzt gespielte einmalige (Echo) und die aktuelle volumeTransitionMs.

Grundlegende Steuerung von Home Assistant aus

Sie können Home Assistant auf zwei Arten verwenden:

  1. Manuelle MQTT-Entitäten: Erstellen Sie Sensoren/Knöpfe in YAML (oder der UI), die aus state lesen und zu cmd veröffentlichen.
  2. MQTT-Erkennung (empfohlen): Aktivieren Sie “MQTT-Erkennung” in der App und Audio Forge erstellt automatisch Entitäten für Sie.

Wenn die Erkennung aktiviert ist, sehen Sie ein Audio Forge-Gerät mit:

  • Binärsensoren (Verfügbar, Musik wird abgespielt, Ambiance wird abgespielt).
  • Sensoren (Bibliotheksname, Musik/Ambiance-Kategorien, Letztes Echo).
  • Knöpfe (Play / Pause / Stop für Musik und Ambiance).
  • Wahlschaltern (Musik/Ambiance-Kategorien auswählen, Bibliotheken wechseln).
  • Nummern (Musik/Ambiance-Lautstärke, Lautstärke-Übergangszeit, optionale Lautstärken pro Kategorie).
  • Optionale Schalter (jeweils ein Schalter pro Ambiance-Kategorie, falls Sie diese exponieren möchten).
  • Optionale Echo-Knöpfe (jeweils ein Knopf pro Echo-Kategorie, wenn Echo-Knöpfe exponiert werden).
Gallery image 1 of 1

Häufige Befehle

Befehle sind kleine JSON-Objekte, die an <base>/cmd gesendet werden. Hier einige nützliche Beispiele:

Ein ganzes Abschnitt abspielen:

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

Eine bestimmte Kategorie nach Namen abspielen:

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

Pause oder Stopp:

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

Lautstärke einstellen (0,0–1,0):

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

Bibliothek wechseln:

{"command": "setActiveLibrary", "libraryName": "Meine Bibliothek"}

Ein einmaliges Echo abspielen:

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

Einen gespeicherten Zustand aus einem vom App erstellten Link wiederherstellen:

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

Wenn ein Befehl nicht ausgeführt werden kann (z. B. ein Kategoriename nicht existiert), veröffentlicht Audio Forge einen Fehler auf <base>/result.

Beispiel: einfache Home Assistant-Automatisierung

Hier ist eine minimale Home Assistant-Automatisierung, die eine “Battle”-Kategorie in Musik startet, wenn ein Hilfsschalter eingeschaltet wird:

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

Dies ist nur ein Beispiel; Sie können Audio Forge an beliebige Ereignisse anschließen (Szenenwechsel, physische Knöpfe, Stream-Deck-Knöpfe usw.).