home@slashpaf ~ $

MQTT / Home Assistant

<- retour à la racine de la documentation  

Ce que MQTT fait pour Audio Forge

MQTT permet à Audio Forge de communiquer avec votre maison intelligente pour que vous puissiez :

  • Voir ce qu’Audio Forge fait (quelle bibliothèque, si la Musique/Ambiance sont en cours de lecture).
  • Déclencher la lecture à partir de Home Assistant, Node‑RED, ou tout autre outil compatible MQTT.
  • Intégrer Audio Forge dans les automatisations avec des lumières, des machines à brouillard, des interrupteurs de scène, et plus encore.

Si vous utilisez déjà un courtier MQTT (Mosquitto, le courtier intégré de Home Assistant, etc.), Audio Forge peut s’y connecter et publier son état tout en écoutant les commandes.

Activer MQTT dans les Paramètres

Dans Audio Forge, allez dans Paramètres → Intégration MQTT et activez la fonctionnalité.

Vous pouvez configurer :

  • Hôte et Port (1883 par défaut, ou 8883 pour TLS).
  • Basculer entre TLS/SSL.
  • Nom d’utilisateur / Mot de passe si votre courtier les exige.
  • ID Client (laissez par défaut sauf si vous savez que vous avez besoin d’un personnalisé).
  • Sujet de base (par défaut : audioforge/<nom-ou-id-appareil> ; par exemple audioforge/mon-pc).
  • QoS (0/1/2 ; 1 est un bon choix par défaut).
  • Si vous souhaitez conserver l’état, se connecter automatiquement au démarrage, publier l’état et s’abonner aux commandes.
  • Découverte MQTT et un éventuel préfixe de découverte (généralement homeassistant).
  • Options avancées pour exposer les commutateurs Ambiance, exposer les volumes de catégorie, et exposer les boutons Echo en tant qu’entités supplémentaires.

Une fois connecté, Audio Forge publiera sa disponibilité et son état à votre courtier et, le cas échéant, écoutera les commandes.

Gallery image 1 of 1

Sujets principaux

En supposant que votre sujet de base soit audioforge/mon-pc, Audio Forge utilise :

  • audioforge/mon-pc/availability – statut en ligne / hors ligne (conservé).
  • audioforge/mon-pc/state – instantané JSON de l’état actuel de la lecture (conservé si vous activez Conserver l’état).
  • audioforge/mon-pc/catalog – catalogue JSON de toutes les bibliothèques et leurs catégories (conservé).
  • audioforge/mon-pc/cmd – où vous envoyez les commandes JSON pour contrôler la lecture.
  • audioforge/mon-pc/result – réponses JSON facultatives (succès / erreur).
  • audioforge/mon-pc/events/echo – événements “echo” ponctuels (non conservés).

La charge utile de l’état inclut des éléments tels que :

  • deviceId, libraryUuid, libraryName.
  • Si la Musique ou l’Ambiance sont en cours de lecture, ainsi que leurs volumes de base.
  • Les catégories actuellement en cours de lecture (musicCategories / ambianceCategories).
  • Facteurs de volume par catégorie (categoryVolume mapping).
  • Le dernier événement ponctuel joué (Echo) et la volumeTransitionMs actuelle.

Contrôle de base à partir de Home Assistant

Vous pouvez utiliser Home Assistant de deux manières :

  1. Entités MQTT manuelles : créez des capteurs/boutons en YAML (ou dans l’interface) qui lisent à partir de state et publient vers cmd.
  2. Découverte MQTT (recommandée) : activez la “Découverte MQTT” dans l’application et Audio Forge créera automatiquement des entités pour vous.

Lorsque la découverte est activée, vous verrez un appareil Audio Forge avec :

  • Capteurs binaires (Disponible, Musique en cours de lecture, Ambiance en cours de lecture).
  • Capteurs (Nom de bibliothèque, Catégories de Musique/Ambiance, Dernier Echo).
  • Boutons (Lecture / Pause / Arrêt pour Musique et Ambiance).
  • Sélections (choisir les catégories Musique/Ambiance, changer de bibliothèque).
  • Nombres (volume Musique/Ambiance, temps de transition de volume, volumes par catégorie facultatifs).
  • Commutateurs facultatifs (un par catégorie Ambiance si vous choisissez de les exposer).
  • Boutons Echo facultatifs (un par catégorie Echo lorsque les boutons Echo sont exposés).
Gallery image 1 of 1

Commandes courantes

Les commandes sont de petits objets JSON publiés sur <base>/cmd. Voici quelques exemples utiles :

Lire une section entière :

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

Lire une catégorie spécifique par nom :

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

Mettre en pause ou arrêter :

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

Régler le volume (0.0–1.0) :

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

Changer de bibliothèque :

{"command": "setActiveLibrary", "libraryName": "Ma Bibliothèque"}

Jouer un Echo ponctuel :

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

Restaurer un état enregistré à partir d’un lien créé par l’application :

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

Si une commande ne peut pas être exécutée (par exemple, un nom de catégorie n’existe pas), Audio Forge publie une erreur sur <base>/result.

Exemple : automatisation simple avec Home Assistant

Voici une automatisation minimale pour Home Assistant qui démarre une catégorie “Battle” en Musique lorsqu’un interrupteur d’assistant est activé :

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

Ceci est juste un exemple ; vous pouvez connecter Audio Forge aux événements de votre choix (changements de scène, boutons physiques, boutons de stream deck, etc.).