> 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. # Transcrições e estratégias de commit > **Note** > > **Guia prático** · Pressupõe que você concluiu o guia de > [streaming no lado do cliente](/docs/pt/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming) ou de > [streaming no lado do servidor](/docs/pt/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming). ## Visão geral Ao transcrever áudio, você receberá transcrições parciais e confirmadas. * **Transcrições parciais** - os resultados provisórios da transcrição * **Transcrições confirmadas** - os resultados finais do segmento de transcrição, enviados quando uma mensagem de "commit" é recebida. Uma sessão pode ter várias transcrições confirmadas. A transcrição confirmada pode conter, opcionalmente, marcações de tempo por palavra. Elas só são recebidas quando a opção "include timestamps" está definida como `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 }); ``` ## Estratégias de commit Ao enviar trechos de áudio pelo WebSocket, os segmentos de transcrição podem ser confirmados de duas formas: commit manual ou detecção de atividade de voz (VAD). ### Commit manual Com a estratégia de commit manual, você controla quando confirmar os segmentos da transcrição. Essa é a estratégia usada por padrão. Confirmar um segmento limpa a transcrição acumulada já processada e inicia um novo segmento sem perder o contexto. Confirmar a cada 20 a 30 segundos é uma boa prática para melhorar a latência. Mesmo que você não faça o commit manualmente, o modelo confirma automaticamente após aproximadamente 36 segundos de áudio acumulado. Para melhores resultados, faça o commit durante períodos de silêncio ou em outro ponto lógico, como uma troca de turno. > **Info** > > O processamento da transcrição começa depois que os primeiros 2 segundos de áudio são enviados. ```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** > > Fazer commits manuais várias vezes em uma sequência curta pode prejudicar o desempenho do modelo. #### Enviando o contexto de texto anterior Ao enviar áudio para transcrição, você pode enviar o contexto de texto anterior junto com o primeiro trecho de áudio para ajudar o modelo a entender o contexto da fala. Isso é útil em alguns cenários: * Texto do agente para casos de uso de IA conversacional - Permite que o modelo entenda mais facilmente o contexto da conversa e produza transcrições melhores. * Reconexão após um erro de rede - Permite que o modelo continue transcrevendo, usando o texto anterior como orientação. * Informações contextuais gerais - Uma breve descrição do assunto da transcrição ajuda o modelo a entender o contexto. > **Warning** > > O envio do contexto `previous_text` só é possível ao enviar o primeiro trecho de áudio via > `connection.send()`. Enviá-lo em trechos posteriores resultará em um erro. O texto anterior funciona > melhor quando tem menos de *50* caracteres. ```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", }); ``` ### Detecção de atividade de voz (VAD) Com a estratégia VAD, o mecanismo de transcrição detecta automaticamente segmentos de fala e silêncio. Quando um limite de silêncio é atingido, o mecanismo de transcrição confirma o segmento automaticamente. Ao transcrever áudio do microfone na [integração no lado do cliente](/docs/pt/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming), recomendamos usar a estratégia VAD. **`Cliente`** ```typescript title="Cliente" 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, }); ``` ## Mantendo a conexão ativa durante o silêncio Os SDKs oficiais não encerram a conexão quando nenhuma mensagem chega, então a maioria das integrações não precisa disso. Se o seu próprio cliente WebSocket, ou um proxy ou balanceador de carga intermediário, encerrar a conexão quando nenhum frame chegar por algum tempo, passe o parâmetro de consulta opcional `keepalive_interval_ms` ao se conectar. Isso é importante durante longos períodos de silêncio, por exemplo, em uma chamada telefônica com pausas de 10 a 15 segundos. Aproximadamente uma vez por intervalo, o servidor envia um `partial_transcript` de keepalive: vazio (`text: ""`) se o segmento atual não tiver texto não confirmado, ou uma repetição do texto parcial mais recente caso tenha. > **Warning** > > Keepalives não são pings executados continuamente: você precisa continuar transmitindo áudio (frames de silêncio funcionam). > Se você parar de enviar áudio, nenhum keepalive será enviado, e o servidor encerrará a conexão após 15 > segundos sem mensagens do cliente. Esse limite do servidor não é configurável. * Aceita um número inteiro entre `500` e `10000` (milissegundos). É desativado por padrão; omita o parâmetro para manter o comportamento atual. * Valores fora do intervalo ou que não sejam inteiros fazem o servidor enviar um erro `invalid_request` e encerrar a conexão. * Os keepalives são acionados pelo modelo realmente processando o áudio silencioso que você envia, não por um temporizador contínuo, portanto também confirmam que o caminho de transcrição está ativo. * O áudio é processado em trechos de aproximadamente 1 segundo, então os keepalives chegam cerca de uma vez por intervalo, arredondado para essa cadência (por exemplo, `1000` é acionado cerca de uma vez por segundo, e `3000`, cerca de uma vez a cada 3 segundos). O primeiro keepalive de uma sessão chega cerca de 2 segundos após seu início, pois o servidor armazena em buffer os primeiros \~2 segundos de áudio antes de transcrever. Defina seu intervalo como, no máximo, cerca de um terço do seu próprio tempo limite de leitura para deixar uma margem. * O `text` de um keepalive só fica vazio quando o segmento atual ainda não tem texto não confirmado. Se ocorrer uma pausa após a fala, mas antes de um commit — mais visível com `filter_background_audio=true` ou no modo de commit manual sem confirmar — o keepalive repete o texto parcial mais recente, para que nunca apague o texto provisório. Após um commit, os keepalives voltam a ficar vazios até que uma nova fala chegue. * Funciona com `commit_strategy=manual` e `commit_strategy=vad`, além de `filter_background_audio=true`. Não afeta a cobrança além do áudio que você já está transmitindo. * A `config` da mensagem `session_started` retorna `keepalive_interval_ms` (`null` quando desativado). > **Info** > > Um `partial_transcript` vazio (`text: ""`) significa "nenhuma fala no segmento atual". Um > `partial_transcript` repetido e idêntico durante uma pausa também é um keepalive — os clientes devem simplesmente renderizar > as transcrições parciais como já fazem, em vez de tratar a repetição como um caso especial. Adicione o parâmetro ao URL do WebSocket: ```text wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&commit_strategy=vad&keepalive_interval_ms=1000 ``` ## Formatos de áudio compatíveis | Formato | Taxa de amostragem | Descrição | | --------- | ------------------ | ------------------------------------------- | | pcm_8000 | 8 kHz | PCM de 16 bits, little-endian | | pcm_16000 | 16 kHz | PCM de 16 bits, little-endian (recomendado) | | pcm_22050 | 22,05 kHz | PCM de 16 bits, little-endian | | pcm_24000 | 24 kHz | PCM de 16 bits, little-endian | | pcm_44100 | 44,1 kHz | PCM de 16 bits, little-endian | | pcm_48000 | 48 kHz | PCM de 16 bits, little-endian | | ulaw_8000 | 8 kHz | Codificação μ-law de 8 bits | ## Boas práticas ### Qualidade do áudio * Para melhores resultados, use uma taxa de amostragem de 16 kHz para um equilíbrio ideal entre qualidade e largura de banda. * Garanta uma entrada de áudio limpa, com o mínimo de ruído de fundo. * Use um ganho de microfone adequado para evitar clipping. * No momento, apenas áudio mono é compatível. ### Tamanho dos trechos * Envie trechos de áudio com duração de 0,1 a 1 segundo para uma transmissão contínua. * Trechos menores resultam em menor latência, mas mais sobrecarga. * Trechos maiores são mais eficientes, mas podem introduzir latência. ## Próximas etapas #### [Streaming no lado do servidor](/docs/pt/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming) Configure a transcrição de áudio no lado do servidor usando a API WebSocket. #### [Referência de eventos](/docs/pt/eleven-api/guides/how-to/speech-to-text/realtime/event-reference) Lista completa de eventos e tipos de erro da API de STT em tempo real.