Initialization

The SDK initiation is composed of two main categories: information to authentication (requires) and recognition configuration (optional), which includes choosing the input audio device, for example.

This page describes the setting and recognizer initialization, mentioning superficially the details linked to authentication.

Check the page Authentication (Iara API) to more information linked to authentication.

Initialization's parameters

The Iara's recognizer initialization is made after his instantiated through method call init(). This method takes an object as a parameter, whose properties (and his values) represents the initialization parameters:

var recognition = new IaraSpeechRecognition();

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

The voice recognizer can be configured to specifics configuration of his application. You can define, for example, if intermediaries results of recognizer will be produced, or chose the language that the recognizer may work out.

The next sessions explain each one of initialization parameters available.

userId and apiToken - authentication

The only required proprieties of passed object init() are userId e apiToken, that describes the information of authentications.

You should have received your userId and apiToken when you had created an account to use the SDK. Write to contato@iarahealth.com to get your login details.

If the proprieties don't exist on initialization object (or if his values are invalid), the SDK show you an error. If everything successfully, the SDK will be ready to recognizer your audios.

lang - recognizer language (default "pt-BR")

The parameter lang allows that you define his audios language of input default that the recognizer is trying recognize:

var recognition = new IaraSpeechRecognition();

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

If lang don't be informed, the recognizer identify that audios default are Portugues Brazilian language (pt-BR). The language supported by Iara are below:

Language	Acronym	Available	Note
Portuguese (Brazil)	pt-BR	Yes	Pattern language used if no language is provided.
Portuguese (Europe)	pt-PT	Not	Feasibility being researched by the development team.

IMPORTANT: currently Iara's voice recognition works only with Brazilian portuguese (pt-BR). The development team is constantly working to expand the available languages. Keep an eye on this page to track our progress.

interimResults - intermediary recognizer (default false)

The parameter interimResults define whether SDK will produce intermediary voice's recognizer results or not:

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

Intermediate results are issued at indefinite intervals that depend on the recognition that Iara makes of default audio and of the processing power of the user's computer. As audios are captured and processed, whether interimResults will true, the SDK will be sent the current recognition result.

Whether interimResults will false (pattern comportment), intermediate results aren't sent, just after final result that stop() will be called.

Check the session voice recognizer and the code example interim-recognition to learn more about intermediate voice recognice results.

input - default audio device (default "auto")

SDK allows the use of several audio input devices, including external USB microphones such as SpeechMike®. You can configure the audio input device through the parameter input:

var recognition = new IaraSpeechRecognition();

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

If the parameter input don't be informed on initialization, the SDK will be initialized of pattern mode like input: 'auto'. In this case the SDK is trying to find the best input device to user environment, with fewer settings steps possible.

Tip: input: 'auto' Is the flexible audio initialization way. In this case, the device with the best quality and the fewest configuration steps by the user is chosen. Check the page audio devices to learn more.

useVAD recognize with voice detection (default false)

The parameter useVAD define if SDK sould use Voice Activity Detection (VAD). After user plays record, SDK will pause and restart conform recognize as speech is detected:

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

IMPORTANT: For VAD work on in addition to passing useVAD as a parameter, it is necessary to pass the parameter input initialized how browsermic.

To learn more about voice recognize with voice activity detection (VAD) acess Avançado on Voice Activity Detection (VAD).

Forcing a specific input audio device

If your application depending on from an input device specific, you can force him for that he be chosen. The next example requires an input device SpeechMike®, producing a boot error if isn't available:

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

Tip check the page audio device to learn more about the settings and use of audio devices.

Checking initialization

You can follow details about the SDK initialization process, ex: if there happened an error, in which part of the initialization the SDK is found, etc. The check out is made through the methods done(), fail() and progress(), called along with the init():

var recognition = new IaraSpeechRecognition();

recognition
  .init({
    userId: "meu@email.com",
    apiToken: "197765800edb8affcb44a7ae7b4ff0a3",
  })
  .done(function (e) {
    // Inicialização finalizada com sucesso
  })
  .fail(function (e) {
    // Initialization has failed.
  })
  .progress(function (e) {
    // Initialization is happening
  });

