API Locale

<- retour à la racine de la doc  

Ce que fait l’API Locale

Audio Forge intègre un petit serveur intégré qui fonctionne sur votre machine. Il permet à des outils externes, comme un plugin Elgato Stream Deck, un script personnalisé ou toute application sur votre PC, de contrôler la lecture via HTTP ou WebSocket, sans logiciel supplémentaire requis.

Si vous utilisez déjà l’intégration MQTT, l’API Locale prend en charge les mêmes commandes. La différence est qu’elle fonctionne entièrement sur votre machine sans aucune configuration : aucun broker à installer, aucun réseau à configurer.

Activation de l’API Locale

Accédez à Paramètres → Contrôle externe → API Locale et assurez-vous que la fonctionnalité est activée (elle l’est par défaut).

Vous pouvez configurer :

• Commutateur Activé (par défaut : activé).
• Numéro de Port (par défaut : 8329).
• Commutateur Écouter sur le LAN (par défaut : désactivé). Une fois activé, les appareils sur votre réseau local peuvent accéder à l’API. Si désactivé, seuls les logiciels sur la même machine peuvent se connecter.
• Clé API (générée automatiquement). Nécessaire lors de la connexion depuis un autre appareil sur le réseau. Vous pouvez la copier ou la régénérer depuis les Paramètres.

Une fois activée, Audio Forge écoute sur http://localhost:8329. Si “Écouter sur le LAN” est activé, il écoute sur toutes les interfaces réseau.

Démarrage rapide

Ouvrez un terminal et essayez :

# Voir ce qui est actuellement en cours de lecture
curl http://localhost:8329/api/state

# Lister chaque bibliothèque et catégorie
curl http://localhost:8329/api/catalog

# Lire une catégorie
curl -X POST http://localhost:8329/api/command ^
  -H "Content-Type: application/json" ^
  -d "{\"command\":\"play\",\"section\":\"Music\",\"categoryName\":\"Battle\"}"

C’est tout, si Audio Forge fonctionne avec l’API Locale activée, vous recevrez des réponses JSON immédiatement.

Points de terminaison HTTP

GET /api/state

Retourne un instantané JSON de ce que fait Audio Forge en ce moment :

{
  "libraryUuid": "...",
  "libraryName": "[Default]",
  "musicPlaying": true,
  "ambiancePlaying": false,
  "musicVolume": 0.75,
  "ambianceVolume": 0.5,
  "musicCategories": [{"uuid": "...", "name": "Battle"}],
  "ambianceCategories": [{"uuid": "...", "name": "Rain"}],
  "lastEcho": {"uuid": "...", "name": "Thunder", "at": "2025-06-01T12:34:56Z"},
  "categoryVolume": {"<uuid>": 0.8}
}

GET /api/catalog

Retourne chaque bibliothèque avec ses catégories Musique et Ambiance :

{
  "activeLibraryUuid": "...",
  "libraries": [
    {
      "uuid": "...",
      "name": "[Default]",
      "music": [{"uuid": "...", "name": "Battle"}],
      "ambiance": [{"uuid": "...", "name": "Rain"}]
    }
  ]
}

POST /api/command

Envoyez une commande JSON dans le corps de la requête. En cas de succès :

{"ok": true, "message": "lecture ok"}

En cas d’erreur :

{"ok": false, "error": "catégorie introuvable"}

WebSocket

Pour les outils qui veulent des mises à jour en temps réel (comme un plugin Stream Deck qui doit montrer l’état actuel), connectez un WebSocket à :

ws://localhost:8329/ws

Envoyer des commandes

Envoyez les mêmes objets de commande JSON que vous posteriez à /api/command :

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

Le serveur répond avec un message de résultat pour chaque commande.

Recevoir des mises à jour

Le serveur envoie automatiquement des mises à jour chaque fois que quelque chose change. Chaque message a un champ type :

Les mises à jour d’état sont temporisées (250 ms) afin que vous ne soyez pas inondé lors de changements rapides comme les balayages de volume.

Commandes

