Inicialização

A inicilização do SDK é composta de duas categorias principais: informações para autenticação (obrigatórias) e configuração do reconhecimento (opcional), que inclui a escolha do dispositivo de audio de entrada, por exemplo.

Essa página descreve a configuração e inicialização do reconhecimento, mencionando de forma superficial os detalhes relacionados à parte de autenciação.

Veja a página Autenticação (API Iara) para mais informações relacionadas à autenticação.

Parâmetros de inicialização

A inicialização do reconhecedor da Iara é feita depois de sua instanciação através da chamada ao método init(). Esse método recebe um objeto como parâmetro, cujas propriedades (e seus valores) representam os parâmetros de inicialização:

var recognition = new IaraSpeechRecognition();

// Inicializa o SDK
recognition.init({
  userId: "meu@email.com",
  apiToken: "197765800edb8affcb44a7ae7b4ff0a3",
});

O reconhecedor de voz pode ser configurado para necessidades específicas de sua aplicação. Você pode definir, por exemplo, se resultados intermediários de reconhecimento serão produzidos, ou escolher o idioma que o reconhecedor deve trabalhar.

As sessões a seguir explicam cada um dos parâmetros de inicialização disponíveis.

userId e apiToken - autenticação

As únicas propriedades obrigatórias do objeto passado ao init() são a userId e apiToken, que descrevem as informações de autenticação.

Você precisa ter um userId e apiToken da API Iara para utilizar o SDK. Escreva para contato@iarahealth.com para obter seus dados de acesso.

Se essas propriedades não existirem no objeto de inicialização (ou se seus valores forem inválidos), o SDK apresentará um erro. Se tudo estiver correto, o SDK estará pronto para reconhecer audios.

lang - linguagem de reconhecimento (default "pt-BR")

O parâmetro lang permite que você defina o idioma dos audios de entrada que o reconhecedor está tentando reconhecer:

var recognition = new IaraSpeechRecognition();

recognition.init({
  userId: "meu@email.com",
  apiToken: "197765800edb8affcb44a7ae7b4ff0a3",
  lang: "pt-BR", // idioma dos audios de entrada
});

Se lang não for informado, o reconhecedor assume que os audios de entrada são do idioma Português brasileiro (pt-BR). As linguagens suportadas pela Iara estão listadas abaixo:

Idioma	Sigla	Disponível	Observação
Português (Brasil)	pt-BR	Sim	Idioma padrão utilizado caso nenhum idioma seja informado.
Português (Europeu)	pt-PT	Não	Viabilidade sendo pesquisada pela equipe de desenvolvimento.

IMPORTANTE: atualmente o reconhecimento de voz da Iara funciona apenas com Português brasileiro (pt-BR). A equipe de desenvolvimento está em constante trabalho para ampliar as linguagens disponíveis. Fique atento a essa página para acompanhar nosso progresso.

interimResults - reconhecimento intermediário (default false)

O parâmetro interimResults define se o SDK produzirá resultados intermediários de reconhecimento de voz ou não:

var recognition = new IaraSpeechRecognition();

recognition.init({
  userId: "meu@email.com",
  apiToken: "197765800edb8affcb44a7ae7b4ff0a3",
  interimResults: false, // se resultados intermediários do reconhecimento
  // de voz devem ser produzidos ou não.
});

Resultados intermediários são emitidos em intervalos não definíveis que dependem do reconhimentos que a Iara faz do audio de entrada e do poder de processamento do computador do usuário. Conforme audios são capturados e processados, se interimResults for true, o SDK emitirá o resultado corrente do reconhecimento.

Se interimResults for false (comportamento padrão), resultados intermediários não são emitidos, apenas o resultado final depois que stop() for invocado.

Veja a seção Reconhecimento de voz e o exemplo de código interim-recognition para saber mais sobre reconhecimento de voz com resultados intermediários.

input - dispositivo de entrada de audio (default "auto")

O SDK permite o uso de diversos dispositivos de entrada de audio, incluise microfones externos USB como o SpeechMike®. Você pode configurar o dispositivo de entrada de audio através do parâmetro input:

var recognition = new IaraSpeechRecognition();

// Inicializa o SDK
recognition.init({
  userId: "meu@email.com",
  apiToken: "197765800edb8affcb44a7ae7b4ff0a3",
  input: "auto", // Dispositivo de entrada de audio
});

Se o parâmetro input não for informado na inicialização, o SDK será inicializado por padrão como input: 'auto'. Nesse caso, o SDK tentará encontrar o melhor dispositivo de entrada para o ambiente do usuário, com menos passos de configuração possíveis.

