Transcripciones y estrategias de confirmación

Descripción general

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

• Transcripciones parciales: resultados provisionales de la transcripción.
• Transcripciones confirmadas: resultados finales del segmento de transcripción que se envían al recibir un mensaje de “confirmación”. Una sesión puede tener varias transcripciones confirmadas.

La transcripción confirmada puede incluir opcionalmente marcas de tiempo a nivel de palabra. Solo se recibe cuando la opción “incluir marcas de tiempo” 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 a través de WebSocket, los segmentos de transcripción se pueden confirmar de dos formas: confirmación manual o detección de actividad de voz (VAD).

Confirmación manual

Con la estrategia de confirmación manual, tú controlas cuándo confirmar los segmentos de transcripción. Esta es la estrategia que se usa de forma predeterminada. Al confirmar un segmento, se borra la transcripción acumulada procesada y se inicia un nuevo segmento sin perder el contexto. Confirmar cada 20-30 segundos es una buena práctica para mejorar la latencia. Aunque no confirmes 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 un cambio de turno en la conversación.

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

Enviar contexto de texto previo

Al enviar audio para transcribir, puedes enviar contexto de texto previo junto con el primer fragmento de audio para ayudar al modelo a entender el contexto de la voz. Esto resulta útil en algunos 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 breve descripción de qué 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 automáticamente el segmento de transcripción.

Al transcribir audio del micrófono en la integración del lado del cliente, se recomienda usar la estrategia 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,
});

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 lo necesitan. Si tu propio cliente de 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 una partial_transcript de mantenimiento: vacía (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 se activan porque el modelo procesa realmente el audio silencioso que envías, no mediante un temporizador continuo, por lo que también confirman que la ruta de transcripción está activa.
• El audio se procesa en fragmentos de aproximadamente 1 segundo, así que los mensajes de mantenimiento llegan aproximadamente una vez por intervalo, ajustados 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 iniciarla, ya que el servidor almacena en búfer los primeros ~2 segundos de audio antes de transcribir. Configura el intervalo como máximo en torno a 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 todavía no tiene texto sin confirmar. Si se produce una pausa después de hablar pero antes de confirmar —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 llegue 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

Buenas prácticas

Calidad de 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 el mínimo ruido de fondo.
• 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 una transmisión fluida.
• 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