Toutes les commandes utilisent le même schéma JSON que l’intégration MQTT. Chaque commande accepte une chaîne requestId optionnelle que vous pouvez utiliser pour faire correspondre les réponses.

play

Lire ou reprendre une section, ou sélectionner une catégorie spécifique.

{"command": "play", "section": "Music"}
{"command": "play", "section": "Music", "categoryName": "Battle"}
{"command": "play", "section": "Ambiance", "categoryUuid": "<uuid>"}

• Sans catégorie : reprend toute la section.
• Avec une catégorie : la sélectionne et la lit.
• Ambiance utilise un comportement de basculement. Lire une catégorie Ambiance déjà active la désactive.

pause

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

stop

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

setActiveLibrary

Changer la bibliothèque active par UUID ou nom.

{"command": "setActiveLibrary", "libraryName": "My Library"}
{"command": "setActiveLibrary", "libraryUuid": "<uuid>"}

setVolume

Régler le volume d’une section entière (0.0 à 1.0), ou d’une catégorie spécifique au sein d’une section.

{"command": "setVolume", "section": "Music", "value": 0.65}
{"command": "setVolume", "section": "Ambiance", "value": 0.5,
  "categoryName": "Rain", "transitionMs": 1000}

La transitionMs optionnelle contrôle la rapidité avec laquelle le volume diminue jusqu’au nouveau niveau (par défaut : 500 ms).

playEcho

Déclencher un son d’écho unique.

{"command": "playEcho", "categoryName": "Thunder"}
{"command": "playEcho", "section": "Ambiance", "categoryUuid": "<uuid>"}

setCategoryEnabled

Activer ou désactiver explicitement une catégorie dans une section.

{"command": "setCategoryEnabled", "section": "Ambiance",
  "categoryName": "Rain", "enabled": true}

restoreState

Restaurer un état précédemment enregistré à partir d’un lien de partage créé par l’application.

{"command": "restoreState", "link": "slashpaf://..."}

setConfig

Transmettre un paramètre de configuration à l’intégration MQTT (si connectée). Utile pour l’automatisation avancée.

{"command": "setConfig", "key": "someKey", "value": "someValue"}

Gestion des erreurs

Si une commande ne peut pas être exécutée (par exemple, un nom de catégorie n’existe pas ou un champ requis manque), la réponse contiendra "ok": false et un message d’error décrivant ce qui s’est mal passé.

{"ok": false, "error": "catégorie introuvable"}
{"ok": false, "error": "section requise"}
{"ok": false, "error": "json invalide"}

Sécurité

Par défaut, l’API Locale se lie à 127.0.0.1 (uniquement local) et n’est pas accessible depuis d’autres appareils sur votre réseau.

Si vous activez Écouter sur le LAN, l’API devient accessible depuis d’autres appareils. Dans ce cas, une clé API est requise pour toutes les requêtes non-locales. La clé est générée automatiquement et affichée dans Paramètres → Contrôle externe → API Locale ; transmettez-la avec chaque requête en utilisant l’un des moyens suivants :

• En-tête : Authorization: Bearer <your-api-key>
• Paramètre de requête : ?apiKey=<your-api-key>

Exemples :

# Utilisation de l'en-tête d'autorisation
curl http://192.168.0.10:8329/api/state ^
  -H "Authorization: Bearer your-api-key-here"

# Utilisation du paramètre de requête
curl "http://192.168.0.10:8329/api/state?apiKey=your-api-key-here"

# Envoi d'une commande depuis un autre appareil
curl -X POST http://192.168.0.10:8329/api/command ^
  -H "Authorization: Bearer your-api-key-here" ^
  -H "Content-Type: application/json" ^
  -d "{\"command\":\"play\",\"section\":\"Music\",\"categoryName\":\"Battle\"}"

# WebSocket avec clé API
wscat -c "ws://192.168.0.10:8329/ws?apiKey=your-api-key-here"

Les requêtes locales n’exigent jamais de clé, même lorsque le mode LAN est activé.

Vous pouvez régénérer la clé API à tout moment depuis Paramètres → Contrôle externe → API Locale. Tout client précédemment connecté devra disposer de la nouvelle clé.