Sessioni e protocollo
Dal token al primo audio: gestisci connessione, input, risposte e chiusura.
Apri il WebSocket
Connettiti al websocket_url restituito dal token. Invia subito il messaggio di handshake. Riceverai session con session_id, poi ready quando provider e slot sono disponibili. Invia input dopo ready. Il renderer SDK supportato è hybrid.
{ "session_token": "TOKEN_MONOUSO", "renderer": "hybrid" }Messaggi in ingresso
Ogni messaggio è JSON. L’audio in ingresso usa PCM signed 16 bit little endian, mono, 24000 Hz, codificato base64. Mantieni i messaggi sotto 150000 caratteri. text e talk usano al massimo 1500 caratteri.
| type | Campi |
|---|---|
| text | text: domanda per il modello |
| talk | text: frase letta direttamente dalla voce |
| audio | audio: PCM base64 |
| mute | muted: boolean |
| interrupt | Nessun campo aggiuntivo |
| truncate | item_id, played_ms: audio effettivamente ascoltato |
| stop | Termina la conversazione |
Eventi in uscita
audio include epoch, item_id e offset_ms. Alla ricezione di clear elimina l’audio in coda e usa il nuovo epoch per ignorare pacchetti obsoleti. generation_done indica fine generazione, non necessariamente fine riproduzione audio.
| Evento | Contenuto |
|---|---|
| session / ready | ID e disponibilità della sessione |
| listening / user_stopped / thinking | Avanzamento della conversazione |
| user_transcript / transcript | text utente / frammenti risposta |
| audio / phonemes / words | Audio e metadati di animazione |
| action | Azione configurata sulla persona |
| clear / generation_done / usage | Reset, fine generazione e consumo |
| response_error / error | Errore recuperabile / errore di sessione |
Concorrenza e riconnessione
PROSOPO_MAX_SESSIONS controlla gli slot condivisi da Studio e SDK (default 8). Quando gli slot sono occupati la connessione attende: usa il controllo indicativo di concorrenza prima dell’avvio. Dopo una disconnessione crea un nuovo token; il riuso viene rifiutato. Il registro attivo è locale al processo: usa un singolo worker per limiti e stop coerenti.