Lokale API

Wat de Lokale API doet

Audio Forge bevat een kleine, ingebouwde server die op uw machine draait. Het stelt externe tools, zoals een Elgato Stream Deck-plugin, een aangepast script of elke app op uw pc, in staat om afspelen te besturen via HTTP of WebSocket, zonder dat er extra software nodig is.

Als u al de MQTT-integratie gebruikt, ondersteunt de Lokale API dezelfde commando’s. Het verschil is dat deze volledig op uw machine draait zonder enige setup: geen broker om te installeren, geen netwerk om te configureren.

De Lokale API inschakelen

Ga naar Instellingen → Externe besturing → Lokale API en zorg ervoor dat de functie is ingeschakeld (standaard is dit het geval).

U kunt configureren:

Ingeschakeld schakelaar (standaard: aan).
Poort nummer (standaard: 8329).
Luisteren op LAN schakelaar (standaard: uit). Wanneer aan, kunnen apparaten op uw 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. U kunt deze kopiëren of regenereren vanuit Instellingen.

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

Snel aan de slag

Open een terminal en probeer:

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

Dat is alles, als Audio Forge draait met de Lokale API ingeschakeld, ontvangt u direct JSON-reacties.

HTTP-eindpunten

Methode	Pad	Beschrijving
GET	`/api/state`	Huidige afspeelstatus
GET	`/api/catalog`	Volledige bibliotheek- en categorielijst
GET	`/api/echoes/active`	Momenteel afspelende one-shot Echo-geluiden
POST	`/api/command`	Voer een commando uit (JSON-body)

GET /api/state

Retourneert een JSON-snapshot van wat Audio Forge op dit moment doet:

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

Alle volumevelden gebruiken de weergaveschaal van de app, van 0.0 tot 1.0. Voor Muziek en Ambiance is 0.5 het normale (eenheids) volume en 1.0 het maximale, versterkte volume. Voor Echo’s is 1.0 het normale volume.

categoryVolume bevat huidige runtime-waarden en kan spaarzaam zijn. Gebruik het volume-veld van /api/catalog wanneer u een volledige waarde voor elke categorie nodig heeft, inclusief categorieën die nog niet zijn gebruikt.

GET /api/catalog

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

