Pular para o conteúdo principal

Guia de uso rápido

Esse guia mostra o básico que você precisa fazer para ter o reconhecimento de voz da Iara funcionando em sua aplicação web.

OBS: esse guia assume que você já tem o SDK javascript e o serviço local (ALS) da Iara já integrados/instalados. Se esse não for o caso, dê uma olhada na página Instalação.

1. Esqueleto básico​

Dada a aplicação web abaixo:

<html>
<head>
  <!-- Iara Speech SDK: https://developers.iarahealth.com/javascript/docs/geral-instalacao -->
  <script src="https://cdn.iarahealth.com/sdk/javascript/1.9.0/iara-speech.min.js"></script>
</head>
<body>
  <button id="btnStart">Iniciar</button>
  <button id="btnStop">Parar</button>

  <script type="text/javascript">
    // Código JS da sua aplicação aqui.
  </script>
</body>

Para simplificar o entendimento, qualquer código Javascript de utilização da Iara mostrado daqui para frente ocupa o lugar do comentário // Código JS da sua aplicação aqui do exemplo acima.

Dica: dê uma olhada nos exemplos de código disponíveis nesse SDK. Você pode utilizar algum deles como base para seu projeto ou integração.

2. Inicialização e autendicação​

O primeiro passo é instanciar e inicializar o reconhecedor da Iara com seus dados de acesso, i.e. userId e apiToken. Você deve ter recebido seu userId e apiToken quando criou uma conta para utilizar o SDK.

var myUserId = 'meu@email.com'; // use o seu userId
var myApiToken = '197765800edb8affcb44a7ae7b4ff0a3'; // use o seu apiToken

// Instancia o reconhecedor da Iara
var recognition = new IaraSpeechRecognition();

// Inicializa o SDK, i.e. autenticação, checa o ALS, baixa modelo de voz, etc.
recognition.init({
    userId: myUserId,
    apiToken: myApiToken
}).done(function(e) {
    // Tudo certo, o reconhecimento pode começar.
}).fail(function(e) {
    // Algum problema aconteceu.
});

Se tudo for inicializado sem problemas, o método done() será chamado, indicando que o SDK está pronto para fazer o reconhecimento de voz. Se algum problema acontecer, o método fail() será chamado com as informações do erro.

Dica: cada usuário da sua aplicação deve possuir um userId próprio, porque o reconhecimento de voz da Iara é personalizado por usuário. O valor do userId identifica unicamente uma pessoa e será usada para download e ajuste de um modelo de voz próprio para o usuário em questão. Veja a seção Autenticação (API Iara) para saber mais.

Você pode acompanhar em detalhes os passos de inicialização feitos pelo SDK através das chamadas ao método progress(), descrito na próxima seção. A utilização do método progress() é opcional, mas é recomendada para garantir uma boa experiência de uso ao usuário de sua aplicação.

IMPORTANTE: Usuários diferentes não devem utilizar um userId com o mesmo valor. Isso degrada a acurácia do reconhecimento de voz.

2.1 Eventos de inicialização via progress() (opcional)​

Depois de autenticar o usuário, o SDK fará diversas incializações internas, como checar se o ALS está rodando, baixar o modelo de voz do usuário, etc.

O método progress() é chamado várias vezes, uma para cada passo de inicialização feito durante a inicialização:

var recognition = new IaraSpeechRecognition();

recognition.init({
    // (...)
}).done(function(e) {
    // (...)
}).fail(function(e) {
    // (...)
}).progress(function(e) {
    console.log('Iara está inicializando: ' + e.detail.type, e.detail);
})

O método progress() será chamado, por exemplo, quando o SDK detectar que o ALS está rodando no computador do usuário, quando o modelo de voz do usuário especificado estiver sendo baixado, quando o modelo de voz foi baixado corretamente, etc.

Veja a página Inicialização e Eventos para saber mais sobre os passos que ocorrem durante a inicialização.

2.2 Configurações do reconhecedor (opcional)​

Você pode configurar o reconhecedor de voz para as suas necessidades, ex.: se quer ou não resultados intermediários de reconhecimento:

var recognition = new IaraSpeechRecognition();

recognition.init({
    userId: 'meu@email.com',
    apiToken: '197765800edb8affcb44a7ae7b4ff0a3',
    interimResults: false,
    input: 'speechmike'
})

Se você não alterar as configurações específicas, os valores padrão serão utilizados. Para mais informações, veja a página Inicialização.

Dica: veja a página Dispositivos de audio para mais informações sobre utilização e configuração de dispositivos de entrada de audio, como o SpeechMike®.

