Trascrizioni e strategie di commit

Panoramica

Durante la trascrizione dell’audio, riceverai trascrizioni parziali e confermate.

• Trascrizioni parziali - i risultati provvisori della trascrizione
• Trascrizioni confermate - i risultati finali del segmento di trascrizione inviati quando viene ricevuto un messaggio di “commit”. Una sessione può avere più trascrizioni confermate.

La trascrizione confermata può facoltativamente contenere timestamp a livello di parola. Viene ricevuta solo quando l’opzione “include timestamps” è impostata su true.

# Initialize the connection
connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
  model_id="scribe_v2_realtime",
  include_timestamps=True, # Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
))

Strategie di commit

Quando invii blocchi audio tramite WebSocket, puoi confermare i segmenti di trascrizione in due modi: commit manuale o Voice Activity Detection (VAD).

Commit manuale

Con la strategia di commit manuale, controlli quando confermare i segmenti di trascrizione. È la strategia utilizzata per impostazione predefinita. Confermare un segmento cancella la trascrizione accumulata già elaborata e avvia un nuovo segmento senza perdere il contesto. Per migliorare la latenza, è consigliabile confermare ogni 20-30 secondi. Anche se non esegui il commit manualmente, il modello lo effettua automaticamente dopo circa 36 secondi di audio accumulato.

Per ottenere risultati ottimali, esegui il commit durante i periodi di silenzio o in un altro punto logico, come il cambio di turno.

await connection.send({
  "audio_base_64": audio_base_64,
  "sample_rate": 16000,
})
# When ready to finalize the segment
await connection.commit()

Invio del contesto di testo precedente

Quando invii audio per la trascrizione, puoi inviare il contesto di testo precedente insieme al primo blocco audio per aiutare il modello a comprendere il contesto del parlato. È utile in alcuni scenari:

• Testo dell’agente per casi d’uso di IA conversazionale - Consente al modello di comprendere più facilmente il contesto della conversazione e produrre trascrizioni migliori.
• Riconnessione dopo un errore di rete - Consente al modello di continuare a trascrivere, usando il testo precedente come guida.
• Informazioni contestuali generali - Una breve descrizione dell’argomento della trascrizione aiuta il modello a comprenderne il contesto.

await connection.send({
  "audio_base_64": audio_base_64,
  "previous_text": "The previous text context",
})

Voice Activity Detection (VAD)

Con la strategia VAD, il motore di trascrizione rileva automaticamente i segmenti di parlato e silenzio. Quando viene raggiunta una soglia di silenzio, il motore di trascrizione conferma automaticamente il segmento di trascrizione.

Quando trascrivi l’audio dal microfono nell’integrazione lato client, è consigliabile usare la strategia VAD.

vad_silence_threshold_secs accetta valori da 0.192 a 3.0 secondi. Gli SDK JavaScript e React accettano solo valori da 0.3 a 3.0.

import { Scribe, AudioFormat, CommitStrategy } from "@elevenlabs/client";
const connection = Scribe.connect({
  token: "sutkn_1234567890",
  modelId: "scribe_v2_realtime",
  audioFormat: AudioFormat.PCM_16000,
  commitStrategy: CommitStrategy.VAD,
  vadSilenceThresholdSecs: 1.5,
  vadThreshold: 0.4,
  minSpeechDurationMs: 100,
  minSilenceDurationMs: 100,
});

Filtrare l’audio in background

Imposta il parametro query filter_background_audio=true per ridurre le false attivazioni causate dal parlato in background, come conversazioni vicine, e dal rumore ambientale. Con il filtro abilitato, il rilevamento dell’attività vocale usa un modello ottimizzato per ignorare il parlato in background e vad_threshold assume per impostazione predefinita il valore 0.15, a meno che tu non lo imposti autonomamente.

Il filtro non modifica la fatturazione: viene fatturato tutto l’audio in streaming, compreso quello ignorato dal filtro.

Mantenere attiva la connessione durante il silenzio

Gli SDK ufficiali non interrompono la connessione quando non arrivano messaggi, quindi la maggior parte delle integrazioni non ne ha bisogno. Se il tuo client WebSocket, oppure un proxy o un load balancer intermedio, chiude la connessione quando non arrivano frame per un po’, passa il parametro query facoltativo keepalive_interval_ms durante la connessione. È importante durante lunghi periodi di silenzio, ad esempio una telefonata con pause di 10-15 secondi. Circa una volta per intervallo, il server invia un partial_transcript di keepalive: vuoto (text: "") se il segmento corrente non ha testo non confermato, oppure una ripetizione dell’ultimo testo parziale in caso contrario.

• Accetta un numero intero tra 500 e 10000 (millisecondi). È disabilitato per impostazione predefinita; ometti il parametro per mantenere il comportamento esistente.
• I valori non interi o fuori intervallo fanno sì che il server invii un errore invalid_request e chiuda la connessione.
• I keepalive dipendono dal modello che elabora effettivamente l’audio silenzioso inviato, non da un timer autonomo, quindi confermano anche che il percorso di trascrizione è attivo.
• L’audio viene elaborato in blocchi di circa 1 secondo, quindi i keepalive arrivano all’incirca una volta per intervallo arrotondato a questa cadenza (ad esempio, 1000 si attiva circa una volta al secondo, 3000 circa una volta ogni 3 secondi). Il primo keepalive di una sessione arriva circa 2 secondi dopo l’avvio, poiché il server mette in buffer i primi ~2 secondi di audio prima di trascriverli. Imposta l’intervallo al massimo a circa un terzo del tuo timeout di lettura per lasciare un margine.
• Il campo text di un keepalive è vuoto solo quando il segmento corrente non contiene ancora testo non confermato. Se si verifica una pausa dopo il parlato ma prima di un commit — situazione più visibile con filter_background_audio=true o in modalità di commit manuale senza confermare — il keepalive ripete invece l’ultimo testo parziale, quindi non cancella mai il testo provvisorio. Dopo un commit, i keepalive tornano a essere vuoti finché non arriva nuovo parlato.
• Funziona sia con commit_strategy=manual sia con commit_strategy=vad, e con filter_background_audio=true. Non influisce sulla fatturazione oltre all’audio che stai già trasmettendo in streaming.
• Il config del messaggio session_started restituisce keepalive_interval_ms (null quando è disabilitato).

Aggiungi il parametro all’URL WebSocket:

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&commit_strategy=vad&keepalive_interval_ms=1000

Formati audio supportati

Best practice

Qualità audio

• Per risultati ottimali, usa una frequenza di campionamento di 16 kHz per un equilibrio ideale tra qualità e larghezza di banda.
• Assicurati che l’input audio sia pulito e con rumore di fondo minimo.
• Usa un guadagno del microfono adeguato per evitare il clipping.
• Al momento è supportato solo l’audio mono.

Dimensione dei blocchi

• Per uno streaming fluido, invia blocchi audio di durata compresa tra 0,1 e 1 secondo.
• I blocchi più piccoli riducono la latenza, ma aumentano l’overhead.
• I blocchi più grandi sono più efficienti, ma possono introdurre latenza.

Passaggi successivi