API Locale

<- torna alla radice della documentazione

Cosa fa l’API Locale

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

Se utilizzi già l’integrazione MQTT, l’API Locale supporta gli stessi comandi. La differenza è che viene eseguita interamente sulla tua macchina senza alcuna configurazione: 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 (è abilitata per impostazione predefinita).

Puoi configurare:

Abilitato (impostazione predefinita: attivo).
Numero di Porta (impostazione predefinita: 8329).
Ascolta sulla LAN (impostazione predefinita: disattivato). Quando è attivo, i dispositivi sulla tua rete locale possono accedere all’API. Quando è disattivato, solo il software sulla stessa macchina può connettersi.
Chiave API (generata automaticamente). Richiesta 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 sulla LAN” è attivato, ascolta su tutte le interfacce di rete.

Guida rapida

Apri un terminale e prova:

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

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

Endpoint HTTP

Metodo	Percorso	Descrizione
GET	`/api/state`	Stato di riproduzione corrente
GET	`/api/catalog`	Catalogo completo della libreria e delle categorie
GET	`/api/echoes/active`	Suoni Echo one-shot attualmente in riproduzione
POST	`/api/command`	Esegui un comando (corpo JSON)

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.5}
}

Tutti i campi del volume utilizzano la scala di visualizzazione dell’app da 0.0 a 1.0. Per Musica e Ambiente, 0.5 è il volume normale (unità) e 1.0 è il massimo potenziato. Per Echoes, 1.0 è il volume normale.

categoryVolume contiene valori di runtime correnti e potrebbe essere scarso. Utilizza il campo volume da /api/catalog quando hai bisogno di un valore completo per ogni categoria, incluse le categorie non ancora utilizzate.

GET /api/catalog

Restituisce ogni libreria con le sue categorie Musica e Ambiente:

{
  "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 indica se la categoria è visibile e abilitata in Forge.
trackCount è il numero di tracce riproducibili attualmente installate per quella categoria.
volume è il volume effettivo della categoria sulla scala 0.0 a 1.0. È presente per ogni categoria, incluse le categorie inattive.

Per una categoria attiva, il catalogo segnala il suo volume di runtime corrente. Per una categoria inattiva, segnala il volume target configurato, o 0.5 quando non esiste un target. Le regolazioni di runtime non sostituiscono il target configurato. Quando una categoria viene riavviata, viene utilizzato un valore di comando esplicito se presente; altrimenti viene utilizzato il target configurato. La precedente regolazione di runtime non viene riutilizzata. Il ripristino di un Link di Stato applica i volumi di runtime registrati in quel link.

GET /api/echoes/active

Restituisce un’istantanea di ogni suono Echo one-shot attualmente in riproduzione. I trigger simultanei vengono restituiti come voci separate, anche quando utilizzano la stessa categoria o file audio.

{
  "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 identifica in modo univoco questo trigger specifico. Due riproduzioni sovrapposte dello stesso categoria ricevono ID diversi.
sampledAt è quando Audio Forge ha generato lo snapshot. I valori di posizione non vengono trasmessi continuamente, quindi i client devono richiedere un nuovo snapshot quando hanno bisogno dello stato corrente.
durationMs, remainingMs, progress e progressPercent sono null quando la durata del suono non è disponibile.
progress utilizza una scala 0.0 a 1.0. progressPercent utilizza 0.0 a 100.0.
fileName contiene solo il nome del file, mai un percorso del file system locale.
I suoni Echo terminati o interrotti vengono rimossi dall’elenco.

Gli Echo condividono il valore globale echoesVolume restituito da /api/state. Non esiste un volume Echo per riproduzione o per categoria.

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 gli strumenti che desiderano aggiornamenti in tempo reale (come un plugin per Stream Deck che deve mostrare lo stato corrente), connettiti a un WebSocket su:

ws://localhost:8329/ws

Invio di comandi

Invia gli stessi oggetti comando JSON che invieresti 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:

tipo	Quando viene inviato	Cosa contiene
`state`	Al momento della connessione + ogni volta che la riproduzione cambia	Come `GET /api/state`
`catalog`	Al momento della connessione + quando le librerie cambiano	Come `GET /api/catalog`
`result`	Dopo ogni comando che invii	`ok`, `message` o `error`, `requestId`
`echo`	Quando viene attivato un suono Echo	`uuid`, `name`, `at`

Gli aggiornamenti dello stato vengono sottoposti a buffering (250 ms) in modo da non essere sommersi durante rapidi cambiamenti come le variazioni di volume.

I messaggi sono oggetti JSON piatti. Il payload non è annidato sotto un campo data o payload. Esempi:

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

Comandi

Tutti i comandi utilizzano 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, oppure seleziona una categoria specifica.

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

Senza una categoria: riprende l’intera sezione.
Con una categoria: seleziona e riproduce.
L’ambiente utilizza la semantica di toggle. La riproduzione di una categoria Ambiente già attiva la disattiva.

pausa

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

stop

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

setActiveLibrary

Passa alla libreria attiva tramite UUID o nome.

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

setVolume

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

L’opzionale transitionMs controlla la velocità con cui il volume si attenua al nuovo livello (impostazione predefinita: 500 ms).

Musica e Ambiente utilizzano la stessa scala di visualizzazione dell’app: 0.5 è il volume normale (unità) e 1.0 è il massimo potenziato. Gli Echo non hanno un intervallo potenziato, quindi 1.0 è il volume normale. L’API converte automaticamente questi valori di visualizzazione nella guadagno di riproduzione interno.

nextTrack

Salta alla traccia successiva in una categoria Musica o Ambiente attiva. La categoria deve già essere in riproduzione.

{"command": "nextTrack", "section": "Music", "categoryUuid": "<uuid>"}
{"command": "nextTrack", "section": "Ambiance", "categoryName": "Rain"}

playEcho

Attiva un suono Echo one-shot.

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

In caso di successo, il comando attende che la riproduzione Echo venga registrata e restituisce i relativi campi di monitoraggio e riproduzione:

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

Usa il playbackId restituito con stopEcho per interrompere solo questa istanza di riproduzione. Puoi anche aggiornare i valori correnti con GET /api/echoes/active.

stopEcho

Interrompi la riproduzione attiva di Echo utilizzando esattamente un selettore:

{"command": "stopEcho", "playbackId": "<playback-id>"}
{"command": "stopEcho", "categoryUuid": "<category-uuid>"}
{"command": "stopEcho", "categoryName": "Thunder"}

playbackId interrompe solo quell’istanza di riproduzione. Ottieni gli ID di riproduzione da GET /api/echoes/active.
categoryUuid interrompe ogni Echo attivo da quella categoria.
categoryName interrompe ogni Echo attivo la cui categoria ha esattamente quel nome. Se le categorie in più librerie condividono lo stesso nome, tutte le corrispondenze vengono interrotte.
Il risultato include stoppedCount. Un selettore senza corrispondenze attive ha successo con stoppedCount: 0.
Per interrompere ogni Echo attivo indipendentemente dalla categoria, usa {"command": "stop", "section": "Echoes"}.

setCategoryEnabled

Abilita o disabilita esplicitamente una categoria in una sezione.

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

Puoi abilitare una categoria e impostare il suo volume in modo atomico includendo value. Se value viene omesso, viene utilizzato il volume target configurato per la categoria. Un regolamento di runtime precedente non viene riutilizzato.

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

restoreState

Ripristina uno stato salvato in precedenza 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 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 è richiesto un campo obbligatorio), la risposta conterrà "ok": false e un messaggio error che descrive cosa è andato storto.

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

Sicurezza

Per impostazione predefinita, l’API Locale si lega a 127.0.0.1 (localhost only) e non è accessibile da altri dispositivi sulla tua rete.

Se abiliti Ascolta sulla LAN, l’API diventa accessibile da altri dispositivi. In tal caso è richiesta una chiave API per tutte le richieste non localhost. La chiave viene generata automaticamente e visualizzata in *Impostazioni → Controllo Esterno → API Locale; passala con ogni richiesta utilizzando uno dei seguenti:

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

Esempi:

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

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. Tutti i client precedentemente connessi dovranno utilizzare la nuova chiave.

Comportamento in background mobile

I sistemi operativi mobili possono sospendere la gestione di HTTP e WebSocket in entrata quando Audio Forge è in background o il dispositivo è bloccato, anche quando la riproduzione audio nativa continua. L’API Locale non si interrompe deliberatamente, ma non può garantire la disponibilità in background su iOS o Android.

Per un controllo remoto stabile durante una sessione, mantieni Audio Forge in primo piano e mantieni lo schermo attivo. Questo evita di fare affidamento sull’esecuzione in background a risparmio energetico che le piattaforme mobili potrebbero interrompere in qualsiasi momento.