Lokale API

<- terug naar documentatie root  

Wat de Lokale API doet

Audio Forge bevat een kleine ingebouwde server die op je machine draait. Hiermee kunnen externe tools, zoals een Elgato Stream Deck plug-in, een aangepast script, of een app op je pc, afspelen via HTTP of WebSocket regelen, zonder extra software.

Als je al de MQTT integratie gebruikt, ondersteunt de Lokale API dezelfde opdrachten. Het verschil is dat het volledig op je machine draait zonder installatie: geen broker nodig, geen netwerkconfiguratie.

De Lokale API inschakelen

Ga naar Instellingen → Externe Controle → Lokale API en zorg ervoor dat de functie is ingeschakeld (standaard aan).

Je kunt configureren:

• Ingeschakeld toggle (standaard: aan).
• Poort nummer (standaard: 8329).
• Luisteren op LAN toggle (standaard: uit). Wanneer ingeschakeld, kunnen apparaten op je lokale netwerk toegang krijgen tot de API. Wanneer uit, kan alleen software op dezelfde machine verbinding maken.
• API Sleutel (automatisch gegenereerd). Vereist bij verbinding vanaf een ander apparaat op het netwerk. Je kunt het kopiëren of opnieuw genereren vanuit Instellingen.

Zodra ingeschakeld, luistert Audio Forge op http://localhost:8329. Als “Luisteren op LAN” is ingeschakeld, luistert het in plaats daarvan op alle netwerkinterfaces.

Snel starten

Open een terminal en probeer:

# Zie wat er nu wordt afgespeeld
curl http://localhost:8329/api/state

# Lijst van alle bibliotheken en categorieën
curl http://localhost:8329/api/catalog

# Speel een categorie af
curl -X POST http://localhost:8329/api/command ^
  -H "Content-Type: application/json" ^
  -d "{\"command\":\"play\",\"section\":\"Music\",\"categoryName\":\"Battle\"}"

Dat is alles, als Audio Forge draait met de ingeschakelde Lokale API, krijg je onmiddellijk JSON-antwoorden.

HTTP eindpunten

GET /api/state

Geeft een JSON-snapshot van wat Audio Forge nu doet:

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

Geeft alle bibliotheken met hun Muziek- en Sfeer-categorieën terug:

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

POST /api/command

Stuur een JSON-opdracht in de request body. Bij succes:

{"ok": true, "message": "afspelen geslaagd"}

Bij fout:

{"ok": false, "error": "categorie niet gevonden"}

WebSocket

Voor tools die real-time updates willen (zoals een Stream Deck plug-in die de huidige status moet tonen), verbind een WebSocket met:

ws://localhost:8329/ws

Commando’s verzenden

Stuur dezelfde JSON-opdrachtobjecten die je zou POSTEN naar /api/command:

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

De server antwoordt met een resultaatbericht voor elke opdracht.

Updates ontvangen

De server pusht automatisch updates wanneer er iets verandert. Elk bericht heeft een type veld:

Statusupdates worden gedebounced (250 ms) zodat je niet overspoeld wordt tijdens snelle veranderingen zoals volumewisselingen.

Commando’s

Alle commando’s gebruiken hetzelfde JSON-schema als de MQTT integratie. Elke opdracht accepteert een optionele requestId string die je kunt gebruiken om reacties te matchen.

play

Speel een sectie af of hervat deze, of selecteer een specifieke categorie.

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

• Zonder categorie: hervat de hele sectie.
• Met categorie: selecteert en speelt het af.
• Sfeer gebruikt schakelgedrag. Een al actieve Sfeer-categorie afspelen schakelt deze uit.

pause

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

stop

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

setActiveLibrary

Schakel de actieve bibliotheek over middels UUID of naam.

{"command": "setActiveLibrary", "libraryName": "Mijn Bibliotheek"}
{"command": "setActiveLibrary", "libraryUuid": "<uuid>"}

setVolume

Stel het volume in voor een hele sectie (0.0 tot 1.0), of voor een specifieke categorie binnen een sectie.

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

De optionele transitionMs bepaalt hoe snel het volume naar het nieuwe niveau overgaat (standaard: 500 ms).

playEcho

Activeer een eenmalig Echo-geluid.

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

setCategoryEnabled

Schakel een categorie in een sectie expliciet in of uit.

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

restoreState

Herstel een eerder opgeslagen status vanuit een deelbare koppeling die door de app is gemaakt.

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

setConfig

Stuur een configuratie-instelling door naar de MQTT-integratie (indien aangesloten). Handig voor geavanceerde automatisering.

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

Foutafhandeling

Als een opdracht niet kan worden uitgevoerd (bijvoorbeeld, een categorienaam bestaat niet of een vereist veld ontbreekt), zal de reactie "ok": false bevatten en een error bericht met een beschrijving van wat er fout ging.

{"ok": false, "error": "categorie niet gevonden"}
{"ok": false, "error": "sectie vereist"}
{"ok": false, "error": "ongeldige json"}

Beveiliging

Standaard bindt de Lokale API aan 127.0.0.1 (alleen localhost) en is niet bereikbaar vanaf andere apparaten op je netwerk.

Als je Luisteren op LAN inschakelt, wordt de API bereikbaar vanaf andere apparaten. In dat geval is een API sleutel vereist voor alle niet-localhost verzoeken. De sleutel wordt automatisch gegenereerd en weergegeven in Instellingen → Externe Controle → Lokale API; geef deze mee met elk verzoek door een van de volgende te gebruiken:

• Header: Authorization: Bearer <jouw-api-sleutel>
• Query parameter: ?apiKey=<jouw-api-sleutel>

Voorbeelden:

# Met behulp van de Authorization header
curl http://192.168.0.10:8329/api/state ^
  -H "Authorization: Bearer jouw-api-sleutel-hier"

# Met behulp van de query parameter
curl "http://192.168.0.10:8329/api/state?apiKey=jouw-api-sleutel-hier"

# Een opdracht verzenden vanaf een ander apparaat
curl -X POST http://192.168.0.10:8329/api/command ^
  -H "Authorization: Bearer jouw-api-sleutel-hier" ^
  -H "Content-Type: application/json" ^
  -d "{\"command\":\"play\",\"section\":\"Music\",\"categoryName\":\"Battle\"}"

# WebSocket met API sleutel
wscat -c "ws://192.168.0.10:8329/ws?apiKey=jouw-api-sleutel-hier"

Lokaal uitgevoerde verzoeken vereisen nooit een sleutel, zelfs niet wanneer LAN-modus is ingeschakeld.

Je kunt de API-sleutel op elk moment opnieuw genereren vanuit Instellingen → Externe Controle → Lokale API. Eerder verbonden clients hebben de nieuwe sleutel nodig.