> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Trascrizioni e strategie di commit > **Note** > > **Guida pratica** · Presuppone che tu abbia completato la guida sullo > [streaming lato client](/docs/it/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming) o sullo > [streaming lato server](/docs/it/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming). ## 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`. ```python # 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 )) ``` ```typescript // Initialize the connection const connection = await elevenlabs.speechToText.realtime.connect({ modelId: "scribe_v2_realtime", includeTimestamps: true, // Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps }); ``` **`React`** ```typescript title="React" const connection = useScribe({ modelId: "scribe_v2_realtime", // Configuring this callback will automatically set the `includeTimestamps` option to `true` onCommittedTranscriptWithTimestamps: (data) => { console.log("Committed with timestamps:", data.text); console.log("Timestamps:", data.words); }, }); ``` **`JavaScript`** ```typescript title="JavaScript" const connection = Scribe.connect({ modelId: "scribe_v2_realtime", includeTimestamps: true, // Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps }); ``` ## Strategie di commit Quando invii chunk audio tramite WebSocket, i segmenti di trascrizione possono essere confermati in due modi: commit manuale o rilevamento dell'attività vocale (VAD). ### Commit manuale Con la strategia di commit manuale, controlli quando confermare i segmenti di trascrizione. Questa è la strategia utilizzata per impostazione predefinita. La conferma di un segmento cancella la trascrizione accumulata elaborata e avvia un nuovo segmento senza perdere il contesto. Per ridurre la latenza, è consigliabile effettuare un commit ogni 20-30 secondi. Anche se non effettui commit manualmente, il modello conferma automaticamente dopo circa 36 secondi di audio accumulato. Per risultati ottimali, effettua il commit durante i periodi di silenzio o in un altro punto logico, ad esempio alla fine di un turno di conversazione. > **Info** > > L'elaborazione della trascrizione inizia dopo l'invio dei primi 2 secondi di audio. ```python await connection.send({ "audio_base_64": audio_base_64, "sample_rate": 16000, }) # When ready to finalize the segment await connection.commit() ``` ```typescript connection.send({ audioBase64: audioBase64, sampleRate: 16000, }); // When ready to finalize the segment connection.commit(); ``` > **Warning** > > Effettuare manualmente più commit in rapida successione può ridurre le prestazioni del modello. #### Invio del contesto testuale precedente Quando invii audio per la trascrizione, puoi inviare il contesto testuale precedente insieme al primo chunk 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 riferimento. * Informazioni contestuali generali - Una breve descrizione dell'argomento della trascrizione aiuta il modello a comprendere il contesto. > **Warning** > > L'invio del contesto `previous_text` è possibile solo quando invii il primo chunk audio tramite > `connection.send()`. Inviarlo nei chunk successivi genera un errore. Il testo precedente funziona > meglio se è lungo meno di *50* caratteri. ```python await connection.send({ "audio_base_64": audio_base_64, "previous_text": "The previous text context", }) ``` ```typescript connection.send({ audioBase64: audioBase64, previousText: "The previous text context", }); ``` ### Rilevamento dell'attività vocale (VAD) Con la strategia VAD, il motore di trascrizione rileva automaticamente i segmenti di parlato e di 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](/docs/it/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming), è consigliabile usare la strategia VAD. **`Client`** ```typescript title="Client" 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, }); ``` ```python from dotenv import load_dotenv from elevenlabs import AudioFormat, CommitStrategy, ElevenLabs, RealtimeAudioOptions load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) connection = await elevenlabs.speech_to_text.realtime.connect( RealtimeAudioOptions( model_id="scribe_v2_realtime", audio_format=AudioFormat.PCM_16000, commit_strategy=CommitStrategy.VAD, vad_silence_threshold_secs=1.5, vad_threshold=0.4, min_speech_duration_ms=100, min_silence_duration_ms=100, ) ) ``` **`TypeScript`** ```typescript title="TypeScript" import { ElevenLabsClient, AudioFormat, CommitStrategy } from '@elevenlabs/elevenlabs-js'; const elevenlabs = new ElevenLabsClient(); const connection = await elevenlabs.speechToText.realtime.connect({ modelId: "scribe_v2_realtime", audioFormat: AudioFormat.PCM_16000, commitStrategy: CommitStrategy.VAD, vadSilenceThresholdSecs: 1.5, vadThreshold: 0.4, minSpeechDurationMs: 100, minSilenceDurationMs: 100, }); ``` ## 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 riceve frame per un certo periodo, passa il parametro query facoltativo `keepalive_interval_ms` durante la connessione. È importante durante lunghi periodi di silenzio, ad esempio in una chiamata telefonica con pause di 10-15 secondi. All'incirca una volta per intervallo, il server invia un `partial_transcript` keepalive: vuoto (`text: ""`) se il segmento corrente non ha testo non confermato, oppure una ripetizione dell'ultimo testo parziale se ne ha. > **Warning** > > I keepalive non sono ping continui: devi continuare a trasmettere audio in streaming (i frame di silenzio vanno bene). > Se smetti di inviare audio, non vengono inviati keepalive e il server chiude la connessione dopo 15 > secondi senza messaggi dal client. Questo limite del server non è configurabile. * Accetta un numero intero compreso tra `500` e `10000` (millisecondi). È disabilitato per impostazione predefinita; ometti il parametro per mantenere il comportamento esistente. * I valori fuori intervallo o non interi fanno sì che il server invii un errore `invalid_request` e chiuda la connessione. * I keepalive dipendono dal fatto che il modello elabori effettivamente l'audio silenzioso inviato, non da un timer continuo, quindi confermano anche che il percorso di trascrizione è attivo. * L'audio viene elaborato in chunk 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 memorizza nel buffer i primi \~2 secondi di audio prima di trascrivere. Imposta l'intervallo a non più di circa un terzo del tuo timeout di lettura, per lasciare margine. * Il valore `text` di un keepalive è vuoto solo quando il segmento corrente non ha ancora testo non confermato. Se si verifica una pausa dopo il parlato ma prima di un commit — più evidente con `filter_background_audio=true` o in modalità di commit manuale senza effettuare il commit — 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 ha alcun impatto sulla fatturazione oltre all'audio che stai già trasmettendo in streaming. * Il valore `config` del messaggio `session_started` restituisce `keepalive_interval_ms` (`null` quando è disabilitato). > **Info** > > Un `partial_transcript` vuoto (`text: ""`) significa "nessun parlato nel segmento corrente". Un > `partial_transcript` ripetuto e identico durante una pausa è anch'esso un keepalive: i client devono semplicemente visualizzare > le trascrizioni parziali come già fanno, anziché gestire separatamente la ripetizione. Aggiungi il parametro all'URL WebSocket: ```text wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&commit_strategy=vad&keepalive_interval_ms=1000 ``` ## Formati audio supportati | Formato | Frequenza di campionamento | Descrizione | | ---------- | -------------------------- | ----------------------------------------- | | pcm\_8000 | 8 kHz | PCM a 16 bit, little-endian | | pcm\_16000 | 16 kHz | PCM a 16 bit, little-endian (consigliato) | | pcm\_22050 | 22,05 kHz | PCM a 16 bit, little-endian | | pcm\_24000 | 24 kHz | PCM a 16 bit, little-endian | | pcm\_44100 | 44,1 kHz | PCM a 16 bit, little-endian | | pcm\_48000 | 48 kHz | PCM a 16 bit, little-endian | | ulaw\_8000 | 8 kHz | codifica μ-law a 8 bit | ## 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 appropriato per evitare il clipping. * Al momento è supportato solo l'audio mono. ### Dimensione dei chunk * Per uno streaming fluido, invia chunk audio della durata di 0,1-1 secondo. * I chunk più piccoli riducono la latenza, ma aumentano l'overhead. * I chunk più grandi sono più efficienti, ma possono introdurre latenza. ## Passaggi successivi #### [Streaming lato server](/docs/it/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming) Configura la trascrizione audio lato server usando l'API WebSocket. #### [Riferimento eventi](/docs/it/eleven-api/guides/how-to/speech-to-text/realtime/event-reference) Elenco completo degli eventi e dei tipi di errore dell'API STT in tempo reale.