Skip to main content

Quick use guide

This guide will show the basics that you need to do to get Iara’s voice recognition working on your web application.

OBS: This guide assumes that you already have SDK javascript and the local service(ALS) integrated/installed on your computer. If it is not the case, check the page Installation.

1. Basic Skeleton​

Given the below web application:

<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">
    // Your application's JS code here.
  </script>
</body>

To simplify the comprehension, any Javascript code used by Iara shown from now, replace the comment // Your application JS code here of the example above.

Tip: check the code examples available in this SDK. You can use some of them as a base for your project or integration.

2. Initialization and authentication​

The first step is to instantiate and initialize the Iara recognizer with your access data, i.e. userId and apiToken. You must have received your userId and apiToken when you created an account to use the SDK.

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

// Instantiate the Iara's recognizer 
var recognition = new IaraSpeechRecognition();

// Initialize the SDK, i.e. autentication, checks the ALS, install the voice model, etc.
recognition.init({
    userId: myUserId,
    apiToken: myApiToken
}).done(function(e) {
    // All alright, recognition is ready to begin.
}).fail(function(e) {
    // Some problem happened.
});

If everything is initialized without problems, the method done() will be called, indicating that the SDK is ready to start voice recognition. If there is a problem, the method fail() will be called with the error information.

Tip: each user of your application must have an own userId, because the Iara's voice recognition is customized by user. The userId value identifies only a person and will be used to download and adjust of an own voice model to the user in question. See the section Authentication (Iara API) to know more.

You can follow in detail the initialization steps made by SDK through calls to the progress() method, described in the next section. The use of progress() method is optional, but we recommend it to ensure a good experience of use to your application user.

IMPORTANT: different users must not use the same userId. It degrades the voice recognition accuracy.

2.1 Startup events throught progress() (optional)​

After user authentication, the SDK will make many internal initializations, like check if the ALS is working, download of the user voice model, etc.

The progress() method, is called several times, one for each startup step done during the boot:

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

The progress() method will be called, for example, when the SDK detects that the ALS is working on the user computer, when the user voice model specified is being installed, when the voice model has been installed correctly, etc.

Check the page Startup and Events to know about the steps that happen in the startup.

2.2 Recognizer settings (optional)​

You can set your voice recognizer to your necessities, ex.: whether or not you want intermediate recognition results:

var recognition = new IaraSpeechRecognition();

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

If you don’t change the specific settings, the default values will be used. For more information, see the page Initialization.

Tip: check the page Audio Devices for more information about utilization and setting of audio input devices, as SpeechMike®.

3. Voice recognition​

Assuming that everything has been initialized without problems, you can start the voice recognition after done() is called:

var recognition = new IaraSpeechRecognition();
recognition.init({
    // (...)
}).done(function(e) {
// The main event of voice recognition is the "onresult", when called
//  some audio on the input is detected.
    recognition.onresult = function(event) {
        // The "event" parameter contains a function called "detail", which is a
        // object IaraSpeechRecognitionDetail. The "transcript" property of this
// object contains the text that Iara recognized based on the input audio.
        var text = event.detail.transcript.toLowerCase();
        console.log('Texto reconhecido: ' + text);
    };

   // We set buttons to enable/disable audio recognition.
    var botaoStart = document.getElementById('btnStart');
    var botaoStop = document.getElementById('btnStop');

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

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

In the example above, when the recognizer calls the done() method to indicate that everything is correctly setted, two activities are made. In the first, a function is created to deal with the event onresult, which is called when some audio is recognized.

In the second activity, two HTML buttons are setted to turn on and turn off the Iara voice recognition. The first button (whose id is btnStart) is setted to activate the voice recognition when clicked. This is made through the button click event, that when is sent, makes a call to recognition.start(), starting the voice recognition. Similarly, the id button btnStop, when clicked, calls recognition.stop(), which ends the recognition operation. Iara will not make new recognition in the audio input device until recognition.start() is called again.

After recognition.start() is called, the event onresult is invoked repeatedly with a variable range, which depends on the user’s computer available computational resources.

Complete basic skeleton​

Below is the skeleton of a basic application, but complete, that uses 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 your userId
    var myApiToken = '197765800edb8affcb44a7ae7b4ff0a3'; // use o seu apiToken

    // Instantiates Iara recognizer
    var recognition = new IaraSpeechRecognition();

    // Initializes the SDK, i.e. authentication, checks the ALS, downloads the voice model, etc.
    recognition.init({
        userId: myUserId,
        apiToken: myApiToken
    }).done(function(e) {
        // The main voice recognition event is the "onresult", called when
        // some input audio is recognized.
        recognition.onresult = function(event) {
            // The "event" parameter contains a function called "detail", wich is a
            // object IaraSpeechRecognitionDetail. The "transcript" function of this 
            // object contains the text that Iara recognized based on the input audio.
            var text = event.detail.transcript.toLowerCase();
            console.log('Recognized text: ' + text);
        };

        // We set up buttons to enable/disable audio recognition.
        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) {
        // Some problem occurred. The "e" parameter contains many information about the error.
        console.error('Algum problema na inicialização da Iara: ' + e.detail.userMessage);     }).progress(function(e) {
        // This method is called several times by the SDK during the boot.
        // You can use it to follow the initialization steps, to report back
        // to your user that your voice model is being downloaded, for example.
        console.debug('A Iara está inicializando: ' + e.detail.type);
    });
  </script>
</body>