Lokale API

<- zurück zum Dokumentenstamm  

Was die lokale API macht

Audio Forge enthält einen kleinen integrierten Server, der auf Ihrem Gerät läuft. Er ermöglicht es externen Tools, wie einem Elgato Stream Deck Plugin, einem benutzerdefinierten Skript oder jeder 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 genau die gleichen Befehle. Der Unterschied besteht darin, dass sie komplett auf Ihrem Gerät läuft, ohne jegliche Einrichtung: Kein Broker muss installiert werden, kein Netzwerk muss konfiguriert werden.

Aktivierung der lokalen API

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

Sie können Folgendes konfigurieren:

• Aktiviert-Umschalter (Standard: ein).
• Portnummer (Standard: 8329).
• Im LAN hören-Umschalter (Standard: aus). Wenn aktiviert, können Geräte in Ihrem lokalen Netzwerk auf die API zugreifen. Wenn deaktiviert, können nur Programme auf dem gleichen Gerät eine Verbindung herstellen.
• API-Schlüssel (automatisch generiert). Notwendig bei Verbindungen von einem anderen Gerät im Netzwerk. Sie können ihn kopieren oder in den Einstellungen neu generieren.

Sobald aktiviert, hört Audio Forge auf http://localhost:8329. Wenn “Im LAN hören” eingeschaltet ist, wird auf allen Netzwerkschnittstellen gehört.

Schnellstart

Öffnen Sie ein Terminal und versuchen Sie:

# Sehen Sie, was gerade abgespielt wird
curl http://localhost:8329/api/state

# Alle Bibliotheken und Kategorien auflisten
curl http://localhost:8329/api/catalog

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

Das war’s, wenn Audio Forge läuft und die lokale API aktiviert ist, erhalten Sie sofortiges JSON-Antworten.

HTTP Endpunkte

GET /api/state

Gibt einen JSON-Snapshot dessen zurück, was Audio Forge gerade tut:

{
  "libraryUuid": "...",
  "libraryName": "[Standard]",
  "musicPlaying": true,
  "ambiancePlaying": false,
  "musicVolume": 0.75,
  "ambianceVolume": 0.5,
  "echoesVolume": 1.0,
  "musicCategories": [{"uuid": "...", "name": "Kampf"}],
  "ambianceCategories": [{"uuid": "...", "name": "Regen"}],
  "lastEcho": {"uuid": "...", "name": "Donner", "at": "2025-06-01T12:34:56Z"},
  "categoryVolume": {"<uuid>": 0.8}
}

GET /api/catalog

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

{
  "activeLibraryUuid": "...",
  "libraries": [
    {
      "uuid": "...",
      "name": "[Standard]",
      "music": [{"uuid": "...", "name": "Kampf"}],
      "ambiance": [{"uuid": "...", "name": "Regen"}]
    }
  ]
}

POST /api/command

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

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

Bei Fehler:

{"ok": false, "error": "Kategorie nicht gefunden"}

WebSocket

Für Tools, die Echtzeit-Updates benötigen (wie ein Stream Deck Plugin, das den aktuellen Status anzeigen muss), verbinden Sie einen WebSocket zu:

ws://localhost:8329/ws

Befehle senden

Senden Sie die gleichen JSON-Befehlsobjekte, die Sie an /api/command senden würden:

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

Der Server antwortet mit einer Ergebnisnachricht für jeden Befehl.

Updates empfangen

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

Zustandsaktualisierungen sind entdoppelt (250 ms), sodass Sie nicht während schneller Änderungen wie Lautstärkeschwankungen überflutet werden.

Befehle

Alle Befehle verwenden das gleiche JSON-Schema wie die MQTT-Integration. Jeder Befehl akzeptiert einen optionalen requestId-String, den Sie verwenden können, um Antworten abzugleichen.

play

Eine Sektion abspielen oder fortsetzen oder eine bestimmte Kategorie auswählen.

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

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

pause

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

stop

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

setActiveLibrary

Wechseln Sie die aktive Bibliothek anhand der UUID oder des Namens.

{"command": "setActiveLibrary", "libraryName": "Meine Bibliothek"}
{"command": "setActiveLibrary", "libraryUuid": "<uuid>"}

setVolume

Legen Sie die Lautstärke für eine gesamte Sektion oder eine bestimmte Kategorie innerhalb einer Sektion fest. 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": "Regen", "transitionMs": 1000}

Das optionale transitionMs steuert, wie schnell die Lautstärke auf das neue Niveau ausblendet (Standard: 500 ms).

playEcho

Löst einen einmaligen Echo-Sound aus.

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

setCategoryEnabled

Aktivieren oder deaktivieren Sie eine Kategorie in einer Sektion explizit.

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

restoreState

Stellt einen zuvor gespeicherten Zustand aus einem vom App erstellten Freigabelink wieder her.

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

setConfig

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

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

Fehlerbehandlung

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

{"ok": false, "error": "Kategorie nicht gefunden"}
{"ok": false, "error": "Sektion erforderlich"}
{"ok": false, "error": "ungültiges JSON"}

Sicherheit

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

Wenn Sie Im LAN hören aktivieren, wird die API von anderen Geräten aus erreichbar. In diesem Fall ist für alle nicht-lokalen Anfragen ein API-Schlüssel erforderlich. Der Schlüssel wird automatisch generiert und in Einstellungen → Externe Steuerung → Lokale API angezeigt; geben Sie ihn mit jeder Anfrage mit einer der folgenden Methoden an:

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

Beispiele:

# Verwendung des Authorization Headers
curl http://192.168.0.10:8329/api/state ^
  -H "Authorization: Bearer your-api-key-here"

# Verwendung des Query-Parameters
curl "http://192.168.0.10:8329/api/state?apiKey=your-api-key-here"

# Senden eines Befehls von einem anderen Gerät
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\":\"Kampf\"}"

# WebSocket mit API-Schlüssel
wscat -c "ws://192.168.0.10:8329/ws?apiKey=your-api-key-here"

Lokale Anfragen erfordern niemals einen Schlüssel, auch wenn der LAN-Modus eingeschaltet ist.

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