---
title: API Locale
weight: 45
date: "2026-03-31"
showMetadata: false
---

[<- torna alla radice della documentazione](/audioforge/doc)
&nbsp;

## 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 via HTTP o WebSocket, senza bisogno di software aggiuntivo.

Se già utilizzi l'[integrazione MQTT](/audioforge/doc/mqtt), l'API Locale supporta esattamente gli stessi comandi. La differenza è che funziona interamente sulla tua macchina senza alcuna configurazione: nessun broker da installare, nessuna rete da configurare.

## Abilitare l'API Locale

Vai a **Impostazioni → Controllo esterno → API Locale** e assicurati che la funzione sia abilitata (è attiva di default).

Puoi configurare:

- Interruttore **Attivato** (default: attivo).
- Numero di **porta** (default: 8329).
- Interruttore **Ascolta su LAN** (default: disattivato). Quando attivato, i dispositivi sulla tua rete locale possono raggiungere l'API. Quando disattivato, 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 "Ascolta su LAN" è attivato, ascolta su tutte le interfacce di rete invece.

## Avvio rapido

Apri un terminale e prova:

```bash
# Vedi cosa sta suonando in questo momento
curl http://localhost:8329/api/state

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

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

Endpoint HTTP

GET /api/state

Ritorna un’istantanea JSON di cosa sta facendo Audio Forge in questo momento:

{
  "libraryUuid": "...",
  "libraryName": "[Predefinito]",
  "musicPlaying": true,
  "ambiancePlaying": false,
  "musicVolume": 0.75,
  "ambianceVolume": 0.5,
  "musicCategories": [{"uuid": "...", "name": "Battle"}],
  "ambianceCategories": [{"uuid": "...", "name": "Pioggia"}],
  "lastEcho": {"uuid": "...", "name": "Tuono", "at": "2025-06-01T12:34:56Z"},
  "categoryVolume": {"<uuid>": 0.8}
}

GET /api/catalog

Ritorna ogni libreria con le sue categorie di Musica e Atmosfera:

{
  "activeLibraryUuid": "...",
  "libraries": [
    {
      "uuid": "...",
      "name": "[Predefinito]",
      "music": [{"uuid": "...", "name": "Battle"}],
      "ambiance": [{"uuid": "...", "name": "Pioggia"}]
    }
  ]
}

POST /api/command

Invia un comando JSON nel corpo della richiesta. Con successo:

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

In caso di errore:

{"ok": false, "error": "categoria non trovata"}

WebSocket

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

ws://localhost:8329/ws

Inviare comandi

Invia gli stessi oggetti comando JSON che invieresti in POST a /api/command:

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

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

Ricevere aggiornamenti

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

Gli aggiornamenti di stato sono regolati (250 ms) quindi non sarai inondato durante cambi rapidi come le variazioni di volume.

Comandi

Tutti i comandi usano lo stesso schema JSON dell’integrazione MQTT. Ogni comando accetta una stringa requestId opzionale che puoi utilizzare 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 l’intera sezione.
• Con categoria: seleziona e la riproduce.
• L’atmosfera usa una semantica toggle. Riprodurre una categoria di Atmosfera già attiva la spegne.

pause

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

stop

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

setActiveLibrary

Cambia la libreria attiva per UUID o nome.

{"command": "setActiveLibrary", "libraryName": "La Mia Libreria"}
{"command": "setActiveLibrary", "libraryUuid": "<uuid>"}

setVolume

Imposta il volume per un’intera sezione (0.0 a 1.0), o per una specifica categoria all’interno di una sezione.

{"command": "setVolume", "section": "Music", "value": 0.65}
{"command": "setVolume", "section": "Ambiance", "value": 0.5,
  "categoryName": "Pioggia", "transitionMs": 1000}

L’opzione transitionMs controlla la rapidità con cui il volume si abbassa al nuovo livello (default: 500 ms).

playEcho

Attiva un suono Echo una tantum.

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

setCategoryEnabled

Abilita o disabilita esplicitamente una categoria all’interno di una sezione.

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

restoreState

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

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

setConfig

Inoltra una configurazione all’integrazione MQTT (se connessa). Utile per l’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 è mancante), la risposta conterrà "ok": false e un messaggio di error che descrive cosa è andato storto.

{"ok": false, "error": "categoria non trovata"}
{"ok": false, "error": "sezione richiesta"}
{"ok": false, "error": "json non valido"}

Sicurezza

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

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

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

Esempi:

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

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

# Inviando 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.