API locale

<- retour à l’accueil de la documentation  

Ce que fait l’API locale

Audio Forge comprend un petit serveur intégré qui fonctionne sur votre machine. Cela 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 supporte exactement les mêmes commandes. La différence est qu’elle fonctionne entièrement sur votre machine sans aucune configuration : pas de courtier à installer, pas de réseau à configurer.

Activation de l’API locale

Allez dans 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 :

• Bascule Activée (par défaut : activé).
• Numéro de port (par défaut : 8329).
• Bascule Écouter sur le LAN (par défaut : désactivé). Lorsque activé, les appareils sur votre réseau local peuvent accéder à l’API. Lorsque désactivé, seul le logiciel de la même machine peut se connecter.
• Clé API (générée automatiquement). Requise pour se connecter 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 en cours de lecture
curl http://localhost:8329/api/state

# Lister toutes les bibliothèques et catégories
curl http://localhost:8329/api/catalog

# Jouer 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 actuellement :

{
  "libraryUuid": "...",
  "libraryName": "[Défaut]",
  "musicPlaying": true,
  "ambiancePlaying": false,
  "musicVolume": 0.75,
  "ambianceVolume": 0.5,
  "echoesVolume": 1.0,
  "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 de musique et d’ambiance :

{
  "activeLibraryUuid": "...",
  "libraries": [
    {
      "uuid": "...",
      "name": "[Défaut]",
      "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 non trouvée"}

WebSocket

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

ws://localhost:8329/ws

Envoi de commandes

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

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

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

Réception des mises à jour

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

Les mises à jour d’état sont rafraîchies (250 ms) pour éviter d’être inondées 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

Lancer 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 catégorie : sélectionne et joue cette catégorie.
• L’ambiance utilise une logique de basculement. Jouer une catégorie d’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": "Ma Bibliothèque"}
{"command": "setActiveLibrary", "libraryUuid": "<uuid>"}

setVolume

Définir le volume pour une section entière, ou pour une catégorie spécifique dans une section. Utilisez value de 0.0 à 1.0, ou de 0 à 100 avec valueScale: percent.

{"command": "setVolume", "section": "Music", "value": 1.0}
{"command": "setVolume", "section": "Music", "value": 75, "valueScale": "percent"}
{"command": "setVolume", "section": "Echoes", "value": 0.5}
{"command": "setVolume", "section": "Ambiance", "value": 0.5,
  "categoryName": "Rain", "transitionMs": 1000}

L’option transitionMs contrôle la rapidité avec laquelle le volume passe au nouveau niveau (par défaut : 500 ms).

playEcho

Déclencher un son d’Écho ponctuel.

{"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 sauvegardé à 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 est manquant), la réponse contiendra "ok": false et un message error décrivant ce qui n’a pas fonctionné.

{"ok": false, "error": "catégorie non trouvée"}
{"ok": false, "error": "section requise"}
{"ok": false, "error": "json invalide"}

Sécurité

Par défaut, l’API locale se lie à 127.0.0.1 (localhost uniquement) 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-localhost. 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’une des méthodes suivantes :

• 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'Authorization
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 en localhost ne nécessitent jamais une 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. Tous les clients précédemment connectés auront besoin de la nouvelle clé.