home@slashpaf ~ $

MQTT / Home Assistant

<- zurück zum Dokumentenstamm  

Was MQTT für Audio Forge macht

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 spielen).
  • 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 integrieren können.

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

MQTT in den Einstellungen aktivieren

Gehen Sie in Audio Forge zu Einstellungen → Externe Steuerung → 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 benötigt.
  • Client-ID (lassen Sie den Standard, es sei denn, Sie wissen, dass Sie eine benutzerdefinierte benötigen).
  • Basisthema (Standard: audioforge/<geräte-name-oder-id>; zum Beispiel audioforge/my-pc).
  • QoS (0/1/2; 1 ist ein guter Standard).
  • Ob der Status beibehalten, beim Start automatisch verbunden, der Status veröffentlicht und Befehle abonniert werden sollen.
  • MQTT Discovery und ein optionales Discovery-Präfix (gewöhnlich homeassistant).
  • Erweiterte Optionen, um Ambiance-Schalter freizugeben, Kategorien-Lautstärken freizugeben und Echo-Tasten freizugeben als zusätzliche Entitäten.

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

Gallery image 1 of 1

Hauptthemen

Wenn Ihr Basisthema audioforge/my-pc ist, verwendet Audio Forge:

  • audioforge/my-pc/availability – online / offline Status (beibehalten).
  • audioforge/my-pc/state – JSON-Snapshot des aktuellen Wiedergabestatus (beibehalten, wenn Status beibehalten aktiviert ist).
  • audioforge/my-pc/catalog – JSON-Katalog aller Bibliotheken und ihrer Kategorien (beibehalten).
  • audioforge/my-pc/cmd – hier senden Sie JSON-Befehle zur Steuerung der Wiedergabe.
  • audioforge/my-pc/result – optionale JSON-Antworten (Erfolg / Fehler).
  • audioforge/my-pc/events/echo – einmalige “Echo”-Ereignisse (nicht beibehalten).

Der Status-Payload umfasst Dinge wie:

  • deviceId, libraryUuid, libraryName.
  • Ob Musik oder Ambiance spielen, sowie deren Basislautstärke.
  • Die aktuell spielenden Kategorien (musicCategories / ambianceCategories).
  • Lautstärke-Faktoren pro Kategorie (categoryVolume-Zuordnung).
  • Das zuletzt gespielte einmalige (Echo) und die aktuelle volumeTransitionMs.

Grundlegende Steuerung von Home Assistant

Sie können Home Assistant auf zwei Arten verwenden:

  1. Manuelle MQTT-Entitäten: Erstellen Sie Sensoren/Tasten in YAML (oder über die UI), die vom state lesen und an cmd senden.
  2. MQTT Discovery (empfohlen): Aktivieren Sie „MQTT Discovery“ in der App, und Audio Forge erstellt die Entitäten automatisch für Sie.

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

  • Binärsensoren (Verfügbar, Musik spielt, Ambiance spielt).
  • Sensoren (Bibliotheksname, Musik-/Ambiance-Kategorien, Letztes Echo).
  • Tasten (Wiedergabe / Pause / Stop für Musik und Ambiance).
  • Auswahlen (Musik-/Ambiance-Kategorien wählen, Bibliotheken wechseln).
  • Zahlen (Musik-/Ambiance-Lautstärke, Lautstärke-Übergangszeit, optionale Lautstärke pro Kategorie).
  • Optionale Schalter (einen pro Ambiance-Kategorie, wenn Sie diese freigeben).
  • Optionale Echo-Tasten (eine pro Echo-Kategorie, wenn Echo-Tasten freigegeben werden).
Gallery image 1 of 1

Häufige Befehle

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

Ein ganzes Segment abspielen:

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

Eine bestimmte Kategorie nach Namen abspielen:

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

Pausieren oder stoppen:

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

Lautstärke festlegen (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 von einem durch die App erstellten Link wiederherstellen:

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

Wenn ein Befehl nicht ausgeführt werden kann (zum Beispiel, wenn 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 der Musik startet, wenn ein Hilfsschalter eingeschaltet wird:

alias: Battle in Audio Forge spielen
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

Dies ist nur ein Beispiel; Sie können Audio Forge mit welchen Ereignissen auch immer verbinden, die Sie möchten (Szenenwechsel, physische Tasten, Streamdeck-Tasten, etc.).