3. Reconhecimento de voz​

Assumindo que tudo foi inicializado sem problemas, você pode iniciar o reconhecimento de voz depois que done() for chamado:

var recognition = new IaraSpeechRecognition();
recognition.init({
    // (...)
}).done(function(e) {
    // O evento principal do reconhecimento de voz é o "onresult", chamado quando
    // algum audio na entrada é reconhecido.
    recognition.onresult = function(event) {
        // O parâmetro "event" contem uma propriedade chamada "detail", que é um
        // objeto IaraSpeechRecognitionDetail. A propriedade "transcript" desse
        // objeto contém o texto que a Iara reconheceu baseados no audio de entrada.
        var text = event.detail.transcript.toLowerCase();
        console.log('Texto reconhecido: ' + text);
    };

    // Configuramos botões para ativar/desativar o reconhecimento de audio.
    var botaoStart = document.getElementById('btnStart');
    var botaoStop = document.getElementById('btnStop');

    botaoStart.addEventListener('click', function() {
        recognition.start();
    });

    botaoStop.addEventListener('click', function() {
        recognition.stop();
    });
});

No exemplo acima, quando o reconhecedor chamar o método done() para indiciar que tudo está corretamente configurado, duas atividades são feitas. Na primeira, cria-se uma função para tratar o evento onresult, que é chamado quando algum audio é reconhecido.

Na segunda atividade, dois botões HTML são configurados para ligar e desligar o reconhecimento de voz da Iara. O primeiro botão (cujo id é btnStart) é configurado para ativar o reconhecimento de voz quando for clicado. Isto é feito através do evento click do botão, que quando é disparado, faz uma chamada a recognition.start(), iniciando o reconhecimento de voz. De forma similar, o botão de id btnStop, quando for clicado, chama recognition.stop(), o que termina a operação de reconhecimento. A Iara não fará novos reconhecimentos no dispositivo de entrada de audio enquanto recognition.start() não for chamado novamente.

Depois que recognition.start() é chamado, o evento onresult é invocado repetidamente com um intervalo variável, que depende dos recursos computacionais disponíveis no computador do usuário.

Esqueleto básico completo​

Abaixo está o esqueleto de uma aplicação básica, mas completa, que utiliza o SDK:

<html>
<head>
  <!-- Iara Speech SDK: https://developers.iarahealth.com/javascript/docs/geral-instalacao -->
  <script src="https://cdn.iarahealth.com/sdk/javascript/1.9.0/iara-speech.min.js"></script>
</head>
<body>

  <button id="btnStart">Iniciar</button>
  <button id="btnStop">Parar</button>

  <script type="text/javascript">
    var myUserId = 'meu@email.com'; // use o seu userId
    var myApiToken = '197765800edb8affcb44a7ae7b4ff0a3'; // use o seu apiToken

    // Instancia o reconhecedor da Iara
    var recognition = new IaraSpeechRecognition();

    // Inicializa o SDK, i.e. autenticação, checa o ALS, baixa modelo de voz, etc.
    recognition.init({
        userId: myUserId,
        apiToken: myApiToken
    }).done(function(e) {
        // O evento principal do reconhecimento de voz é o "onresult", chamado quando
        // algum audio na entrada é reconhecido.
        recognition.onresult = function(event) {
            // O parâmetro "event" contem uma propriedade chamada "detail", que é um
            // objeto IaraSpeechRecognitionDetail. A propriedade "transcript" desse
            // objeto contém o texto que a Iara reconheceu baseados no audio de entrada.
            var text = event.detail.transcript.toLowerCase();
            console.log('Texto reconhecido: ' + text);
        };

        // Configuramos botões para ativar/desativar o reconhecimento de audio.
        var botaoStart = document.getElementById('btnStart');
        var botaoStop = document.getElementById('btnStop');

        botaoStart.addEventListener('click', function() {
            recognition.start();
        });

        botaoStop.addEventListener('click', function() {
            recognition.stop();
        });
    }).fail(function(e) {
        // Algum problema aconteceu. O parâmetro "e" contem várias informações sobre o erro.
        console.error('Algum problema na inicialização da Iara: ' + e.detail.userMessage);
    }).progress(function(e) {
        // Esse método é invocado várias vezes pelo SDK ao longo de sua inicialização.
        // Você pode usar ele para acompanhar os passos da inicialização, para informar
        // ao seu usuário que seu modelo de voz está sendo baixado, por exemplo.
        console.debug('A Iara está inicializando: ' + e.detail.type);
    });
  </script>
</body>