Lokale API

<- zurück zur Dokumentation  

Was die lokale API macht

Audio Forge beinhaltet einen kleinen integrierten Server, der auf Ihrem Rechner läuft. Er ermöglicht es externen Werkzeugen, wie 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 nutzen, unterstützt die lokale API genau die gleichen Befehle. Der Unterschied ist, dass sie komplett auf Ihrem Rechner läuft, ohne zusätzliche Einrichtung: Kein Broker zu installieren, kein Netzwerk zu konfigurieren.

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 aktiviert).

Sie können konfigurieren:

• Aktiviert Umschaltoption (Standard: an).
• Port Nummer (Standard: 8329).
• Auf LAN lauschen Umschaltoption (Standard: aus). Wenn aktiviert, können Geräte in Ihrem lokalen Netzwerk auf die API zugreifen. Wenn deaktiviert, kann nur Software auf demselben Rechner eine Verbindung herstellen.
• API-Schlüssel (automatisch generiert). Erforderlich, wenn Sie sich von einem anderen Gerät im Netzwerk verbinden. Sie können ihn kopieren oder aus den Einstellungen neu generieren.

Sobald aktiviert, hört Audio Forge auf http://localhost:8329. Wenn “Auf LAN lauschen” aktiviert ist, hört es stattdessen auf allen Netzwerkschnittstellen.

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\":\"Musik\",\"categoryName\":\"Kampf\"}"

Das war’s, wenn Audio Forge mit aktivierter lokaler API läuft, erhalten Sie sofort JSON-Antworten.

HTTP-Endpunkte

GET /api/state

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

{
  "libraryUuid": "...",
  "libraryName": "[Standard]",
  "musicPlaying": true,
  "ambiancePlaying": false,
  "musicVolume": 0.75,
  "ambianceVolume": 0.5,
  "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 Ambiente-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 Anfragekörper. Bei Erfolg:

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

Bei Fehler:

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

WebSocket

Für Werkzeuge, die Echtzeit-Aktualisierungen wünschen (zum Beispiel ein Stream Deck Plugin, das den aktuellen Status anzeigen muss), verbinden Sie ein WebSocket zu:

ws://localhost:8329/ws

Befehle senden

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

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

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

Updates empfangen

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

Statusaktualisierungen sind gedrosselt (250 ms), sodass Sie nicht bei schnellen Änderungen wie Lautstärkeschwenkungen überflutet werden.

Befehle

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

play

Spielt einen Abschnitt ab oder setzt ihn fort, oder wählt eine bestimmte Kategorie aus.

{"command": "play", "section": "Musik"}
{"command": "play", "section": "Musik", "categoryName": "Kampf"}
{"command": "play", "section": "Ambiente", "categoryUuid": "<uuid>"}

• Ohne Kategorie: setzt den gesamten Abschnitt fort.
• Mit Kategorie: wählt und spielt sie.
• Ambiente verwendet Umschaltlogik. Das Abspielen einer bereits aktiven Ambiente-Kategorie schaltet sie ab.

pause

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

stop

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

setActiveLibrary

Wechselt die aktive Bibliothek nach UUID oder Name.

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

setVolume

Setzt die Lautstärke für einen gesamten Abschnitt (0,0 bis 1,0) oder für eine bestimmte Kategorie innerhalb eines Abschnitts.

{"command": "setVolume", "section": "Musik", "value": 0.65}
{"command": "setVolume", "section": "Ambiente", "value": 0.5,
  "categoryName": "Regen", "transitionMs": 1000}

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

playEcho

Löst einen einmaligen Echo-Sound aus.

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

setCategoryEnabled

Aktiviert oder deaktiviert explizit eine Kategorie in einem Abschnitt.

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

restoreState

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

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

setConfig

Leitet eine Konfigurationseinstellung an die MQTT-Integration weiter (sofern 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": "Abschnitt 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 Auf LAN lauschen aktivieren, wird die API auch von anderen Geräten erreichte. In diesem Fall ist ein API-Schlüssel für alle Anfragen erforderlich, die nicht von localhost stammen. Der Schlüssel wird automatisch generiert und unter Einstellungen → Externe Steuerung → Lokale API angezeigt; übergeben Sie ihn mit jeder Anfrage, indem Sie eine der folgenden Optionen nutzen:

• Header: Authorization: Bearer <ihr-api-schlüssel>
• Abfrageparameter: ?apiKey=<ihr-api-schlüssel>

Beispiele:

# Verwendung des Authorization-Headers
curl http://192.168.0.10:8329/api/state ^
  -H "Authorization: Bearer ihr-api-schlüssel-hier"

# Verwendung des Abfrageparameters
curl "http://192.168.0.10:8329/api/state?apiKey=ihr-api-schlüssel-hier"

# Senden eines Befehls von einem anderen Gerät
curl -X POST http://192.168.0.10:8329/api/command ^
  -H "Authorization: Bearer ihr-api-schlüssel-hier" ^
  -H "Content-Type: application/json" ^
  -d "{\"command\":\"play\",\"section\":\"Musik\",\"categoryName\":\"Kampf\"}"

# WebSocket mit API-Schlüssel
wscat -c "ws://192.168.0.10:8329/ws?apiKey=ihr-api-schlüssel-hier"

Für localhost-Anfragen ist nie ein Schlüssel erforderlich, auch wenn der LAN-Modus aktiviert ist.

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