Dica: input: 'auto' é a forma mais flexível de inicialização de audio. Nesse caso, o dispositivo com melhor qualidade e menos passos de cofiguruação pelo usuário é escolhido. Veja a página Dispositivos de audio para saber mais.

useVAD - reconhecimento com detecção de voz (default false)

O parâmetro useVAD define se o SDK deverá utilizar o Voice Activity Detection (VAD). Após o usuário iniciar a gravação, o SDK irá pausar e retomar o reconhecimento conforme é detectada a fala:

var recognition = new IaraSpeechRecognition();

recognition.init({
  userId: "meu@email.com",
  apiToken: "197765800edb8affcb44a7ae7b4ff0a3",
  input: "browsermic",
  useVAD: true, // se o reconhecimento deverá utilizar VAD ou não
});

IMPORTANTE: Para o funcionamento do VAD além de passar o useVAD como parâmetro é necessário passar o parâmetro input inicializado como browsermic.

Para saber mais sobre reconhecimento de voz com voice activity detection (VAD) acesse a aba Avançado na seção Detectar atividade de voz (VAD).

Forçando um determinado dispositivo de entrada de audio

Se sua aplicação depende de um dispositivo de entrada em específico, você pode forçar que ele seja escolhido. O exemplo abaixo exige um SpeechMike® como dispositivo de entrada, produzindo um erro de inicialização caso ele não esteja disponível:

var recognition = new IaraSpeechRecognition();

// Inicializa o SDK
recognition
  .init({
    userId: "meu@email.com",
    apiToken: "197765800edb8affcb44a7ae7b4ff0a3",
    input: "speechmike", // força a utilização do SpeechMike® como
    // dispositivo de entrada de audio
  })
  .fail(function (e) {
    console.error("Dispositivo de entrada SpeechMike® não disponível!");
  });

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

Monitorando a inicialização

Você pode acompanhar em detalhes o processo de inicialização do SDK, ex.: se houve erro, em qual parte da inicialização o SDK se encontra, etc. O monitoramento é feito através dos métodos done(), fail() e progress(), chamados junto com o init():

var recognition = new IaraSpeechRecognition();

recognition
  .init({
    userId: "meu@email.com",
    apiToken: "197765800edb8affcb44a7ae7b4ff0a3",
  })
  .done(function (e) {
    // Inicialização finalizada com sucesso
  })
  .fail(function (e) {
    // Inicialização falhou.
  })
  .progress(function (e) {
    // Inicialização está acontecendo
  });

As sessões a seguir explicam em detalhes cada um dos métodos de acompanhamento da inicialização.

done() - sucesso na inicialização

O método done() é invocado quando a inicialização foi finalizada, não houve erros e o SDK está pronto para fazer reconhecimentos de voz.

A incialização do SDK depende de diversos passos, como checar se o ALS está rodando, baixar o modelo de voz do usário informado através do userId, etc. Por essa razão, sua aplicação não conseguirá fazer reconhecimentos de voz enquanto done() não seja invocado.

IMPORTANTE: sua aplicação precisa esperar até que done() seja chamado para poder fazer qualquer reconhecimento de voz.

O método done() recebe como parâmetro um evento cuja propriedade detail do tipo IaraInitDetail contém informações sobre a Iara.

fail() - falha na inicialização

Se qualquer erro acontecer durante a inicialização do SDK, ex. o ALS não foi encontrado, o SDK invocará o método fail(). A chamada a esse método indica que o SDK não consegue fazer reconhecimento de voz no ambiente fornecido.

Veja a página Eventos para saber mais sobre o parâmetro que fail() recebe contendo as informações sobre o erro.

O método fail() recebe como parâmetro um evento cuja propriedade detail do tipo IaraInitDetail contém informações sobre o erro que aconteceu durante a inicialização:

var recognition = new IaraSpeechRecognition();

