API Locale

<- retour à la racine du document  

Ce que fait l’API Locale

Audio Forge inclut un petit serveur intégré qui fonctionne sur votre machine. Il permet aux 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 configuration particulière : aucun broker à installer, aucun réseau à configurer.

Activer l’API Locale

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

Vous pouvez configurer :

• Activé (par défaut : activé).
• Port (par défaut : 8329).
• Écouter sur le LAN (par défaut : désactivé). Lorsque cette option est activée, les appareils de votre réseau local peuvent accéder à l’API. Lorsque cette option est désactivée, seuls les logiciels de la même machine peuvent se connecter.
• Clé API (générée automatiquement). Requise lors de la connexion depuis un autre appareil sur le réseau. Vous pouvez la copier ou la régénérer dans 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 :

# See what's playing right now
curl http://localhost:8329/api/state

# List every library and category
curl http://localhost:8329/api/catalog

# List one-shot Echo sounds that are playing now
curl http://localhost:8329/api/echoes/active

# Play a category
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 est en cours d’exécution avec l’API Locale activée, vous obtiendrez des réponses JSON immédiatement.

Points de terminaison HTTP

GET /api/state

Renvoie une capture instantanée JSON de ce qu’Audio Forge fait actuellement :

{
  "libraryUuid": "...",
  "libraryName": "[Default]",
  "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.5}
}

Tous les champs de volume utilisent l’échelle d’affichage de l’application, de 0.0 à 1.0. Pour la Musique et l’Ambiance, 0.5 est le volume normal (unité) et 1.0 est le volume maximum boosté. Pour les Échos, 1.0 est le volume normal.

categoryVolume contient les valeurs d’exécution actuelles et peut être sparse. Utilisez le volume de /api/catalog pour chaque catégorie lorsque vous avez besoin d’une valeur complète pour chaque catégorie, y compris les catégories qui ne sont pas encore utilisées.

GET /api/catalog

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

{
  "activeLibraryUuid": "...",
  "libraries": [
    {
      "uuid": "...",
      "name": "[Default]",
      "music": [{
        "uuid": "...",
        "name": "Battle",
        "enabledInForge": true,
        "trackCount": 3,
        "volume": 0.5
      }],
      "ambiance": [{
        "uuid": "...",
        "name": "Rain",
        "enabledInForge": false,
        "trackCount": 0,
        "volume": 0.5
      }]
    }
  ]
}

• enabledInForge indique si la catégorie est visible et activée dans Forge.
• trackCount est le nombre de pistes jouables actuellement installées pour cette catégorie.
• volume est le volume effectif de la catégorie sur l’échelle 0.0 à 1.0. Il est présent pour chaque catégorie, y compris les catégories inactives.

Pour une catégorie active, le catalogue signale son volume d’exécution actuel. Pour une catégorie inactive, il signale le volume cible configuré, ou 0.5 s’il n’y a pas de cible. Les ajustements d’exécution ne remplacent pas la cible configurée. Lorsqu’une catégorie redémarre, une valeur de commande explicite est utilisée si elle est présente ; sinon, la cible configurée est utilisée. L’ajustement d’exécution précédent n’est pas réutilisé. La restauration d’un Lien d’État applique les volumes d’exécution enregistrés dans ce lien.

GET /api/echoes/active

Renvoie une capture instantanée de chaque son d’écho d’un seul coup qui est actuellement en cours de lecture. Les déclenchements simultanés sont renvoyés sous forme d’entrées séparées, même s’ils utilisent la même catégorie ou le même fichier audio.

{
  "count": 1,
  "sampledAt": "2026-07-24T12:00:02.500Z",
  "echoes": [
    {
      "playbackId": "7b304347-410f-4eaf-bad7-4e8488778302",
      "categoryUuid": "2e4d51f1-11ce-46af-a411-0c6bc2c420cb",
      "categoryName": "Thunder",
      "fileName": "thunder-01.wav",
      "startedAt": "2026-07-24T12:00:00.000Z",
      "durationMs": 10000,
      "positionMs": 2500,
      "remainingMs": 7500,
      "progress": 0.25,
      "progressPercent": 25.0,
      "playing": true,
      "processingState": "ready"
    }
  ]
}

