Transcripciones y estrategias de confirmación

Resumen

Al transcribir audio, recibirás transcripciones parciales y confirmadas.

• Transcripciones parciales: los resultados provisionales de la transcripción.
• Transcripciones confirmadas: los resultados finales del segmento de transcripción, que se envían al recibir un mensaje de «commit». Una sesión puede tener varias transcripciones confirmadas.

La transcripción confirmada puede incluir opcionalmente marcas de tiempo por palabra. Solo se recibe cuando la opción «include timestamps» está configurada 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
))

Estrategias de confirmación

Al enviar fragmentos de audio mediante WebSocket, puedes confirmar segmentos de transcripción de dos formas: confirmación manual o detección de actividad de voz (VAD).

Confirmación manual

Con la estrategia de confirmación manual, controlas cuándo confirmar los segmentos de transcripción. Esta es la estrategia predeterminada. Al confirmar un segmento, se borra la transcripción acumulada ya procesada y se inicia un segmento nuevo sin perder el contexto. Para mejorar la latencia, es recomendable confirmar cada 20-30 segundos. Incluso si no confirmas manualmente, el modelo confirma automáticamente tras aproximadamente 36 segundos de audio acumulado.

Para obtener los mejores resultados, confirma durante periodos de silencio o en otro punto lógico, como al finalizar un turno.

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

Envío de contexto de texto anterior

Al enviar audio para transcribir, puedes enviar contexto de texto anterior junto con el primer fragmento de audio para ayudar al modelo a entender el contexto de la conversación. Esto resulta útil en varios casos:

• Texto del agente para casos de uso de IA conversacional: permite al modelo entender más fácilmente el contexto de la conversación y generar mejores transcripciones.
• Reconexión tras un error de red: permite al modelo seguir transcribiendo y usar el texto anterior como guía.
• Información contextual general: una descripción breve de lo que tratará la transcripción ayuda al modelo a entender el contexto.

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

Detección de actividad de voz (VAD)

Con la estrategia VAD, el motor de transcripción detecta automáticamente los segmentos de voz y silencio. Cuando se alcanza un umbral de silencio, el motor de transcripción confirma el segmento automáticamente.

Al transcribir audio del micrófono en la integración del lado del cliente, se recomienda usar la estrategia VAD.

vad_silence_threshold_secs acepta de 0.192 a 3.0 segundos. Los SDK de JavaScript y React solo aceptan 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,
});

Filtrar audio de fondo

Configura el parámetro de consulta filter_background_audio=true para reducir las activaciones falsas causadas por voces de fondo, como conversaciones cercanas, y ruido ambiental. Con el filtrado activado, la detección de actividad de voz utiliza un modelo ajustado para ignorar las voces de fondo, y vad_threshold se establece de forma predeterminada en 0.15, a menos que lo configures tú.

El filtrado no cambia la facturación: se factura todo el audio que transmitas, incluido el audio que el filtro ignora.

Mantener la conexión activa durante el silencio

Los SDK oficiales no interrumpen la conexión cuando no llegan mensajes, así que la mayoría de integraciones no necesitan esto. Si tu propio cliente WebSocket, o un proxy o equilibrador de carga intermedio, cierra la conexión cuando no llegan tramas durante un tiempo, pasa el parámetro de consulta opcional keepalive_interval_ms al conectarte. Esto es importante durante periodos largos de silencio, por ejemplo, en una llamada telefónica con pausas de 10-15 segundos. Aproximadamente una vez por intervalo, el servidor envía un partial_transcript de mantenimiento: vacío (text: "") si el segmento actual no tiene texto sin confirmar, o una repetición del último texto parcial si lo tiene.

• Acepta un número entero entre 500 y 10000 (milisegundos). Está desactivado de forma predeterminada; omite el parámetro para mantener el comportamiento actual.
• Los valores fuera de rango o no enteros hacen que el servidor envíe un error invalid_request y cierre la conexión.
• Los mensajes de mantenimiento dependen de que el modelo procese realmente el audio silencioso que envías, no de un temporizador continuo, por lo que también confirman que la ruta de transcripción sigue activa.
• El audio se procesa en fragmentos de aproximadamente 1 segundo, así que los mensajes de mantenimiento llegan aproximadamente una vez por intervalo redondeado a esa cadencia (por ejemplo, 1000 se activa aproximadamente una vez por segundo y 3000, aproximadamente cada 3 segundos). El primer mensaje de mantenimiento de una sesión llega unos 2 segundos después de iniciarse, ya que el servidor almacena en búfer los primeros ~2 segundos de audio antes de transcribir. Configura el intervalo como máximo en alrededor de un tercio de tu propio tiempo de espera de lectura para dejar margen.
• El text de un mensaje de mantenimiento solo está vacío cuando el segmento actual aún no tiene texto sin confirmar. Si hay una pausa después de hablar pero antes de confirmar —algo más visible con filter_background_audio=true o en modo de confirmación manual sin confirmar—, el mensaje de mantenimiento repite el último texto parcial, por lo que nunca borra el texto provisional. Tras una confirmación, los mensajes de mantenimiento vuelven a estar vacíos hasta que llega nueva voz.
• Funciona tanto con commit_strategy=manual como con commit_strategy=vad, y con filter_background_audio=true. No afecta a la facturación más allá del audio que ya estés transmitiendo.
• La config del mensaje session_started devuelve keepalive_interval_ms (null cuando está desactivado).

Añade el parámetro a la URL de WebSocket:

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

Formatos de audio compatibles

Prácticas recomendadas

Calidad del audio

• Para obtener los mejores resultados, usa una frecuencia de muestreo de 16 kHz para lograr un equilibrio óptimo entre calidad y ancho de banda.
• Asegúrate de que la entrada de audio sea limpia y tenga un ruido de fondo mínimo.
• Usa una ganancia de micrófono adecuada para evitar la saturación.
• Por el momento, solo se admite audio mono.

Tamaño de los fragmentos

• Envía fragmentos de audio de entre 0.1 y 1 segundo para un streaming fluido.
• Los fragmentos más pequeños reducen la latencia, pero generan más sobrecarga.
• Los fragmentos más grandes son más eficientes, pero pueden introducir latencia.

Próximos pasos