recognition
  .init({
    // (...)
  })
  .done(function (e) {
    // (...)
  })
  .fail(function (e) {
    // Inicialização falhou. A propriedade "detail" do evento "e" possui as propriedades:
    //
    //  type
    //              tipo do evento, que é IaraInitEvent.FAIL nesse caso.
    //  developerMessage
    //              mensagem de erro voltada a desenvolvedores, com sugestões
    //              de como resolver o problema.
    //  userMessage
    //              mensagem de erro intuitiva, sem termos técnicos, que pode
    //              ser mostrada ao usuário da aplicação.
    //  errorCode
    //              inteiro que indica o código do erro que aconteceu.
    //  moreInfo
    //              link(s) para a documentação do Iara Speech SDK que pode(m)
    //              ajudar com o problema.

    console.error(
      "Erro " +
        e.detail.errorCode +
        ":" +
        e.detail.developerMEssage +
        ". Mais info:" +
        e.detail.moreInfo
    );
    alert(e.userMessage);
  })
  .progress(function (e) {
    // (...)
  });

O evento de erro passado a fail() como parâmetro contém informações uteis a desenvolvedores e usuários de sua aplicação. A propriedade userMessage do evento contém uma mensagem de erro intuitiva, sem termos técnicos, que pode ser mostrada ao usuário da aplicação.

DICA: se fail(e) for chamado, utilize e.detail.developerMessage e e.detail.moreInfo para saber de forma técnica o que aconteceu e como resolver o problema.

Similarmente, a propriedade developerMessage contém uma mensagem de erro voltada a desenvolvedores, com sugestões de como resolver o problema. Nesse contexto, a propriedade errorCode contém um inteiro que indica o código do erro que aconteceu, e moreInfo contém link(s) para a documentação do Iara Speech SDK que pode(m) ajudar com o problema.

progress() - progresso da inicialização

O processo de inicialização do SDK é composto de vários passos, como checar se o ALS está rodando, baixar o modelo de voz do usuário, etc.

Veja a página Eventos para saber mais sobre o parâmetro que progress() recebe contendo as informações de inicialização.

Você pode utilizar as chamadas ao método progress() para companhar esses passos. O método progress() será chamado várias vezes durante a inicialização, uma para cada passo de processo:

// (...)
var recognition = new IaraSpeechRecognition();

recognition
  .init({
    // (...)
  })
  .done(function (e) {
    // (...)
  })
  .fail(function (e) {
    // (...)
  })
  .progress(function (e) {
    // Inicialização está acontecendo. A propriedade "detail" do evento "e"
    // possui as propriedades:
    //
    //  type
    //              tipo do evento, que pode ser qualquer um dos eventos
    //              nomeados como IaraInitEvent.INIT_*.
    //  developerMessage
    //              mensagem voltada a desenvolvedores, descrevendo o passo
    //              de inicialização sendo executado.
    //  userMessage
    //              mensagem intuitiva, sem termos técnicos, que descreve
    //              o passo de inicialização. Ex.: "Seu modelo de voz está
    //              sendo baixado.".
    //  moreInfo
    //              link(s) para a documentação do Iara Speech SDK que explica(m)
    //              o passo de inicialização.
    console.debug(
      "[" + e.detail.type + "] iara iniciando: " + e.detail.developerMessage
    );
    console.log(e.detail.userMessage);
  });

O método progress() será chamado várias vezes antes que done() ou fail() seja finalmente chamado. Por exemplo, progress() será chamado 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.

Como boa prática de usabilidade, recomenda-se que o usuário de sua aplicação seja informado visualmente dos passos de inicialização. Isso evita frustrações por parte do usuário, que não ficará olhando para uma aplicação que parece travada.

Nesse sentido, a propriedade userMessage da propriedade detail do evento passado a progress() contém uma mensagem intuitiva, sem termos técnicos, que descreve o passo de inicialização. Um exemplo de frase é "Seu modelo de voz está sendo baixado.".

Veja a página Exemplos e o exemplo events-listeners que ilustram sobre o uso de progress() da forma recomendada.

De forma similar, a propriedade developerMessage contém uma mensagem voltada a desenvolvedores, descrevendo o passo de inicialização sendo executado. A propriedade moreInfo contém link(s) para a documentação do Iara Speech SDK que explica(m) o passo de inicialização.

Permissão para abrir aplicativos no dispositivo

Após atualizações recentes em navegadores baseados em Chromium, como Google Chrome e Microsoft Edge, o navegador pode solicitar ao usuário uma permissão para permitir que páginas web abram aplicativos instalados no dispositivo.

Caso o usuário recuse essa permissão em "Apps no dispositivo", o SDK passa a emitir um novo evento de erro com o código 60. Esse erro permite que a integração identifique a recusa da permissão e trate o fluxo de forma adequada, por exemplo exibindo uma orientação para que o usuário autorize a abertura do aplicativo externo.

IMPORTANTE: ao tratar erros retornados pelo SDK, verifique o código 60 para identificar esse cenário.