• playbackId identifie de manière unique ce déclenchement spécifique. Deux lectures superposées du même catégorie reçoivent des ID différents.
• sampledAt indique quand Audio Forge a généré la capture instantanée. Les valeurs de position ne sont pas transmises en continu, donc les clients doivent demander une nouvelle capture instantanée lorsqu’ils ont besoin de l’état actuel.
• durationMs, remainingMs, progress et progressPercent sont null si la durée du son est inconnue.
• progress utilise une échelle 0.0 à 1.0. progressPercent utilise 0.0 à 100.0.
• fileName contient uniquement le nom du fichier, jamais un chemin d’accès au système de fichiers local.
• Les sons d’écho terminés ou arrêtés sont supprimés de la liste.

Les Échos partagent la valeur globale echoesVolume renvoyée par /api/state. Il n’y a pas de volume par lecture ou par catégorie pour les Échos.

POST /api/command

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

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

En cas d’erreur :

{"ok": false, "error": "category not found"}

GET /api/icon/{categoryUuid}

Renvoie l’image de l’icône d’une catégorie. Utilisez l’UUID de la catégorie fourni par /api/catalog. La catégorie doit appartenir à une bibliothèque active. Le paramètre de requête facultatif size définit la taille demandée pour les icônes de police et SVG ; sa valeur par défaut est de 144 pixels.

• Les icônes de police et SVG sont rendues en PNG et teintées avec la couleur de la catégorie.
• Si un fichier personnalisé est introuvable ou si un SVG ne peut pas être rastérisé, l’API utilise l’icône de police en remplacement.
• Les icônes personnalisées PNG, JPG et JPEG sont renvoyées sans modification ; le paramètre size est ignoré.
• Les réponses réussies utilisent image/png ou image/jpeg et peuvent être mises en cache pendant une heure.
• Si la catégorie est introuvable, la réponse est 404 avec {"error":"category not found"}.
• Si l’icône ne peut pas être rendue, la réponse est 500 avec {"error":"failed to render icon"}.

WebSocket

Pour les outils qui souhaitent 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 via POST à /api/command :

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

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

Réception 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 amorties (250 ms) pour éviter d’être inondé lors de changements rapides, comme des balayages de volume.

Les messages sont des objets JSON plats. La charge utile n’est pas imbriquée sous un champ data ou payload. Exemples :

{"type": "state", "musicPlaying": true, "ambiancePlaying": false,
  "musicVolume": 0.5, "ambianceVolume": 0.5,
  "musicCategories": [], "ambianceCategories": [], "categoryVolume": {}}

{"type": "catalog", "activeLibraryUuid": "<uuid>", "libraries": []}

{"type": "result", "ok": true, "message": "play ok", "requestId": "request-1"}

{"type": "echo", "uuid": "<uuid>", "name": "Thunder",
  "at": "2026-07-18T12:34:56Z"}

Commandes

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

play

Lecture ou reprise d’une section, ou sélection d’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 : sélectionne et la joue.
• L’Ambiance utilise une sémantique de basculement. La lecture d’une catégorie Ambiance déjà active la désactive.

pause

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

stop

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

setActiveLibrary

Basculer vers la bibliothèque active par UUID ou nom.

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

setVolume

Définir le volume pour toute la section, 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}

Le transitionMs facultatif contrôle la vitesse à laquelle le volume s’estompe vers le nouveau niveau (par défaut : 500 ms).

La Musique et l’Ambiance utilisent la même échelle d’affichage que l’application : 0.5 est le volume normal (unité) et 1.0 est le maximum boosté. Les Échos n’ont pas de plage boostée, donc 1.0 est le volume normal. L’API convertit automatiquement ces valeurs d’affichage en gain de lecture interne.

nextTrack

Passez à la piste suivante dans une catégorie Musique ou Ambiance active. La catégorie doit déjà être en cours de lecture.

{"command": "nextTrack", "section": "Music", "categoryUuid": "<uuid>"}
{"command": "nextTrack", "section": "Ambiance", "categoryName": "Rain"}

playEcho

Déclenche un son d’écho d’un seul coup.

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

En cas de réussite, la commande attend que la lecture de l’écho soit enregistrée, puis renvoie ses champs de suivi et de lecture :

