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

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

GET /api/icon/{categoryUuid}

Restituisce l’immagine dell’icona di una categoria. Utilizza l’UUID della categoria restituito da /api/catalog. La categoria deve appartenere a una libreria attiva. Il parametro di query facoltativo size imposta la dimensione richiesta per le icone dei font e SVG e il valore predefinito è di 144 pixel.

• Le icone dei font e SVG vengono renderizzate come immagini PNG e colorate con il colore della categoria.
• Se manca un file personalizzato o un SVG non può essere rasterizzato, l’API utilizza l’icona del font come alternativa.
• Le icone personalizzate PNG, JPG e JPEG vengono restituite senza modifiche; il parametro size viene ignorato.
• Le risposte riuscite utilizzano image/png o image/jpeg e possono essere memorizzate nella cache per un’ora.
• Se la categoria non viene trovata, la risposta è 404 con {"error":"category not found"}.
• Se l’icona non può essere renderizzata, la risposta è 500 con {"error":"failed to render icon"}.

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:

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

Rilevamento delle funzionalità

Le versioni più recenti di Audio Forge aggiungono funzionalità all’API. In questo modo, uno strumento può capire cosa supporta l’app in esecuzione: il server annuncia la sua versione. È il primo messaggio WebSocket, e GET /api/info restituisce la stessa cosa:

{"type": "hello", "apiVersion": 3,
  "features": {"aiDirector": {"available": true, "enabled": true},
               "roomControl": {"commands": ["play", "pause", "stop", "..."]}}}

Le versioni precedenti di Audio Forge non inviano alcun messaggio hello e non hanno /api/info: in tal caso, considera la versione come apiVersion 1 e non chiamare nulla di più recente. Mostra o chiama le funzionalità dell’AI Director solo quando available e enabled sono entrambi true.

Controllo della stanza

Quando ospiti una stanza online, puoi consentire agli ospiti di controllare Audio Forge dalla pagina ospite. Due comandi definiscono chi può (funzionano solo mentre la stanza è aperta):

{"command": "setRoomDefaultPermission", "permission": "control"}
{"command": "setRoomGuestPermission", "clientId": "<guest clientId>", "permission": "listen"}

permission può essere "listen" (solo tu controlli Audio Forge) o "control". Lo stato della stanza in GET /api/state (room) include quindi defaultGuestPermission e un permission per ogni elemento di guests (quello effettivo: con "control" come predefinito, puoi comunque impostare un singolo ospite su "listen"). room.chatMessages elenca anche cosa hanno fatto gli ospiti che controllano, come voci con kind: "activity", command e params risolti; le voci di chat hanno kind: "chat". Gli ospiti che si uniscono o lasciano la stanza appaiono come voci di attività con command guestJoined, guestLeft, guestRemoved o guestReconnected. Mentre gli ospiti possono controllare, Audio Forge carica anche le icone delle categorie sul server della stanza in modo che la pagina ospite possa mostrarle. Gli ospiti con il controllo possono eseguire solo i comandi elencati in features.roomControl.commands; la cattura, la rimozione degli ospiti, la configurazione, l’AI Director e le autorizzazioni rimangono sotto il tuo controllo.

AI Director

L’AI Director ascolta la tua tavola e cambia la musica e l’atmosfera per te. Tramite la Local API puoi avviarlo e arrestarlo, scegliere da dove ottenere l’audio, fornirgli testo e seguire ciò che ha capito e fatto. Ha bisogno che l’AI Director sia abilitato nell’app e che i suoi modelli siano installati.

Comandi

inputSource può essere "device" (il dispositivo di input scelto in Audio Forge, il valore predefinito) o "remote" (audio inviato dal tuo strumento tramite WebSocket).

{"command": "aiDirectorStart", "inputSource": "remote", "fresh": true}

Invio di testo

aiDirectorSendText è un’operazione “fire and forget”: la risposta conferma solo che il testo è stato messo in coda. Come con la voce, il Director AI raccoglie ciò che sente per alcuni secondi e poi decide cosa, se qualcosa, cambiare. Viene rifiutato a meno che il Director AI non sia in esecuzione.

{"command": "aiDirectorSendText", "text": "Heavy rain starts to fall on the old market square."}

Questo è utile per strumenti che già hanno una trascrizione, per sessioni basate su testo e per testare come il Director AI reagisce a una scena.

Stato

GET /api/ai_director/status, e il messaggio WebSocket ai_director, che viene inviato ogni volta che qualcosa cambia:

{"type": "ai_director", "available": true, "enabled": true, "entitled": true,
  "modelsReady": true, "state": "listening", "inputSource": "device",
  "sceneDescription": "Heavy rain over a market square", "lastTranscript": "...", "error": null}

Registro attività

Il messaggio WebSocket ai_director_log contiene ciò che l’AI Director ha sentito e fatto. Viene inviato integralmente quando ti connetti (reset: true, le ultime 100 voci), quindi solo le nuove voci:

{"type": "ai_director_log", "reset": false,
  "entries": [{"id": 42, "at": "2026-10-27T15:20:48Z", "kind": "transcript", "text": "..."}]}

kind è transcript (ciò che è stato sentito), action (ciò che è stato modificato), error o info.

Per un’analisi più approfondita, GET /api/ai_director/debug?since=<id> restituisce ogni voce dopo id, inclusa la richiesta inviata al modello linguistico e la sua risposta originale. È destinato alla messa a punto, non alla visualizzazione.

Invio del tuo audio dal microfono

Con inputSource impostato su "remote", invia frame WebSocket binari di audio raw: 16 kHz, mono, signed 16-bit little-endian PCM. Audio Forge applica la sua solita rilevazione del silenzio, quindi puoi trasmettere continuamente. I frame vengono ignorati mentre la sorgente è "device". Solo un client WebSocket può fornire audio alla volta; quando si disconnette, l’AI Director torna al dispositivo di input.

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.