{
  "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 geeft aan of de categorie zichtbaar en ingeschakeld is in de Forge.
trackCount is het aantal speelbare tracks dat momenteel voor die categorie is geïnstalleerd.
volume is het effectieve volume van de categorie op de 0.0 tot 1.0 schaal. Het is aanwezig voor elke categorie, inclusief inactieve categorieën.

Voor een actieve categorie rapporteert de catalogus het huidige runtime-volume. Voor een inactieve categorie rapporteert deze het geconfigureerde doelvvolume, of 0.5 wanneer er geen doelvvolume bestaat. Runtime-aanpassingen vervangen het geconfigureerde doelvvolume niet. Wanneer een categorie opnieuw start, wordt een expliciete commando-waarde gebruikt indien aanwezig; anders wordt het geconfigureerde doelvvolume gebruikt. De vorige runtime-aanpassing wordt niet hergebruikt. Het herstellen van een State Link past de runtime-volumes toe die in die link zijn vastgelegd.

GET /api/echoes/active

Retourneert een bemonsterde snapshot van elk one-shot Echo-geluid dat momenteel wordt afgespeeld. Gelijktijdige triggers worden gerapporteerd als afzonderlijke items, zelfs als ze dezelfde categorie of geluidsbestand gebruiken.

{
  "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 identificeert deze specifieke trigger uniek. Twee overlappende afspelingen van dezelfde categorie ontvangen verschillende ID’s.
sampledAt is wanneer Audio Forge de snapshot heeft gegenereerd. Positiewaarden worden niet continu gestreamd, dus clients moeten een nieuwe snapshot aanvragen wanneer ze de huidige voortgang nodig hebben.
durationMs, remainingMs, progress, en progressPercent zijn null wanneer de duur van het geluid onbekend is.
progress gebruikt een 0.0 tot 1.0 schaal. progressPercent gebruikt 0.0 tot 100.0.
fileName bevat alleen de bestandsnaam, nooit een lokaal bestandspad.
Echo-geluiden die zijn voltooid of gestopt, worden verwijderd uit de lijst.

Echo’s delen de globale echoesVolume-waarde die wordt geretourneerd door /api/state. Er is geen Echo-volume per afspeeling of per categorie.

POST /api/command

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

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

Bij een fout:

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

WebSocket

Voor tools die real-time updates willen (zoals een Stream Deck-plugin die de huidige status moet weergeven), maak dan een WebSocket verbinding met:

ws://localhost:8329/ws

Commando’s verzenden

Stuur dezelfde JSON-commando-objecten die u zou POSTEN naar /api/command:

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

De server reageert met een resultaatbericht voor elk commando.

Updates ontvangen

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

type	Wanneer het wordt verzonden	Wat het bevat
`state`	Bij verbinding + telkens wanneer de afspeeling verandert	Dezelfde als `GET /api/state`
`catalog`	Bij verbinding + wanneer bibliotheken veranderen	Dezelfde als `GET /api/catalog`
`result`	Na elk commando dat u verzendt	`ok`, `message` of `error`, `requestId`
`echo`	Wanneer een Echo-geluid wordt geactiveerd	`uuid`, `name`, `at`

Statusupdates worden gedebounced (250 ms) zodat u niet overspoeld wordt tijdens snelle veranderingen, zoals volumebewegingen.

Berichten zijn platte JSON-objecten. De payload staat niet onder een data of payload-veld. Voorbeelden:

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

Commando’s

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

play

Start of hervat een sectie, of selecteer een specifieke categorie.

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

Zonder een categorie: hervat de hele sectie.
Met een categorie: selecteert en speelt deze af.
Ambiance gebruikt toggle-semantiek. Het afspelen van een reeds actieve Ambiance-categorie zet deze uit.

pause

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

stop

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

setActiveLibrary

Schakel de actieve bibliotheek in via UUID of naam.

{"command": "setActiveLibrary", "libraryName": "My Library"}
{"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).

Muziek en Ambiance gebruiken dezelfde weergaveschaal als de app: 0.5 is het normale (eenheids) volume en 1.0 is het maximale, versterkte volume. Echo’s hebben geen versterkt bereik, dus 1.0 is het normale volume. De API zet deze weergadewaarden automatisch om naar de interne afspeelversterking.

nextTrack

Sla over naar het volgende nummer in een actieve Muziek- of Ambiance-categorie. De categorie moet al worden afgespeeld.

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

playEcho

Activeer een one-shot Echo-geluid.

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

Bij een geslaagde opdracht wordt gewacht tot de Echo-weergave is geregistreerd. Daarna worden de bijbehorende tracking- en afspeelvelden teruggestuurd:

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

Gebruik de geretourneerde playbackId met stopEcho om alleen deze afspeelinstantie te stoppen. Je kunt de actuele waarden ook vernieuwen met GET /api/echoes/active.

stopEcho

Stop actieve Echo-afspeling met precies één selector:

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

playbackId stopt alleen die afspeelinstantie. Verkrijg afspeel-ID’s van GET /api/echoes/active.
categoryUuid stopt elk actief Echo uit die categorie.
categoryName stopt elk actief Echo waarvan de categorie die exacte naam heeft. Als categorieën in meerdere bibliotheken dezelfde naam delen, worden alle overeenkomsten gestopt.
De reactie bevat stoppedCount. Een selector met geen actieve overeenkomsten slaagt met stoppedCount: 0.
Om elk actief Echo ongeacht de categorie te stoppen, gebruik dan {"command": "stop", "section": "Echoes"}.

setCategoryEnabled

Schakel expliciet een categorie in een sectie in of uit.

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

U kunt een categorie inschakelen en tegelijkertijd het volume instellen door value op te nemen. Als value wordt weggelaten, wordt het geconfigureerde doelvvolume van de categorie gebruikt. Een vorige runtime-aanpassing wordt niet hergebruikt.

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

restoreState

Herstel een eerder opgeslagen status van een deel link 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 bestaat een categorienaam niet of ontbreekt een vereiste waarde), bevat de reactie "ok": false en een error-bericht dat beschrijft wat er fout is gegaan.

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

Beveiliging

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

Als u Luisteren op LAN inschakelt, wordt de API toegankelijk 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 besturing → Lokale API; geef deze mee bij elk verzoek met een van de volgende:

Header: Authorization: Bearer <your-api-key>
Queryparameter: ?apiKey=<your-api-key>

Voorbeelden:

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

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

U kunt de API-sleutel op elk moment regenereren in Instellingen → Externe besturing → Lokale API. Alle eerder verbonden clients hebben de nieuwe sleutel nodig.

Gedrag in de mobiele achtergrond

Mobiele besturingssystemen kunnen inkomende HTTP- en WebSocket-afhandeling opschorten wanneer Audio Forge op de achtergrond draait of het apparaat vergrendeld is, zelfs wanneer native audio- afspeling doorgaat. De Lokale API stopt zichzelf niet opzettelijk, maar kan de beschikbaarheid op de achtergrond op iOS of Android niet garanderen.

Voor stabiele externe besturing tijdens een sessie, houd Audio Forge dan in de voorgrond en houd het scherm actief. Dit voorkomt dat u vertrouwt op batterijintensieve achtergronduitvoering die mobiele platforms op elk moment kunnen stoppen.