Lokale API

<- zurück zur Dokumentwurzel  

Was die lokale API tut

Audio Forge enthält einen kleinen, integrierten Server, der auf Ihrem Computer läuft. Er ermöglicht externen Tools, wie z. B. einem Elgato Stream Deck-Plugin, einem benutzerdefinierten Skript oder einer beliebigen App auf Ihrem PC, die Wiedergabe über HTTP oder WebSocket zu steuern, ohne dass zusätzliche Software erforderlich ist.

Wenn Sie bereits die MQTT-Integration verwenden, unterstützt die lokale API die gleichen Befehle. Der Unterschied besteht darin, dass sie vollständig auf Ihrem Computer ohne zusätzliche Einrichtung läuft: kein Broker muss installiert werden, kein Netzwerk muss konfiguriert werden.

Aktivieren der lokalen API

Gehen Sie zu Einstellungen → Externe Steuerung → Lokale API und stellen Sie sicher, dass die Funktion aktiviert ist (standardmäßig ist sie aktiviert).

Sie können konfigurieren:

• Aktiviert-Umschalter (Standard: aktiviert).
• Port-Nummer (Standard: 8329).
• Auf LAN hören-Umschalter (Standard: deaktiviert). Wenn aktiviert, können Geräte im lokalen Netzwerk auf die API zugreifen. Wenn deaktiviert, kann nur Software auf demselben Computer eine Verbindung herstellen.
• API-Schlüssel (automatisch generiert). Erforderlich, wenn eine Verbindung von einem anderen Gerät im Netzwerk hergestellt wird. Sie können ihn in den Einstellungen kopieren oder regenerieren.

Sobald die API aktiviert ist, lauscht Audio Forge auf http://localhost:8329. Wenn “Auf LAN hören” aktiviert ist, lauscht sie stattdessen auf allen Netzwerkschnittstellen.

Schnellstart

Öffnen Sie ein Terminal und versuchen Sie:

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

Das ist alles, wenn Audio Forge mit der lokalen API aktiviert läuft, erhalten Sie sofort JSON-Antworten.

HTTP-Endpunkte

GET /api/state

Gibt einen JSON-Schnappschuss dessen zurück, was Audio Forge im Moment tut:

