Lokale API

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

Methode	Pfad	Beschreibung
GET	`/api/state`	Aktueller Wiedergabezustand
GET	`/api/catalog`	Vollständiges Bibliotheks- und Kategorieverzeichnis
GET	`/api/echoes/active`	Aktuell abgespielte One-Shot-Echo-Sounds
POST	`/api/command`	Befehl ausführen (JSON-Body)

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

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:

Typ	Wann er gesendet wird	Was er enthält
`state`	Beim Verbinden + jedes Mal, wenn sich die Wiedergabe ändert	Dasselbe wie `GET /api/state`
`catalog`	Beim Verbinden + wenn sich Bibliotheken ändern	Dasselbe wie `GET /api/catalog`
`result`	Nach jedem gesendeten Befehl	`ok`, `message` oder `error`, `requestId`
`echo`	Wenn ein Echo-Sound ausgelöst wird	`uuid`, `name`, `at`

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

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.