home@slashpaf ~ $

MQTT / Home Assistant

<- back to doc root  

What MQTT does for Audio Forge

MQTT lets Audio Forge talk to your smart home so you can:

  • See what Audio Forge is doing (which library, whether Music/Ambiance are playing).
  • Trigger playback from Home Assistant, Node‑RED, or any MQTT‑capable tool.
  • Wire Audio Forge into automations with lights, fog machines, scene switches, and more.

If you already run an MQTT broker (Mosquitto, Home Assistant’s built‑in broker, etc.), Audio Forge can connect to it and publish its state while listening for commands.

Enabling MQTT in Settings

In Audio Forge, go to Settings → MQTT Integration and enable the feature.

You can configure:

  • Host and Port (1883 by default, or 8883 for TLS).
  • TLS/SSL toggle.
  • Username / Password if your broker requires them.
  • Client ID (leave the default unless you know you need a custom one).
  • Base Topic (default: audioforge/<device-name-or-id>; for example audioforge/my-pc).
  • QoS (0/1/2; 1 is a good default).
  • Whether to retain state, auto‑connect on startup, publish state, and subscribe to commands.
  • MQTT Discovery and an optional Discovery prefix (usually homeassistant).
  • Advanced options to expose Ambiance switches, expose category volumes, and expose Echo buttons as extra entities.

Once connected, Audio Forge will publish its availability and state to your broker and (optionally) listen for commands.

Gallery image 1 of 1

Main topics

Assuming your base topic is audioforge/my-pc, Audio Forge uses:

  • audioforge/my-pc/availability – online / offline status (retained).
  • audioforge/my-pc/state – JSON snapshot of the current playback state (retained if you enable Retain state).
  • audioforge/my-pc/catalog – JSON catalog of all libraries and their categories (retained).
  • audioforge/my-pc/cmd – where you send JSON commands to control playback.
  • audioforge/my-pc/result – optional JSON replies (success / error).
  • audioforge/my-pc/events/echo – one‑shot “echo” events (not retained).

The state payload includes things like:

  • deviceId, libraryUuid, libraryName.
  • Whether Music or Ambiance are playing, plus their base volumes.
  • The currently playing categories (musicCategories / ambianceCategories).
  • Per‑category volume factors (categoryVolume mapping).
  • The last played one‑shot (Echo) and the current volumeTransitionMs.

Basic control from Home Assistant

You can use Home Assistant in two ways:

  1. Manual MQTT entities: create sensors/buttons in YAML (or the UI) that read from state and publish to cmd.
  2. MQTT Discovery (recommended): enable “MQTT Discovery” in the app and Audio Forge will auto‑create entities for you.

When discovery is enabled, you’ll see an Audio Forge device with:

  • Binary sensors (Available, Music Playing, Ambiance Playing).
  • Sensors (Library name, Music/Ambiance categories, Last Echo).
  • Buttons (Play / Pause / Stop for Music and Ambiance).
  • Selects (choose Music/Ambiance categories, switch libraries).
  • Numbers (Music/Ambiance volume, volume transition time, optional per‑category volumes).
  • Optional switches (one per Ambiance category if you choose to expose them).
  • Optional Echo buttons (one per Echo category when Echo buttons are exposed).
Gallery image 1 of 1

Common commands

Commands are small JSON objects published to <base>/cmd. Here are a few useful examples:

Play a whole section:

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

Play a specific category by name:

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

Pause or stop:

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

Set volume (0.0–1.0):

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

Switch library:

{"command": "setActiveLibrary", "libraryName": "My Library"}

Play a one‑shot Echo:

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

Restore a saved state from a link created by the app:

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

If a command cannot be executed (for example, a category name doesn’t exist), Audio Forge publishes an error on <base>/result.

Example: simple Home Assistant automation

Here is a minimal Home Assistant automation that starts a “Battle” category in Music when a helper switch is turned on:

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

This is just one example; you can connect Audio Forge to whatever events you like (scene changes, physical buttons, stream deck buttons, etc.).