home@slashpaf ~ $

MQTT / Home Assistant

<- retour à la racine de la doc  

Ce que MQTT apporte à Audio Forge

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

  • Voir ce que fait Audio Forge (quelle bibliothèque, si la musique / l’ambiance est en train de jouer).
  • Déclencher la lecture depuis Home Assistant, Node‑RED, ou tout autre outil compatible MQTT.
  • Connecter Audio Forge à des automatisations avec des lumières, machines à brouillard, interrupteurs de scène, et plus encore.

Si vous avez déjà un courtier MQTT en cours d’exécution (Mosquitto, 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 à Paramètres → Contrôle Externe → Intégration MQTT et activez la fonctionnalité.

Vous pouvez configurer :

  • Hôte et Port (1883 par défaut, ou 8883 pour TLS).
  • Commutateur TLS/SSL.
  • Nom d’utilisateur / Mot de passe si votre courtier l’exige.
  • ID Client (laissez la valeur par défaut sauf si vous savez que vous avez besoin d’un personnalisée).
  • Sujet de base (par défaut : audioforge/<nom-ou-id-de-l'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 préfixe de découverte optionnel (habituellement homeassistant).
  • Options avancées pour exposer les commutateurs d’ambiance, exposer les volumes par 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 (facultativement) écoutera les commandes.

Gallery image 1 of 1

Principaux sujets

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

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

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

  • deviceId, libraryUuid, libraryName.
  • Si Musique ou Ambiance est en cours, ainsi que leurs volumes de base.
  • Les catégories actuellement jouées (musicCategories / ambianceCategories).
  • Facteurs de volume par catégorie (catégorieVolume mappant).
  • Le dernier une-fois joué (Echo) et la transitionVolumeMs actuelle.

Contrôle de base depuis Home Assistant

Vous pouvez utiliser Home Assistant de deux manières :

  1. Entités MQTT manuelles : créer des capteurs / boutons en YAML (ou via l’UI) qui lisent depuis state et publient sur cmd.
  2. Découverte MQTT (recommandé) : 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, Ambiance en cours).
  • Capteurs (Nom de la bibliothèque, catégories de Musique/Ambiance, Dernière Echo).
  • Boutons (Lire / Pause / Stop pour la musique et l’ambiance).
  • Sélecteurs (choisissez les catégories Musique/Ambiance, changez de bibliothèque).
  • Nombres (volume Musique/Ambiance, temps de transition du volume, volumes par catégorie optionnels).
  • Commutateurs optionnels (un par catégorie d’Ambiance si vous choisissez de les exposer).
  • Boutons Echo optionnels (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 à <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"}

Pause ou arrêt :

{"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 unique :

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

Restaurer un état sauvegardé à 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 de Home Assistant qui démarre une catégorie “Battle” dans Musique lorsqu’un commutateur d’aide 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 à tous les événements qui vous conviennent (changements de scène, boutons physiques, boutons de stream deck, etc.).