Lokale API

<- terug naar de documentroot  

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

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

GET /api/icon/{categoryUuid}

Retourneert de afbeelding van een categoriepictogram. Gebruik de categorie-UUID uit /api/catalog. De categorie moet tot een actieve bibliotheek behoren. Met de optionele queryparameter size stel je de gewenste grootte in voor lettertype- en SVG-pictogrammen; de standaardwaarde is 144 pixels.

• Lettertype- en SVG-pictogrammen worden als PNG-afbeeldingen gerenderd en krijgen de categoriekleur.
• Als een aangepast bestand ontbreekt of een SVG niet kan worden gerasteriseerd, gebruikt de API het lettertypepictogram als fallback.
• Aangepaste PNG-, JPG- en JPEG-pictogrammen worden ongewijzigd geretourneerd; size wordt genegeerd.
• Succesvolle antwoorden gebruiken image/png of image/jpeg en kunnen één uur worden gecachet.
• Als de categorie niet wordt gevonden, is het antwoord 404 met {"error":"category not found"}.
• Als het pictogram niet kan worden gerenderd, is het antwoord 500 met {"error":"failed to render icon"}.

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:

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

Functies detecteren

Nieuwere versies van Audio Forge voegen functies toe aan de API. Zo kan een tool bepalen welke functies de actieve app ondersteunt; de server kondigt zijn versie aan. Dit is het eerste WebSocket-bericht, en GET /api/info retourneert hetzelfde:

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

Oudere versies van Audio Forge sturen geen hello-bericht en hebben geen /api/info: behandel dit dan als apiVersion 1 en roep niets nieuws aan. Toon of roep AI Director-functies alleen aan als zowel available als enabled true zijn.

Kamerbesturing

Wanneer u een online kamer host, kunt u gasten toestaan om Audio Forge te besturen vanaf de gastenpagina. Twee commando’s bepalen wie wat mag (ze werken alleen terwijl een kamer open is):

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

permission is "listen" (alleen u bestuurt Audio Forge) of "control". De kamerstatus in GET /api/state (room) bevat dan defaultGuestPermission en een permission voor elke vermelding van guests (de effectieve waarde: met "control" als standaard kunt u nog steeds een enkele gast op "listen" zetten). room.chatMessages vermeldt ook wat de besturende gasten hebben gedaan, als vermeldingen met kind: "activity", command en opgeloste params; chatberichten hebben kind: "chat". Gasten die zich aanmelden of verlaten, verschijnen als activiteitvermeldingen met command guestJoined, guestLeft, guestRemoved of guestReconnected. Terwijl gasten de controle hebben, uploadt Audio Forge ook de categorie-iconen naar de kamerserver, zodat de gastenpagina ze kan weergeven. Gasten met controle kunnen alleen de commando’s uitvoeren die vermeld staan in features.roomControl.commands; het vastleggen, verwijderen van gasten, configuratie, de AI Director en permissies blijven bij u.

AI Director

De AI Director luistert naar uw tafel en past de muziek en sfeer voor u aan. Via de Local API kunt u deze starten en stoppen, kiezen waar deze zijn audio vandaan haalt, deze tekst voeren en volgen wat deze heeft begrepen en gedaan. Het heeft de AI Director nodig die is ingeschakeld in de app en waarvan de modellen zijn geïnstalleerd.

Commando’s

inputSource is "device" (het invoerapparaat gekozen in Audio Forge, de standaard) of "remote" (audio verzonden door uw tool via de WebSocket).

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

Tekst verzenden

aiDirectorSendText is fire and forget: het antwoord bevestigt alleen dat de tekst in de wachtrij is geplaatst. Net als bij spraak verzamelt de AI Director wat hij hoort gedurende een paar seconden en beslist dan wat, indien iets, er veranderd moet worden. Het wordt geweigerd tenzij de AI Director draait.

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

Dit is handig voor tools die al een transcript hebben, voor tekstgebaseerde sessies en om te testen hoe de AI Director reageert op een scène.

Status

GET /api/ai_director/status, en het ai_director WebSocket bericht, dat wordt gepusht telkens wanneer er iets verandert:

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

Activiteitenlogboek

Het ai_director_log WebSocket-bericht bevat wat de AI Director heeft gehoord en gedaan. Het wordt volledig verzonden wanneer u verbinding maakt (reset: true, de laatste 100 vermeldingen), en vervolgens alleen nieuwe vermeldingen:

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

kind is transcript (wat er is gehoord), action (wat het heeft veranderd), error of info.

Voor een diepere blik, retourneert GET /api/ai_director/debug?since=<id> elke vermelding na id, inclusief de prompt die naar het taalmodel is verzonden en het ruwe antwoord. Het is bedoeld voor afstemming, niet voor weergave.

Uw eigen microfoonaudio verzenden

Met inputSource ingesteld op "remote", verzend dan binaire WebSocket-frames van ruwe audio: 16 kHz, mono, signed 16-bit little-endian PCM. Audio Forge past zijn gebruikelijke stilte detectie toe, zodat u continu kunt streamen. Frames worden genegeerd terwijl de bron "device" is. Slechts één WebSocket-client kan tegelijkertijd audio leveren; wanneer deze ontkoppelt, gaat de AI Director terug naar het invoerapparaat.

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.