API Locale

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

Méthode	Chemin	Description
GET	`/api/state`	État de lecture actuel
GET	`/api/catalog`	Catalogue complet de la bibliothèque et des catégories
GET	`/api/echoes/active`	Sons d’écho d’un seul coup actuellement en cours de lecture
POST	`/api/command`	Exécuter une commande (corps JSON)

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"}

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 :

type	Quand il est envoyé	Ce qu’il contient
`state`	Lors de la connexion + chaque fois que la lecture change	Identique à `GET /api/state`
`catalog`	Lors de la connexion + lorsque les bibliothèques changent	Identique à `GET /api/catalog`
`result`	Après chaque commande que vous envoyez	`ok`, `message` ou `error`, `requestId`
`echo`	Lorsqu’un son d’écho est déclenché	`uuid`, `name`, `at`

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"}

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.