{
  "ok": true,
  "message": "echo played",
  "requestId": "play-thunder",
  "playbackId": "<playback-id>",
  "categoryUuid": "<category-uuid>",
  "categoryName": "Thunder",
  "fileName": "thunder-01.wav",
  "startedAt": "2026-08-09T12:00:00.000Z",
  "durationMs": 4000,
  "positionMs": 0,
  "remainingMs": 4000,
  "progress": 0.0,
  "progressPercent": 0.0,
  "playing": true,
  "processingState": "ready"
}

Utilisez le playbackId renvoyé avec stopEcho pour arrêter uniquement cette instance de lecture. Vous pouvez également actualiser les valeurs avec GET /api/echoes/active.

stopEcho

Arrêtez la lecture active des sons d’écho en utilisant exactement un sélecteur :

{"command": "stopEcho", "playbackId": "<playback-id>"}
{"command": "stopEcho", "categoryUuid": "<category-uuid>"}
{"command": "stopEcho", "categoryName": "Thunder"}

• playbackId arrête uniquement cette instance de lecture. Obtenez les ID de lecture à partir de GET /api/echoes/active.
• categoryUuid arrête tous les sons d’écho actifs de cette catégorie.
• categoryName arrête tous les sons d’écho dont la catégorie a exactement ce nom. Si les catégories de plusieurs bibliothèques partagent le même nom, toutes les correspondances sont arrêtées.
• Le résultat inclut stoppedCount. Un sélecteur sans correspondances actives réussit avec stoppedCount: 0.
• Pour arrêter tous les sons d’écho actifs, quel que soit la catégorie, utilisez {"command": "stop", "section": "Echoes"}.

setCategoryEnabled

Active ou désactive explicitement une catégorie dans une section.

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

Vous pouvez activer une catégorie et définir son volume de manière atomique en incluant value. Si value est omis, le volume cible configuré de la catégorie est utilisé. Un ajustement d’exécution précédent n’est pas réutilisé.

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

restoreState

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

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

setConfig

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

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

Détection des fonctionnalités

Les versions plus récentes d’Audio Forge ajoutent des fonctionnalités à l’API. Ainsi, un outil peut déterminer ce que la version de l’application en cours prend en charge, et le serveur annonce sa version. C’est le premier message WebSocket, et GET /api/info renvoie la même chose :

{"type": "hello", "apiVersion": 3,
  "features": {"aiDirector": {"available": true, "enabled": true},
               "roomControl": {"commands": ["play", "pause", "stop", "..."]}}}

Les versions plus anciennes d’Audio Forge n’envoient aucun message hello et n’ont pas /api/info : traitez cela comme apiVersion 1 et n’appelez rien de plus récent. N’affichez ou n’appelez les fonctionnalités de l’AI Director que si available et enabled sont tous deux true.

Contrôle du salon

Lorsque vous hébergez un salon en ligne, vous pouvez permettre aux invités de contrôler Audio Forge à partir de la page invité. Deux commandes définissent qui peut (elles ne fonctionnent que lorsque le salon est ouvert) :

{"command": "setRoomDefaultPermission", "permission": "control"}
{"command": "setRoomGuestPermission", "clientId": "<guest clientId>", "permission": "listen"}

permission est "listen" (vous seul contrôlez Audio Forge) ou "control". L’état du salon dans GET /api/state (room) inclut alors defaultGuestPermission et une permission pour chaque entrée de guests (l’une effective : avec "control" comme valeur par défaut, vous pouvez toujours définir un seul invité sur "listen"). room.chatMessages liste également ce que les invités qui contrôlent ont fait, sous forme d’entrées avec kind: "activity", command et des params résolus ; les entrées de chat ont kind: "chat". Les invités qui rejoignent ou quittent le salon apparaissent comme des entrées d’activité avec command guestJoined, guestLeft, guestRemoved ou guestReconnected. Pendant que les invités peuvent contrôler, Audio Forge télécharge également les icônes de catégorie vers le serveur du salon afin que la page invité puisse les afficher. Les invités disposant d’un contrôle ne peuvent exécuter que les commandes répertoriées dans features.roomControl.commands ; la capture, la suppression d’invités, la configuration, l’AI Director et les autorisations restent sous votre contrôle.

AI Director