The next sections explain in details each of the methods initialization.

done() - initialization successfully

Method done() is called when initialization is complete, there are no errors, and the SDK is ready to do voice recognition.

SDK initialization depends on several steps, such as checking if ALS it's been running, download user voice model through userId, etc. Because that, his application don't get voice recognize done() while don't be called.

IMPORTANT: application need wait until done() be called to do any voice recognize.

Method done() have how parameter an event whose property detail type IaraInitDetail contains Iara's information.

fail() initialization failed

If happen any error during SDK initialization, ex ALS is not found, the SDK called the method fail(). Calling this method indicates that the SDK is unable to do voice recognition in the given environment.

Check the page events to learn more about parameter fail() that have information about the error.

Method fail() have how parameter an event whose property detail type IaraInitDetail contains information about the error happened during initialization process:

var recognition = new IaraSpeechRecognition();

recognition
  .init({
    // (...)
  })
  .done(function (e) {
    // (...)
  })
  .fail(function (e) {
    // Initialization has failed. The property "detail" of event "and" have the properties:
    //
    //  type
    //              event type, that's it IaraInitEvent.FAIL in this case.
    //  developerMessage
    //              message to developer, with suggestions
    //              about how fix the problem.
    //  userMessage
    //              intuitive error message, without technical terms, that can
    //              be shown to the application user.
    //  errorCode
    //              integer that indicates the error code that occurred.
    //  moreInfo
    //              link(s) to Iara's Speech SDK documentation that can 
    //             help to fix the problem.

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

The past error event fail() as parameter contains useful information to developers and users of your application. The propriety userMessage of the event contains an intuitive error message, without technical terms, which can be shown to the application user.

TIP: if fail(e) be called, use e.detail.developerMessage and e.detail.moreInfo to know technical form what heppened and how fix it.

Similar that, the propriety developerMessage contains an error message directed developers, with suggestions about how fix it. By the way, the propiety errorCode contains an integer that indicates the code of the error that happened, moreInfo and contains link(s) to the Iara Speech SDK documentation that may help with the problem.

progress() - initialization progress

SDK initialization process is made several steps, how check if ALS is running, donwload user voice model, etc.

Check the page events to learn more about parameter progress() have information about initialization.

You can use method calls progress() to follow these steps. Method progress() will be called several times during the initialization, one for each process step:

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

recognition
  .init({
    // (...)
  })
  .done(function (e) {
    // (...)
  })
  .fail(function (e) {
    // (...)
  })
  .progress(function (e) {
    // Initialization is happening. Propriety "detail" of event "and"
    // has the proprieties:
    //
    //  type
    //              event type, which can be any of the events
    //              named IaraInitEvent.INIT_*.
    //  developerMessage
    //              message direct to developers, describing steps
    //              initialization is running.
    //  userMessage
    //              intuitive message, without technical terms, that describes
    //              steps initialization. Ex.: "Downloading
    //              your voice model".
    //  moreInfo
    //              link(s) to Iara's Speech SDK documentation that explain 
    //             the steps of initialization.
    console.debug(
      "[" + e.detail.type + "] starting iara: " + e.detail.developerMessage
    );
    console.log(e.detail.userMessage);
  });

The method progress() will be called many times before done() or fail() finally be called. For example, progress() will be called when SDK detect that ALS is running on the user's computer, when the specific voice model of user is being download, when the voice model was download successfully etc.

As a good usability, it's recommend that user of application be visually informed about the initialization steps. That's avoid user's deceptions, who will not remain looking at an application that appears to be stuck.

On this point, the propriety userMessage of propriety detail passed event the progress() have an intuitive message, without technical terms and that describe initialization steps. One example is the phrase "downloading your voice model".

Check the page examples and the example events-listeners illustrate about the use progress() recommend way.

Similar way, the propriety developerMessage have a message to the developers, describing about initialization steps that's have being executing. The propriety moreInfo have link(s) that directs to Iara Speech SDK documentation to explain initialization steps.