home@slashpaf ~ $

MQTT / Home Assistant

<- volver al inicio del documento  

Qué hace MQTT para Audio Forge

MQTT permite que Audio Forge se comunique con tu hogar inteligente para que puedas:

  • Ver qué está haciendo Audio Forge (qué biblioteca, si se está reproduciendo Música/Ambiente).
  • Iniciar la reproducción desde Home Assistant, Node-RED, o cualquier herramienta compatible con MQTT.
  • Conectar Audio Forge con automatizaciones como luces, máquinas de niebla, interruptores de escena y más.

Si ya ejecutas un broker MQTT (Mosquitto, el broker incorporado de Home Assistant, etc.), Audio Forge puede conectarse y publicar su estado mientras escucha comandos.

Habilitando MQTT en Configuración

En Audio Forge, ve a Configuración → Control Externo → Integración de MQTT y habilita la función.

Puedes configurar:

  • Host y Puerto (1883 por defecto, o 8883 para TLS).
  • Alternar TLS/SSL.
  • Usuario / Contraseña si tu broker los requiere.
  • ID de Cliente (deja el valor por defecto a menos que necesites uno personalizado).
  • Tema Base (por defecto: audioforge/<nombre-del-dispositivo-o-id>; por ejemplo audioforge/mi-pc).
  • QoS (0/1/2; 1 es un buen valor por defecto).
  • Si deseas retener el estado, conectarse automáticamente al iniciar, publicar estado, y suscribirse a comandos.
  • Descubrimiento de MQTT y un Prefijo de descubrimiento opcional (usualmente homeassistant).
  • Opciones avanzadas para exponer interruptores de Ambiente, exponer volúmenes de categoría, y exponer botones Echo como entidades adicionales.

Una vez conectado, Audio Forge publicará su disponibilidad y estado a tu broker y (opcionalmente) escuchará comandos.

Gallery image 1 of 1

Temas principales

Asumiendo que tu tema base es audioforge/mi-pc, Audio Forge utiliza:

  • audioforge/mi-pc/availability – estado de en línea / desconectado (retenido).
  • audioforge/mi-pc/state – Instantánea JSON del estado de reproducción actual (retenido si habilitas Retener estado).
  • audioforge/mi-pc/catalog – Catálogo JSON de todas las bibliotecas y sus categorías (retenido).
  • audioforge/mi-pc/cmd – donde envías comandos JSON para controlar la reproducción.
  • audioforge/mi-pc/result – respuestas JSON opcionales (éxito / error).
  • audioforge/mi-pc/events/echo – eventos de “echo” de un solo uso (no retenidos).

La carga útil del estado incluye elementos como:

  • deviceId, libraryUuid, libraryName.
  • Si Música o Ambiente están reproduciéndose, además de sus volúmenes base.
  • Las categorías que se están reproduciendo actualmente (musicCategories / ambianceCategories).
  • Factores de volumen por-categoría (mapeo de categoryVolume).
  • El último sonido de un solo uso (Echo) y el volumeTransitionMs actual.

Control básico desde Home Assistant

Puedes usar Home Assistant de dos maneras:

  1. Entidades MQTT manuales: crear sensores/botones en YAML (o la interfaz) que leen de state y publican en cmd.
  2. Descubrimiento MQTT (recomendado): habilita el “Descubrimiento MQTT” en la app y Audio Forge creará automáticamente entidades para ti.

Cuando el descubrimiento está habilitado, verás un dispositivo Audio Forge con:

  • Sensores binarios (Disponible, Música Reproduciendo, Ambiente Reproduciendo).
  • Sensores (Nombre de la biblioteca, categorías de Música/Ambiente, Último Echo).
  • Botones (Reproducir / Pausar / Detener para Música y Ambiente).
  • Selectores (elegir categorías de Música/Ambiente, cambiar bibliotecas).
  • Números (volumen de Música/Ambiente, tiempo de transición de volumen, volúmenes por categoría opcionales).
  • Interruptores opcionales (uno por categoría de Ambiente si decides exponerlos).
  • Botones Echo opcionales (uno por categoría Echo cuando se exponen botones Echo).
Gallery image 1 of 1

Comandos comunes

Los comandos son pequeños objetos JSON publicados en <base>/cmd. Aquí algunos ejemplos útiles:

Reproducir una sección completa:

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

Reproducir una categoría específica por nombre:

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

Pausar o detener:

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

Establecer volumen (0.0-1.0):

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

Cambiar biblioteca:

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

Reproducir un Echo de un solo uso:

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

Restaurar un estado guardado desde un enlace creado por la aplicación:

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

Si no se puede ejecutar un comando (por ejemplo, si un nombre de categoría no existe), Audio Forge publica un error en <base>/result.

Ejemplo: automatización simple en Home Assistant

Aquí tienes una automatización mínima en Home Assistant que inicia una categoría “Battle” en Música cuando un interruptor auxiliar se enciende:

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

Este es solo un ejemplo; puedes conectar Audio Forge a cualquier evento que desees (cambios de escena, botones físicos, botones de stream deck, etc.).