L’AI Director écoute votre table et modifie la musique et l’ambiance pour vous. Grâce à l’API locale, vous pouvez le démarrer et l’arrêter, choisir d’où il obtient son audio, lui fournir du texte et suivre ce qu’il a compris et fait. Il a besoin que l’AI Director soit activé dans l’application et que ses modèles soient installés.

Commandes

inputSource est "device" (le périphérique d’entrée choisi dans Audio Forge, la valeur par défaut) ou "remote" (audio envoyé par votre outil via le WebSocket).

{"command": "aiDirectorStart", "inputSource": "remote", "fresh": true}

Envoi de texte

aiDirectorSendText est un appel “fire and forget” : la réponse ne confirme que le texte a été mis en file d’attente. Comme pour la parole, l’AI Director recueille ce qu’elle entend pendant quelques secondes, puis décide quoi faire, le cas échéant. Il est refusé si l’AI Director n’est pas en cours d’exécution.

{"command": "aiDirectorSendText", "text": "Heavy rain starts to fall on the old market square."}

Ceci est utile pour les outils qui ont déjà une transcription, pour les sessions textuelles et pour tester la réaction de l’AI Director à une scène.

Statut

GET /api/ai_director/status, et le message WebSocket ai_director, qui est poussé chaque fois que quelque chose change :

{"type": "ai_director", "available": true, "enabled": true, "entitled": true,
  "modelsReady": true, "state": "listening", "inputSource": "device",
  "sceneDescription": "Heavy rain over a market square", "lastTranscript": "...", "error": null}

Journal d’activité

Le message WebSocket ai_director_log contient ce que le Directeur IA a entendu et fait. Il est envoyé en entier lors de la connexion (reset: true, les 100 dernières entrées), puis uniquement les nouvelles entrées :

{"type": "ai_director_log", "reset": false,
  "entries": [{"id": 42, "at": "2026-10-27T15:20:48Z", "kind": "transcript", "text": "..."}]}

kind est transcript (ce qui a été entendu), action (ce qu’il a modifié), error ou info.

Pour une analyse plus approfondie, GET /api/ai_director/debug?since=<id> renvoie chaque entrée après id, y compris l’invite envoyée au modèle de langage et sa réponse brute. Cela est destiné au réglage, et non à l’affichage.

Envoyer votre propre audio microphone

Avec inputSource défini sur "remote", envoyez des trames WebSocket binaires contenant de l’audio brut : 16 kHz, mono, signé 16 bits little-endian PCM. Audio Forge applique sa détection de silence habituelle, vous pouvez donc diffuser en continu. Les trames sont ignorées lorsque la source est "device". Un seul client WebSocket peut fournir de l’audio à la fois ; lorsqu’il se déconnecte, le Directeur IA revient au périphérique d’entrée.

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 error décrivant ce qui s’est mal passé.

{"ok": false, "error": "category not found"}
{"ok": false, "error": "section required"}
{"ok": false, "error": "invalid json"}

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 de 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 ; elle doit être transmise 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 :

# Using the Authorization header
curl http://192.168.0.10:8329/api/state ^
  -H "Authorization: Bearer your-api-key-here"

# Using the query parameter
curl "http://192.168.0.10:8329/api/state?apiKey=your-api-key-here"

# Sending a command from another device
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 with API key
wscat -c "ws://192.168.0.10:8329/ws?apiKey=your-api-key-here"

Les requêtes localhost ne nécessitent jamais de clé, même lorsque le mode LAN est activé.

Vous pouvez régénérer la clé API à tout moment dans Paramètres → Contrôle externe → API Locale. Tous les clients précédemment connectés devront utiliser la nouvelle clé.

Comportement en arrière-plan mobile

Les systèmes d’exploitation mobiles peuvent suspendre la gestion des requêtes HTTP et WebSocket lorsque Audio Forge est en arrière-plan ou que l’appareil est verrouillé, même lorsque la lecture audio native continue. L’API Locale ne s’arrête pas délibérément, mais elle ne peut pas garantir la disponibilité en arrière-plan sur iOS ou Android.

Pour un contrôle à distance stable pendant une session, gardez Audio Forge au premier plan et gardez l’écran allumé. Cela évite de s’appuyer sur une exécution en arrière-plan gourmande en batterie que les plateformes mobiles peuvent arrêter à tout moment.