Lokale API

<- terug naar document root  

Wat de Lokale API doet

Audio Forge bevat een kleine ingebouwde server die op jouw machine draait. Hiermee kunnen externe tools, zoals een Elgato Stream Deck plugin, een aangepast script of een willekeurige app op je PC, de weergave beheren via HTTP of WebSocket, zonder extra software.

Als je al de MQTT-integratie gebruikt, ondersteunt de Lokale API dezelfde commando’s. Het verschil is dat deze volledig op je machine draait zonder extra configuratie: geen broker om te installeren, geen netwerkconfiguratie nodig.

De Lokale API inschakelen

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

Je kunt configureren:

• Ingeschakeld schakelaar (standaard: aan).
• Poort nummer (standaard: 8329).
• Luisteren op LAN schakelaar (standaard: uit). Wanneer ingeschakeld, kunnen apparaten op je lokale netwerk de API bereiken. Wanneer uit, kan alleen software op dezelfde machine verbinden.
• API-sleutel (automatisch gegenereerd). Vereist bij verbinding vanaf een ander apparaat in het netwerk. Je kunt deze kopiëren of opnieuw genereren via Instellingen.

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

Snel starten

Open een terminal en probeer:

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

# Lijst 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 Lokale API ingeschakeld, krijg je onmiddellijk JSON-antwoorden.

HTTP-eindpunten

GET /api/state

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

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

Geeft elke bibliotheek terug met zijn Muziek- en Ambiance-categorieën:

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

POST /api/command

Stuur een JSON-opdracht in de aanvraagbody. Bij succes:

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

Bij fout:

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

WebSocket

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

ws://localhost:8329/ws

Commando’s verzenden

Stuur dezelfde JSON-opdrachten als je zou POSTen naar /api/command:

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

De server reageert met een resultaatbericht voor elke opdracht.

Updates ontvangen

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

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

Commando’s

Alle commando’s gebruiken hetzelfde JSON-schema als de MQTT-integratie. Elk commando 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 deze af.
• Ambiance gebruikt togglesemantiek. Het afspelen van een al actieve Ambiance-categorie schakelt deze uit.

pause

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

stop

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

setActiveLibrary

Schakel de actieve bibliotheek om via UUID of naam.

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

setVolume

Stel het volume in voor een hele sectie of voor een specifieke categorie binnen een sectie. Gebruik value van 0.0 tot 1.0, of van 0 tot 100 met 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}

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

playEcho

Activeer een eenmalig Echo-geluid.

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

setCategoryEnabled

Een categorie in een sectie expliciet inschakelen of uitschakelen.

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

restoreState

Herstel een eerder opgeslagen status van een deellink die door de app is gemaakt.

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

setConfig

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

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

Foutafhandeling

Als een commando niet kan worden uitgevoerd (bijvoorbeeld, een categorienaam bestaat niet of een vereist veld ontbreekt), bevat de reactie "ok": false en een error bericht dat beschrijft wat er is misgegaan.

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

Beveiliging

Standaard bindt de Lokale API zich 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 via een van deze opties:

• Header: Authorization: Bearer <your-api-key>
• Query parameter: ?apiKey=<your-api-key>

Voorbeelden:

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

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

# Verzenden van een commando vanaf een ander apparaat
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 met API-sleutel
wscat -c "ws://192.168.0.10:8329/ws?apiKey=your-api-key-here"

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

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