Uso

El SDK Sofya Transcription proporciona una solución robusta y flexible para la transcripción de audio en tiempo real. Esta guía le ayudará a comenzar a usar el SDK en sus proyectos.

Nota de migración

¿Qué cambió?

• El método stopTranscription ahora es asíncrono y devuelve una Promise<void>.
• Ahora debe usar await o .then() al llamar a stopTranscription para asegurarse de que el proceso de transcripción se detenga completamente antes de continuar.

¿Por qué se cambió?

• Este cambio garantiza que todas las operaciones de limpieza (como finalizar transcripciones en curso) se completen antes de que su código continúe. Previene condiciones de carrera y fugas de recursos que podrían ocurrir si el método fuera síncrono.

Cómo migrar

Antes:

transcriber.stopTranscription();
// Continuar inmediatamente con otra lógica

Después:

await transcriber.stopTranscription();
// o
transcriber.stopTranscription().then(() => {
  // Continuar con otra lógica
});

Ejemplo en React:

const stopTranscription = async () => {
  if (transcriber.current) {
    await transcriber.current.stopTranscription();
    transcriber.current = null;
  }
};

Acción requerida

• Actualice todos los usos de stopTranscription en su base de código para manejar la Promise devuelta.
• Si utiliza este método dentro de controladores de eventos o componentes React, haga que el controlador sea async y use await.

Resumen:
stopTranscription ahora es asíncrono. Siempre utilice await o .then() para asegurar una limpieza adecuada. Este cambio mejora la confiabilidad y la gestión de recursos en sus flujos de trabajo de transcripción.

Uso Básico

Aquí hay un ejemplo básico de cómo usar Sofya Transcription en su proyecto:

1. Importe la Biblioteca:

   import { MediaElementAudioCapture, SofyaTranscriber } from 'sofya.transcription';

2. Cree una Instancia del Servicio de Transcripción:

   // Usando conexión con clave de API
   const transcriber = new SofyaTranscriber({
     apiKey: 'SU_CLAVE_API',
     config: {
       language: 'es-419'
     }
   });
   
   // O usando un proveedor específico
   const transcriber = new SofyaTranscriber({
     provider: 'sofya_compliance',
     endpoint: 'SU_ENDPOINT',
     config: {
       language: 'es-419',
       token: 'SU_TOKEN',
       compartmentId: 'SU_COMPARTMENT_ID',
       region: 'SU_REGION'
     }
   });

3. Inicialice e Inicie la Transcripción:

   // Espere a que el transcriber esté listo
   transcriber.on('ready', () => {
     // Obtenga el flujo de medios
     navigator.mediaDevices.getUserMedia({ audio: true })
       .then(mediaStream => {
         // Inicie la transcripción
         transcriber.startTranscription(mediaStream);
       })
       .catch(error => {
         console.error('Error al acceder al micrófono:', error);
       });
   });

4. Gestione Eventos de Transcripción:

   transcriber.on('recognizing', (text) => {
     console.log('Reconociendo: ' + text);
   });
   
   transcriber.on('recognized', (text) => {
     console.log('Reconocido: ' + text);
   });
   
   transcriber.on('error', (error) => {
     console.error('Error en la transcripción:', error);
   });
   
   transcriber.on('stopped', () => {
     console.log('Transcripción detenida');
   });

Identificar la Consulta y Pedir la Grabación

Si su aplicación necesita asociar una transcripción con una consulta específica, o pedirle al servidor que grabe la sesión, configure external_id y record en la conexión y escuche el evento stt_session:

import { SofyaTranscriber } from 'sofya.transcription';

const transcriber = new SofyaTranscriber({
  apiKey: 'SU_CLAVE_API',
  config: {
    language: 'es-419',
    external_id: consultation.id,   // el mismo valor en cada reconexión
    record: true,
  },
});

const sttSessionIds: string[] = [];
transcriber.on('stt_session', ({ sttSessionId }) => sttSessionIds.push(sttSessionId));

transcriber.startTranscription(mediaStream);
// …
await transcriber.stopTranscription();
// sttSessionIds === transcriber.getSttSessionIds()

Guarde external_id y los sttSessionId junto con la consulta: son las dos claves para localizar la grabación después. Consulte Conexiones para la referencia completa de external_id/record y SofyaTranscriber para el evento stt_session y los métodos getSttSessionId/getSttSessionIds.

Autenticando una Conexión Directa

Cuando conectas directamente a un endpoint ({ provider, endpoint, config }), puedes enviar la clave de API del STT con la config opcional auth. El transporte por defecto coloca la clave en un subprotocolo extra del WebSocket:

import { SofyaTranscriber } from 'sofya.transcription';

const transcriber = new SofyaTranscriber({
  provider: 'sofya_as_service',
  endpoint: '<wss-url>',
  config: {
    language: 'es-ES',
    auth: { type: 'api_key', key: '<clave-api-stt>' },
  },
});

El SDK envía ["sofya-stt.v1", "x-api-key.<clave>"]: tus protocols siguen primero y el token de la clave va siempre al final, porque el servidor rechaza el handshake en el que la clave es el único subprotocolo.

Si la clave no puede ser un token RFC 6455 (contiene =, /, ,, espacios o comillas), usa el transporte por query:

const transcriber = new SofyaTranscriber({
  provider: 'sofya_as_service',
  endpoint: '<wss-url>',
  config: {
    language: 'es-ES',
    auth: { type: 'api_key', key: '<clave-api-stt>', transport: 'query' },
  },
});

Eso añade x-api-key=<clave> a la URL de tiempo real, que proxies y navegadores registran en sus logs, así que prefiere el transporte por subprotocolo. Una clave rechazada por el servidor cierra la conexión con el código 4401: el SDK emite error con un SofyaAuthError y deja de reconectar. Consulta Conexiones para la referencia completa.

Autenticando con un JWT

Si tus usuarios se autentican con JWT, pásalo con type: "jwt" en lugar de la clave de API — el token sin procesar, sin Bearer , porque el SDK añade el prefijo:

const transcriber = new SofyaTranscriber({
  provider: 'sofya_as_service',
  endpoint: '<wss-url>',
  config: {
    language: 'pt-BR',
    auth: { type: 'jwt', token: '<jwt>' },
  },
});

El JWT va como primer subprotocolo del WebSocket y como Authorization: Bearer <jwt> en el batch, el batch reprocess y el audit ingestion. Reemplaza a config.token, que está obsoleto. Consulta Conexiones para la referencia completa.