Transcrições e estratégias de confirmação

Guia prático · Pressupõe que você tenha concluído o guia de streaming no cliente ou de streaming no servidor.

Visão geral

Ao transcrever áudio, você receberá transcrições parciais e confirmadas.

Transcrições parciais - os resultados intermediá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 incluir, opcionalmente, carimbos de data e hora no nível das palavras. Isso só é recebido quando a opção “include timestamps” é definida como 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
))

Estratégias de confirmação

Ao enviar blocos de áudio pelo WebSocket, os segmentos de transcrição podem ser confirmados de duas formas: confirmação manual ou detecção de atividade de voz (VAD).

Confirmação manual

Com a estratégia de confirmação manual, você controla quando confirmar os segmentos de transcrição. Essa é a estratégia usada por padrão. Confirmar um segmento limpará a transcrição acumulada já processada e iniciará 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 confirme manualmente, o modelo confirma automaticamente após aproximadamente 36 segundos de áudio acumulado.

Para melhores resultados, confirme durante períodos de silêncio ou em outro ponto lógico, como uma mudança de turno.

O processamento da transcrição começa depois que os primeiros 2 segundos de áudio são enviados.

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

Fazer várias confirmações manuais em uma sequência curta pode prejudicar o desempenho do modelo.

Enviando contexto de texto anterior

Ao enviar áudio para transcrição, você pode enviar um contexto de texto anterior junto com o primeiro bloco 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 a transcrição usando o texto anterior como orientação.
Informações contextuais gerais - Uma breve descrição sobre o tema da transcrição ajuda o modelo a entender o contexto.

O envio do contexto previous_text só é possível ao enviar o primeiro bloco de áudio por connection.send(). Enviá-lo em blocos posteriores resultará em um erro. O texto anterior funciona melhor quando tem menos de 50 caracteres.

await connection.send({
  "audio_base_64": audio_base_64,
  "previous_text": "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 automaticamente o segmento da transcrição.

Ao transcrever áudio do microfone na integração no cliente, recomendamos usar a estratégia VAD.

vad_silence_threshold_secs aceita de 0.192 a 3.0 segundos. Os SDKs de JavaScript e React aceitam apenas de 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,
});

Filtragem de áudio de fundo

Defina o parâmetro de consulta filter_background_audio=true para reduzir ativações falsas causadas por fala ao fundo, como conversas próximas, e ruído ambiente. Com a filtragem ativada, a detecção de atividade de voz usa um modelo ajustado para ignorar falas ao fundo, e vad_threshold assume o padrão 0.15, a menos que você o defina.

filter_background_audio não pode ser combinado com include_timestamps. Se você definir ambos, o servidor enviará um erro invalid_request e fechará a conexão.

A filtragem não altera a cobrança: todo o áudio que você transmite é cobrado, incluindo o áudio que o filtro ignora.

Mantendo a conexão ativa durante o silêncio

Os SDKs oficiais não encerram a conexão quando nenhuma mensagem chega, portanto a maioria das integrações não precisa disso. Se seu próprio cliente WebSocket, ou um proxy ou balanceador de carga intermediário, fechar a conexão quando nenhum frame chegar por algum tempo, envie o parâmetro de consulta opcional keepalive_interval_ms ao conectar. Isso é importante durante longos períodos de silêncio, por exemplo, em uma ligação telefônica com pausas de 10 a 15 segundos. Aproximadamente uma vez por intervalo, o servidor envia uma partial_transcript de manutenção: vazia (text: "") se o segmento atual não tiver texto não confirmado, ou uma repetição do texto parcial mais recente se tiver.

As mensagens de manutenção não são um ping contínuo: você precisa continuar transmitindo áudio (frames de silêncio são aceitos). Se parar de enviar áudio, nenhuma mensagem de manutenção será enviada, e o servidor fechará 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 fechar a conexão.
As mensagens de manutenção são acionadas pelo processamento, pelo modelo, do áudio silencioso que você envia, não por um temporizador contínuo. Portanto, elas também confirmam que o caminho de transcrição está ativo.
O áudio é processado em blocos de aproximadamente 1 segundo, então as mensagens de manutenção chegam cerca de uma vez por intervalo, arredondado para essa cadência (por exemplo, 1000 é acionado aproximadamente uma vez por segundo, e 3000, aproximadamente uma vez a cada 3 segundos). A primeira mensagem de manutenção de uma sessão chega cerca de 2 segundos depois de 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 uma mensagem de manutenção 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 uma confirmação — mais visível com filter_background_audio=true ou no modo de confirmação manual sem confirmar — a mensagem de manutenção repete o texto parcial mais recente, para que nunca apague o texto intermediário. Após uma confirmação, as mensagens de manutenção voltam a ficar vazias até que uma nova fala chegue.
Funciona com commit_strategy=manual e commit_strategy=vad, e com filter_background_audio=true. Não afeta a cobrança além do áudio que você já está transmitindo.
O config da mensagem session_started retorna keepalive_interval_ms (null quando desativado).

Uma partial_transcript vazia (text: "") significa “sem fala no segmento atual”. Uma partial_transcript repetida e idêntica durante uma pausa também é uma mensagem de manutenção — os clientes devem simplesmente renderizar as parciais como já fazem, em vez de tratar a repetição como um caso especial.

Adicione o parâmetro à URL do WebSocket:

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 saturação.
No momento, apenas áudio mono é compatível.

Tamanho do bloco

Envie blocos de áudio com duração de 0,1 a 1 segundo para uma transmissão fluida.
Blocos menores resultam em menor latência, mas geram mais sobrecarga.
Blocos maiores são mais eficientes, mas podem introduzir latência.

Próximas etapas

Streaming no servidor

Configure a transcrição de áudio no servidor usando a API WebSocket.

Referência de eventos

Lista completa de eventos e tipos de erro da API de STT em tempo real.