home@slashpaf ~ $

MQTT / Home Assistant

<- volver a la raíz del documento  

Qué hace MQTT por 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).
  • Activar la reproducción desde Home Assistant, Node‑RED o cualquier herramienta compatible con MQTT.
  • Integrar Audio Forge en automatizaciones con luces, máquinas de niebla, interruptores de escenas y más.

Si ya utilizas un servidor MQTT (Mosquitto, el servidor incorporado de Home Assistant, etc.), Audio Forge puede conectarse a él y publicar su estado mientras escucha comandos.

Habilitando MQTT en Configuración

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

Puedes configurar:

  • Host y Puerto (1883 por defecto, o 8883 para TLS).
  • Alternar TLS/SSL.
  • Nombre de usuario / Contraseña si tu servidor lo requiere.
  • ID de Cliente (deja el valor predeterminado a menos que sepas que necesitas uno personalizado).
  • Tema Base (por defecto: audioforge/<nombre-o-id-del-dispositivo>; por ejemplo audioforge/mi-pc).
  • QoS (0/1/2; 1 es una buena opción por defecto).
  • Si deseas retener el estado, conectarte automáticamente al inicio, publicar estado y suscribirte a comandos.
  • Descubrimiento de MQTT y un prefijo de descubrimiento opcional (usualmente homeassistant).
  • Opciones avanzadas para exponer interruptores de Ambientación, exponer volúmenes por categoría y exponer botones Eco como entidades adicionales.

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

Gallery image 1 of 1

Temas principales

Suponiendo que tu tema base sea audioforge/mi-pc, Audio Forge utiliza:

  • audioforge/mi-pc/availability – estado online / offline (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 “eco” de una sola vez (no retenidos).

La carga útil del estado incluye cosas como:

  • deviceId, libraryUuid, libraryName.
  • Si Música o Ambiente están en reproducción, además de sus volúmenes base.
  • Las categorías que se están reproduciendo actualmente (musicCategories / ambianceCategories).
  • Factores de volumen por categoría (categoryVolume mapeo).
  • El último eco reproducido de una sola vez y el actual volumeTransitionMs.

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 lean del state y publiquen en cmd.
  2. Descubrimiento MQTT (recomendado): habilita “Descubrimiento MQTT” en la aplicación 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 en reproducción, Ambiente en reproducción).
  • Sensores (Nombre de la biblioteca, Categorías de Música/Ambiente, Último Eco).
  • Botones (Reproducir / Pausar / Detener para Música y Ambiente).
  • Selectores (elegir categorías de Música/Ambiente, cambiar de bibliotecas).
  • Números (Volumen de Música/Ambiente, tiempo de transición de volumen, volúmenes por categoría opcionales).
  • Interruptores opcionales (uno por cada categoría de Ambiente si eliges exponerlos).
  • Botones Eco opcionales (uno por cada categoría de Eco cuando los botones Eco están expuestos).
Gallery image 1 of 1

Comandos comunes

Los comandos son pequeños objetos JSON publicados en <base>/cmd. Aquí tienes 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"}

Ajustar el volumen (0.0–1.0):

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

Cambiar de biblioteca:

{"command": "setActiveLibrary", "libraryName": "Mi Biblioteca"}

Reproducir un eco de una sola vez:

{"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 un comando no se puede ejecutar (por ejemplo, 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 se activa un interruptor auxiliar:

alias: Reproducir Battle 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 los eventos que desees (cambios de escena, botones físicos, botones de stream deck, etc.).