Audio input/output devices

SDK allows the use of several audio input devices, including external USB microphones such as SpeechMike®.

Choosing a device

Audio devices can be chosen either during the SDK initialization as in execution time, while the application is running.

During initialization

You can set the audio input device during the SDK initialization through the attribute input passed to the method init():

var recognition = new IaraSpeechRecognition();

// Starts SDK
recognition.init({
    userId: 'meu@email.com',
    apiToken: '197765800edb8affcb44a7ae7b4ff0a3',
    input: 'auto'                                  // Audio input device
});

Operational systems and browsers have unique privacy requirements and audio capture functionality. For this reason, the SDK handles any complications under the hood by using the option input: 'auto' (default), which chooses the input device automatically.

If input: 'auto' is used as an audio input device, the SDK will attempt to configure the best input device for the user's environment with as little interaction as possible.

Tip: if input was not informed on initialization, input: 'auto' will be used. This is the most flexible way to choose the audio input device.

With use of input: 'auto', for example, if one SpeechMike® is found in some USB input, the SDK will try to use him. On Mac computers, for example, depending from the operating system version, the audio capture can be done without user interaction or through the user interaction browser.

In cases like that, when the SDK is unable to get the audio catch device without user intervention, necessary asks will be emitted, ex: ask the user to authorize the audio catch through the microphone accessible by the browser.

Forcing boot with a particular audio device

If your application depending on from an input device specific, you can force him for that he be chosen during the initialization. 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!');
});

Available device initialization

The chart below show you a list of values that can be use on quality input passed for methodinit().

Name	Value of input	Description
Auto chose	automático	The SDK choose the best input audio device with minimum of user interaction.
SpeechMike	speechmike	SpeechMike® USB external microphone.
Microphone of system	osmic	The template of system input audio device, ex: computer front microphone. If osmic is use, the user won't need to authorize the audio catch because she won't be made from the browser, but on operational system.
Browser microphone	browsermic	The default audio input device made available by the browser through the callnavigator.mediaDevices.getUserMedia(). If browsermic to use, the user will need authorize the audio catch by an interation whith browser.

Execution time

Device input and output device can be chosen at any time at execution time by the method calls setAudioInput() e setAudioOutput(), respectively.

As well setAudioInput() as setAudioOutput() receives two parameters: the id of the audio device to be used, and one callback function, flagged when the operation is complete.

The example below shows the selection of a dummy audio device id 12345:

var recognition = new IaraSpeechRecognition();

// Inicializa o SDK
recognition.init({
    userId: 'meu@email.com',
    apiToken: '197765800edb8affcb44a7ae7b4ff0a3',

}).done(function(e) {
    recognition.setAudioInput(12345, function() {
        console.log('Dispositivo de audio selecionado');
    });
});

Listing audios devices available

After initialization, the input and output audios devices exist on the user's computer can be consulted though the proprieties audioInputs e audioOutputs recognizer.

The example below have a list with all devices of audio input and output available:

var recognition = new IaraSpeechRecognition();

// Inicializa o SDK
recognition.init({
    userId: 'meu@email.com',
    apiToken: '197765800edb8affcb44a7ae7b4ff0a3',

}).done(function(e) {
    var i, device;

    for(i = 0; i < recognition.audioInputs.length; i++) {
        device = recognition.audioInputs[i];
        console.log('Dispositivo de entrada: ', device.id, device.name, device.selected);
    }

    for(i = 0; i < recognition.audioOutputs.length; i++) {
        device = recognition.audioOutputs[i];
        console.log('Dispositivo de saída: ', device.id, device.name, device.selected);
    }
});

The propriety's id audio device is the id expect by setAudioInput() and setAudioOutput() to the select of devices.

The propriety's selected audio devices listed by audioInputs and audioOutputs show if the devic is in use or not. The propriety is read-only (read-only). Changes made to them will haven't effect and will be overwritten by the recognizer periodically.

If you wish to chose a imput/output audio device, use setAudioInput() e setAudioOutput().

IMPORTANT: the proprieties audioInputs and audioOutputs and inputs are read-only. Select input/output device through of setAudioInput() and setAudioOutput().

Testing audio devices

To know if that audio devices are set up and working is essential for speech voice recognition applications. For this reason, Iara's recognizer provides the method testAudioInputOutput().

This method record audio input devices (by N seconds), then play that audio using the output device. Testing is similar to test calls made by video calling applications such as Skype.

The next example show a 3 seconds of audio test:

function gravacaoFinalizada() {
    console.log('Gravação finalizada. Iniciando reprodução.');
}

function reproducacaoFinalizada() {
    console.log('Reprodução finalizada. Do you do heard something?');
}

var recognition = new IaraSpeechRecognition();

recognition.init({
    userId: 'meu@email.com',
    apiToken: '197765800edb8affcb44a7ae7b4ff0a3',

}).done(function(e) {
    // start for 3 seconds the audio input/output test.
    // During stipulated while, the SDK will record the audio from the input device.
    // Next, the function `gravacaoFinalizada()` will be called and the recorded audio will be
    // played. When the audio playback have been successfully, the function
    // `reproducacaoFinalizada()` will be called. If everything has alright, user should hear 
// what was recorded.
    recognition.testAudioInputOutput(3, gravacaoFinalizada, reproducacaoFinalizada);
});

The exampleaudio-devices-test contains ready codes referring to audio devices.