Transcrições e estratégias de commit

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.

# 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 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.

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

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.

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 o segmento automaticamente.

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

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,
});

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.

• 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).

Adicione o parâmetro ao 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

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