Versão: 0.0.16

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.

Nota de Migração

O que mudou?

O método stopTranscription agora é assíncrono e retorna uma Promise<void>.
Agora é necessário usar await ou .then() ao chamar stopTranscription para garantir que o processo de transcrição seja totalmente finalizado antes de continuar.

Por que isso mudou?

Essa alteração garante que todas as operações de limpeza (como finalizar transcrições em andamento) sejam concluídas antes que seu código continue. Isso previne condições de corrida e vazamentos de recursos que poderiam ocorrer se o método fosse síncrono.

Como migrar

Antes:

transcriber.stopTranscription();
// Continua imediatamente com outra lógica

Depois:

await transcriber.stopTranscription();
// ou
transcriber.stopTranscription().then(() => {
  // Continua com outra lógica
});

Exemplo em React:

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

Ação necessária

Atualize todos os usos de stopTranscription no seu código para lidar com a Promise retornada.
Se você usar esse método dentro de handlers de eventos ou componentes React, torne o handler async e use await.

Resumo:
stopTranscription agora é assíncrono. Sempre utilize await ou .then() para garantir a limpeza adequada. Essa mudança melhora a confiabilidade e o gerenciamento de recursos nos seus fluxos de transcrição.

Uso Básico

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

Importe a Biblioteca:

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

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

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

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

Controle a Transcrição:

// Pause a transcrição
transcriber.pauseTranscription();

// Retome a transcrição
transcriber.resumeTranscription();

// Pare a transcrição
await transcriber.stopTranscription();

Exemplo de Controle Completo:

// Exemplo com fluxo de controle completo
let isPaused = false;

// Inicie a transcrição
transcriber.on('ready', () => {
  navigator.mediaDevices.getUserMedia({ audio: true })
    .then(mediaStream => {
      transcriber.startTranscription(mediaStream);
    });
});

// Funções de controle
const pauseTranscription = () => {
  if (!isPaused) {
    transcriber.pauseTranscription();
    isPaused = true;
    console.log('Transcrição pausada');
  }
};

const resumeTranscription = () => {
  if (isPaused) {
    transcriber.resumeTranscription();
    isPaused = false;
    console.log('Transcrição retomada');
  }
};

const stopTranscription = async () => {
  await transcriber.stopTranscription();
  isPaused = false;
  console.log('Transcrição parada');
};

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

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

Sempre Escute Eventos de Erro

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

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
}

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

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

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

Nota de Migração​

O que mudou?​

Por que isso mudou?​

Como migrar​

Ação necessária​

Uso Básico​

Tratamento de Erros​

Estratégias de Tratamento de Erros​

Melhores Práticas para Tratamento de Erros​

Cenários Comuns de Erro e Soluções​