API Locale

<- torna alla radice della documentazione  

Cosa fa l’API Locale

Audio Forge include un piccolo server integrato che gira sulla tua macchina. Permette a strumenti esterni, come un plugin Elgato Stream Deck, uno script personalizzato o qualsiasi app sul tuo PC, di controllare la riproduzione tramite HTTP o WebSocket, senza necessità di software aggiuntivo.

Se già usi l’integrazione MQTT, l’API Locale supporta gli stessi comandi esatti. La differenza è che funziona interamente sulla tua macchina senza configurazioni: nessun broker da installare, nessuna rete da configurare.

Abilitare l’API Locale

Vai su Impostazioni → Controllo Esterno → API Locale e assicurati che la funzionalità sia abilitata (è attiva per default).

Puoi configurare:

• Attivare/disattivare il toggle Abilitato (predefinito: acceso).
• Numero di Porta (predefinito: 8329).
• Ascolto su LAN toggle (predefinito: spento). Quando attivo, i dispositivi sulla tua rete locale possono raggiungere l’API. Quando disattivo, solo il software sulla stessa macchina può connettersi.
• Chiave API (generata automaticamente). Necessaria quando ci si connette da un altro dispositivo sulla rete. Puoi copiarla o rigenerarla dalle Impostazioni.

Una volta abilitata, Audio Forge ascolta su http://localhost:8329. Se “Ascolto su LAN” è acceso, ascolta su tutte le interfacce di rete.

Avvio rapido

Apri un terminale e prova:

# Vedi cosa sta riproducendo al momento
curl http://localhost:8329/api/state

# Elenco di tutte le librerie e categorie
curl http://localhost:8329/api/catalog

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

Tutto qui, se Audio Forge è in esecuzione con l’API Locale abilitata, riceverai risposte JSON immediatamente.

Endpoint HTTP

GET /api/state

Restituisce un’istantanea JSON di ciò che Audio Forge sta facendo in questo momento:

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

GET /api/catalog

Restituisce ogni libreria con le sue categorie di Musica e Ambiente:

{
  "activeLibraryUuid": "...",
  "libraries": [
    {
      "uuid": "...",
      "name": "[Default]",
      "music": [{"uuid": "...", "name": "Battle"}],
      "ambiance": [{"uuid": "...", "name": "Rain"}]
    }
  ]
}

POST /api/command

Invia un comando JSON nel corpo della richiesta. In caso di successo:

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

In caso di errore:

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

WebSocket

Per strumenti che vogliono aggiornamenti in tempo reale (come un plugin Stream Deck che deve mostrare lo stato attuale), collega un WebSocket a:

ws://localhost:8329/ws

Invio di comandi

Invia gli stessi oggetti comando JSON che posteresti a /api/command:

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

Il server risponde con un messaggio di risultato per ogni comando.

Ricezione di aggiornamenti

Il server invia automaticamente aggiornamenti ogni volta che qualcosa cambia. Ogni messaggio ha un campo type:

Gli aggiornamenti di stato sono attutiti (250 ms) così non sarai sopraffatto durante cambi rapidi come gli sweep di volume.

Comandi

Tutti i comandi usano lo stesso schema JSON dell’integrazione MQTT. Ogni comando accetta una stringa requestId opzionale che puoi usare per abbinare le risposte.

play

Riproduci o riprendi una sezione, o seleziona una categoria specifica.

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

• Senza categoria: riprende tutta la sezione.
• Con una categoria: la seleziona e la riproduce.
• L’Ambiente utilizza una logica di interruttore. Riprodurre una categoria Ambiente già attiva la spegne.

pause

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

stop

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

setActiveLibrary

Cambia la libreria attiva tramite UUID o nome.

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

setVolume

Imposta il volume per un’intera sezione, o per una categoria specifica all’interno di una sezione. Usa value da 0.0 a 1.0, o da 0 a 100 con 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}

Il transitionMs opzionale controlla la velocità con cui il volume sfuma al nuovo livello (predefinito: 500 ms).

playEcho

Attiva un suono Echo a scatto singolo.

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

setCategoryEnabled

Abilita o disabilita esplicitamente una categoria in una sezione.

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

restoreState

Ripristina uno stato precedentemente salvato da un link di condivisione creato dall’app.

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

setConfig

Inoltra un’impostazione di configurazione all’integrazione MQTT (se connessa). Utile per automazione avanzata.

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

Gestione degli errori

Se un comando non può essere eseguito (ad esempio, un nome di categoria non esiste o un campo richiesto manca), la risposta conterrà "ok": false e un messaggio di error che descrive cosa è andato storto.

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

Sicurezza

Per default, l’API Locale si collega a 127.0.0.1 (solo localhost) e non è raggiungibile da altri dispositivi sulla tua rete.

Se abiliti l’opzione Ascolto su LAN, l’API diventa raggiungibile da altri dispositivi. In tal caso è necessaria una chiave API per tutte le richieste non localhost. La chiave viene generata automaticamente e mostrata in Impostazioni → Controllo Esterno → API Locale; passala con ogni richiesta usando uno di:

• Intestazione: Authorization: Bearer <your-api-key>
• Parametro di query: ?apiKey=<your-api-key>

Esempi:

# Usando l'intestazione Authorization
curl http://192.168.0.10:8329/api/state ^
  -H "Authorization: Bearer your-api-key-here"

# Usando il parametro di query
curl "http://192.168.0.10:8329/api/state?apiKey=your-api-key-here"

# Inviare un comando da un altro dispositivo
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 con chiave API
wscat -c "ws://192.168.0.10:8329/ws?apiKey=your-api-key-here"

Le richieste localhost non richiedono mai una chiave, anche quando la modalità LAN è attiva.

Puoi rigenerare la Chiave API in qualsiasi momento da Impostazioni → Controllo Esterno → API Locale. Qualsiasi client precedentemente connesso avrà bisogno della nuova chiave.