Uso

O SDK Sofya Transcription fornece uma solução robusta e flexível para transcrição de áudio em tempo real. Este guia ajudará você a começar a usar o SDK em seus projetos.

Uso Básico

Aqui está um exemplo básico de como usar o Sofya Transcription em seu projeto:

1. Importe a Biblioteca:

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

2. Crie uma Instância do Serviço de Transcrição:

   // Usando conexão com chave de API
   const transcriber = new SofyaTranscriber({
     apiKey: 'SUA_CHAVE_API',
     config: {
       language: 'pt-BR'
     }
   });
   
   // Ou usando um provedor específico
   const transcriber = new SofyaTranscriber({
     provider: 'sofya_compliance',
     endpoint: 'SEU_ENDPOINT',
     config: {
       language: 'pt-BR',
       token: 'SEU_TOKEN',
       compartmentId: 'SEU_COMPARTMENT_ID',
       region: 'SUA_REGIAO'
     }
   });

3. Inicialize e Inicie a Transcrição:

   // Aguarde o transcriber estar pronto
   transcriber.on('ready', () => {
     // Obtenha o fluxo de mídia
     navigator.mediaDevices.getUserMedia({ audio: true })
       .then(mediaStream => {
         // Inicie a transcrição
         transcriber.startTranscription(mediaStream);
       })
       .catch(error => {
         console.error('Erro ao acessar o microfone:', error);
       });
   });

4. Gerencie Eventos de Transcrição:

   transcriber.on('recognizing', (text) => {
     console.log('Reconhecendo: ' + text);
   });
   
   transcriber.on('recognized', (text) => {
     console.log('Reconhecido: ' + text);
   });
   
   transcriber.on('error', (error) => {
     console.error('Erro na transcrição:', error);
   });
   
   transcriber.on('stopped', () => {
     console.log('Transcrição parada');
   });

5. Controle a Transcrição:

   // Pause a transcrição
   transcriber.pauseTranscription();
   
   // Retome a transcrição
   transcriber.resumeTranscription();
   
   // Pare a transcrição
   transcriber.stopTranscription();

Tratamento de Erros

O SDK Sofya Transcription fornece tratamento de erros abrangente para garantir uma experiência de transcrição robusta e confiável. O SDK usa uma combinação de lançamento de erros, emissão de eventos e registro para lidar com erros em diferentes estágios do processo de transcrição.

Estratégias de Tratamento de Erros

1. Erros de Validação

   • Chave de API ausente
   • Endpoint ausente para conexão com provedor
   • Configuração ausente para conexão com provedor
   • Objeto de conexão inválido

2. Erros de Conexão

   • Falha de autenticação
   • Problemas de conectividade de rede
   • Indisponibilidade do serviço do provedor
   • Configuração inválida do provedor

3. Erros de Transcrição

   • Acesso ao microfone negado
   • Erros de processamento de áudio
   • Erros do serviço do provedor durante a transcrição

Melhores Práticas para Tratamento de Erros

1. Sempre Escute Eventos de Erro

   transcriber.on('error', (error) => {
     console.error('Erro na transcrição:', error);
     // Trate o erro apropriadamente
   });

2. Use Blocos Try-Catch para Inicialização

   try {
     const transcriber = new SofyaTranscriber({
       apiKey: 'SUA_CHAVE_API',
       config: {
         language: 'pt-BR'
       }
     });
     
     // Use o transcriber
   } catch (error) {
     console.error('Falha ao inicializar o transcriber:', error);
     // Trate o erro apropriadamente
   }

3. Verifique o Evento Ready Antes de Iniciar a Transcrição

   transcriber.on('ready', () => {
     console.log('Serviço de transcrição está pronto');
     
     // Obtenha o fluxo de mídia e inicie a transcrição
     navigator.mediaDevices.getUserMedia({ audio: true })
       .then(mediaStream => {
         transcriber.startTranscription(mediaStream);
       })
       .catch(error => {
         console.error('Erro ao acessar o microfone:', error);
         // Trate o erro apropriadamente
       });
   });

4. Implemente Lógica de Tentativa para Operações Críticas

   function startTranscriptionWithRetry(transcriber, mediaStream, maxRetries = 3) {
     let retryCount = 0;
     
     function attemptStart() {
       try {
         transcriber.startTranscription(mediaStream);
       } catch (error) {
         console.error(`Falha ao iniciar a transcrição (tentativa ${retryCount + 1}/${maxRetries}):`, error);
         
         if (retryCount < maxRetries) {
           retryCount++;
           setTimeout(attemptStart, 1000); // Tente novamente após 1 segundo
         } else {
           console.error('Falha ao iniciar a transcrição após múltiplas tentativas');
           // Trate o erro apropriadamente
         }
       }
     }
     
     attemptStart();
   }

Cenários Comuns de Erro e Soluções

1. Falha na Autenticação da Chave de API

   • Mensagem de Erro: "Não foi possível autenticar. Por favor, valide sua chave de API e tente novamente."
   • Solução: Verifique se a chave de API está correta e não expirou. Se o problema persistir, entre em contato com o suporte da Sofya.

2. Falha na Conexão com o Provedor

   • Mensagem de Erro: "Falha ao conectar a qualquer provedor. Por favor, verifique sua chave de API e tente novamente."
   • Solução: Verifique sua conectividade de rede e confirme se os serviços do provedor estão disponíveis. Se o problema persistir, tente usar um provedor diferente ou entre em contato com o suporte da Sofya.

3. Acesso ao Microfone Negado

   • Mensagem de Erro: "Erro ao acessar o microfone: NotAllowedError"
   • Solução: Certifique-se de que o usuário concedeu permissão para acessar o microfone. Se a permissão foi negada, o usuário precisará conceder permissão através das configurações do navegador.

4. Erro no Serviço de Transcrição

   • Mensagem de Erro: "Erro no serviço de transcrição: [erro específico do provedor]"
   • Solução: Verifique a mensagem de erro específica do provedor para obter detalhes. Problemas comuns incluem configuração inválida, problemas de conectividade de rede ou indisponibilidade do serviço do provedor.