{
  "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 Lautstärke-Felder verwenden die Anzeigeskala der App von 0.0 bis 1.0. Für Musik und Ambiente ist 0.5 die normale (Einheits-)Lautstärke und 1.0 die maximale, verstärkte Lautstärke. Für Echoes ist 1.0 die normale Lautstärke.

categoryVolume enthält aktuelle Laufzeitwerte und kann spärlich sein. Verwenden Sie das volume-Feld für jede Kategorie aus /api/catalog, wenn Sie einen vollständigen Wert für jede Kategorie benötigen, auch für Kategorien, die noch nicht verwendet wurden.

GET /api/catalog

Gibt jede Bibliothek mit ihren Musik- und Ambient-Kategorien zurück:

{
  "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 gibt an, ob die Kategorie in Forge sichtbar und aktiviert ist.
• trackCount ist die Anzahl der aktuell installierten, abspielbaren Tracks für diese Kategorie.
• volume ist die effektive Lautstärke der Kategorie auf der 0.0 bis 1.0-Skala. Sie ist für jede Kategorie vorhanden, auch für inaktive Kategorien.

Für eine aktive Kategorie meldet das Verzeichnis die aktuelle Laufzeitlautstärke. Für eine inaktive Kategorie wird die konfigurierte Ziellautstärke gemeldet, oder 0.5, wenn kein Ziel existiert. Laufzeit-Anpassungen ersetzen nicht die konfigurierte Ziellautstärke. Wenn eine Kategorie erneut gestartet wird, wird ein expliziter Befehlswert verwendet, falls vorhanden; andernfalls wird die konfigurierte Ziellautstärke verwendet. Die vorherige Laufzeit-Anpassung wird nicht wiederverwendet. Das Wiederherstellen eines State Links wendet die im State Link aufgezeichneten Laufzeitlautstärken an.

GET /api/echoes/active

Gibt einen Stichproben-Schnappschuss aller aktuell abgespielten One-Shot-Echo-Sounds zurück. Gleichzeitige Auslösungen werden als separate Einträge zurückgegeben, auch wenn sie dieselbe Kategorie oder die gleiche Sounddatei verwenden.

{
  "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 identifiziert diese spezifische Auslösung eindeutig. Zwei überlappende Wiedergaben derselben Kategorie erhalten unterschiedliche IDs.
• sampledAt ist der Zeitpunkt, zu dem Audio Forge den Schnappschuss erstellt hat. Positionswerte werden nicht kontinuierlich gestreamt, daher sollten Clients bei Bedarf einen neuen Schnappschuss anfordern.
• durationMs, remainingMs, progress und progressPercent sind null, wenn die Dauer des Sounds nicht verfügbar ist.
• progress verwendet eine 0.0 bis 1.0-Skala. progressPercent verwendet 0.0 bis 100.0.
• fileName enthält nur den Dateinamen, niemals einen lokalen Dateisystempfad.
• Beendete oder gestoppte Echo-Sounds werden aus der Liste entfernt.

Echoes teilen sich den globalen echoesVolume-Wert, der von /api/state zurückgegeben wird. Es gibt keine Echo-Lautstärke pro Wiedergabe oder pro Kategorie.

POST /api/command

Senden Sie einen JSON-Befehl im Anfrage-Body. Bei Erfolg:

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

Bei einem Fehler:

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

GET /api/icon/{categoryUuid}

Gibt das Bild eines Kategoriesymbols zurück. Verwenden Sie die Kategorie-UUID aus /api/catalog. Die Kategorie muss zu einer aktiven Bibliothek gehören. Der optionale Query-Parameter size legt die angeforderte Größe für Schrift- und SVG-Symbole fest und verwendet standardmäßig 144 Pixel.

• Schrift- und SVG-Symbole werden als PNG-Bilder gerendert und mit der Kategoriefarbe eingefärbt.
• Wenn eine benutzerdefinierte Datei fehlt oder ein SVG nicht gerastert werden kann, verwendet die API stattdessen das Schrift-Symbol.
• Benutzerdefinierte PNG-, JPG- und JPEG-Symbole werden unverändert zurückgegeben; size wird ignoriert.
• Erfolgreiche Antworten verwenden image/png oder image/jpeg und können eine Stunde zwischengespeichert werden.
• Wenn die Kategorie nicht gefunden wird, antwortet der Server mit 404 und {"error":"category not found"}.
• Wenn das Symbol nicht gerendert werden kann, antwortet der Server mit 500 und {"error":"failed to render icon"}.

WebSocket

Für Tools, die Echtzeit-Updates wünschen (z. B. ein Stream Deck-Plugin, das den aktuellen Status anzeigen muss), verbinden Sie einen WebSocket mit:

ws://localhost:8329/ws

Befehle senden

Senden Sie dieselben JSON-Befehlobjekte, die Sie auch an /api/command POSTen würden:

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

Der Server antwortet mit einer Ergebnis-Nachricht für jeden Befehl.

Updates empfangen

Der Server pusht automatisch Updates, sobald sich etwas ändert. Jede Nachricht hat ein type-Feld:

Zustandsupdates werden gedrosselt (250 ms), sodass Sie nicht während schneller Änderungen wie Lautstärke-Sweeps überflutet werden.

Nachrichten sind flache JSON-Objekte. Die Nutzlast ist nicht unter einem data oder payload-Feld verschachtelt. Beispiele:

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

Befehle

Alle Befehle verwenden dasselbe JSON-Schema wie die MQTT-Integration. Jeder Befehl akzeptiert eine optionale requestId-Zeichenkette, die Sie verwenden können, um Antworten abzugleichen.

play

Wiedergabe oder Fortsetzung einer Sektion oder Auswahl einer bestimmten Kategorie.

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

• Ohne Kategorie: setzt die gesamte Sektion fort.
• Mit Kategorie: wählt sie aus und spielt sie ab.
• Ambiente verwendet Toggle-Semantik. Das Abspielen einer bereits aktiven Ambient-Kategorie schaltet sie aus.

pause

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

stop

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

setActiveLibrary

Umschalten der aktiven Bibliothek nach UUID oder Name.

{"command": "setActiveLibrary", "libraryName": "My Library"}
{"command": "setActiveLibrary", "libraryUuid": "<uuid>"}

setVolume

Festlegen der Lautstärke für eine ganze Sektion oder für eine bestimmte Kategorie innerhalb einer Sektion. Verwenden Sie value von 0,0 bis 1,0 oder von 0 bis 100 mit 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}

Der optionale transitionMs steuert, wie schnell die Lautstärke auf den neuen Pegel ausgeblendet wird (Standard: 500 ms).

Musik und Ambiente verwenden dieselbe Anzeigeskala wie die App: 0.5 ist die normale (Einheits-)Lautstärke und 1.0 ist die maximale, verstärkte Lautstärke. Echoes haben keinen verstärkten Bereich, sodass 1.0 die normale Lautstärke ist. Die API konvertiert diese Anzeigewerte automatisch in den internen Wiedergabe-Gain.

nextTrack

Überspringen zum nächsten Track in einer aktiven Musik- oder Ambient-Kategorie. Die Kategorie muss bereits abgespielt werden.

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

playEcho

Auslösen eines One-Shot-Echo-Sounds.

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

Bei Erfolg wartet der Befehl, bis die Echo-Wiedergabe registriert ist, und gibt die zugehörigen Tracking- und Wiedergabefelder zurück:

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

Verwenden Sie die zurückgegebene playbackId mit stopEcho, um nur diese Wiedergabeinstanz zu stoppen. Aktuelle Werte können auch mit GET /api/echoes/active abgerufen werden.

stopEcho

Stoppen der aktiven Echo-Wiedergabe mithilfe genau eines Selektors:

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

• playbackId stoppt nur diese Wiedergabeinstanz. Holen Sie sich Wiedergabe-IDs aus GET /api/echoes/active.
• categoryUuid stoppt alle aktiven Echoes aus dieser Kategorie.
• categoryName stoppt alle aktiven Echoes, deren Kategorie genau diesen Namen hat. Wenn Kategorien in mehreren Bibliotheken denselben Namen haben, werden alle Übereinstimmungen gestoppt.
• Die Antwort enthält stoppedCount. Ein Selektor ohne aktive Übereinstimmungen ist erfolgreich mit stoppedCount: 0.
• Um alle aktiven Echoes unabhängig von der Kategorie zu stoppen, verwenden Sie {"command": "stop", "section": "Echoes"}.

setCategoryEnabled

Aktivieren oder Deaktivieren einer Kategorie in einer Sektion explizit.

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

Sie können eine Kategorie aktivieren und gleichzeitig ihre Lautstärke festlegen, indem Sie value einschließen. Wenn value weggelassen wird, wird die konfigurierte Ziellautstärke der Kategorie verwendet. Eine vorherige Laufzeit-Anpassung wird nicht wiederverwendet.

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

restoreState

Wiederherstellen eines zuvor gespeicherten Zustands aus einem Share-Link, der von der App erstellt wurde.

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

setConfig

Weiterleiten einer Konfigurationseinstellung an die MQTT-Integration (falls verbunden). Nützlich für erweiterte Automatisierung.

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

Funktionserkennung

Neuere Versionen von Audio Forge fügen Funktionen zur API hinzu. So kann ein Tool erkennen, welche Funktionen die laufende App unterstützt; der Server kündigt seine Version an. Es ist die erste WebSocket-Nachricht, und GET /api/info gibt das Gleiche zurück:

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

Ältere Versionen von Audio Forge senden keine hello-Nachricht und haben keinen /api/info: behandeln Sie dies als apiVersion 1 und rufen Sie nichts Neueres auf. Zeigen Sie KI-Director-Funktionen nur an oder rufen Sie sie auf, wenn sowohl available als auch enabled true sind.

Raumsteuerung

Wenn Sie einen Online-Raum hosten, können Sie Gästen ermöglichen, Audio Forge von der Gastseite aus zu steuern. Zwei Befehle legen fest, wer welche Berechtigungen hat (sie funktionieren nur, während ein Raum geöffnet ist):

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

permission ist entweder "listen" (nur Sie steuern Audio Forge) oder "control". Der Raumstatus in GET /api/state (room) enthält dann defaultGuestPermission und eine permission für jeden Eintrag in guests (die effektive Berechtigung: mit "control" als Standard können Sie immer noch einen einzelnen Gast auf "listen" setzen). room.chatMessages listet auch auf, was steuernde Gäste getan haben, als Einträge mit kind: "activity", command und aufgelösten params; Chat-Einträge haben kind: "chat". Gäste, die beitreten oder den Raum verlassen, erscheinen als Aktivitätseinträge mit command guestJoined, guestLeft, guestRemoved oder guestReconnected. Während Gäste die Steuerung haben, lädt Audio Forge auch die Kategorie-Symbole auf den Raumserver hoch, damit die Gastseite sie anzeigen kann. Gäste mit Steuerung dürfen nur die in features.roomControl.commands aufgeführten Befehle ausführen; die Aufnahme, das Entfernen von Gästen, die Konfiguration, der KI-Director und die Berechtigungen verbleiben bei Ihnen.

KI-Director

Der KI-Director hört auf Ihre Tischrunde und ändert die Musik und die Atmosphäre für Sie. Über die Local API können Sie ihn starten und stoppen, auswählen, woher er sein Audio bezieht, ihn mit Text füttern und verfolgen, was er verstanden und getan hat. Er benötigt, dass der KI-Director in der App aktiviert ist und seine Modelle installiert sind.

Befehle

inputSource ist entweder "device" (das in Audio Forge ausgewählte Eingabegerät, Standard) oder "remote" (Audio, das von Ihrem Tool über WebSocket gesendet wird).

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

Text senden

aiDirectorSendText ist ein “Feuer-und-vergiss”-Befehl: die Antwort bestätigt nur, dass der Text in die Warteschlange gestellt wurde. Wie bei Sprache sammelt der KI-Director einige Sekunden lang das Gehörte und entscheidet dann, ob und was geändert werden soll. Er wird abgelehnt, wenn der KI-Director nicht ausgeführt wird.

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

Dies ist nützlich für Tools, die bereits eine Transkription haben, für textbasierte Sitzungen und zum Testen, wie der KI-Director auf eine Szene reagiert.

Status

GET /api/ai_director/status und die ai_director-WebSocket-Nachricht, die jedes Mal gepusht wird, wenn sich etwas ändert:

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

Aktivitätsprotokoll

Die ai_director_log-WebSocket-Nachricht enthält, was der KI-Director gehört und getan hat. Sie wird vollständig gesendet, wenn Sie sich verbinden (reset: true, die letzten 100 Einträge), danach nur neue Einträge:

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

kind ist transcript (das gehörte), action (die vorgenommene Aktion), error oder info.

Für eine detailliertere Untersuchung gibt GET /api/ai_director/debug?since=<id> jeden Eintrag nach id zurück, einschließlich des an das Sprachmodell gesendeten Prompts und seiner rohen Antwort. Dies ist für die Feinabstimmung gedacht, nicht für die Anzeige.

Senden Ihres eigenen Mikrofon-Audios

Wenn inputSource auf "remote" gesetzt ist, senden Sie binäre WebSocket-Frames mit rohem Audio: 16 kHz, Mono, vorzeichenbehaftet, 16-Bit, Little-Endian PCM. Audio Forge wendet seine übliche Stillerkennung an, sodass Sie kontinuierlich streamen können. Frames werden ignoriert, während die Quelle auf "device" eingestellt ist. Nur ein WebSocket-Client kann gleichzeitig Audio liefern; wenn er sich trennt, wechselt der KI-Director zurück zum Eingabegerät.

Fehlerbehandlung

Wenn ein Befehl nicht ausgeführt werden kann (z. B. wenn ein Kategoriename nicht existiert oder ein erforderliches Feld fehlt), enthält die Antwort "ok": false und eine error-Nachricht, die beschreibt, was schief gelaufen ist.

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

Sicherheit

Standardmäßig bindet sich die lokale API an 127.0.0.1 (nur localhost) und ist nicht von anderen Geräten in Ihrem Netzwerk aus erreichbar.

Wenn Sie Auf LAN hören aktivieren, wird die API von anderen Geräten aus erreichbar. In diesem Fall ist ein API-Schlüssel für alle Anfragen von Nicht-localhost-Geräten erforderlich. Der Schlüssel wird automatisch generiert und in Einstellungen → Externe Steuerung → Lokale API angezeigt; übergeben Sie ihn mit jeder Anfrage mithilfe von:

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

Beispiele:

# 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-Anfragen benötigen keinen Schlüssel, auch wenn LAN-Modus aktiviert ist.

Sie können den API-Schlüssel jederzeit in Einstellungen → Externe Steuerung → Lokale API regenerieren. Alle zuvor verbundenen Clients benötigen den neuen Schlüssel.

Verhalten im Hintergrund auf Mobilgeräten

Mobile Betriebssysteme können die Verarbeitung von HTTP- und WebSocket-Anfragen anhalten, wenn Audio Forge im Hintergrund ausgeführt wird oder das Gerät gesperrt ist, auch wenn die native Audio-Wiedergabe fortgesetzt wird. Die lokale API stoppt sich nicht absichtlich, kann aber die Verfügbarkeit im Hintergrund auf iOS oder Android nicht garantieren.

Für eine stabile Fernsteuerung während einer Sitzung halten Sie Audio Forge im Vordergrund und halten Sie den Bildschirm aktiv. Dadurch wird vermieden, dass Sie sich auf eine batterieintensive Hintergrundausführung verlassen, die mobile Plattformen jederzeit stoppen können.